sliccy 4.28.2 → 4.29.0

package/README.md

@@ -28,6 +28,20 @@ SLICC runs in a browser and controls the browser it runs in. It combines a shell
 
 > Status: active working prototype. The macOS app is the easiest way in today; and we have submitted the extension to Chrome Web Store.
 
+## Breaking release — thin extension + hosted webapp
+
+This release splits the webapp out of the extension. The Chrome extension is now a thin **CDP pass-through bridge + per-page launcher**; the webapp UI and the agent engine load from the hosted leader tab (`https://www.sliccy.ai/?slicc=leader`, or `http://localhost:5710/?slicc=leader` for the `SLICC_EXT_DEV=1` dev build).
+
+What changed:
+
+- **Origin split.** The UI is served from `sliccy.ai` (or the local wrangler on `:8787`); the local CLI bridge runs on `:5710`. Page-side fetches to `/api/*` route to the bridge over CORS with an `X-Bridge-Token` header, never to the UI origin.
+- **No more bundled side-panel UI or offscreen agent engine.** The extension does not ship `index.html` / `offscreen.html` / `sidepanel.html` anymore, and dropped the `sidePanel` and `offscreen` manifest permissions. The agent runs in the hosted leader tab.
+- **One pinned hosted leader tab per Chrome profile.** The service worker creates and re-creates it; clicking the toolbar icon focuses it.
+- **Per-page launcher overlay.** A content script injects `<slicc-launcher>` into every page; clicking it opens an iframe that auto-follows the leader.
+- **Electron overlay is gone.** The standalone Electron flow now uses the same thin bridge model — the launched Electron app runs as a CDP target attached to a hosted leader.
+
+If you previously loaded the extension from `dist/extension/` and used the side panel, you need to re-load the new build and use the pinned leader tab. State stored in the old extension origin (`chrome-extension://<id>/...`) does not migrate.
+
 ## Why SLICC is different
 
 - **Browser-native, not browser-adjacent.** The agent runtime lives in the browser, and the agent can act on the same browser it lives in. A great mix of power and containment. If you don't like what the AI does, close the browser tab and it's over.
@@ -35,7 +49,7 @@ SLICC runs in a browser and controls the browser it runs in. It combines a shell
 - **UI on the fly.** SLICC can generate rich user interfaces on the fly. These can be small visualizations in a chat response, or full-blown web applications that run in a sidebar, or even a separate tab.
 - **Built around Skills.** Agents don't suffer from missing capabilities, they suffer from skill issues. SLICC can install native skills into `/workspace/skills`, and it also discovers compatible `.agents` / `.claude` skills read-only across the reachable VFS.
 - **More than a coding panel.** Coding is one strong use case, but SLICC is built for practical browser work too: authenticated web apps, repetitive tab work, content operations, debugging, research, and automation.
-- **Works across runtimes.** Start in the CLI, run as a Chrome extension, connect multiple tray sessions, or attach to Electron apps with the same core model.
+- **Works across runtimes.** Start in the CLI, run the thin Chrome extension that loads SLICC from `sliccy.ai`, connect multiple tray sessions, or attach to Electron apps with the same core model.
 - **Delegates in parallel.** The main agent can spin up isolated sub-agents for task-specific work instead of stuffing everything into one conversation.
 
 ## Who it is for
@@ -96,27 +110,14 @@ npm start
 
 ### 4. Chrome extension
 
-The extension runs the same core experience as a Chrome side panel with no separate server process.
+The extension is a **thin CDP bridge + per-page launcher** — no bundled UI, no offscreen agent engine. The full SLICC webapp loads from the hosted leader tab (`https://www.sliccy.ai/?slicc=leader`); the extension just pins that tab, proxies `chrome.debugger` to it, and injects a small `<slicc-launcher>` overlay into every page.
 
 ```bash
 npm install
 npm run build:extension
 ```
 
-Load `dist/extension/` as an unpacked extension in `chrome://extensions`, then open the SLICC side panel.
-
-**Pop out to a full-page tab.** In the Chrome extension, the side panel
-header has a "Pop out" button that opens SLICC in a full-page tab with
-the standalone split-pane layout. Close the tab to return to the side
-panel. State (chat history, scoops, VFS) is shared.
-
-While a detached tab is open, the side panel is disabled globally
-(across all Chrome windows) — clicking the toolbar icon focuses the
-detached tab. This is intentional; close the tab to restore the side
-panel. The optional best-effort SW hard-close of any open side panels
-uses `chrome.sidePanel.close` (Chrome 141+). Older Chrome versions
-still get full mutual exclusion via `window.close()` from the panel,
-the send-path lock, and the non-dismissible overlay.
+Load `dist/extension/` as an unpacked extension in `chrome://extensions`. The service worker pins the hosted leader tab on install; clicking the toolbar icon focuses it (or recreates it if the user closed it). Each page you visit gets the launcher overlay, which iframes the same hosted webapp as an auto-follow follower.
 
 ### 5. Run a second browser
 

package/dist/node-server/bridge-security.d.ts

@@ -77,6 +77,32 @@ export declare function validateBridgeToken(presented: string | string[] | undef
  * — 122 bits of entropy is plenty for a session-scoped capability.
  */
 export declare function mintBridgeToken(): string;
+/**
+ * Resolve the `/cdp` upgrade-gate token for this server process.
+ *
+ * Honors an inbound `SLICC_BRIDGE_TOKEN` env var (forwarded by
+ * `electron-main.ts` to the `--serve-only`/`--electron` child) so the
+ * gate is enforced even when `thinBridgeMode` is false. Falls back to
+ * minting a fresh token in `thinBridgeMode`, and to `null` (gate off)
+ * in the remaining legacy modes.
+ */
+export declare function resolveServerBridgeToken(env: Record<string, string | undefined>, opts: {
+    thinBridgeMode: boolean;
+}): string | null;
+/**
+ * Decide whether the thin-bridge CORS + PNA middleware should be mounted on
+ * the `/api` surface.
+ *
+ * Mounted in canonical thin-bridge mode, and additionally whenever a
+ * per-process bridge token is present even with `thinBridgeMode` false (e.g.
+ * `--electron` with a forwarded `SLICC_BRIDGE_TOKEN`): the Electron overlay
+ * loads cross-origin from the hosted leader, so its `/api/runtime-config`
+ * fetch needs `access-control-*` headers. Mirrors the `/cdp` gate, which
+ * already honors a present token regardless of mode. Legacy dev /
+ * serve-only-without-token keep `bridgeToken === null` ⇒ CORS stays off ⇒
+ * same-origin behavior preserved.
+ */
+export declare function shouldMountThinBridgeCors(thinBridgeMode: boolean, bridgeToken: string | null): boolean;
 /**
  * Parse the `Sec-WebSocket-Protocol` request header into a trimmed list. The
  * header is a comma-separated list per RFC 6455; `ws` exposes it raw.

package/dist/node-server/bridge-security.js

@@ -123,8 +123,16 @@ const CORS_BASE_ALLOW_HEADERS = [
  * bridge (`decodeForbiddenResponseHeaders` reads `X-Proxy-Set-Cookie`).
  */
 const CORS_EXPOSE_HEADERS = 'Link, X-Proxy-Error, X-Proxy-Set-Cookie';
-/** Methods exposed to the hosted leader. */
-const CORS_ALLOW_METHODS = 'GET, POST, PUT, DELETE, OPTIONS';
+/**
+ * Methods exposed to the hosted leader. Must cover the FULL `/api/fetch-proxy`
+ * verb set — `app.all('/api/fetch-proxy')` forwards any method, so the agent's
+ * `curl -X PROPFIND|REPORT|MKCALENDAR|PATCH …` reaches it cross-origin from
+ * sliccy.ai only if the browser's preflight sees the actual method advertised
+ * here. Standard CRUD verbs + WebDAV (RFC 4918) + CalDAV (RFC 4791). MUST stay
+ * byte-identical to Swift's `BridgeSecurity.corsAllowMethods` and to the Swift
+ * server's `fetchProxyMethods` list (`APIRoutes.swift`).
+ */
+const CORS_ALLOW_METHODS = 'GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, PROPFIND, PROPPATCH, MKCOL, MKCALENDAR, REPORT, COPY, MOVE, LOCK, UNLOCK';
 /**
  * True iff `origin` is in the bridge allowlist. The frozen prod base
  * (`BRIDGE_ALLOWED_ORIGINS`) is matched case-sensitively against the
@@ -195,6 +203,37 @@ export function validateBridgeToken(presented, expected) {
 export function mintBridgeToken() {
     return randomUUID();
 }
+/**
+ * Resolve the `/cdp` upgrade-gate token for this server process.
+ *
+ * Honors an inbound `SLICC_BRIDGE_TOKEN` env var (forwarded by
+ * `electron-main.ts` to the `--serve-only`/`--electron` child) so the
+ * gate is enforced even when `thinBridgeMode` is false. Falls back to
+ * minting a fresh token in `thinBridgeMode`, and to `null` (gate off)
+ * in the remaining legacy modes.
+ */
+export function resolveServerBridgeToken(env, opts) {
+    const fromEnv = env['SLICC_BRIDGE_TOKEN'];
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    return opts.thinBridgeMode ? mintBridgeToken() : null;
+}
+/**
+ * Decide whether the thin-bridge CORS + PNA middleware should be mounted on
+ * the `/api` surface.
+ *
+ * Mounted in canonical thin-bridge mode, and additionally whenever a
+ * per-process bridge token is present even with `thinBridgeMode` false (e.g.
+ * `--electron` with a forwarded `SLICC_BRIDGE_TOKEN`): the Electron overlay
+ * loads cross-origin from the hosted leader, so its `/api/runtime-config`
+ * fetch needs `access-control-*` headers. Mirrors the `/cdp` gate, which
+ * already honors a present token regardless of mode. Legacy dev /
+ * serve-only-without-token keep `bridgeToken === null` ⇒ CORS stays off ⇒
+ * same-origin behavior preserved.
+ */
+export function shouldMountThinBridgeCors(thinBridgeMode, bridgeToken) {
+    return thinBridgeMode || bridgeToken !== null;
+}
 /**
  * Parse the `Sec-WebSocket-Protocol` request header into a trimmed list. The
  * header is a comma-separated list per RFC 6455; `ws` exposes it raw.

package/dist/node-server/chrome-launch.d.ts

@@ -26,7 +26,7 @@ interface FindChromeExecutableOptions {
 export declare function isCliProfileName(value: string | null | undefined): value is CliProfileName;
 export declare function resolveQaProfilesRoot(projectRoot: string): string;
 export declare function resolveProfilesDir(platform?: NodeJS.Platform, homeDir?: string, env?: NodeJS.ProcessEnv): string;
-export declare function resolveDefaultChromeUserDataDir(profilesDir?: string, servePort?: number): string;
+export declare function resolveDefaultChromeUserDataDir(profilesDir?: string, servePort?: number, env?: NodeJS.ProcessEnv): string;
 /**
  * Builds the ordered list of legacy candidate paths to check during migration.
  * Checks $TMPDIR first (the macOS per-user temp dir used by terminal sessions),
@@ -137,6 +137,67 @@ export declare function waitForCdpPortFromStderr(child: ChildProcess, timeoutMs?
  * avoid but is not worth crashing over.
  */
 export declare function clearStaleDevToolsActivePort(userDataDir: string): Promise<void>;
+/**
+ * Clear Chrome's "did not exit cleanly" flags so the next launch does NOT
+ * restore the previous session's tabs (or pop the crash-restore bubble).
+ *
+ * `npm run dev` is almost always stopped with Ctrl-C, which terminates the
+ * launched Chrome without a graceful shutdown. Chrome then records
+ * `profile.exit_type: "Crashed"` in `Default/Preferences` and, on the next
+ * launch against the same persistent profile, reopens the prior session's
+ * tabs. With the standalone single-client CDP proxy that is actively
+ * harmful: a *restored* duplicate webapp tab and the freshly-launched tab
+ * both dial `ws://<host>/cdp`, and because the proxy keeps only one client
+ * they evict each other in an endless ~5s reconnect war (each evicted page
+ * re-dials on the next leader-target refresh).
+ *
+ * Rewriting `exit_type` to `"Normal"` (and `exited_cleanly` to `true`) — the
+ * same trick ChromeDriver uses — before spawn makes Chrome believe the last
+ * session ended cleanly, so it starts fresh with a single tab.
+ *
+ * Best-effort and idempotent: a missing Preferences file (first run) is left
+ * absent — there is nothing to restore — and an unparseable one is left as-is
+ * for Chrome to regenerate. Never throws; a failure here must not block a
+ * launch.
+ */
+export declare function clearChromeRestoreState(userDataDir: string): Promise<void>;
+/**
+ * Remove Chrome's session-restore snapshot so a relaunch opens ONLY the
+ * command-line tab instead of also reopening the previous window's tabs.
+ *
+ * The dev launcher passes the UI URL on the command line, but Chrome ALSO
+ * restores `Default/Sessions/` from the prior run — so every `npm run dev` was
+ * adding a tab. `exit_type` only governs the *crash* bubble, not this; the fix
+ * is to drop the snapshot. Run before every spawn (like
+ * {@link clearStaleDevToolsActivePort}). Cookies / localStorage / IndexedDB
+ * live elsewhere and are untouched. Best-effort.
+ *
+ * Modern Chrome keeps the whole snapshot under `Default/Sessions/`; `Last
+ * Session` / `Last Tabs` are belt-and-suspenders for older Chromium builds that
+ * still wrote those two as top-level files under `Default/`.
+ */
+export declare function clearChromeSessionRestore(userDataDir: string): Promise<void>;
+/** Injectable seams for {@link terminateExistingProfileChrome} (tests). */
+export interface ProfileChromeTerminationDeps {
+    readlinkImpl?: (path: string) => Promise<string>;
+    isAlive?: (pid: number) => boolean;
+    kill?: (pid: number, signal: NodeJS.Signals) => void;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Terminate a Chrome instance still holding this `user-data-dir`, then clear
+ * the stale Singleton lock files, so a fresh launch isn't refused.
+ *
+ * Chrome is single-instance per profile: a second `open -n` against a locked
+ * profile either exits non-zero ("Chrome exited … before reporting CDP port")
+ * or silently adds a tab to the running instance. On macOS the launcher starts
+ * Chrome via LaunchServices, so it isn't our child and Ctrl-C never reaps it —
+ * a leftover Chrome lingers across `npm run dev` runs. Chrome records the
+ * owning PID in the `SingletonLock` symlink (`<host>-<pid>`); if that process
+ * is alive we stop it (SIGTERM, then SIGKILL), then unlink the Singleton lock
+ * files. Best-effort and idempotent; a missing lock is a no-op.
+ */
+export declare function terminateExistingProfileChrome(userDataDir: string, deps?: ProfileChromeTerminationDeps): Promise<void>;
 export interface ProbeCdpAliveOptions {
     /** Per-probe HTTP timeout in milliseconds. Default 500 ms. */
     timeoutMs?: number;

package/dist/node-server/chrome-launch.js

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync } from 'fs';
-import { cp, mkdir, readFile, rm, unlink, writeFile } from 'fs/promises';
+import { cp, mkdir, readFile, readlink, rm, unlink, writeFile } from 'fs/promises';
 import { request as httpRequest } from 'http';
 import { homedir, platform as osPlatform, tmpdir } from 'os';
 import { dirname, join } from 'path';
@@ -85,7 +85,12 @@ export function resolveProfilesDir(platform = osPlatform(), homeDir = homedir(),
     }
     return tmpdir();
 }
-export function resolveDefaultChromeUserDataDir(profilesDir = resolveProfilesDir(), servePort) {
+export function resolveDefaultChromeUserDataDir(profilesDir = resolveProfilesDir(), servePort, env = process.env) {
+    // Explicit override — e.g. SLICC_USER_DATA_DIR=$(mktemp -d) for a
+    // guaranteed-fresh profile without touching production data.
+    const explicit = env.SLICC_USER_DATA_DIR?.trim();
+    if (explicit)
+        return explicit;
     const suffix = servePort && servePort !== 5710 ? `-${servePort}` : '';
     return join(profilesDir, `${DEFAULT_USER_DATA_DIR_NAME}${suffix}`);
 }
@@ -521,6 +526,167 @@ export async function clearStaleDevToolsActivePort(userDataDir) {
         // Intentionally ignored — see docstring.
     }
 }
+/**
+ * Clear Chrome's "did not exit cleanly" flags so the next launch does NOT
+ * restore the previous session's tabs (or pop the crash-restore bubble).
+ *
+ * `npm run dev` is almost always stopped with Ctrl-C, which terminates the
+ * launched Chrome without a graceful shutdown. Chrome then records
+ * `profile.exit_type: "Crashed"` in `Default/Preferences` and, on the next
+ * launch against the same persistent profile, reopens the prior session's
+ * tabs. With the standalone single-client CDP proxy that is actively
+ * harmful: a *restored* duplicate webapp tab and the freshly-launched tab
+ * both dial `ws://<host>/cdp`, and because the proxy keeps only one client
+ * they evict each other in an endless ~5s reconnect war (each evicted page
+ * re-dials on the next leader-target refresh).
+ *
+ * Rewriting `exit_type` to `"Normal"` (and `exited_cleanly` to `true`) — the
+ * same trick ChromeDriver uses — before spawn makes Chrome believe the last
+ * session ended cleanly, so it starts fresh with a single tab.
+ *
+ * Best-effort and idempotent: a missing Preferences file (first run) is left
+ * absent — there is nothing to restore — and an unparseable one is left as-is
+ * for Chrome to regenerate. Never throws; a failure here must not block a
+ * launch.
+ */
+export async function clearChromeRestoreState(userDataDir) {
+    const prefsPath = join(userDataDir, 'Default', 'Preferences');
+    let raw;
+    try {
+        raw = await readFile(prefsPath, 'utf8');
+    }
+    catch {
+        return; // no Preferences yet (first run) — nothing to restore
+    }
+    let prefs;
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isJsonObject(parsed))
+            return;
+        prefs = parsed;
+    }
+    catch {
+        return; // corrupt file — leave it for Chrome to regenerate
+    }
+    const profile = ensureObject(prefs, 'profile');
+    if (profile['exit_type'] === 'Normal' && profile['exited_cleanly'] === true) {
+        return; // already clean — avoid a needless rewrite
+    }
+    profile['exit_type'] = 'Normal';
+    profile['exited_cleanly'] = true;
+    try {
+        await writeJsonFile(prefsPath, prefs);
+    }
+    catch {
+        // Best-effort — a write failure just leaves the prior restore behavior.
+    }
+}
+/**
+ * Remove Chrome's session-restore snapshot so a relaunch opens ONLY the
+ * command-line tab instead of also reopening the previous window's tabs.
+ *
+ * The dev launcher passes the UI URL on the command line, but Chrome ALSO
+ * restores `Default/Sessions/` from the prior run — so every `npm run dev` was
+ * adding a tab. `exit_type` only governs the *crash* bubble, not this; the fix
+ * is to drop the snapshot. Run before every spawn (like
+ * {@link clearStaleDevToolsActivePort}). Cookies / localStorage / IndexedDB
+ * live elsewhere and are untouched. Best-effort.
+ *
+ * Modern Chrome keeps the whole snapshot under `Default/Sessions/`; `Last
+ * Session` / `Last Tabs` are belt-and-suspenders for older Chromium builds that
+ * still wrote those two as top-level files under `Default/`.
+ */
+export async function clearChromeSessionRestore(userDataDir) {
+    const defaultDir = join(userDataDir, 'Default');
+    try {
+        await rm(join(defaultDir, 'Sessions'), { recursive: true, force: true });
+    }
+    catch {
+        // ignore
+    }
+    for (const name of ['Last Session', 'Last Tabs']) {
+        try {
+            await unlink(join(defaultDir, name));
+        }
+        catch {
+            // ignore (missing)
+        }
+    }
+}
+/**
+ * Terminate a Chrome instance still holding this `user-data-dir`, then clear
+ * the stale Singleton lock files, so a fresh launch isn't refused.
+ *
+ * Chrome is single-instance per profile: a second `open -n` against a locked
+ * profile either exits non-zero ("Chrome exited … before reporting CDP port")
+ * or silently adds a tab to the running instance. On macOS the launcher starts
+ * Chrome via LaunchServices, so it isn't our child and Ctrl-C never reaps it —
+ * a leftover Chrome lingers across `npm run dev` runs. Chrome records the
+ * owning PID in the `SingletonLock` symlink (`<host>-<pid>`); if that process
+ * is alive we stop it (SIGTERM, then SIGKILL), then unlink the Singleton lock
+ * files. Best-effort and idempotent; a missing lock is a no-op.
+ */
+export async function terminateExistingProfileChrome(userDataDir, deps = {}) {
+    const readlinkImpl = deps.readlinkImpl ?? readlink;
+    const isAlive = deps.isAlive ?? defaultPidIsAlive;
+    const kill = deps.kill ?? ((pid, signal) => process.kill(pid, signal));
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let pid = null;
+    try {
+        pid = parseSingletonLockPid(await readlinkImpl(join(userDataDir, 'SingletonLock')));
+    }
+    catch {
+        pid = null; // no SingletonLock — nothing holding the profile
+    }
+    if (pid !== null && isAlive(pid)) {
+        try {
+            kill(pid, 'SIGTERM');
+        }
+        catch {
+            // already gone between the alive-check and the signal
+        }
+        for (let i = 0; i < 30 && isAlive(pid); i++) {
+            await sleep(100);
+        }
+        if (isAlive(pid)) {
+            try {
+                kill(pid, 'SIGKILL');
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    for (const name of ['SingletonLock', 'SingletonSocket', 'SingletonCookie']) {
+        try {
+            await unlink(join(userDataDir, name));
+        }
+        catch {
+            // ignore (missing)
+        }
+    }
+}
+/**
+ * `SingletonLock` is a symlink to `<hostname>-<pid>`. The hostname can contain
+ * dashes, so the PID is the segment after the LAST dash.
+ */
+function parseSingletonLockPid(target) {
+    const dash = target.lastIndexOf('-');
+    if (dash < 0)
+        return null;
+    const pid = Number.parseInt(target.slice(dash + 1), 10);
+    return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+function defaultPidIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        // ESRCH = no such process; EPERM = exists but not signalable by us.
+        return err.code === 'EPERM';
+    }
+}
 /**
  * Single-shot HTTP probe of Chrome's `/json/version` endpoint. Resolves
  * `true` only when the port answers with a 2xx response whose body is

package/dist/node-server/electron-controller.d.ts

@@ -1,5 +1,57 @@
 import { type ChildProcess } from 'child_process';
 import { type ElectronInspectableTarget } from './electron-runtime.js';
+/**
+ * Query param name used to mark the role of an overlay tab on the hosted
+ * launcher URL. The pinned leader carries `role=leader`; auto-follow
+ * followers carry `role=follower`. The hosted webapp interprets these to
+ * decide which tab anchors the CDP bridge vs. follows the leader.
+ */
+export declare const BRIDGE_ROLE_QUERY_PARAM = "role";
+export declare const BRIDGE_ROLE_LEADER = "leader";
+export declare const BRIDGE_ROLE_FOLLOWER = "follower";
+/**
+ * Thin-bridge coordinates for the Electron overlay. The injected overlay
+ * always loads from a hosted launcher (`hostedLeaderOrigin`, defaulting to
+ * production `https://www.sliccy.ai`) and dials back to the local `/cdp`
+ * WebSocket using the per-process bridge token. This is the only overlay
+ * path — the legacy bundled-UI overlay served from the local serve port
+ * was retired.
+ */
+export interface ThinBridgeConfig {
+    hostedLeaderOrigin: string;
+    bridgeWsUrl: string;
+    bridgeToken: string;
+}
+export type OverlayRole = typeof BRIDGE_ROLE_LEADER | typeof BRIDGE_ROLE_FOLLOWER;
+/**
+ * Build the thin-bridge config for the Electron overlay injector. The
+ * hosted-leader origin defaults to production `https://www.sliccy.ai`
+ * (overridable via `SLICC_HOSTED_LEADER_ORIGIN` / `WORKER_BASE_URL`), so
+ * the only genuinely unresolvable case is a missing per-process bridge
+ * token — in which case this returns `null` and the caller fails fast
+ * rather than falling back to a (now-retired) bundled overlay.
+ */
+export declare function resolveOverlayThinBridge(env: Record<string, string | undefined>, bridgeToken: string | null, servePort: number): ThinBridgeConfig | null;
+export interface ThinOverlayUrlOptions extends ThinBridgeConfig {
+    role: OverlayRole;
+    activeTab?: string;
+}
+/**
+ * Build the hosted launcher URL for an overlay injection. Mirrors the
+ * standalone Path A launch-URL shape (`bridge`, `bridgeToken` query
+ * params) with one Electron-specific addition: a `role` param that pins
+ * the first injected tab as the leader and marks every subsequent tab as
+ * an auto-follow follower.
+ */
+export declare function buildThinOverlayAppUrl(opts: ThinOverlayUrlOptions): string;
+/**
+ * Resolve the hosted leader origin Chrome / Electron should open in thin
+ * mode. Prefers explicit overrides (`SLICC_HOSTED_LEADER_ORIGIN`, then
+ * `WORKER_BASE_URL`) so dev can point at staging; defaults to production
+ * `https://www.sliccy.ai`. Trailing slashes are stripped so callers can
+ * safely concatenate paths.
+ */
+export declare function resolveHostedLeaderOrigin(env?: Record<string, string | undefined>): string;
 interface RunningProcessInfo {
     pid: number;
     commandLine: string;
@@ -41,13 +93,43 @@ export declare function computeAverageLuminance(pixels: Buffer, width: number, h
  * actually needs unblocking when the parent is a local file.
  */
 export declare function resolveFetchProxyOrigin(targetUrl: string, servePort: number): string;
+/**
+ * Pre-built bootstrap scripts for thin-mode injection — one per overlay
+ * role. The injector picks `leader` for the first injected target and
+ * `follower` for every subsequent target.
+ */
+export interface ThinBootstrapSet {
+    leader: string;
+    follower: string;
+}
+/**
+ * JS probe that reports whether the overlay iframe actually loaded. Walks the
+ * `<slicc-launcher>` host's (open) shadow root to find the iframe
+ * depth-agnostically, then classifies by cross-origin reachability: the
+ * thin-bridge overlay is ALWAYS a different origin (hosted webapp) than the
+ * app document, so a committed cross-origin navigation makes
+ * `iframe.contentWindow.location.href` THROW — that throw is the ONLY success
+ * signal. Any READABLE href (`about:blank`, `''`, or a CSP-blocked swap to
+ * `chrome-error://chromewebdata/`) means the cross-origin nav did NOT commit,
+ * so the overlay did not load and the setBypassCSP escalation must fire.
+ * Returns `'ok'` only from the catch; otherwise `'no-host' / 'no-iframe' /
+ * 'no-src' / 'blank:<href>'`.
+ */
+export declare const OVERLAY_LOADED_PROBE_EXPRESSION = "(function() {\n          var host = document.getElementById('slicc-electron-overlay-root');\n          if (!host || !host.shadowRoot) return 'no-host';\n          var iframe = host.shadowRoot.querySelector('iframe');\n          if (!iframe) return 'no-iframe';\n          if (!iframe.src) return 'no-src';\n          try {\n            // Thin-bridge overlay is ALWAYS cross-origin (hosted webapp) vs the app\n            // document. A committed cross-origin navigation makes this access THROW.\n            // Any READABLE href means the cross-origin nav did NOT commit \u2014 still\n            // about:blank, or swapped to chrome-error://chromewebdata/ by a CSP block \u2014\n            // so the overlay did NOT load and the setBypassCSP escalation must fire.\n            var href = iframe.contentWindow && iframe.contentWindow.location ? iframe.contentWindow.location.href : '';\n            return 'blank:' + href;\n          } catch (e) {\n            return 'ok';\n          }\n        })()";
 export declare class ElectronOverlayInjector {
     private readonly cdpPort;
     private readonly servePort;
-    private readonly bootstrapScript;
+    /** Thin-mode bootstrap pair — the only overlay path. */
+    private readonly thinBootstraps;
     private readonly probeDelayMs;
     private readonly connections;
     private readonly cspBypassedTargets;
+    /**
+     * URL of the target currently elected as the pinned leader. Cleared by
+     * `syncTargets` when that target disappears so the next injection
+     * re-elects a fresh leader.
+     */
+    private leaderTargetUrl;
     private syncTimer;
     private syncing;
     private constructor();
@@ -56,6 +138,13 @@ export declare class ElectronOverlayInjector {
         servePort: number;
         dev: boolean;
         projectRoot: string;
+        /**
+         * Thin-bridge coordinates: the overlay loads from the hosted launcher
+         * with bridge-URL + token query params and tabs are split into one
+         * pinned leader and N auto-follow followers. Required — the legacy
+         * bundled overlay path was retired.
+         */
+        thinBridge: ThinBridgeConfig;
     }): Promise<ElectronOverlayInjector>;
     /**
      * Test-only factory: skips bundle loading and lets tests drive the per-target
@@ -65,28 +154,49 @@ export declare class ElectronOverlayInjector {
     static _createForTesting(options: {
         cdpPort?: number;
         servePort: number;
-        bootstrapScript?: string;
+        thinBootstraps?: ThinBootstrapSet;
         probeDelayMs?: number;
     }): ElectronOverlayInjector;
+    /** Test-only: snapshot the elected leader target URL (null when no leader). */
+    _testingLeaderTargetUrl(): string | null;
+    /** Test-only: seed the elected leader (drives the follower-election path). */
+    _testingSeedLeaderTargetUrl(url: string | null): void;
     /** Test-only: drive the per-target connect flow without going through `start`. */
     _testingConnectToTarget(target: ElectronInspectableTarget): void;
     /** Test-only: seed the per-target "already bypassed" guard. */
     _testingSeedBypassedTarget(url: string): void;
     /** Test-only: snapshot the per-target "already bypassed" guard set. */
     _testingBypassedTargets(): ReadonlySet<string>;
+    /** Test-only: drive a single `syncTargets` pass without `start()`'s interval. */
+    _testingSyncTargets(): Promise<void>;
     /** Test-only: close any sockets opened by `_testingConnectToTarget`. */
     _testingCloseConnections(): void;
     start(): Promise<void>;
     stop(): void;
     private syncTargets;
     /**
-     * Check if the overlay iframe loaded successfully by evaluating a probe script.
-     * Returns true if the iframe element exists and has started loading content.
+     * Check if the overlay iframe loaded successfully by evaluating a probe
+     * script. Walks the `<slicc-launcher>` host's (open) shadow root to find the
+     * iframe depth-agnostically and classifies by cross-origin reachability: the
+     * thin-bridge overlay is ALWAYS a different origin than the app document, so
+     * only a THROW on `iframe.contentWindow.location.href` (a committed
+     * cross-origin navigation) counts as loaded. Any readable href — including a
+     * CSP-blocked swap to `chrome-error://chromewebdata/` — means the nav did not
+     * commit, so the Fetch-proxy escalation must still fire.
+     * See {@link OVERLAY_LOADED_PROBE_EXPRESSION}.
      */
     private probeOverlayIframeLoaded;
+    /**
+     * Pick the bootstrap script for `target`, electing the leader on first
+     * use when thin-mode is active. Same target URL ↔ same role across
+     * reconnects so a page that bounces its CDP session stays the leader
+     * (no re-election on transient drops, only on `syncTargets` cleanup).
+     */
+    private resolveBootstrapForTarget;
     /**
      * Build a script that sets the SLICC theme preference in localStorage to
-     * match the target app's detected theme, then runs the bootstrap.
+     * match the target app's detected theme, then runs the bootstrap. The
+     * bootstrap is target-specific (leader vs. follower).
      */
     private buildThemedBootstrap;
     /**