@vantran-se/openchamber-web 2.0.3 → 2.0.5

package/server/lib/event-stream/rebind.test.js

@@ -132,6 +132,7 @@ describe('rebindUpstream (#2638)', () => {
     expect(fetchCalls).toBe(2);
     expect(fetchImpl.mock.calls[1][0]).toContain(':5000/api/event');
     expect(socket.sent.some((frame) => frame.type === 'event' && frame.eventId === 'evt-2')).toBe(true);
+    expect(socket.sent.filter((frame) => frame.type === 'ready' && frame.scope === 'global')).toHaveLength(2);
 
     socket.close();
     await runtime.close();

package/server/lib/event-stream/runtime.js

@@ -182,8 +182,7 @@ export function createMessageStreamWsRuntime({
      * `Last-Event-ID` and re-establish the stream against the new port.
      */
     rebindUpstream() {
-      globalHub.stop();
-      globalHub.start();
+      globalHub.rebind();
       for (const socket of Array.from(directorySockets)) {
         try {
           socket.close(1012, 'OpenCode upstream restarted');

package/server/lib/event-stream/upstream-reader.js

@@ -144,7 +144,7 @@ export function createUpstreamSseReader({
               response,
             });
             await cancelResponseBody(response);
-            await waitForReconnectDelay(reconnectDelayMs, signal);
+            await waitForReconnectDelay(resolveTimeoutMs(reconnectDelayMs, DEFAULT_UPSTREAM_RECONNECT_DELAY_MS), signal);
             continue;
           }
 
@@ -219,7 +219,8 @@ export function createUpstreamSseReader({
         }
 
         if (!stopped && !signal?.aborted) {
-          await waitForReconnectDelay(reconnectDelayMs, signal);
+          // A function is read before every wait, so a caller can back off between attempts.
+          await waitForReconnectDelay(resolveTimeoutMs(reconnectDelayMs, DEFAULT_UPSTREAM_RECONNECT_DELAY_MS), signal);
         }
       }
     })().finally(() => {

package/server/lib/git/DOCUMENTATION.md

@@ -43,7 +43,7 @@ The following functions are exported and used by the web server:
 - `applyHunk(directory, filePath, options)`: Apply a single-hunk patch via `git apply`. `options.action` is `stage` (`git apply --cached`), `unstage` (`git apply --cached --reverse`), or `discard` (`git apply --reverse` in the working tree). Inside the index mutation queue, the server verifies that the complete patch exactly matches one current three-context-line hunk for that file and scope, then runs `--check` before applying. Applicability alone cannot prove an unstaged change: old staged or committed hunks can reverse cleanly too. Stale, historical and multi-file patches fail with a refresh error. Temporary patch files are removed on success and failure; hunk content retains CRLF bytes.
 
 ### Branch Operations
-- `getBranchBase(directory, branch)`: Read a named creation source from reflog. After a rebase, the creation source is no longer a current parent record, so return `null` and let the user choose a base. Explicit per-runtime, directory, and branch choices in the shared UI outrank detection.
+- `getBranchBase(directory, branch)`: Read a named creation source from reflog. After a rebase, the creation source is no longer a current parent record, so return `null` and let the user choose a base. A source that is the branch's own remote copy (`git switch feat` records `Created from refs/remotes/origin/feat`) is not a parent either and also returns `null`. Explicit per-runtime, directory, and branch choices in the shared UI outrank detection.
 - `getBranches(directory)`: Get list of local and remote branches (filtered to active remote branches).
 - `getUnpushedBranchCounts(directory, branchNames)`: Count commits ahead of each locally known upstream for up to five supplied local branches. This reads local refs only and omits branches without an upstream.
 - `createBranch(directory, branchName, options)`: Create and checkout a new branch.

package/server/lib/git/service.js

@@ -3097,6 +3097,21 @@ export function parseBranchCreationSource(reflogText) {
   return null;
 }
 
+async function isOwnRemoteCopy(git, source, branchName) {
+  const fullName = await git
+    .raw(['rev-parse', '--symbolic-full-name', source])
+    .then((value) => String(value || '').trim())
+    .catch(() => '');
+  if (!fullName.startsWith('refs/remotes/')) return false;
+  const upstream = await git
+    .raw(['rev-parse', '--symbolic-full-name', `refs/heads/${branchName}@{upstream}`])
+    .then((value) => String(value || '').trim())
+    .catch(() => '');
+  if (upstream && fullName === upstream) return true;
+  // Upstream may be unset; a remote ref with the branch's own name is still its copy.
+  return fullName.slice('refs/remotes/'.length).split('/').slice(1).join('/') === branchName;
+}
+
 /**
  * Resolve the branch the given branch was created from, from its reflog.
  * Returns { base: null } when git has no authoritative record (clone, detached
@@ -3130,6 +3145,13 @@ export async function getBranchBase(directory, branch) {
     return { base: null };
   }
 
+  // `git switch feat` from a remote branch records "Created from
+  // refs/remotes/origin/feat": the branch's own remote copy, not a parent.
+  // Comparing against it hides every pushed commit.
+  if (await isOwnRemoteCopy(git, source, branchName)) {
+    return { base: null };
+  }
+
   return { base: source };
 }
 

package/server/lib/git/service.test.js

@@ -2316,6 +2316,14 @@ describe.runIf(canRunGit())('getRangeDiff', () => {
     }
   });
 
+  it('does not treat a branch checked out from its own remote copy as its base', async () => {
+    const { repository } = createRepositoryWithRemote();
+    runGit(repository, ['checkout', '-b', 'react', '--track', 'origin/react']);
+    expect(await getBranchBase(repository, 'react')).toEqual({ base: null });
+    runGit(repository, ['checkout', '--no-track', '-b', 'loose', 'origin/react']);
+    expect(await getBranchBase(repository, 'loose')).toEqual({ base: 'origin/react' });
+  });
+
   it('asks for a new base after restacking and compares against the selected parent', async () => {
     const { repository } = createRepositoryWithRemote();
     runGit(repository, ['checkout', '-b', 'child', 'origin/react']);

package/server/lib/guests/DOCUMENTATION.md

@@ -7,6 +7,7 @@ OpenChamber-owned install and static serve for iframe guests. This is not the Op
 ## Routes
 
 - `POST /api/guests/:id/storage` accepts the SDK's `GuestStorageRequest` and returns `GuestStorageResult`. It requires an installed, enabled, fully approved guest with either a panel or background entry, but no additional capability. The UI host supplies the frame's own identity. Guest-scoped asset tokens cannot call this route. Data lives beside `extensions.json` in `guest-storage/<id>.json`. Each key is 1 to 128 characters, each JSON value at most 64 KiB UTF-8, the whole namespace at most 2 MiB and 2,000 keys. `storage.js` owns serialized authorization/read/write/removal; writes are atomic and failures preserve prior bytes. `uninstallGuest` removes storage for every install source. Missing keys return `found: false`, including after removal; stored JSON null returns `found: true`.
+- `GET /api/guests` also exposes `statusEntry` and optional `statusTitle` / `statusHeight` for `contributes.statusSection`, the extension's Work Status section. Its HTML and built scripts pass the same install checks, and it may be the package's only frame: the storage route and the asset route's `hasRuntime` accept `entry`, `backgroundEntry`, or `statusEntry`.
 - `GET /api/guests` also exposes `pageEntry` and optional `pageTitle` for `contributes.page`. Full-screen page HTML and its built scripts pass the same install checks as attach HTML. No new serving/auth path is required.
 
 - `GET /api/guests` returns installed guests. `attach` is `"panel"` or `"dialog"` when declared, and `attachEntry` is the dialog's separate HTML. `version` is the package semver. `integration` is the public slice: name, description, `auth`, and settings; OAuth URLs and tokens stay on the server. `service` includes `runtime`, optional `permissions`, optional `socketBindings`, and `granted`. `capabilities` carries `{ requested, granted }`, derived through the SDK's `requestedGuestCapabilities`. `actions`, `commands`, `tools`, and `filesystem` retain their parsed declarations; UI owns menu placement, command collisions, and tool precedence. `entry` is the optional visible panel and `backgroundEntry` is independent on-demand execution HTML. Background-only extensions get no rail surface; tools-only extensions with neither entry mount no frame. A guest without every requested grant is inactive until approval. `enabled: false` pauses it. A failed listing is 500, never an empty list.
@@ -30,13 +31,13 @@ OpenChamber-owned install and static serve for iframe guests. This is not the Op
 - `POST /api/guests/updates/check` — `{ force?: boolean }` → `{ updates: Record<guestId, { version }> }` for every git install whose origin now carries a newer `package.json` `version`. The check runs `git fetch --depth 1 origin <ref|HEAD>` inside the installed clone and reads `FETCH_HEAD:package.json` through the SDK manifest parser; the only signal is semver (`updates.js` `compareSemver`, prerelease below release), no commit hashes. Results sit in a memory cache per store file and guest id for `UPDATE_CHECK_TTL_MS` (one hour); `force` asks the network again. That cache is separate from the catalog cache, so a store write does not drop it. One guest's failed fetch never hides another's update. Folder and zip installs are never checked.
 - `POST /api/guests/:id/update` — replace the installed git copy with a fresh clone of its stored origin. Answers `{ guest }` (the refreshed catalog row) or 400 `{ error }` with `not-git` (folder, zip, or no stored origin), `clone-failed`, `invalid-manifest` (also when the clone declares a different panel id), `missing-build`, `host-too-old` (body may include `required`), or `swap-failed`. Unknown id is 404. Grants, tokens, settings, and the paused flag are keyed by guest id and stay as they were; a version that asks for more capabilities shows up as needs-approval in the catalog and goes through the usual review dialog.
 - `DELETE /api/guests/:id` — drops the store row, any service grant, and socket overrides; stops a running service. Path-install does not delete the user's folder. Zip and git copies under `{openchamberDataDir}/extensions/` are deleted. Unknown id is 404.
-- `GET /api/guests/:id/{*filePath}` serves package-local files. Unknown IDs, escapes, missing files, and unknown types return 404. HTML and JS require either `entry` or `backgroundEntry`, expressed by `resolveGuestServedFile`'s `hasRuntime` option. Tools-only extensions still serve their SVG icons but no executable content. Guest HTML propagates the scoped `oc_url_token` onto relative script/link/image URLs. The token is minted for `guest:<id>` and works only under that guest's asset route, never `/api/fs/raw` or event streams. Every response carries `Content-Security-Policy: sandbox allow-scripts`, including direct document navigation. The host serves built files from disk and never compiles guest sources.
+- `GET /api/guests/:id/{*filePath}` serves package-local files. Unknown IDs, escapes, missing files, and unknown types return 404. HTML and JS require `entry`, `backgroundEntry`, or `statusEntry`, expressed by `resolveGuestServedFile`'s `hasRuntime` option. Tools-only extensions still serve their SVG icons but no executable content. Guest HTML propagates the scoped `oc_url_token` onto relative script/link/image URLs. The token is minted for `guest:<id>` and works only under that guest's asset route, never `/api/fs/raw` or event streams. Every response carries `Content-Security-Policy: sandbox allow-scripts`, including direct document navigation. The host serves built files from disk and never compiles guest sources.
 
 ## Install
 
 `contributes.background.entry` is optional package-local `.html`, separate from `panel.entry`. Install validates its HTML and every referenced built script using the same path confinement as visible panels. `backgroundEntry` is exposed on the catalog independently of `entry`; adding it does not create a rail icon or a visible page. Capabilities, services, integrations, and storage work with either execution entry. The SDK refuses visible contributions without `panel.entry` and all runtime contributions when neither entry exists. See `packages/sdk/DOCUMENTATION.md` for on-demand invocation ownership.
 
-`html-styles.js` appends the SDK's shared scrollbar stylesheet to served HTML, including requests without an asset token. This applies to existing panel, page, and attach bundles in direct and relay mode; the relay loader retains the inline style in `srcDoc`. Appending preserves the doctype and avoids rewriting tag-like text inside scripts or comments. Authored CSP stays intact and can block inline styling. Package files on disk and non-HTML responses are unchanged. Scrollbar colors follow the SDK theme variables inside the frame.
+`html-styles.js` appends the SDK's shared scrollbar stylesheet and its small inline activity script (`GUEST_SCROLLBAR_SCRIPT`: shows a scrollbar while its element scrolls) to served HTML, including requests without an asset token. An authored CSP that blocks inline scripts leaves hover-only scrollbars. This applies to existing panel, page, and attach bundles in direct and relay mode; the relay loader retains the inline style in `srcDoc`. Appending preserves the doctype and avoids rewriting tag-like text inside scripts or comments. Authored CSP stays intact and can block inline styling. Package files on disk and non-HTML responses are unchanged. Scrollbar colors follow the SDK theme variables inside the frame.
 
 Built-ins ship with the app; user extensions are installed separately. Add a folder, local ZIP, HTTPS Git/ZIP URL, or SSH Git address from Settings → Extensions. The ZIP picker and drop zone upload the archive on web and remote desktop instances. A guest with a page must ship built classic-IIFE JavaScript, for example from `bunx openchamber-guest-bundle panel/main.ts panel/main.js`; the sandbox does not support ESM imports. `package.json` needs a semver version. A missing panel SVG or invalid manifest fails installation; page-less tools-only packages skip HTML/script checks. Optional `engines.openchamber` is checked against this host. Provider accounts are connected separately in Settings → Integrations.
 
@@ -63,7 +64,7 @@ A missing folder is omitted from the list. Other guests stay. A corrupt `extensi
 - `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.
+- `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. Viewer ids are random UUIDs. Every input batch reaches the service with `x-surface-viewer` and `x-surface-frame-seq`: the service's own sequence number (kept apart from the host's bumped `seq`) of the frame that viewer last acknowledged, read when the batch arrives, not when the queue reaches it. A 409 answer becomes an `INPUT_STALE` error to that viewer. Control notices carry `viewer` for a user controller. `viewerHeaders(guestId, viewerId)` gives `/api/guests/:id/service/request` the same viewer, control, and frame headers when the panel names a live viewer of that extension (`viewerId` in the body, from `surface-viewers.ts` in the UI); an unknown id adds nothing. `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.

package/server/lib/guests/catalog.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
-import { hasGuestPage, requestedGuestCapabilities, resolveAttachEntry, resolveAttachMode, resolvePageEntry, toPublicService, toPublicIntegration, hostMeetsOpenChamberEngine, openChamberEngineMinimum } from '@openchamber/sdk';
+import { hasGuestPage, requestedGuestCapabilities, resolveAttachEntry, resolveAttachMode, resolvePageEntry, resolveStatusSectionEntry, toPublicService, toPublicIntegration, hostMeetsOpenChamberEngine, openChamberEngineMinimum } from '@openchamber/sdk';
 import { parseManifestJson } from '@openchamber/sdk/schemas';
 
 import { listRelativeGuestScriptHrefs, resolveGuestHtmlRelativePath } from './html-tokens.js';
@@ -247,6 +247,21 @@ export const inspectGuestPackage = async (packageRoot, { openchamberVersion, ski
     const page = parsed.manifest.contributes.page;
     if (page !== true && page?.title) guest.pageTitle = page.title;
   }
+  // The Work Status section is checked like any other entry, and may be the
+  // package's only frame.
+  const statusEntry = resolveStatusSectionEntry(parsed.manifest.contributes);
+  if (statusEntry) {
+    if (!await resolveGuestAssetPath(packageRoot, statusEntry)) {
+      return { ok: false, code: 'invalid-manifest' };
+    }
+    if (!await guestBuiltScriptsReady(packageRoot, statusEntry)) {
+      return { ok: false, code: 'missing-build' };
+    }
+    guest.statusEntry = statusEntry;
+    const section = parsed.manifest.contributes.statusSection;
+    if (section !== true && section?.title) guest.statusTitle = section.title;
+    if (section !== true && section?.height !== undefined) guest.statusHeight = section.height;
+  }
   if (parsed.manifest.contributes.capabilities?.length) {
     guest.capabilities = [...parsed.manifest.contributes.capabilities];
   }
@@ -324,6 +339,9 @@ export const toPublicGuest = (guest) => {
   const attach = resolveAttachMode(guest.attach);
   if (guest.pageEntry) row.pageEntry = guest.pageEntry;
   if (guest.pageTitle) row.pageTitle = guest.pageTitle;
+  if (guest.statusEntry) row.statusEntry = guest.statusEntry;
+  if (guest.statusTitle) row.statusTitle = guest.statusTitle;
+  if (Number.isInteger(guest.statusHeight)) row.statusHeight = guest.statusHeight;
   if (attach) {
     row.attach = attach;
   }

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

@@ -257,6 +257,28 @@ describe('page-less packages', () => {
       expect(toPublicGuest(inspected.guest)).toMatchObject({ pageEntry: 'panel/page.html', pageTitle: 'Tasks' });
     } finally { await fs.rm(dir, { recursive: true, force: true }); }
   });
+  test('a status-section-only package validates its HTML and scripts and publishes title and height without a panel entry', async () => {
+    const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-status-'));
+    try {
+      await fs.writeFile(path.join(dir, 'package.json'), JSON.stringify({ version: '1.0.0', openchamber: {
+        apiVersion: 1, contributes: {
+          panel: { id: 'git-graph', name: 'Git graph', icon: 'git-commit' },
+          statusSection: { entry: 'status/index.html', title: 'Recent commits', height: 160 },
+        },
+      } }));
+      expect(await inspectGuestPackage(dir)).toMatchObject({ ok: false, code: 'invalid-manifest' });
+      await fs.mkdir(path.join(dir, 'status'));
+      await fs.writeFile(path.join(dir, 'status/index.html'), '<script src="main.js"></script>');
+      expect(await inspectGuestPackage(dir)).toMatchObject({ ok: false, code: 'missing-build' });
+      await fs.writeFile(path.join(dir, 'status/main.js'), 'console.log("status")');
+      const inspected = await inspectGuestPackage(dir);
+      expect(inspected.ok).toBe(true);
+      const row = toPublicGuest(inspected.guest);
+      expect(row).toMatchObject({ statusEntry: 'status/index.html', statusTitle: 'Recent commits', statusHeight: 160 });
+      expect(row).not.toHaveProperty('entry');
+    } finally { await fs.rm(dir, { recursive: true, force: true }); }
+  });
+
   test('installs a tools-only package without entry, omits entry from the row, and never serves it a frame', async () => {
     const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'oc-guest-'));
     const guestRoot = path.join(dir, 'tools-only');

package/server/lib/guests/html-styles.js

@@ -1,6 +1,8 @@
-import { GUEST_SCROLLBAR_CSS } from '@openchamber/sdk';
+import { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from '@openchamber/sdk';
 
 /** Append instead of matching tags inside untrusted comments, scripts, or templates.
- * Browsers accept the style after the document; its doctype and authored CSP stay intact.
+ * Browsers accept the style and script after the document; its doctype and authored CSP stay intact.
+ * The script only marks scrolling elements so their scrollbars show while scrolling; an authored
+ * CSP that blocks inline scripts leaves the hover-only behavior of the stylesheet.
  */
-export const injectGuestDocumentStyles = (html) => `${html}\n<style data-openchamber-guest-styles>${GUEST_SCROLLBAR_CSS}</style>`;
+export const injectGuestDocumentStyles = (html) => `${html}\n<style data-openchamber-guest-styles>${GUEST_SCROLLBAR_CSS}</style>\n<script data-openchamber-guest-scrollbar>${GUEST_SCROLLBAR_SCRIPT}</script>`;

package/server/lib/guests/html-styles.test.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import path from 'node:path';
 import express from 'express';
 import request from 'supertest';
-import { GUEST_SCROLLBAR_CSS } from '@openchamber/sdk';
+import { GUEST_SCROLLBAR_CSS, GUEST_SCROLLBAR_SCRIPT } from '@openchamber/sdk';
 import { injectGuestDocumentStyles } from './html-styles.js';
 import { registerGuestRoutes } from './routes.js';
 import { writeExtensionStore } from './persist.js';
@@ -19,6 +19,7 @@ describe('guest document styles', () => {
     expect(decorated.startsWith(html)).toBe(true);
     expect(decorated).toContain(GUEST_SCROLLBAR_CSS);
     expect(decorated).toContain('data-openchamber-guest-styles');
+    expect(decorated).toContain(`<script data-openchamber-guest-scrollbar>${GUEST_SCROLLBAR_SCRIPT}</script>`);
   });
 
   test('serves scrollbar defaults to existing guests with or without an asset token', async () => {
@@ -36,6 +37,7 @@ describe('guest document styles', () => {
       expect(response.headers['content-security-policy']).toBe('sandbox allow-scripts');
       expect(response.headers['cache-control']).toBe('no-store');
       expect(response.text).toContain(GUEST_SCROLLBAR_CSS);
+      expect(response.text).toContain(GUEST_SCROLLBAR_SCRIPT);
       expect(response.text.startsWith('<!doctype html>')).toBe(true);
       expect(response.text).toContain(suffix ? 'main.js?oc_url_token=fixture-scope' : 'src="main.js"');
     }

package/server/lib/guests/routes.js

@@ -88,6 +88,12 @@ const requestBodySchema = z.object({
   body: z.string().max(64_000).optional(),
 });
 
+const serviceRequestBodySchema = requestBodySchema.extend({
+  // The shared-surface viewer open in the same window, if any. The host
+  // resolves it; an id that is not a live viewer of this extension is ignored.
+  viewerId: z.string().min(1).max(128).optional(),
+});
+
 const fileBodySchema = z.object({
   op: z.enum(['read', 'write', 'list', 'stat']),
   path: z.string().min(1).max(GUEST_FILE_PATH_MAX),
@@ -196,6 +202,7 @@ export const registerGuestRoutes = (app, {
   resolveOptionalProjectDirectory,
   getSmallModelService,
   onGuestDeactivated = async () => false,
+  surfaceViewerHeaders = () => null,
 }) => {
   const persistPath = extensionsPersistPath(openchamberDataDir);
   const authPath = guestAuthPersistPath(openchamberDataDir);
@@ -547,7 +554,7 @@ export const registerGuestRoutes = (app, {
       if (!guest?.service) {
         return res.status(404).json({ error: 'not-found' });
       }
-      const parsed = requestBodySchema.safeParse(req.body);
+      const parsed = serviceRequestBodySchema.safeParse(req.body);
       if (!parsed.success) {
         return res.status(400).json({ error: 'invalid-request' });
       }
@@ -562,6 +569,7 @@ export const registerGuestRoutes = (app, {
         path: parsed.data.path,
         query: parsed.data.query,
         body: parsed.data.body,
+        headers: parsed.data.viewerId ? surfaceViewerHeaders(guest.id, parsed.data.viewerId) ?? undefined : undefined,
       });
       res.json(result);
     } catch (error) {
@@ -580,7 +588,7 @@ export const registerGuestRoutes = (app, {
     try {
       const result = await runGuestStorage(persistPath, req.params.id, parsed.data, async () => {
         const guest = await loadGuest(req.params.id);
-        if (!guest || guest.enabled === false || (!guest.entry && !guest.backgroundEntry)) throw new Error('Extension is unavailable.');
+        if (!guest || guest.enabled === false || (!guest.entry && !guest.backgroundEntry && !guest.statusEntry)) throw new Error('Extension is unavailable.');
         if (!requestedGuestCapabilities(guest).every((capability) => guest.capabilityGrants.includes(capability))) throw new Error('Extension needs approval.');
       });
       return res.json(result);
@@ -814,7 +822,7 @@ export const registerGuestRoutes = (app, {
         return res.status(404).end();
       }
       const served = await resolveGuestServedFile(guest.packageRoot, relativePath, {
-        hasRuntime: Boolean(guest.entry || guest.backgroundEntry),
+        hasRuntime: Boolean(guest.entry || guest.backgroundEntry || guest.statusEntry),
       });
       if (!served) {
         return res.status(404).end();

package/server/lib/guests/service.js

@@ -552,6 +552,7 @@ const ensureGuestService = async (params) => {
  *   query?: Record<string, string>,
  *   body?: string,
  *   accept?: string,
+ *   headers?: Record<string, string>,
  *   timeoutMs?: number,
  *   idleStopMs?: number,
  *   signal?: AbortSignal,
@@ -572,6 +573,7 @@ export const openGuestServiceRequest = async ({
   query,
   body,
   accept = 'application/json',
+  headers: extraHeaders,
   timeoutMs = GUEST_REQUEST_TIMEOUT_MS,
   idleStopMs,
   signal,
@@ -645,6 +647,9 @@ export const openGuestServiceRequest = async ({
 
   /** @type {Record<string, string>} */
   const headers = {
+    // Host-set context (surface viewer headers) first: nothing in it can
+    // replace the bearer or the content type below.
+    ...extraHeaders,
     Accept: accept,
     [OPENCHAMBER_SERVICE_AUTH_HEADER]: `Bearer ${runtime.token}`,
   };

package/server/lib/guests/surface.js

@@ -20,6 +20,8 @@
  * holding it releases it.
  */
 
+import { randomUUID } from 'node:crypto';
+
 import { WebSocketServer } from 'ws';
 
 import {
@@ -30,6 +32,7 @@ import {
   SURFACE_FRAME_MAX_BYTES,
   SURFACE_FRAME_MIMES,
   SURFACE_FRAME_PATH,
+  SURFACE_FRAME_SEQ_HEADER,
   SURFACE_FRAME_WAIT_MS,
   SURFACE_HEIGHT_HEADER,
   SURFACE_INPUT_PATH,
@@ -37,6 +40,8 @@ import {
   SURFACE_SEQ_HEADER,
   SURFACE_TITLE_HEADER,
   SURFACE_TITLE_MAX,
+  SURFACE_VIEWER_CONTROLS_HEADER,
+  SURFACE_VIEWER_HEADER,
   SURFACE_WIDTH_HEADER,
   isGuestApproved,
   requestedGuestCapabilities,
@@ -97,7 +102,9 @@ export const createGuestSurfaceRuntime = ({
   idleStopMs,
   openServiceRequest = openGuestServiceRequest,
   holdService = holdGuestService,
-  createViewerId = () => `viewer-${Math.random().toString(36).slice(2, 10)}`,
+  // Unguessable: a page call that names a viewer is told whether that viewer
+  // holds control, so the id works as the viewer's lease.
+  createViewerId = () => `viewer-${randomUUID()}`,
   setTimer = setTimeout,
   clearTimer = clearTimeout,
 }) => {
@@ -109,13 +116,15 @@ export const createGuestSurfaceRuntime = ({
    *   id: string,
    *   ws: import('ws').WebSocket,
    *   sentSeq: number,
+   *   sentServiceSeq: number,
+   *   shownServiceSeq: number,
    *   awaitingAck: boolean,
    * }} Viewer
    * @typedef {{
    *   guestId: string,
    *   guest: object,
    *   viewers: Map<string, Viewer>,
-   *   latest: { seq: number, width: number, height: number, mime: string, title?: string, agentActive: boolean, bytes: Buffer } | null,
+   *   latest: { seq: number, serviceSeq: number, width: number, height: number, mime: string, title?: string, agentActive: boolean, bytes: Buffer } | null,
    *   controller: 'none' | 'agent' | string,
    *   agentTimer: ReturnType<typeof setTimeout> | null,
    *   pumpAbort: AbortController | null,
@@ -164,13 +173,13 @@ export const createGuestSurfaceRuntime = ({
     return run;
   };
 
-  const notifyService = async (session, controller) => {
+  const notifyService = async (session, controller, viewerId) => {
     if (session.ended) return;
     try {
       const { response, finished } = await serviceRequest(session, {
         method: 'POST',
         path: SURFACE_CONTROL_PATH,
-        body: JSON.stringify({ controller }),
+        body: JSON.stringify(controller === 'user' && viewerId ? { controller, viewer: viewerId } : { controller }),
         timeoutMs: QUICK_REQUEST_TIMEOUT_MS,
       });
       await response.arrayBuffer().catch(() => undefined);
@@ -186,7 +195,8 @@ export const createGuestSurfaceRuntime = ({
     for (const viewer of session.viewers.values()) {
       send(viewer, { type: 'control', controller: kind, mine: session.controller === viewer.id });
     }
-    void enqueue(session, () => notifyService(session, kind));
+    const holder = kind === 'user' ? session.controller : undefined;
+    void enqueue(session, () => notifyService(session, kind, holder));
   };
 
   const clearAgentTimer = (session) => {
@@ -208,6 +218,7 @@ export const createGuestSurfaceRuntime = ({
     if (!frame || viewer.awaitingAck || viewer.sentSeq >= frame.seq || viewer.ws.readyState !== 1) return;
     viewer.awaitingAck = true;
     viewer.sentSeq = frame.seq;
+    viewer.sentServiceSeq = frame.serviceSeq;
     const meta = {
       type: 'frame',
       seq: frame.seq,
@@ -260,6 +271,9 @@ export const createGuestSurfaceRuntime = ({
     const title = (response.headers.get(SURFACE_TITLE_HEADER) || '').slice(0, SURFACE_TITLE_MAX);
     const frame = {
       seq,
+      // The service's own number, kept when `seq` is bumped below: input is
+      // stamped with it, and only the service knows which view it belongs to.
+      serviceSeq: seq,
       width,
       height,
       mime,
@@ -357,7 +371,7 @@ export const createGuestSurfaceRuntime = ({
    * control back: the user already let go, and re-taking it from a queued
    * click would lock the agent out with nobody to press the button.
    */
-  const handleInput = async (session, viewer, events, handoff) => {
+  const handleInput = async (session, viewer, events, handoff, frameSeq) => {
     if (viewer.gone) return;
     if (session.controller !== viewer.id) {
       if (session.controller !== 'none' && session.controller !== 'agent') {
@@ -373,10 +387,20 @@ export const createGuestSurfaceRuntime = ({
         method: 'POST',
         path: SURFACE_INPUT_PATH,
         body: JSON.stringify({ events }),
+        headers: {
+          [SURFACE_VIEWER_HEADER]: viewer.id,
+          [SURFACE_FRAME_SEQ_HEADER]: String(frameSeq),
+        },
         timeoutMs: QUICK_REQUEST_TIMEOUT_MS,
       });
       await response.arrayBuffer().catch(() => undefined);
       finished();
+      // 409: made on a picture the service no longer shows. Nothing reached
+      // the page, and the next frame shows the viewer what is there now.
+      if (response.status === 409) {
+        send(viewer, { type: 'error', code: 'INPUT_STALE', message: 'The picture changed before this input arrived; it was not applied.' });
+        return;
+      }
       if (response.status < 200 || response.status >= 300) {
         send(viewer, { type: 'error', code: 'INPUT_REJECTED', message: `The extension refused this input (HTTP ${response.status}).` });
       }
@@ -445,7 +469,8 @@ export const createGuestSurfaceRuntime = ({
   const handleViewerMessage = (session, viewer, raw) => {
     let parsed;
     try {
-      parsed = surfaceViewerMessageSchema.safeParse(JSON.parse(String(raw)));
+      // Node's `ws` delivers a Buffer, Bun's a Uint8Array; both decode here.
+      parsed = surfaceViewerMessageSchema.safeParse(JSON.parse(Buffer.from(raw).toString('utf8')));
     } catch {
       parsed = { success: false };
     }
@@ -458,12 +483,17 @@ export const createGuestSurfaceRuntime = ({
       case 'ack':
         if (message.seq === viewer.sentSeq) {
           viewer.awaitingAck = false;
+          // Acknowledged after drawing: this is the picture its next input is made on.
+          viewer.shownServiceSeq = viewer.sentServiceSeq;
           deliverLatest(session, viewer);
         }
         return;
       case 'input': {
         const handoff = session.handoffs;
-        void enqueue(session, () => handleInput(session, viewer, message.events, handoff));
+        // Read on arrival, not when the queue reaches the batch: the socket
+        // delivers acks and input in the order the viewer drew and acted.
+        const frameSeq = viewer.shownServiceSeq;
+        void enqueue(session, () => handleInput(session, viewer, message.events, handoff, frameSeq));
         return;
       }
       case 'release':
@@ -485,7 +515,7 @@ export const createGuestSurfaceRuntime = ({
 
   const attachViewer = (guestId, guest, ws) => {
     const session = ensureSession(guestId, guest);
-    const viewer = { id: createViewerId(), ws, sentSeq: 0, awaitingAck: false, gone: false };
+    const viewer = { id: createViewerId(), ws, sentSeq: 0, sentServiceSeq: 0, shownServiceSeq: 0, awaitingAck: false, gone: false };
     session.viewers.set(viewer.id, viewer);
     // Started with the first viewer in place: the pump's loop condition is
     // the viewer count, and it is checked before the first await.
@@ -609,6 +639,22 @@ export const createGuestSurfaceRuntime = ({
       if (session) endSession(session, 'extension-unavailable');
     },
 
+    /**
+     * Headers for a page `serviceRequest` made from the window that holds
+     * `viewerId`, or null when that id is not a live viewer of this
+     * extension (then the request goes out without any).
+     */
+    viewerHeaders(guestId, viewerId) {
+      const session = sessions.get(guestId);
+      const viewer = session && !session.ended ? session.viewers.get(viewerId) : undefined;
+      if (!viewer || viewer.gone) return null;
+      return {
+        [SURFACE_VIEWER_HEADER]: viewer.id,
+        [SURFACE_VIEWER_CONTROLS_HEADER]: session.controller === viewer.id ? '1' : '0',
+        [SURFACE_FRAME_SEQ_HEADER]: String(viewer.shownServiceSeq),
+      };
+    },
+
     /** Test seam. */
     sessionOf(guestId) {
       return sessions.get(guestId) ?? null;