@vantran-se/openchamber-web 1.24.4 → 2.0.1

package/server/lib/fs/byte-range.js

@@ -0,0 +1,35 @@
+/**
+ * One HTTP `Range` header, reduced to the single byte span this server serves.
+ *
+ * Media elements ask for `bytes=0-` first and then for `bytes=<offset>-` on
+ * every seek; without a 206 answer Chromium and WebKit refuse to seek at all,
+ * and Safari refuses to play. Multi-range requests are answered with the whole
+ * file: no media consumer sends them, and a multipart body is not worth
+ * carrying for a viewer.
+ */
+
+/**
+ * @param {unknown} header
+ * @param {number} size
+ * @returns {{ kind: 'range', start: number, end: number } | { kind: 'whole' } | { kind: 'unsatisfiable' }}
+ */
+export const resolveByteRange = (header, size) => {
+  if (!header || size <= 0) return { kind: 'whole' };
+  const match = /^bytes=(\d*)-(\d*)$/.exec(String(header).trim());
+  if (!match) return { kind: 'whole' };
+  const [, rawStart, rawEnd] = match;
+  if (rawStart === '' && rawEnd === '') return { kind: 'whole' };
+
+  // `bytes=-500` means the final 500 bytes.
+  if (rawStart === '') {
+    const suffix = Number(rawEnd);
+    if (suffix === 0) return { kind: 'unsatisfiable' };
+    return { kind: 'range', start: Math.max(0, size - suffix), end: size - 1 };
+  }
+
+  const start = Number(rawStart);
+  if (start >= size) return { kind: 'unsatisfiable' };
+  const end = rawEnd === '' ? size - 1 : Math.min(Number(rawEnd), size - 1);
+  if (end < start) return { kind: 'unsatisfiable' };
+  return { kind: 'range', start, end };
+};

package/server/lib/fs/byte-range.test.js

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveByteRange } from './byte-range.js';
+
+describe('resolveByteRange', () => {
+  it('serves the whole file without a header, for an empty file, and for anything but one bytes span', () => {
+    expect(resolveByteRange(undefined, 100)).toEqual({ kind: 'whole' });
+    expect(resolveByteRange('bytes=0-', 0)).toEqual({ kind: 'whole' });
+    expect(resolveByteRange('items=0-1', 100)).toEqual({ kind: 'whole' });
+    expect(resolveByteRange('bytes=0-1,5-9', 100)).toEqual({ kind: 'whole' });
+    expect(resolveByteRange('bytes=-', 100)).toEqual({ kind: 'whole' });
+  });
+
+  it('answers the open-ended span a media element sends on seek', () => {
+    expect(resolveByteRange('bytes=0-', 100)).toEqual({ kind: 'range', start: 0, end: 99 });
+    expect(resolveByteRange('bytes=40-', 100)).toEqual({ kind: 'range', start: 40, end: 99 });
+  });
+
+  it('clamps a closed span to the file and honours a suffix span', () => {
+    expect(resolveByteRange('bytes=10-19', 100)).toEqual({ kind: 'range', start: 10, end: 19 });
+    expect(resolveByteRange('bytes=90-500', 100)).toEqual({ kind: 'range', start: 90, end: 99 });
+    expect(resolveByteRange('bytes=-30', 100)).toEqual({ kind: 'range', start: 70, end: 99 });
+    expect(resolveByteRange('bytes=-300', 100)).toEqual({ kind: 'range', start: 0, end: 99 });
+  });
+
+  it('rejects a span that starts past the end or runs backwards', () => {
+    expect(resolveByteRange('bytes=100-', 100)).toEqual({ kind: 'unsatisfiable' });
+    expect(resolveByteRange('bytes=50-40', 100)).toEqual({ kind: 'unsatisfiable' });
+    expect(resolveByteRange('bytes=-0', 100)).toEqual({ kind: 'unsatisfiable' });
+  });
+});

package/server/lib/fs/routes.js

@@ -1,4 +1,5 @@
 import { createRealpathCache } from '../path-realpath-cache.js';
+import { resolveByteRange } from './byte-range.js';
 import nodeFsPromises from 'node:fs/promises';
 import nodePath from 'node:path';
 
@@ -67,25 +68,6 @@ export const mintOutsideFileGrant = async (targetPath, {
   };
 };
 
-const resolveOutsideFileGrant = async ({ token, targetPath, scope, fsPromises }) => {
-  pruneOutsideFileGrants();
-  if (typeof token !== 'string' || !token.trim()) {
-    return { ok: false, error: 'Outside workspace file access requires a grant' };
-  }
-  const grant = outsideFileGrants.get(token.trim());
-  if (!grant) {
-    return { ok: false, error: 'Outside workspace file grant is invalid or expired' };
-  }
-  if (!grant.scopes.has(scope)) {
-    return { ok: false, error: 'Outside workspace file grant does not allow this operation' };
-  }
-  const canonicalPath = await fsPromises.realpath(targetPath);
-  if (canonicalPath !== grant.canonicalPath) {
-    return { ok: false, error: 'Outside workspace file grant does not match requested path' };
-  }
-  return { ok: true, base: grant.base, resolved: canonicalPath, granted: true };
-};
-
 const createCommandTimeoutMs = () => {
   const raw = Number(process.env.OPENCHAMBER_FS_EXEC_TIMEOUT_MS);
   if (Number.isFinite(raw) && raw > 0) return raw;
@@ -125,14 +107,30 @@ const FILE_MIME_MAP = Object.freeze({
   '.xml': 'application/xml',
   '.txt': 'text/plain',
   '.md': 'text/markdown',
+  '.mmd': 'text/plain',
   '.pdf': 'application/pdf',
   '.csv': 'text/csv',
+  '.tsv': 'text/tab-separated-values',
   '.woff2': 'font/woff2',
   '.woff': 'font/woff',
   '.ttf': 'font/ttf',
+  '.otf': 'font/otf',
   '.eot': 'application/vnd.ms-fontobject',
   '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac',
+  '.wav': 'audio/wav',
+  '.flac': 'audio/flac',
+  '.ogg': 'audio/ogg',
+  '.oga': 'audio/ogg',
+  '.opus': 'audio/ogg',
+  '.weba': 'audio/webm',
   '.mp4': 'video/mp4',
+  '.m4v': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mov': 'video/quicktime',
+  '.ogv': 'video/ogg',
+  '.mkv': 'video/x-matroska',
   '.png': 'image/png',
   '.jpg': 'image/jpeg',
   '.jpeg': 'image/jpeg',
@@ -450,19 +448,14 @@ const escapeCloneSshKeyPath = (sshKeyPath) => {
   return `'${normalized.replace(/'/g, "'\\''")}'`;
 };
 
-const resolveReadPathFromContext = async ({ req, targetPath, scope, resolveProjectDirectory, path, os, fsPromises, normalizeDirectoryPath, managedRoots }) => {
+const resolveReadPathFromContext = async ({ req, targetPath, resolveProjectDirectory, path, os, fsPromises, normalizeDirectoryPath, managedRoots }) => {
   if (req.query?.allowOutsideWorkspace === 'true') {
     const normalized = normalizeDirectoryPath(targetPath);
     if (!normalized || typeof normalized !== 'string') {
       return { ok: false, error: 'Path is required' };
     }
     const resolved = path.resolve(normalized);
-    return resolveOutsideFileGrant({
-      token: req.query?.outsideFileGrant,
-      targetPath: resolved,
-      scope,
-      fsPromises,
-    });
+    return { ok: true, base: path.dirname(resolved), resolved };
   }
 
   return resolveWorkspacePathFromContext({
@@ -1088,19 +1081,7 @@ export const registerFsRoutes = (app, dependencies) => {
       }
 
       const ext = path.extname(canonicalPath).toLowerCase();
-      const mimeMap = {
-        '.png': 'image/png',
-        '.jpg': 'image/jpeg',
-        '.jpeg': 'image/jpeg',
-        '.gif': 'image/gif',
-        '.svg': 'image/svg+xml',
-        '.webp': 'image/webp',
-        '.ico': 'image/x-icon',
-        '.bmp': 'image/bmp',
-        '.avif': 'image/avif',
-        '.pdf': 'application/pdf',
-      };
-      const mimeType = mimeMap[ext] || 'application/octet-stream';
+      const mimeType = FILE_MIME_MAP[ext] || 'application/octet-stream';
 
       const download = req.query.download === 'true';
       if (download) {
@@ -1114,11 +1095,35 @@ export const registerFsRoutes = (app, dependencies) => {
         res.setHeader('Content-Disposition', `attachment; filename="${fallback}"; filename*=UTF-8''${encoded}`);
       }
 
-      const content = await fsPromises.readFile(canonicalPath);
       res.setHeader('Cache-Control', 'no-store');
-      if (resolved.granted) {
-        res.setHeader('Referrer-Policy', 'no-referrer');
+      res.setHeader('Referrer-Policy', 'no-referrer');
+      res.setHeader('Accept-Ranges', 'bytes');
+
+      // A byte span is streamed from disk rather than read whole: the audio
+      // and video players ask for one on every seek, and a recording can be
+      // hundreds of megabytes.
+      const range = resolveByteRange(req.headers?.range, stats.size);
+      if (range.kind === 'unsatisfiable') {
+        res.setHeader('Content-Range', `bytes */${stats.size}`);
+        return res.status(416).end();
+      }
+      if (range.kind === 'range') {
+        const handle = await fsPromises.open(canonicalPath, 'r');
+        res.status(206);
+        res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${stats.size}`);
+        res.setHeader('Content-Length', String(range.end - range.start + 1));
+        res.type(mimeType);
+        // The handle closes with the stream, on success and on failure alike.
+        const stream = handle.createReadStream({ start: range.start, end: range.end });
+        stream.on('error', (error) => {
+          console.error('Failed to stream raw file range:', error);
+          res.destroy(error);
+        });
+        stream.pipe(res);
+        return undefined;
       }
+
+      const content = await fsPromises.readFile(canonicalPath);
       return res.type(mimeType).send(content);
     } catch (error) {
       const err = error;

package/server/lib/fs/routes.test.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { Readable, Writable } from 'node:stream';
 import path from 'path';
 import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
 import * as nativeFs from 'node:fs/promises';
@@ -572,8 +573,7 @@ describe('fs read', () => {
     expect(fsPromises.readFile).toHaveBeenCalledWith('/shared/target.txt', 'utf8');
   });
 
-  it('rejects outside workspace reads without a grant', async () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  it('reads outside workspace files without a grant', async () => {
     const fsPromises = {
       stat: vi.fn(async () => ({ isFile: () => true, size: 3 })),
       readFile: vi.fn(async () => 'secret'),
@@ -582,10 +582,9 @@ describe('fs read', () => {
 
     const res = await callRead(handler, { path: '/etc/passwd', allowOutsideWorkspace: 'true' });
 
-    expect(res.statusCode).toBe(400);
-    expect(res.body).toEqual({ error: 'Outside workspace file access requires a grant' });
-    expect(fsPromises.readFile).not.toHaveBeenCalled();
-    warn.mockRestore();
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toBe('secret');
+    expect(fsPromises.readFile).toHaveBeenCalledWith('/etc/passwd', 'utf8');
   });
 
   it('allows outside workspace reads with an exact-path grant', async () => {
@@ -611,7 +610,7 @@ describe('fs read', () => {
     expect(res.body).toBe('secret');
   });
 
-  it('rejects outside workspace grants for a different canonical path', async () => {
+  it('ignores legacy grants when reading another outside file', async () => {
     const fsPromises = {
       realpath: vi.fn(async (targetPath) => targetPath),
       stat: vi.fn(async () => ({ isFile: () => true, size: 6 })),
@@ -630,35 +629,58 @@ describe('fs read', () => {
       outsideFileGrant: grant.outsideFileGrant,
     });
 
-    expect(res.statusCode).toBe(400);
-    expect(res.body).toEqual({ error: 'Outside workspace file grant does not match requested path' });
-    expect(fsPromises.readFile).not.toHaveBeenCalled();
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toBe('secret');
+    expect(fsPromises.readFile).toHaveBeenCalledWith('/outside/b.txt', 'utf8');
   });
 
-  it('sets no-referrer on raw responses served through outside file grants', async () => {
+  it('reads outside raw files without a grant and sets no-referrer', async () => {
     const fsPromises = {
       realpath: vi.fn(async (targetPath) => targetPath),
       stat: vi.fn(async () => ({ isFile: () => true, size: 6 })),
       readFile: vi.fn(async () => Buffer.from('secret')),
     };
-    const grant = await mintOutsideFileGrant('/outside/image.png', {
-      scopes: ['raw'],
-      fsPromises,
-      path: path.posix,
-      crypto: { randomUUID: () => 'grant-raw' },
-    });
     const handler = registerRaw(fsPromises);
 
     const res = await callRaw(handler, {
       path: '/outside/image.png',
       allowOutsideWorkspace: 'true',
-      outsideFileGrant: grant.outsideFileGrant,
     });
 
     expect(res.statusCode).toBe(200);
     expect(res.getHeader('referrer-policy')).toBe('no-referrer');
   });
 
+  it('stats outside files without a grant', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    registerFsRoutes(app, {
+      path: path.posix,
+      os: { homedir: () => '/home/user' },
+      fsPromises: {
+        realpath: async (targetPath) => targetPath,
+        stat: async () => ({ isFile: () => true, size: 100, mtimeMs: 123 }),
+      },
+      normalizeDirectoryPath: (p) => p,
+      resolveProjectDirectory: async () => ({ directory: '/repo' }),
+      openchamberUserConfigRoot: '/home/user/.config',
+    });
+    const res = await callRead(getRoute('GET', '/api/fs/stat'), { path: '/tmp/plan.txt', allowOutsideWorkspace: 'true' });
+    expect(res.statusCode).toBe(200);
+    expect(res.body).toEqual({ path: '/tmp/plan.txt', isFile: true, size: 100, mtimeMs: 123 });
+  });
+
+  it.each([
+    ['ENOENT', 404, { error: 'File not found' }],
+    ['EACCES', 403, { error: 'Access to file denied', reason: 'os-permission' }],
+  ])('reports %s for outside files instead of requiring a grant', async (code, status, body) => {
+    const handler = registerRead({
+      realpath: async () => { throw Object.assign(new Error(code), { code }); },
+    });
+    const res = await callRead(handler, { path: '/tmp/plan.txt', allowOutsideWorkspace: 'true' });
+    expect(res.statusCode).toBe(status);
+    expect(res.body).toEqual(body);
+  });
+
   it('rejects outside workspace mkdir without a trusted directory grant', async () => {
     const fsPromises = {
       mkdir: vi.fn(async () => undefined),
@@ -1012,6 +1034,88 @@ describe('fs exec git-read cache', () => {
   });
 });
 
+describe('fs raw byte ranges', () => {
+  const createStreamingResponse = () => {
+    const chunks = [];
+    const headers = new Map();
+    let statusCode = 200;
+    const res = new Writable({
+      write(chunk, _encoding, callback) {
+        chunks.push(Buffer.from(chunk));
+        callback();
+      },
+    });
+    Object.assign(res, {
+      status(code) { statusCode = code; return res; },
+      json(payload) { chunks.push(Buffer.from(JSON.stringify(payload))); return res; },
+      type() { return res; },
+      send(payload) { chunks.push(Buffer.from(payload)); return res; },
+      setHeader(name, value) { headers.set(name.toLowerCase(), value); return res; },
+      getHeader(name) { return headers.get(name.toLowerCase()); },
+    });
+    return {
+      res,
+      finished: new Promise((resolve) => res.on('finish', resolve)),
+      get statusCode() { return statusCode; },
+      get body() { return Buffer.concat(chunks).toString('utf8'); },
+    };
+  };
+
+  const registerRawWithFile = (bytes) => {
+    const open = vi.fn(async () => ({
+      createReadStream: ({ start, end }) => Readable.from([bytes.subarray(start, end + 1)]),
+    }));
+    const readFile = vi.fn(async () => bytes);
+    const handler = registerRaw({
+      stat: async () => ({ isFile: () => true, size: bytes.length }),
+      open,
+      readFile,
+    });
+    return { handler, open, readFile };
+  };
+
+  it('answers a bytes span with 206, the span headers, and only those bytes', async () => {
+    const { handler, open, readFile } = registerRawWithFile(Buffer.from('0123456789'));
+    const response = createStreamingResponse();
+
+    await handler({ query: { path: '/repo/clip.mp4' }, headers: { range: 'bytes=3-' } }, response.res);
+    await response.finished;
+
+    expect(response.statusCode).toBe(206);
+    expect(response.getHeader?.('content-range') ?? response.res.getHeader('content-range')).toBe('bytes 3-9/10');
+    expect(response.res.getHeader('content-length')).toBe('7');
+    expect(response.res.getHeader('accept-ranges')).toBe('bytes');
+    expect(response.body).toBe('3456789');
+    expect(open).toHaveBeenCalledWith('/repo/clip.mp4', 'r');
+    expect(readFile).not.toHaveBeenCalled();
+  });
+
+  it('serves the whole file, advertising ranges, when no span is asked for', async () => {
+    const { handler, open } = registerRawWithFile(Buffer.from('0123456789'));
+    const res = createMockResponse();
+
+    await handler({ query: { path: '/repo/clip.mp4' }, headers: {} }, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.getHeader('accept-ranges')).toBe('bytes');
+    expect(res.body.toString('utf8')).toBe('0123456789');
+    expect(open).not.toHaveBeenCalled();
+  });
+
+  it('rejects a span past the end with 416 and the file size', async () => {
+    const { handler, open } = registerRawWithFile(Buffer.from('0123456789'));
+    const res = createMockResponse();
+    res.end = vi.fn(() => res);
+
+    await handler({ query: { path: '/repo/clip.mp4' }, headers: { range: 'bytes=10-' } }, res);
+
+    expect(res.statusCode).toBe(416);
+    expect(res.getHeader('content-range')).toBe('bytes */10');
+    expect(res.end).toHaveBeenCalled();
+    expect(open).not.toHaveBeenCalled();
+  });
+});
+
 describe('fs raw download Content-Disposition', () => {
   it('uses RFC 5987 filename*= encoding for non-ASCII filenames on download', async () => {
     const fsPromises = {
@@ -1446,6 +1550,7 @@ describe('fs stat directory error handling', () => {
     try {
       await mkdir(path.join(directory, 'fs'));
       await copyFile(new URL('./routes.js', import.meta.url), path.join(directory, 'fs/routes.mjs'));
+      await copyFile(new URL('./byte-range.js', import.meta.url), path.join(directory, 'fs/byte-range.js'));
       await copyFile(new URL('../path-realpath-cache.js', import.meta.url), path.join(directory, 'path-realpath-cache.js'));
       expect(() => execFileSync('node', [
         '--input-type=module',

package/server/lib/git/service.js

@@ -2501,6 +2501,18 @@ export async function getTrackingBranch(directory) {
   return tracking || null;
 }
 
+// Whether `sha` is reachable from the checked-out HEAD. An object git has never
+// fetched fails the same way an unrelated commit does: not an ancestor.
+export async function isAncestorOfHead(directory, sha) {
+  const normalizedDirectory = normalizeDirectoryPath(directory);
+  const normalizedSha = typeof sha === 'string' ? sha.trim() : '';
+  if (!normalizedDirectory || !/^[0-9a-f]{7,64}$/i.test(normalizedSha)) {
+    return false;
+  }
+  const result = await runGitCommand(normalizedDirectory, ['merge-base', '--is-ancestor', normalizedSha, 'HEAD']);
+  return result.success;
+}
+
 async function readStatus(normalizedDirectory, lightMode) {
   try {
     // Prefer an explicit non-repo check before simple-git status so a missing

package/server/lib/github/DOCUMENTATION.md

@@ -83,7 +83,7 @@ that page, so callers cannot mistake a partial page for a complete one.
 - It first searches for **open** PRs by likely source owner plus exact head branch.
 - If that fails, it falls back to broader GitHub search for open PRs on the branch name.
 - An **open PR from any candidate repo always wins** over a closed/merged one, so a merged fork PR can never hide an open upstream PR for the same head.
-- Only when no target has an open PR does it return the branch's newest closed/merged PR, as history.
+- Only when no target has an open PR does it return the branch's newest closed/merged PR, as history — and only when that PR's head commit is an ancestor of the checkout's `HEAD`. History is matched by branch name, and names get reused: a fresh worktree cut from the default branch under a name that was merged before must not inherit the old PR.
 - History is looked up **only for the ranked-first remote and the branch's own name** — the repo it actually pushes to. Live status is worth searching the whole fork network for; history is not, and asking every target for it multiplies serial GitHub calls until the route hits its `12s` resolve timeout and returns no status at all.
 - The history answer is remembered per repo+branch so discovery polls do not re-query it: a found closed/merged record for `6h`, and "no history yet" for `10m`. A found record only changes if a second PR appears on the same head, and while that one is open the open-PR path wins without ever reading this cache.
 - Creating, merging, or closing a PR invalidates both the shared repo pull list and that remembered history.

package/server/lib/github/pr-status.js

@@ -1,5 +1,5 @@
 import { stat } from 'node:fs/promises';
-import { getRemotes, getTrackingBranch } from '../git/index.js';
+import { getRemotes, getTrackingBranch, isAncestorOfHead } from '../git/index.js';
 import { resolveGitHubRepoFromDirectory } from './repo/index.js';
 import { noteIfGitHubRateLimit } from './rate-limit.js';
 
@@ -543,6 +543,26 @@ const searchFallbackPr = async ({ octokit, branch, repoNames }) => {
 
 const isTerminalPr = (pr) => Boolean(pr) && (pr.state === 'closed' || Boolean(pr.merged_at));
 
+// A closed/merged PR is matched by head branch NAME, and names get reused: a
+// fresh worktree called `feature` cut from the default branch would inherit
+// the merged PR of last month's `feature`. The PR only belongs to this checkout
+// when the commit it was merged or closed at is part of the checkout's history.
+// `isAncestor` is the git check, replaceable so the tests need no git repository.
+const isHistoricalPrOfCheckout = async (directory, pr, { isAncestor = isAncestorOfHead } = {}) => {
+  const headSha = normalizeText(pr?.head?.sha);
+  if (!headSha) {
+    return false;
+  }
+  try {
+    return await isAncestor(directory, headSha);
+  } catch {
+    return false;
+  }
+};
+
+// Exported for focused unit tests.
+export { isHistoricalPrOfCheckout };
+
 /**
  * Resolve the PRs a branch is associated with in one repo target.
  *
@@ -764,7 +784,7 @@ export async function resolveGitHubPrStatus({ octokit, directory, branch, remote
     }
   }
 
-  if (historicalMatch) {
+  if (historicalMatch && await isHistoricalPrOfCheckout(directory, historicalMatch.pr)) {
     return historicalMatch;
   }
 

package/server/lib/github/pr-status.test.js

@@ -1,21 +1,10 @@
 import { afterEach, beforeEach, describe, expect, mock, test, vi } from 'bun:test';
 
-const listMock = mock(async () => ({ data: [] }));
-
-mock.module('../git/index.js', () => ({
-  getRemotes: async () => [],
-  getTrackingBranch: async () => null,
-}));
+import { findBranchPrCandidates, invalidateRepoPullsCache, isHistoricalPrOfCheckout } from './pr-status.js';
 
-mock.module('./repo/index.js', () => ({
-  resolveGitHubRepoFromDirectory: async () => null,
-}));
-
-mock.module('./rate-limit.js', () => ({
-  noteIfGitHubRateLimit: () => {},
-}));
+const listMock = mock(async () => ({ data: [] }));
 
-const { findBranchPrCandidates, invalidateRepoPullsCache } = await import('./pr-status.js');
+const isAncestorMock = mock(async () => false);
 
 const openPr = {
   number: 15,
@@ -180,3 +169,27 @@ describe('findBranchPrCandidates', () => {
     expect(listMock.mock.calls.length).toBeGreaterThan(callsAfterFirst + 1);
   });
 });
+
+describe('isHistoricalPrOfCheckout', () => {
+  beforeEach(() => {
+    isAncestorMock.mockReset();
+  });
+
+  test('a merged PR whose head commit is in the checkout history belongs to it', async () => {
+    isAncestorMock.mockImplementation(async () => true);
+    const pr = { ...mergedPr, head: { ...mergedPr.head, sha: 'abc1234' } };
+    expect(await isHistoricalPrOfCheckout('/repo', pr, { isAncestor: isAncestorMock })).toBe(true);
+    expect(isAncestorMock).toHaveBeenCalledWith('/repo', 'abc1234');
+  });
+
+  test('a reused branch name without the merged commits does not inherit the PR', async () => {
+    isAncestorMock.mockImplementation(async () => false);
+    const pr = { ...mergedPr, head: { ...mergedPr.head, sha: 'abc1234' } };
+    expect(await isHistoricalPrOfCheckout('/repo', pr, { isAncestor: isAncestorMock })).toBe(false);
+  });
+
+  test('a PR without a head sha is never attributed', async () => {
+    expect(await isHistoricalPrOfCheckout('/repo', mergedPr, { isAncestor: isAncestorMock })).toBe(false);
+    expect(isAncestorMock).not.toHaveBeenCalled();
+  });
+});

package/server/lib/guests/DOCUMENTATION.md

@@ -62,7 +62,20 @@ A missing folder is omitted from the list. Other guests stay. A corrupt `extensi
 - `contributes.actions`, `contributes.commands`, and `contributes.tools` are validated by the SDK parse at install (`invalid-actions` / `invalid-commands` / `invalid-tools` surface as `invalid-manifest`) and copied to the catalog row unchanged. Tool presentations are applied in the UI only (`packages/ui/src/lib/guests/tool-presentation.ts`); no server route reads them. No server route runs an action or a command: the message or session item is built in the UI from the same records Export as Markdown uses, and a slash command is answered by the guest frame over `postMessage`. The rail badge is UI memory only.
 - `contributes.attach` is copied as `"panel"` or `"dialog"`. The composer + menu and New Worktree read that field. Omitted guests stay off those menus. The object form's `entry` (dialog only) is checked at install like `panel.entry`: missing HTML is `invalid-manifest`, an unbuilt script it loads is `missing-build`; the catalog exposes it as `attachEntry` and the attach window loads that page instead of `panel.entry`. The optional attach `data` payload lives only in the UI's chip, queued context part, and session metadata snapshot; no server route parses it.
 - `request` never leaves the declared `apiOrigin`. A 401 refreshes once. If that fails, tokens for that guest are dropped. Host Linear does not drop Linear auth on a failed GraphQL query. A paused guest never proxies `request` or `serviceRequest`.
+- A service with `provides: ["browser"]` is also driven by the host (`../browser-control/provider.js`), not only by a panel: `proxyGuestServiceRequest` takes `timeoutMs`, `responseMax`, `idleStopMs`, and `signal` for that. A service that never became ready is `SERVICE_FAILED` (nothing was sent); a request that was sent and got no usable answer is `REQUEST_FAILED` (the service may have acted on it), and callers word their errors accordingly. `idleStopMs` arms a per-guest timer re-armed at the end of every request; when it fires with no request in flight the process is discarded (not a Pause: no epoch bump) and the next request respawns it. A user-facing stop clears the timer. Panel requests pass none of these and keep the SDK limits. The guest routes call `onGuestDeactivated({ guestId, guestName })` after a pause, a removal, or a withdrawn approval so a host role the extension held is handed back and the user told.
+- `surface.js` hosts shared surfaces (`contributes.service.surface`). `/api/guests/:id/surface/ws` (URL-token WebSocket, allowlisted in `ui-auth.js` and `relay/tunnel-host.js`; upgrade refused with 404 unless `isSurfaceGuest`: enabled, fully approved, declares the surface) attaches a viewer to the extension's one session. The session holds the service (`holdGuestService`) and runs one pump: `GET /surface/frame?after=<seq>&wait=25000` through `openGuestServiceRequest`, newest frame kept, delivered per viewer only after that viewer acknowledged the previous one (`frame` text message + one binary message). Control is the session's: `none`, `agent` (set by `noteAgentActivity`, expires after `SURFACE_AGENT_HOLD_MS`), or a viewer id; the first deliberate input (anything but a button-less pointer move) from a viewer while nobody or the agent holds it takes it, `release` or the holder's disconnect gives it back, a second viewer's input is refused with a `control` message. Every change is broadcast (`mine` per connection) and posted to `POST /surface/control`. Input, control notices, resizes, and clipboard reads run through one promise chain per session, in socket order; work queued for an ended session is dropped, and an ended session's close handlers never call the service, so closing a panel after a pause, removal, or withdrawn approval cannot restart the process under the session's old authorization. When the last viewer leaves normally the session stays registered until its queue (including the final `none`) has drained, so a deactivation in that window still finds and cancels it; a viewer that reattaches meanwhile restarts the pump. Every hand-off (release, holder disconnect) bumps `session.handoffs`; an input batch remembers the count it arrived under and, if it no longer holds control, may take control only when nothing was handed off since, so a click queued behind a slow request cannot re-take control after the user let go, and a viewer that left (`gone`) never becomes the controller. `userControls` gates the browser provider; `endForGuest` (pause, removal, withdrawn approval) and a failed frame request end the session with an `ended` reason, and `stop()` closes every viewer on shutdown.
 - `serviceRequest` never leaves that guest's loopback port. Auth to the service is `Authorization: Bearer` with a host-minted token. The service env is an allowlist (PATH, HOME, temp, locale, Windows system variables) plus `OPENCHAMBER_SERVICE_*`; host secrets are not inherited. There is no sandbox: an allowed service has the user's full access, and the grant card says so. Ready is `GET /health` → 200. Parallel first requests share one spawn; they must not kill each other mid-start. Host quit stops every service. Disabling a guest stops its service without clearing OAuth or grants.
 - File access is decided in `files.js` on canonical paths, never on the string the guest sent. `matchesFilesystemPattern`, `expandHome`, and `globToRegExp` are pure; `resolveGuestFilePath` and `runGuestFileOperation` take `fsPromises` / `nodePath` so tests can stub the OS. The project directory is whatever `resolveOptionalProjectDirectory` validated for this request, so a guest cannot name a project the UI did not open.
 - Update swap (`updates.js` `updateGuest`): the new clone lands in `{dataDir}/extensions/.tmp-<id>-<random>` and is inspected exactly like an install before anything else moves. Only then: stop the guest's service, rename current → `.old-<id>`, rename temp → final, delete `.old-<id>`. Any failure before the swap deletes the temp dir and leaves the install untouched; a failed second rename moves `.old-<id>` back. The store row is not rewritten (same path, same id), the catalog cache and that guest's update cache entry are dropped.
 - The OAuth callback skips UI auth. Everything else under `/api/guests` stays behind the usual session.
+
+## Host shutdown
+
+`beginGuestServiceShutdown` closes service admission synchronously. Requests retain
+their host lifecycle across store reads and startup awaits, so a late completion
+cannot spawn a process during shutdown or enter a later host lifecycle.
+`stopAllGuestServices` cancels and drains pending starts as well as running and
+already-stopping children. Per-guest Pause and ordinary cleanup do not close host
+admission. `beginGuestServiceHost` opens a new lifecycle only after that drain.
+The common graceful-shutdown runtime stops surface viewers before the services.
+Crash/SIGKILL recovery remains outside this in-memory registry.

package/server/lib/guests/catalog.js

@@ -197,6 +197,12 @@ export const inspectGuestPackage = async (packageRoot, { openchamberVersion, ski
   if (panel.entry) {
     guest.entry = panel.entry;
   }
+  if (panel.dock !== undefined) {
+    guest.entryDock = panel.dock;
+  }
+  if (panel.size !== undefined) {
+    guest.entrySize = panel.size;
+  }
   const backgroundEntry = parsed.manifest.contributes.background?.entry;
   if (backgroundEntry) {
     if (!await resolveGuestAssetPath(packageRoot, backgroundEntry)) {
@@ -293,6 +299,12 @@ export const toPublicGuest = (guest) => {
   if (guest.entry) {
     row.entry = guest.entry;
   }
+  if (guest.entryDock) {
+    row.entryDock = guest.entryDock;
+  }
+  if (typeof guest.entrySize === 'number') {
+    row.entrySize = guest.entrySize;
+  }
   if (guest.backgroundEntry) {
     row.backgroundEntry = guest.backgroundEntry;
   }

package/server/lib/guests/catalog.test.js

@@ -204,6 +204,39 @@ describe('listInstalledGuests', () => {
 
     await fs.rm(dir, { recursive: true, force: true });
   });
+
+  test('a page docked beside a shared surface reaches the public row with its edge and size', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
+    const guestRoot = path.join(dir, 'sim');
+    await fs.mkdir(path.join(guestRoot, 'panel'), { recursive: true });
+    await fs.writeFile(path.join(guestRoot, 'panel', 'index.html'), '<script src="./main.js"></script>');
+    await fs.writeFile(path.join(guestRoot, 'panel', 'main.js'), 'console.log("strip")');
+    await fs.writeFile(path.join(guestRoot, 'service.js'), 'console.log("service")');
+    await fs.writeFile(path.join(guestRoot, 'package.json'), JSON.stringify({
+      name: '@openchamber/sim',
+      version: '1.0.0',
+      openchamber: {
+        apiVersion: 1,
+        contributes: {
+          panel: { id: 'sim', name: 'Sim', icon: 'window', entry: 'panel/index.html', dock: 'right', size: 240 },
+          service: { entry: 'service.js', runtime: 'host', surface: true },
+        },
+      },
+    }));
+
+    const inspected = await inspectGuestPackage(guestRoot, { openchamberVersion: '1.0.0' });
+    expect(inspected.ok).toBe(true);
+    if (inspected.ok) {
+      expect(toPublicGuest({ ...inspected.guest, source: 'path', path: guestRoot })).toMatchObject({
+        entry: 'panel/index.html',
+        entryDock: 'right',
+        entrySize: 240,
+        service: expect.objectContaining({ surface: true }),
+      });
+    }
+
+    await fs.rm(dir, { recursive: true, force: true });
+  });
 });
 
 describe('page-less packages', () => {