diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index d308323a5..6c9ec0447 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -92,7 +92,7 @@ jobs:
           fi
 
           # WHY no hard-fail when both secrets are absent: every submodule
-          # repo (the five Juliusolsson05 packages/* repos and openai/codex)
+          # repo (every Juliusolsson05 packages/* repo and openai/codex)
           # is PUBLIC, so the plain HTTPS URLs in .gitmodules clone fine
           # anonymously. The exit-1 here predated the repos going public and
           # contradicted README.md's "no special access needed" (#506
@@ -198,7 +198,7 @@ jobs:
           fi
 
           # WHY no hard-fail when both secrets are absent: every submodule
-          # repo (the five Juliusolsson05 packages/* repos and openai/codex)
+          # repo (every Juliusolsson05 packages/* repo and openai/codex)
           # is PUBLIC, so the plain HTTPS URLs in .gitmodules clone fine
           # anonymously. The exit-1 here predated the repos going public and
           # contradicted README.md's "no special access needed" (#506
diff --git a/.gitmodules b/.gitmodules
index fdb440b40..487678196 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -19,3 +19,6 @@
 [submodule "packages/workflow-mcp"]
 	path = packages/workflow-mcp
 	url = https://github.com/Juliusolsson05/workflow-mcp.git
+[submodule "packages/agent-code-extension-api"]
+	path = packages/agent-code-extension-api
+	url = https://github.com/Juliusolsson05/agent-code-extension-api.git
diff --git a/docs/extensions/authoring.md b/docs/extensions/authoring.md
new file mode 100644
index 000000000..77bd77761
--- /dev/null
+++ b/docs/extensions/authoring.md
@@ -0,0 +1,477 @@
+# Writing an Agent Code extension
+
+> **Status:** live. API version **1**.
+>
+> This document is the contract. Where it and the code disagree, the code wins and
+> this document is the bug — it has been wrong before, in the way described in §3.
+
+An extension is a **GitHub repository** containing a manifest and a built ES
+module. Agent Code downloads it, validates it, and runs it **inside a sandboxed
+iframe at its own origin**. Nothing is compiled into the app.
+
+```
+Settings → Extensions → owner/repo → Install
+```
+
+---
+
+## 0. The execution model — read this first
+
+Your extension does **not** run in Agent Code's renderer. It runs in a separate
+document served from `agent-code-ext://<your-id>/`, embedded in a sandboxed
+`<iframe>`.
+
+Everything else in this document follows from that one fact:
+
+- **You are a normal web page.** Bundle whatever you like. React, Preact, Svelte,
+  a canvas, plain DOM — no framework negotiation with the host, because you do not
+  share a realm with it.
+- **You cannot reach the host.** Not `window.parent`'s DOM, not Agent Code's
+  internals, not another extension. Your only channel is the `api` object handed to
+  `activate()`, which is brokered over `postMessage` and validated on the far side.
+- **You have no network access.** The frame's Content-Security-Policy is
+  `connect-src` your own origin only. `fetch` to any other host fails. So does
+  `window.open`, form submission, top-level navigation, and creating a nested
+  frame. This is deliberate: an extension that could phone home would make the
+  install prompt meaningless.
+- **You get a fresh document every time your view opens**, and it is destroyed when
+  the view closes. Persistent state belongs in `api.storage`, not in a module-level
+  variable.
+
+---
+
+## 1. The manifest
+
+`agent-code.extension.json`, at the repository root.
+
+```jsonc
+{
+  "id": "timer",
+  "name": "Timer",
+  "description": "Focus timer with interval reminders.",
+  "version": "0.1.0",
+  "apiVersion": 1,
+  "entry": "dist/index.js",
+
+  "contributes": {
+    "commands": [
+      { "id": "timer.open",  "title": "Open Timer", "keywords": ["pomodoro"] },
+      { "id": "timer.start", "title": "Start Timer" }
+    ],
+    "views": [
+      { "id": "timer.main", "title": "Timer", "mount": "modal" }
+    ],
+    "settings": [
+      { "id": "timer.defaultMinutes", "title": "Default duration",
+        "type": "number", "default": 30 }
+    ],
+    "keybindings": [
+      { "command": "timer.start", "key": "cmd+shift+t" }
+    ]
+  }
+}
+```
+
+| Field | Rules |
+|---|---|
+| `id` | `/^[a-z][a-z0-9-]{0,63}$/`. Becomes a directory name, your storage namespace, and your origin's host. **Permanent** — renaming orphans user data. |
+| `name`, `description` | Required, non-empty. `description` is shown in the palette and Settings. |
+| `version` | Free text. Displayed and recorded; never parsed. |
+| `apiVersion` | Must equal the host's. `1` today. Checked at install **and on every launch** — a host that implements only v1 refuses a v2 manifest with a message saying so. |
+| `entry` | Relative path to a built ES module. No absolute paths, no `..`, no backslashes, must end `.js`/`.mjs`. |
+| `contributes.*.id` | Must start with `<your id>.`. Enforced at install. |
+| `permissions` | See §6. Only three values are accepted today. |
+
+### Why contributions are declared
+
+The palette and Settings need to know what you offer **before your code has been
+loaded**. That is what makes lazy loading possible — a command can be listed and
+invoked while your module has never been imported. It also means a *broken*
+extension still shows what it contributes, with the failure reason next to it,
+instead of vanishing.
+
+### Activation events
+
+`activationEvents` is accepted and validated (an event naming a contribution you do
+not declare fails the install), but **no activation event fires in this version.**
+Do not rely on it.
+
+What actually happens: your module is imported and `activate()` is called when one
+of your views opens — either directly, or because a contributed command with no
+matching view opened your single view in order to run. There is no background
+execution while every view of yours is closed.
+
+The practical consequence, taking a timer as the example: a deadline stored in
+`api.storage` is correctly restored when the view opens, so no *time* is lost — but
+a reminder does not fire while the view is closed. If your extension
+needs to do work with no window open, v1 cannot support it. This is tracked as the
+background-frame follow-up; the fix has to be a hidden frame, because running an
+extension in the host realm is exactly what the sandbox exists to prevent.
+
+---
+
+## 2. The module
+
+Your `entry` must export `activate`, and may export `deactivate`.
+
+```ts
+export function activate(context) {
+  context.subscriptions.push(
+    context.registerCommand('timer.start', () => { /* … */ }),
+    context.registerView('timer.main', element => {
+      element.textContent = 'hello'
+      return () => { /* cleanup when the view closes */ }
+    }),
+  )
+}
+
+export function deactivate() { /* optional */ }
+```
+
+- **`registerCommand`/`registerView` reject an id you did not declare.** A handler
+  the palette has no entry for could never be invoked, so this fails loudly rather
+  than leaving you with a dead command and no clue why.
+- **A view mount may return a cleanup function.** It runs when the view closes.
+- **`deactivate()` runs when the view closes**, after the view's own cleanup.
+- **Everything in `context.subscriptions` is disposed** after that, in reverse
+  order.
+
+Teardown order on close is: view cleanup → `deactivate()` → subscriptions in
+reverse. It is best-effort and synchronous, because the document is being
+destroyed — do not `await` anything you need to complete.
+
+### Views are DOM-level
+
+```ts
+type ViewMount = (element: HTMLElement) => void | (() => void)
+```
+
+You get an empty element. Do whatever you like inside it:
+
+```tsx
+import { createRoot } from 'react-dom/client'
+
+context.registerView('timer.main', element => {
+  const root = createRoot(element)
+  root.render(<App />)
+  return () => root.unmount()
+})
+```
+
+### How a command reaches your code
+
+- A command whose id **equals a view id** opens that view. It is never dispatched to
+  a handler — opening a declared view is the host's job.
+- A command ending in **`.open`** opens your view too, but only if you declare
+  exactly one. With zero or several views the host cannot guess, so it dispatches
+  normally.
+- Any other command is delivered **into your running frame**. If no view of yours is
+  open and you declare exactly one, the host opens it and delivers the command as
+  soon as `activate()` resolves — so a cold "start" both opens and starts.
+- An extension with **no views** cannot run an action command cold. There is nowhere
+  to run it until one of your views is open.
+
+### Where a view appears
+
+`mount` in the manifest decides which host shell opens your view:
+
+- `"modal"` — a floating dialog. It sizes itself to your content: report your
+  natural size by simply laying out normally, and the host measures it. An
+  oversized view is scaled down to fit the window rather than clipped.
+- `"panel"` — a **pane** in the tiled workspace, alongside agent and terminal
+  panes. Your view fills the tile.
+
+Both are implemented. A pane persists across restarts: Agent Code remembers which
+view the pane hosts and rebuilds it on launch, showing a "not installed" message if
+the extension is gone.
+
+**Keyboard caveat for both shells.** Because your view is a cross-origin frame,
+keystrokes inside it never reach Agent Code, so application shortcuts — the command
+palette, pane navigation, everything — do not fire while focus is inside your view.
+
+**Escape is the one exception.** Agent Code forwards it, and an unhandled Escape
+closes your view. If you want Escape for something of your own (dismissing a
+popover, cancelling an edit), call `preventDefault()` on the event and the host
+never hears about it:
+
+```ts
+element.addEventListener('keydown', event => {
+  if (event.key === 'Escape' && myPopoverIsOpen) {
+    event.preventDefault()   // the host will NOT close the view
+    closeMyPopover()
+  }
+})
+```
+
+For everything else, give the user a visible way out — a close button, or
+`api.ui.close()`. The host's own modal close button is always available.
+
+---
+
+## 3. React (and every other dependency): bundle it
+
+**Bundle your own React. Normally. Like any web app.**
+
+If you have seen an older version of this document telling you to alias `react` to
+`globalThis.__agentCodeHost` — that guidance was for a previous architecture where
+extensions ran inside Agent Code's own renderer and would have collided with the
+host's React instance. **It is wrong now and will break your extension**, because a
+cross-origin frame cannot see the host's globals at all: the shim would read
+`undefined` at module-evaluation time and your extension would fail before
+`activate()` ran.
+
+Your frame is its own document with its own realm. Two React instances in two
+documents are not a conflict; they never meet.
+
+The SDK ships types and a Vite preset that produces the right output. It is **not
+on npm** — install it from GitHub, which works because its `dist/` is committed:
+
+```bash
+npm i -D github:Juliusolsson05/agent-code-extension-api
+```
+
+```ts
+// vite.config.ts
+import { extensionViteConfig } from 'agent-code-extension-api'
+export default extensionViteConfig()
+```
+
+The SDK is optional. It gives you `ExtensionManifest`, `ExtensionContext` and
+`AgentCodeApiV1` types plus the build preset; an extension is a plain ES module and
+nothing in the host requires you to depend on it.
+
+---
+
+## 4. Build output
+
+Two hard requirements:
+
+1. **A single ES module** at the manifest's `entry` path.
+2. **Committed to the repository.** The installer downloads your repo's source
+   tarball, not a release asset, so a `dist/` that only exists in CI means every
+   install fails with *"Manifest points at … which does not exist"*.
+
+If you are not using the preset:
+
+```ts
+build: {
+  lib: { entry: 'src/index.ts', formats: ['es'], fileName: () => 'index.js' },
+  rollupOptions: { output: { inlineDynamicImports: true } },
+  cssCodeSplit: false,
+},
+
+// REQUIRED if you depend on anything from the React ecosystem.
+define: { 'process.env.NODE_ENV': JSON.stringify('production') },
+```
+
+### ⚠️ `process is not defined` — read this before you debug it
+
+**Vite's library mode does not replace `process.env.NODE_ENV`.** A normal app build
+does; a library is expected to leave it for the consuming bundler. There is no
+consuming bundler here — your output is loaded straight into a browser document
+where `process` does not exist.
+
+Nearly every React-ecosystem package guards its dev warnings with
+`process.env.NODE_ENV !== "production"`, so the first one to execute throws and
+your extension fails during `activate()` — **after** installing and importing
+cleanly, which makes it look like your code rather than your build.
+
+The `define` above is the fix. Do **not** shim a global `process` object instead:
+libraries would then take Node code paths inside a browser realm, which fails later
+and far less obviously.
+
+**CSS must be inlined by your bundle**, not emitted as a sibling file. Vite's
+library mode emits `style.css` regardless of `cssCodeSplit`, and the host imports
+exactly one file — a stylesheet nothing requests silently never applies. Import it
+`?inline` and inject a `<style>` tag yourself.
+
+**Symlinks must be relative.** If your bundle aliases a file with a symlink, make
+it relative. An absolute symlink points outside the installed bundle once the
+extension has been copied into place, and the installer refuses it.
+
+---
+
+## 5. The API
+
+Your `context.api` is `AgentCodeApiV1`. **Every method returns a Promise**, with no
+exceptions — a future transport cannot be made synchronous, and widening a
+signature later would touch every call site in every extension.
+
+### Tier 0 — always available, no permission needed
+
+```ts
+api.extension.id                     // your id
+api.extension.apiVersion             // 1
+
+api.storage.get(key)                 // your own namespace, persisted
+api.storage.set(key, value)
+api.storage.delete(key)
+api.storage.keys()
+
+api.ui.close()                       // close your view (the modal or the pane)
+api.ui.showToast(message)            // app-wide toast
+
+api.theme.tokens()                   // resolved --theme-* values
+```
+
+### Tier 1 — requires a permission (see §6)
+
+```ts
+api.workspace.observe()              // { activeTabId, tabIds, sessionCount }
+api.workspace.subscribe(listener)    // returns an unsubscribe
+
+api.sessions.observe()               // [{ id, kind, cwd, title }]
+api.sessions.subscribe(listener)
+
+api.panes.observe()                  // [{ tabId, leafSessionIds }]
+api.panes.subscribe(listener)
+```
+
+`subscribe` gives you a change *nudge* carrying no data — re-read with `observe()`
+when it fires. Calling `observe()` without the matching permission rejects.
+
+### Reading a contributed setting
+
+A `contributes.settings` entry renders a row in Agent Code's Settings, and the value
+the user picks is written to **your own storage under the setting's full id**. The
+manifest `default` is what the row displays before anything is stored; it is not
+written for you. So read it with the same default:
+
+```ts
+const minutes = (await api.storage.get('timer.defaultMinutes')) ?? 30
+```
+
+### Storage notes
+
+- Namespaced by extension id; you cannot read another extension's data.
+- Values must be JSON-serializable. **`NaN` and `Infinity` are rejected** rather
+  than silently stored as `null`.
+- Keys may not be `__proto__`, `constructor` or `prototype`.
+- Concurrent writes are serialized, so `void set('a',1); void set('b',2)` is safe.
+- **Survives uninstall.** Uninstall-then-reinstall is a normal troubleshooting
+  move; destroying user data as a side effect of it would be hostile.
+- A modal and a pane of the same extension share one namespace.
+
+---
+
+## 6. Permissions
+
+Declare what you need in `permissions`. The user approves them in a blocking
+dialog at install time, and the grant is bound to the exact bytes installed — if
+you ship new code, the user is asked again.
+
+**Three permissions exist in v1:**
+
+| Permission | Grants |
+|---|---|
+| `workspace.observe` | `api.workspace.observe` / `subscribe` |
+| `sessions.observe` | `api.sessions.observe` / `subscribe` |
+| `panes.observe` | `api.panes.observe` / `subscribe` |
+
+Anything else fails the install with a message naming what this build supports.
+Filesystem, transcript, git, prompt-sending and network capabilities **do not
+exist** — they are not "not yet granted", they are unimplemented, and asking for
+one is an install error rather than a silent no-op. Omit `permissions` entirely to
+stay Tier 0, which installs with no prompt at all.
+
+---
+
+## 7. Theming
+
+Agent Code pushes its palette into your frame as `--theme-*` custom properties,
+**before** your view mounts, and again whenever the theme changes. Use them in CSS
+and you inherit the user's theme for free:
+
+```css
+.my-extension {
+  background: var(--theme-surface);
+  color: var(--theme-ink);
+  border: 1px solid var(--theme-border);
+}
+```
+
+Common tokens: `--theme-canvas`, `--theme-surface`, `--theme-ink`,
+`--theme-ink-dim`, `--theme-muted`, `--theme-border`, `--theme-accent`,
+`--theme-accent-fg`, `--theme-font-code`.
+
+You do not need a fallback palette — the tokens are guaranteed present before your
+first paint. Prefer plain CSS over `api.theme.tokens()`; the accessor exists for
+canvas and inline-SVG consumers that cannot use the cascade.
+
+**Only the `--theme-*` layer is contract.** The `--color-*` Tailwind bindings are
+an implementation detail of how the app wires its utilities.
+
+---
+
+## 8. Developing locally
+
+Cutting a GitHub release for every change is not a dev loop. Use **Load folder…**:
+
+```
+Settings → Extensions → Load folder… → pick your built folder
+```
+
+That takes a *snapshot copy* of the folder through the exact same validation as a
+GitHub install. Rebuild, press **Reload** on the extension's row, and reopen your
+view. Because the grant is bound to the installed bytes, a rebuild that changes
+requested permissions asks for consent again.
+
+---
+
+## 9. Publishing
+
+```bash
+npm run build          # produces dist/index.js
+git add dist && git commit
+git tag v0.1.0 && git push --tags
+gh release create v0.1.0
+```
+
+Agent Code prefers **the latest release tag** and falls back to the default
+branch — a release is the author saying *this is ready*, whereas a branch is
+whatever was pushed thirty seconds ago. Either way it downloads the **source
+tarball**, which is why `dist/` must be committed.
+
+The installer records the resolved ref, a SHA-256 of the tarball, and a SHA-256 of
+the installed bundle, so "which bytes am I running" stays answerable.
+
+Archives are capped at **32 MB**.
+
+---
+
+## 10. Failure modes you will hit
+
+| Symptom | Cause |
+|---|---|
+| *"Repository has no agent-code.extension.json"* | manifest missing, or not at the repo root |
+| *"Manifest points at … which does not exist in the repository"* | `dist/` not committed, or a wrong `entry` |
+| *"contribution id … must start with …"* | a contributed id outside your namespace |
+| *"registerCommand(x) — not declared"* | id missing from `contributes.commands` |
+| *"entry module does not export an activate(context) function"* | wrong export, or the bundle is not an ES module |
+| *"unknown capability … not available yet"* | you asked for a permission this build does not implement (§6) |
+| *"extension targets Agent Code API v2, this build implements v1"* | Agent Code is older than your extension |
+| *"The repository contains a symlink … that points outside"* | make internal symlinks relative (§4) |
+| *"Extension failed to load: process is not defined"* | missing `define` — see §4 |
+| *"The extension frame did not start"* | the bundle could not be served or was blocked by the frame CSP |
+| renders unstyled | CSS emitted as a sibling file instead of inlined |
+| `fetch` fails | you have no network access — see §0 |
+| a shortcut does nothing while your view has focus | expected; keystrokes do not leave the frame (§2) |
+
+Failures appear in **Settings → Extensions**, on the extension's row, with the
+message. A broken extension never prevents others from loading and cannot take
+down the app.
+
+---
+
+## 11. What v1 deliberately does not have
+
+Recorded so you know these are decisions, not oversights:
+
+- **No background execution.** Activation events do not fire; your code runs while
+  a view of yours is open (§1).
+- **No network.** The frame's CSP permits only your own origin (§0).
+- **No filesystem, transcript, git or prompt access.** Those are unimplemented, not
+  merely ungranted (§6).
+- **No marketplace.** The repo name is the trust decision.
+- **No cross-extension communication.** Each extension is its own origin and cannot
+  see another's frame, storage, or bundle.
diff --git a/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md b/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
new file mode 100644
index 000000000..364cb17d1
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
@@ -0,0 +1,1382 @@
+# Extension Platform — Stage 1 Implementation Plan
+
+> **Status: SUPERSEDED (2026-07-20) by `2026-07-20-extension-platform.md`.**
+>
+> This plan was executed. It produced a working host plus a compiled-in Timer app,
+> and the Timer was then deleted: a compiled-in app is app source code behind an API
+> boundary, not an extension. It cannot be installed and it ships in the bundle.
+>
+> Two claims in this document were later shown to be wrong and must not be reused:
+> that Stage 2 is "a registry swap plus a five-line commandDefs change" (an
+> adversarial audit enumerated eight more host changes), and that React would be
+> "injected through the host object" (the ABI has no react field; the successor plan
+> resolves this with a namespaced global and a DOM-level view contract).
+>
+> Kept for the reasoning in §0-§3, which the successor builds on.
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a working in-app Timer, mounted through a real extension host API (`AgentCodeApiV1`), so that Stage 2 can move the Timer out of this repo without changing one line inside it.
+
+**Architecture:** Apps are compiled into the renderer and registered in one static array — the same contract `app/surfaces/registry.tsx` and `features/command-palette/registry.ts` already use. The load-bearing discipline is that an app receives **exactly one prop, `api: AgentCodeApiV1`, and imports nothing from `@renderer/*`**. That prop is the transport boundary: today it is a direct function table, and in Stage 2 it becomes a `postMessage` RPC facade with no change on the app side. Per-app state is main-owned under `STATE_DIR`, never the zustand-persist `Settings` store.
+
+**Tech Stack:** TypeScript, React 18, Zustand, Radix Dialog, Electron IPC, Vitest (existing suite only — see Global Constraints).
+
+**Prior art this plan is derived from:**
+- `docs/superpowers/specs/2026-07-20-extension-platform-investigation.md` (evidence, committed on this branch)
+- Four consultants under orchestration run `extension-platform-consult`. Both Claude consultants — assigned opposing briefs — independently converged on "compiled-in first, but built as Stage 2's substrate." The Codex API consultant supplied the tiering model; the Codex frame-boundary consultant priced Stage 2's alternative at ~350–650 LOC of bridge and is why Stage 2 is *conditional*, not scheduled.
+
+---
+
+## Global Constraints
+
+- **No new committed test files.** Per standing repo feedback, feature PRs do not add test files or wire new `test:*` scripts. Verification in this plan is `npm run typecheck` plus explicit manual smoke steps. Where a test *would* go, the plan says so in a `TEST-SITE:` note so a later cleanup PR can pick it up. **If this constraint is lifted, convert every `TEST-SITE:` note into a real `*.renderer.test.tsx` before starting the task it belongs to.**
+- **Every host API call returns a `Promise`.** No exceptions, including ones that could be synchronous today. This is the single forward-compatibility constraint that keeps Stage 2 a swap instead of a rewrite — `postMessage` cannot be made synchronous later. Costs nothing now.
+- **An app imports nothing from `@renderer/*`.** Not the store, not `components/ui`, not `lib/utils`. If an app needs something, it comes through `api`. This is binary and checkable by grep.
+- **Extension state never touches the zustand-persist `Settings` store.** `app-state/store.ts:35-57` records that a forgotten version bump black-screened launch twice (#249). Extension data must not be able to do that.
+- **`AppDefinition` stays serializable-plus-one.** Every field except `Component` must be expressible in a JSON manifest. Adding a host-only field (e.g. `getWorkspace: () => Workspace`) converts this from a manifest target into a host interface and is exactly the tear-out this staging exists to avoid.
+- **Node 24** (`.nvmrc`), **Electron 43.1.1** (lockfile). The local `node_modules` in this worktree may be stale at 31.7.7 — see Task 0.
+- New surface registry entries go at the **END** of their array unless a stacking reason is written down (`app/surfaces/registry.tsx:33-38`; PR #505 shipped a regression by ignoring this).
+
+---
+
+## File Structure
+
+**New — main process**
+
+| File | Responsibility |
+|---|---|
+| `src/main/extensions/storage.ts` | Read/write one JSON blob per app id under `STATE_DIR/extensions/<id>/state.json`, atomically. Id validation lives here. |
+| `src/main/ipc/extensions.ts` | Four `ipcMain.handle` registrations wrapping the above. |
+
+**New — preload**
+
+| File | Responsibility |
+|---|---|
+| `src/preload/api/extensions.ts` | `extensionStorage*` invoke wrappers. |
+
+**New — renderer**
+
+| File | Responsibility |
+|---|---|
+| `src/renderer/src/apps/api/types.ts` | `AgentCodeApiV1` — the ABI. The most permanent artifact in this plan. |
+| `src/renderer/src/apps/api/useAppHostApi.ts` | Builds a per-app `AgentCodeApiV1` instance. |
+| `src/renderer/src/apps/types.ts` | `AppDefinition`. |
+| `src/renderer/src/apps/registry.ts` | `APPS` array + `APP_BY_ID`. One import + one entry per app. |
+| `src/renderer/src/apps/surfaces/AppHostSurface.tsx` | The single surface entry. Resolves `openAppId`, renders the app in a `DialogContent`. |
+| `src/renderer/src/apps/commands/appCommands.ts` | `CommandDef[]` derived by mapping `APPS`. |
+| `src/renderer/src/apps/timer/index.ts` | The Timer's `AppDefinition`. |
+| `src/renderer/src/apps/timer/ui/TimerApp.tsx` | The Timer UI. Imports only `react` and `../../api/types`. |
+
+**Modified**
+
+| File | Change |
+|---|---|
+| `src/main/storage/paths.ts` | `+ EXTENSION_STATE_DIR` |
+| `src/main/ipc/index.ts` | `+ import`, `+ registerExtensionsIpc()` |
+| `src/preload/api/index.ts` | `+ import`, `+ ...extensionsApi` |
+| `src/renderer/src/app-state/uiShell/types.ts` | `+ openAppId`, `+ openApp`, `+ closeApp` |
+| `src/renderer/src/app-state/uiShell/slice.ts` | initial value + two actions |
+| `src/renderer/src/app/surfaces/registry.tsx` | `+ import`, `+ { id: 'app-host', … }` at END of `modalSurfaces` |
+| `src/renderer/src/features/command-palette/types.ts` | `+ openApp` on `CommandContext.ui` |
+| `src/renderer/src/features/command-palette/registry.ts` | `+ import`, `+ ...appCommands` |
+| `src/renderer/src/components/ui/README.md` | Paragraph recording why `AppHostSurface` is not a "surface factory" |
+
+---
+
+## Task 0: Restore the toolchain
+
+**Files:** none — environment only.
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces: a `node_modules` matching the lockfile. Every later task's `npm run typecheck` depends on this.
+
+- [ ] **Step 1: Check what is actually installed**
+
+```bash
+cd /Users/juliusolsson/Desktop/Development/agent-code/.worktrees/extension-platform
+node -p "require('electron/package.json').version"
+```
+
+Expected if stale: `31.7.7`. Expected if healthy: `43.1.1`. **If it already prints `43.1.1`, skip to Step 4.**
+
+- [ ] **Step 2: Reinstall from the lockfile**
+
+`node_modules` is shared by ~30 worktrees via symlink, so this is a global change. Confirm no dev server or build is running anywhere first.
+
+```bash
+cd /Users/juliusolsson/Desktop/Development/agent-code
+nvm use          # .nvmrc = 24
+unset NODE_ENV   # NODE_ENV=production strips ALL devDeps, including electron
+npm ci --include=dev
+```
+
+Expected: completes, and `postinstall` runs `electron-rebuild -f -w node-pty`.
+
+- [ ] **Step 3: Verify**
+
+```bash
+node -p "require('electron/package.json').version"   # → 43.1.1
+```
+
+- [ ] **Step 4: Baseline the worktree**
+
+```bash
+cd /Users/juliusolsson/Desktop/Development/agent-code/.worktrees/extension-platform
+npm run typecheck
+```
+
+Expected: PASS. If it fails, fix that **before** writing any code — a pre-existing failure will be misattributed to this work. Note: `hotkeyBinding.test.ts` is a known pre-existing failure in fresh worktrees and is not caused by this plan.
+
+- [ ] **Step 5: No commit** — nothing changed in the repo.
+
+---
+
+## Task 1: Per-app storage (main + IPC + preload)
+
+**Files:**
+- Create: `src/main/extensions/storage.ts`
+- Create: `src/main/ipc/extensions.ts`
+- Create: `src/preload/api/extensions.ts`
+- Modify: `src/main/storage/paths.ts`
+- Modify: `src/main/ipc/index.ts`
+- Modify: `src/preload/api/index.ts`
+
+**Interfaces:**
+- Consumes: `STATE_DIR` from `@main/storage/paths.js`.
+- Produces: on `window.api` —
+  - `extensionStorageGet(appId: string, key: string): Promise<unknown>`
+  - `extensionStorageSet(appId: string, key: string, value: unknown): Promise<void>`
+  - `extensionStorageDelete(appId: string, key: string): Promise<void>`
+  - `extensionStorageKeys(appId: string): Promise<string[]>`
+
+- [ ] **Step 1: Add the state root**
+
+In `src/main/storage/paths.ts`, after the `STATE_FILE` export:
+
+```ts
+// Per-app extension state, one directory per app id, one state.json inside.
+//
+// WHY main-owned and not the renderer's zustand-persist blob: app-state/store.ts:35-57
+// records that adding a field without bumping the persist version black-screened launch
+// twice (#249). Extension data is authored outside the app's release cycle, so it must
+// not be able to reach that failure mode at all. A per-app file also means uninstalling
+// an app is `rm -rf` of one directory.
+export const EXTENSION_STATE_DIR = join(STATE_DIR, 'extensions')
+```
+
+- [ ] **Step 2: Write the storage module**
+
+Create `src/main/extensions/storage.ts`:
+
+```ts
+import { mkdir, readFile, rename, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { EXTENSION_STATE_DIR } from '@main/storage/paths.js'
+
+// WHY ids are validated rather than sanitized: an app id becomes a directory name, so
+// a permissive id is a path-traversal primitive. Sanitizing (stripping bad characters)
+// silently collapses distinct ids onto the same directory — `../x` and `x` would share
+// state. Rejecting is the only option where the failure is visible.
+const APP_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/
+
+export class InvalidAppIdError extends Error {}
+
+function stateFileFor(appId: string): string {
+  if (!APP_ID_PATTERN.test(appId)) {
+    throw new InvalidAppIdError(
+      `invalid app id ${JSON.stringify(appId)} — must match ${APP_ID_PATTERN}`,
+    )
+  }
+  return join(EXTENSION_STATE_DIR, appId, 'state.json')
+}
+
+async function readAll(appId: string): Promise<Record<string, unknown>> {
+  const file = stateFileFor(appId)
+  try {
+    const raw = await readFile(file, 'utf8')
+    const parsed: unknown = JSON.parse(raw)
+    // A corrupt or non-object file degrades to empty rather than throwing. An app
+    // losing its saved state is recoverable; an app that cannot start is not.
+    return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+      ? (parsed as Record<string, unknown>)
+      : {}
+  } catch {
+    return {}
+  }
+}
+
+async function writeAll(appId: string, data: Record<string, unknown>): Promise<void> {
+  const file = stateFileFor(appId)
+  await mkdir(join(EXTENSION_STATE_DIR, appId), { recursive: true })
+  // temp+rename, matching workspace.json's discipline: a crash mid-write must not be
+  // able to leave a half-written JSON file that then fails to parse forever.
+  const tmp = `${file}.tmp`
+  await writeFile(tmp, JSON.stringify(data, null, 2), 'utf8')
+  await rename(tmp, file)
+}
+
+export async function extensionStorageGet(appId: string, key: string): Promise<unknown> {
+  return (await readAll(appId))[key]
+}
+
+export async function extensionStorageSet(
+  appId: string,
+  key: string,
+  value: unknown,
+): Promise<void> {
+  const data = await readAll(appId)
+  data[key] = value
+  await writeAll(appId, data)
+}
+
+export async function extensionStorageDelete(appId: string, key: string): Promise<void> {
+  const data = await readAll(appId)
+  delete data[key]
+  await writeAll(appId, data)
+}
+
+export async function extensionStorageKeys(appId: string): Promise<string[]> {
+  return Object.keys(await readAll(appId))
+}
+```
+
+`TEST-SITE:` `src/main/extensions/storage.test.ts` — id rejection (`../evil`, `''`, `A`), round-trip, corrupt-file-degrades-to-empty.
+
+- [ ] **Step 3: Write the IPC module**
+
+Create `src/main/ipc/extensions.ts`:
+
+```ts
+import { ipcMain } from 'electron'
+
+import {
+  extensionStorageDelete,
+  extensionStorageGet,
+  extensionStorageKeys,
+  extensionStorageSet,
+} from '@main/extensions/storage.js'
+
+// WHY appId is a parameter rather than derived from the sender: in Stage 1 every app
+// shares the one renderer WebContents, so the sender cannot distinguish them. This is
+// therefore NOT an authority boundary yet — it is a namespace. Stage 2, where each app
+// gets its own frame/preload, is where appId becomes sender-derived and enforceable.
+// Do not add any capability beyond storage here until that binding exists.
+export function registerExtensionsIpc(): void {
+  ipcMain.handle('extensions:storage-get', (_e, appId: string, key: string) =>
+    extensionStorageGet(appId, key),
+  )
+  ipcMain.handle('extensions:storage-set', (_e, appId: string, key: string, value: unknown) =>
+    extensionStorageSet(appId, key, value),
+  )
+  ipcMain.handle('extensions:storage-delete', (_e, appId: string, key: string) =>
+    extensionStorageDelete(appId, key),
+  )
+  ipcMain.handle('extensions:storage-keys', (_e, appId: string) => extensionStorageKeys(appId))
+}
+```
+
+- [ ] **Step 4: Register it**
+
+In `src/main/ipc/index.ts`, add the import alongside the others:
+
+```ts
+import { registerExtensionsIpc } from '@main/ipc/extensions.js'
+```
+
+and the call at the end of `registerAllIpc`, after `registerWorkflowIpc(deps.workflowBridge)`:
+
+```ts
+  registerExtensionsIpc()
+```
+
+- [ ] **Step 5: Write the preload domain**
+
+Create `src/preload/api/extensions.ts`:
+
+```ts
+import { ipcRenderer } from 'electron'
+
+export const extensionsApi = {
+  extensionStorageGet: (appId: string, key: string): Promise<unknown> =>
+    ipcRenderer.invoke('extensions:storage-get', appId, key),
+  extensionStorageSet: (appId: string, key: string, value: unknown): Promise<void> =>
+    ipcRenderer.invoke('extensions:storage-set', appId, key, value),
+  extensionStorageDelete: (appId: string, key: string): Promise<void> =>
+    ipcRenderer.invoke('extensions:storage-delete', appId, key),
+  extensionStorageKeys: (appId: string): Promise<string[]> =>
+    ipcRenderer.invoke('extensions:storage-keys', appId),
+}
+```
+
+In `src/preload/api/index.ts` add the import and spread it last:
+
+```ts
+import { extensionsApi } from '@preload/api/extensions.js'
+// …
+  ...workflowsApi,
+  ...extensionsApi,
+}
+```
+
+- [ ] **Step 6: Verify**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Manual smoke**
+
+```bash
+npm run dev
+```
+
+In the renderer DevTools console:
+
+```js
+await window.api.extensionStorageSet('timer', 'presets', [5, 15, 25])
+await window.api.extensionStorageGet('timer', 'presets')   // → [5, 15, 25]
+await window.api.extensionStorageKeys('timer')             // → ['presets']
+```
+
+Then confirm on disk:
+
+```bash
+cat ~/.config/agent-code/extensions/timer/state.json
+```
+
+Expected: `{ "presets": [5, 15, 25] }`. Also confirm rejection:
+
+```js
+await window.api.extensionStorageGet('../evil', 'x')       // → throws InvalidAppIdError
+```
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/main/extensions/storage.ts src/main/ipc/extensions.ts \
+        src/main/storage/paths.ts src/main/ipc/index.ts \
+        src/preload/api/extensions.ts src/preload/api/index.ts
+git commit -m "feat(extensions): per-app main-owned storage
+
+Namespaced JSON state per app id under STATE_DIR/extensions/<id>/, atomic
+temp+rename. Ids are validated, not sanitized: an id becomes a directory
+name, so a permissive id is a traversal primitive and sanitizing would
+silently collapse distinct ids onto one directory.
+
+Deliberately NOT the zustand-persist Settings store — app-state/store.ts:35-57
+records that a forgotten persist version bump black-screened launch twice
+(#249), and extension data is authored outside the app's release cycle.
+
+appId is a namespace here, not authority: Stage 1 apps share one WebContents
+so the sender cannot distinguish them. It becomes enforceable in Stage 2.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 2: `AgentCodeApiV1` — the ABI
+
+**Files:**
+- Create: `src/renderer/src/apps/api/types.ts`
+- Create: `src/renderer/src/apps/api/useAppHostApi.ts`
+
+**Interfaces:**
+- Consumes: `window.api.extensionStorage*` (Task 1), `useGlobalToast` from `@renderer/ui/GlobalToast`.
+- Produces: `AgentCodeApiV1` type and `useAppHostApi(appId: string, onClose: () => void): AgentCodeApiV1`.
+
+- [ ] **Step 1: Define the ABI**
+
+Create `src/renderer/src/apps/api/types.ts`:
+
+```ts
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+
+/**
+ * The Agent Code app host API, version 1.
+ *
+ * WHY this exists at all in a stage where apps are compiled in and could simply
+ * import `useAppStore`: this object IS the migration boundary. An app that talks
+ * only through it can move out of this repo — into a runtime-loaded bundle or an
+ * iframe — with zero edits. An app that reaches into `@renderer/*` cannot, and the
+ * cost of discovering that is a rewrite of every app at once. The rule is binary
+ * and grep-checkable, which is the only kind of architectural rule that survives.
+ *
+ * WHY every method returns a Promise, including ones that could be synchronous:
+ * under a future postMessage transport nothing can be synchronous, and a signature
+ * cannot be made async later without touching every call site in every app. This
+ * costs nothing today and is the single highest-value forward-compatibility
+ * decision in the design.
+ *
+ * WHY the surface is this small: it is Tier 0 from the API consultation —
+ * everything an app can have without asking for consent. Workspace, session,
+ * transcript, git, and network access are Tiers 1-3, each gated on a manifest
+ * capability that does not exist yet. Adding one before a real app needs it means
+ * guessing at a contract with no consumer to validate it against.
+ */
+export interface AgentCodeApiV1 {
+  readonly extension: {
+    readonly id: string
+    readonly apiVersion: 1
+  }
+
+  readonly storage: {
+    get<T extends JsonValue>(key: string): Promise<T | undefined>
+    set(key: string, value: JsonValue): Promise<void>
+    delete(key: string): Promise<void>
+    keys(): Promise<string[]>
+  }
+
+  readonly ui: {
+    /** Close this app's view. */
+    close(): Promise<void>
+    /** Transient app-wide toast. Not an OS notification — that is Tier 3. */
+    showToast(message: string): Promise<void>
+  }
+
+  readonly theme: {
+    /**
+     * Resolved `--theme-*` custom properties. Apps should prefer plain CSS
+     * (`var(--theme-surface)`) — those cascade for free today and keep working
+     * across a frame boundary once the host pushes them. This accessor exists
+     * only for imperative consumers (canvas, inline SVG fills).
+     */
+    tokens(): Promise<Record<string, string>>
+  }
+}
+```
+
+- [ ] **Step 2: Build the host instance**
+
+Create `src/renderer/src/apps/api/useAppHostApi.ts`:
+
+```ts
+import { useMemo } from 'react'
+
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
+
+import type { AgentCodeApiV1, JsonValue } from '@renderer/apps/api/types'
+
+/**
+ * Builds the AgentCodeApiV1 instance handed to one app.
+ *
+ * WHY a hook and not a module-level singleton: `showToast` comes from React
+ * context (ui/GlobalToast.tsx), and `close` is the host's own state action. Both
+ * are per-mount. The app never sees either of those origins — it sees the ABI.
+ *
+ * WHY appId is closed over rather than passed per call: the app must not be able
+ * to name a different app's namespace. In Stage 1 that is a convention enforced by
+ * this closure; in Stage 2 it becomes enforceable because each app gets its own
+ * frame and the main process derives the id from the sender instead.
+ */
+export function useAppHostApi(appId: string, onClose: () => void): AgentCodeApiV1 {
+  const { showToast } = useGlobalToast()
+
+  return useMemo<AgentCodeApiV1>(
+    () => ({
+      extension: { id: appId, apiVersion: 1 },
+
+      storage: {
+        get: async <T extends JsonValue>(key: string): Promise<T | undefined> =>
+          (await window.api.extensionStorageGet(appId, key)) as T | undefined,
+        set: (key: string, value: JsonValue) =>
+          window.api.extensionStorageSet(appId, key, value),
+        delete: (key: string) => window.api.extensionStorageDelete(appId, key),
+        keys: () => window.api.extensionStorageKeys(appId),
+      },
+
+      ui: {
+        close: async () => {
+          onClose()
+        },
+        showToast: async (message: string) => {
+          showToast(message)
+        },
+      },
+
+      theme: {
+        tokens: async () => {
+          // Read from the documented token layer only (--theme-*), not the Tailwind
+          // binding layer (--color-*). The former is the stable contract; the latter
+          // is an implementation detail of how utilities are wired and would make an
+          // app depend on the app's build system.
+          const style = getComputedStyle(document.documentElement)
+          const out: Record<string, string> = {}
+          for (const sheet of Array.from(document.styleSheets)) {
+            let rules: CSSRuleList
+            try {
+              rules = sheet.cssRules
+            } catch {
+              continue // cross-origin stylesheet (webfonts); nothing to read
+            }
+            for (const rule of Array.from(rules)) {
+              if (!(rule instanceof CSSStyleRule)) continue
+              for (const prop of Array.from(rule.style)) {
+                if (prop.startsWith('--theme-')) {
+                  out[prop] = style.getPropertyValue(prop).trim()
+                }
+              }
+            }
+          }
+          return out
+        },
+      },
+    }),
+    [appId, onClose, showToast],
+  )
+}
+```
+
+- [ ] **Step 3: Verify**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS. There are no consumers yet — this task's deliverable is the contract.
+
+`TEST-SITE:` `src/renderer/src/apps/api/useAppHostApi.renderer.test.tsx` — storage calls carry the closed-over appId; `close` invokes `onClose`.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/renderer/src/apps/api/
+git commit -m "feat(extensions): AgentCodeApiV1, the app host ABI
+
+The migration boundary, defined before it has consumers. An app that talks
+only through this object moves out of the repo in Stage 2 unchanged; an app
+that reaches into @renderer/* cannot, and finding that out later means
+rewriting every app at once.
+
+Every method returns a Promise even where it could be synchronous — a future
+postMessage transport cannot be made sync, and widening a signature later
+touches every call site in every app. Free now, expensive later.
+
+Surface is Tier 0 only: storage, close, toast, theme tokens. Workspace,
+session, git and network are Tiers 1-3 and stay unrepresentable until a real
+app needs them and a capability model exists to gate them.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 3: The apps host — definition, registry, state, surface
+
+**Files:**
+- Create: `src/renderer/src/apps/types.ts`
+- Create: `src/renderer/src/apps/registry.ts`
+- Create: `src/renderer/src/apps/surfaces/AppHostSurface.tsx`
+- Modify: `src/renderer/src/app-state/uiShell/types.ts`
+- Modify: `src/renderer/src/app-state/uiShell/slice.ts`
+- Modify: `src/renderer/src/app/surfaces/registry.tsx`
+- Modify: `src/renderer/src/components/ui/README.md`
+
+**Interfaces:**
+- Consumes: `AgentCodeApiV1` + `useAppHostApi` (Task 2).
+- Produces: `AppDefinition`, `APPS`, `APP_BY_ID`, `AppHostSurface`, and on the store: `openAppId: string | null`, `openApp(appId)`, `closeApp()`.
+
+- [ ] **Step 1: Define `AppDefinition`**
+
+Create `src/renderer/src/apps/types.ts`:
+
+```ts
+import type { ComponentType } from 'react'
+
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+/**
+ * One built-in app.
+ *
+ * WHY every field except `Component` is JSON-expressible: this shape is
+ * deliberately the target a future out-of-tree manifest resolves INTO. Keeping it
+ * a strict superset-by-one of a manifest is what makes Stage 2 a swap — the loader
+ * produces `Component`, everything else is read from disk. Adding a host-only
+ * field here (`getWorkspace: () => Workspace`, a store selector, a React context)
+ * silently converts this from a manifest target into a host-only interface, and
+ * that IS the substrate-to-tear-out this staging exists to prevent.
+ */
+export type AppDefinition = {
+  /**
+   * Stable id. Becomes the command id (`app.open.<id>`), the value stored in
+   * `openAppId`, and the on-disk state directory name. Renaming it orphans saved
+   * state and breaks muscle memory — treat as permanent. Must satisfy the same
+   * pattern main enforces: /^[a-z][a-z0-9-]{0,63}$/.
+   */
+  id: string
+  title: string
+  /**
+   * REQUIRED and non-empty: this becomes the palette command's description, and
+   * buildCommandRegistry throws on a blank one (features/command-palette/registry.ts).
+   * A missing description is a launch crash, not a lint warning.
+   */
+  description: string
+  keywords?: string[]
+  /**
+   * The app's UI.
+   *
+   * WHY exactly one prop, unlike SurfaceEntry.Component which takes none: for a
+   * first-party surface, propless is right because it can read the store directly.
+   * For an app the opposite is true — the prop IS the boundary that makes it
+   * portable. `api` is the only thing an app is allowed to depend on.
+   */
+  Component: ComponentType<{ api: AgentCodeApiV1 }>
+}
+```
+
+- [ ] **Step 2: Create the registry**
+
+Create `src/renderer/src/apps/registry.ts`:
+
+```ts
+import type { AppDefinition } from '@renderer/apps/types'
+
+// Adding an app = ONE import + ONE array entry, matching
+// app/surfaces/registry.tsx and features/command-palette/registry.ts. An explicit
+// import list is grep-able and compiler-checked; side-effect self-registration is
+// neither, and makes load order load-bearing.
+//
+// Stage 2 note: this becomes `[...BUILTIN_APPS, ...loadedApps]`. Nothing else in
+// the apps/ directory needs to change for that — which is the point.
+export const APPS: AppDefinition[] = []
+
+export const APP_BY_ID = new Map<string, AppDefinition>(APPS.map(app => [app.id, app]))
+```
+
+- [ ] **Step 3: Add the store field**
+
+In `src/renderer/src/app-state/uiShell/types.ts`, next to `agentViewModePickerSessionId`:
+
+```ts
+  /**
+   * Non-null when a built-in app is open; the value is its AppDefinition id.
+   *
+   * WHY one nullable id rather than one boolean per app: apps are mutually
+   * exclusive by construction — a single host surface renders one at a time — and
+   * N booleans would let two be true, a state the host cannot express. Same shape
+   * as rewindPromptSessionId above.
+   *
+   * WHY uiShell (in-memory) and not persisted Settings: an app open across a
+   * restart is not desirable, and more importantly extension-adjacent data must
+   * never enter the zustand-persist blob (see app-state/store.ts:35-57, #249).
+   */
+  openAppId: string | null
+```
+
+and in the actions section of the same file, alongside `openRewindPrompt`/`closeRewindPrompt`:
+
+```ts
+  openApp: (appId: string) => void
+  closeApp: () => void
+```
+
+- [ ] **Step 4: Add the slice implementation**
+
+In `src/renderer/src/app-state/uiShell/slice.ts`, add to the initial state block next to `agentViewModePickerSessionId: null,`:
+
+```ts
+  openAppId: null,
+```
+
+and next to `openRewindPrompt` / `closeRewindPrompt`:
+
+```ts
+  openApp: appId => set({ openAppId: appId }, false, 'uiShell/openApp'),
+  closeApp: () => set({ openAppId: null }, false, 'uiShell/closeApp'),
+```
+
+- [ ] **Step 5: Write the host surface**
+
+Create `src/renderer/src/apps/surfaces/AppHostSurface.tsx`:
+
+```tsx
+import { useCallback } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import { Dialog, DialogContent, DialogTitle } from '@renderer/components/ui/dialog'
+import { useAppHostApi } from '@renderer/apps/api/useAppHostApi'
+import { APP_BY_ID } from '@renderer/apps/registry'
+import type { AppDefinition } from '@renderer/apps/types'
+
+/**
+ * The single surface entry that hosts every built-in app.
+ *
+ * WHY DialogContent rather than a hand-rolled shell: it mounts
+ * data-agent-code-interaction-owner="app" for exactly the interval Radix traps
+ * focus (components/ui/dialog.tsx:52-60). Without that marker, typing in an app's
+ * input can leak Enter/paste into a background agent composer — the exact failure
+ * components/ui/README.md records from the old composer guards. An app gets that
+ * protection for free and cannot forget it.
+ *
+ * WHY the split into an inner component: useAppHostApi is a hook, so it cannot be
+ * called conditionally after the `if (!app) return null` guard.
+ */
+export function AppHostSurface() {
+  const openAppId = useAppStore(state => state.openAppId)
+  const app = openAppId ? APP_BY_ID.get(openAppId) : undefined
+
+  // An unknown id degrades to closed, deliberately unlike
+  // providers/registry.renderer.ts:53 which throws on an unknown pane kind. That
+  // throw is right there — a pane with no renderer is a broken workspace and must
+  // be loud. It is wrong here: openAppId can hold a stale id after an app is
+  // removed, and throwing inside a surface App.tsx mounts unconditionally is the
+  // #249 black-screen failure mode.
+  if (!app) return null
+
+  return <OpenApp app={app} />
+}
+
+function OpenApp({ app }: { app: AppDefinition }) {
+  const closeApp = useAppStore(state => state.closeApp)
+  const onClose = useCallback(() => closeApp(), [closeApp])
+  const api = useAppHostApi(app.id, onClose)
+
+  return (
+    <Dialog
+      open
+      onOpenChange={open => {
+        if (!open) closeApp()
+      }}
+    >
+      <DialogContent showCloseButton>
+        <DialogTitle className="sr-only">{app.title}</DialogTitle>
+        <app.Component api={api} />
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+- [ ] **Step 6: Register the surface**
+
+In `src/renderer/src/app/surfaces/registry.tsx`, add the import with the others:
+
+```tsx
+import { AppHostSurface } from '@renderer/apps/surfaces/AppHostSurface'
+```
+
+and append to the END of `modalSurfaces`, after `{ id: 'usage', … }`:
+
+```tsx
+  // Built-in apps host. Last in the modal stack, which per the paint-order rule
+  // above means it paints above everything already mounted. That is correct rather
+  // than incidental: an app is always user-initiated from the palette and is the
+  // thing awaiting input while open, so nothing already on screen should cover it.
+  { id: 'app-host', Component: AppHostSurface },
+```
+
+- [ ] **Step 7: Record the guardrail reading**
+
+`components/ui/README.md` forbids "a generic modal schema, JSON-driven form renderer, or surface factory." Append to that section:
+
+```markdown
+### Why the apps host is not a surface factory
+
+`apps/surfaces/AppHostSurface` renders one of N app components inside a standard
+`DialogContent`. It does not generate surfaces, synthesize shells from schemas, or
+introduce a second modal mechanism — it is one ordinary registry entry that
+switches on `openAppId`. The guardrail targets first-party component proliferation,
+where a factory hides which surfaces exist; here the surfaces are a single
+compile-time array (`apps/registry.ts`) that is as greppable as the registry it
+sits beside.
+
+Worth noting for whoever revisits this: the runtime-loaded and iframe hosting
+options both *would* require a genuine factory — a loader producing mount points
+from manifests. This guardrail is an argument for the compiled-in staging, not
+against it.
+```
+
+- [ ] **Step 8: Verify**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS.
+
+```bash
+npm run dev
+```
+
+Expected: app launches and looks **completely unchanged** — `APPS` is empty, so `AppHostSurface` always returns `null`. In DevTools:
+
+```js
+// no visible change, and no crash:
+window.__ZUSTAND_DEVTOOLS__ // not required; instead confirm via the app not erroring
+```
+
+The real check is that nothing regressed: open the command palette (Cmd+Shift+P), open Settings, press Escape in each. All must behave as before.
+
+`TEST-SITE:` `src/renderer/src/apps/surfaces/AppHostSurface.renderer.test.tsx` — unknown id renders null rather than throwing; `onOpenChange(false)` clears `openAppId`.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/renderer/src/apps/ src/renderer/src/app-state/uiShell/ \
+        src/renderer/src/app/surfaces/registry.tsx \
+        src/renderer/src/components/ui/README.md
+git commit -m "feat(extensions): apps host surface, registry and store field
+
+One surface entry hosts every app. AppDefinition is deliberately
+serializable-plus-one so it is the shape a future manifest resolves into —
+the loader would produce Component and read the rest from disk.
+
+Apps mount inside DialogContent so they inherit the interaction-ownership
+marker for exactly the focus-trap interval. Without it an app's input can
+leak Enter/paste into a background agent composer, which is the failure
+components/ui/README.md records from the old composer guards.
+
+Unknown openAppId degrades to closed rather than throwing — unlike the
+provider pane registry, which is right to throw. A stale id here would
+otherwise be a #249-class black screen inside an unconditionally mounted
+surface.
+
+Registry is empty; no user-visible change yet.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 4: The Timer app
+
+**Files:**
+- Create: `src/renderer/src/apps/timer/index.ts`
+- Create: `src/renderer/src/apps/timer/ui/TimerApp.tsx`
+- Modify: `src/renderer/src/apps/registry.ts`
+
+**Interfaces:**
+- Consumes: `AgentCodeApiV1` (Task 2), `AppDefinition` (Task 3).
+- Produces: `timerApp: AppDefinition`, registered in `APPS`.
+
+- [ ] **Step 1: Write the UI**
+
+Create `src/renderer/src/apps/timer/ui/TimerApp.tsx`. **Note the import list — `react` and the ABI type, nothing else. That constraint is the whole point of the app.**
+
+```tsx
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+const DEFAULT_PRESETS = [5, 15, 25] as const
+
+function formatRemaining(totalSeconds: number): string {
+  const safe = Math.max(0, totalSeconds)
+  const minutes = Math.floor(safe / 60)
+  const seconds = safe % 60
+  return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`
+}
+
+export function TimerApp({ api }: { api: AgentCodeApiV1 }) {
+  const [presets, setPresets] = useState<number[]>([...DEFAULT_PRESETS])
+  const [remaining, setRemaining] = useState(0)
+  const [running, setRunning] = useState(false)
+
+  // Deadline-based rather than decrement-based: a setInterval that subtracts 1 each
+  // tick drifts, and drifts badly when the renderer is throttled or the machine
+  // sleeps. Storing the wall-clock deadline means a late tick self-corrects.
+  const deadlineRef = useRef<number | null>(null)
+
+  useEffect(() => {
+    void api.storage.get<number[]>('presets').then(saved => {
+      if (Array.isArray(saved) && saved.every(n => typeof n === 'number')) setPresets(saved)
+    })
+  }, [api])
+
+  useEffect(() => {
+    if (!running) return
+    const id = setInterval(() => {
+      const deadline = deadlineRef.current
+      if (deadline == null) return
+      const left = Math.round((deadline - Date.now()) / 1000)
+      if (left <= 0) {
+        setRemaining(0)
+        setRunning(false)
+        deadlineRef.current = null
+        void api.ui.showToast('Timer finished')
+        return
+      }
+      setRemaining(left)
+    }, 250)
+    return () => clearInterval(id)
+  }, [running, api])
+
+  const start = useCallback((minutes: number) => {
+    deadlineRef.current = Date.now() + minutes * 60_000
+    setRemaining(minutes * 60)
+    setRunning(true)
+  }, [])
+
+  const stop = useCallback(() => {
+    setRunning(false)
+    deadlineRef.current = null
+    setRemaining(0)
+  }, [])
+
+  return (
+    <div className="flex flex-col items-center gap-6 px-8 py-10">
+      <div
+        className="font-mono tabular-nums"
+        style={{
+          fontSize: '64px',
+          lineHeight: 1,
+          color: remaining === 0 && !running ? 'var(--theme-muted)' : 'var(--theme-ink)',
+        }}
+      >
+        {formatRemaining(remaining)}
+      </div>
+
+      <div className="flex gap-2">
+        {presets.map(minutes => (
+          <button
+            key={minutes}
+            type="button"
+            onClick={() => start(minutes)}
+            className="px-3 py-1.5 text-[13px] outline-none"
+            style={{
+              background: 'var(--theme-control-bg)',
+              color: 'var(--theme-control-fg)',
+              border: '1px solid var(--theme-control-border)',
+            }}
+          >
+            {minutes}m
+          </button>
+        ))}
+      </div>
+
+      <div className="flex gap-2">
+        <button
+          type="button"
+          onClick={stop}
+          disabled={!running}
+          className="px-4 py-1.5 text-[13px] outline-none disabled:opacity-40"
+          style={{
+            background: 'var(--theme-accent)',
+            color: 'var(--theme-accent-fg)',
+            border: '1px solid var(--theme-accent)',
+          }}
+        >
+          Stop
+        </button>
+        <button
+          type="button"
+          onClick={() => void api.ui.close()}
+          className="px-4 py-1.5 text-[13px] outline-none"
+          style={{
+            background: 'transparent',
+            color: 'var(--theme-ink-dim)',
+            border: '1px solid var(--theme-border)',
+          }}
+        >
+          Close
+        </button>
+      </div>
+    </div>
+  )
+}
+```
+
+Note the inline `var(--theme-*)` styles rather than Tailwind utilities (`bg-surface`). Tailwind utilities are a build-time binding that will not exist once this file lives in another repo; the token names will. This is the app obeying its own portability rule.
+
+- [ ] **Step 2: Write the definition**
+
+Create `src/renderer/src/apps/timer/index.ts`:
+
+```ts
+import type { AppDefinition } from '@renderer/apps/types'
+
+import { TimerApp } from '@renderer/apps/timer/ui/TimerApp'
+
+export const timerApp: AppDefinition = {
+  id: 'timer',
+  title: 'Timer',
+  description: 'Countdown timer with presets. Toasts when it finishes.',
+  keywords: ['timer', 'countdown', 'pomodoro', 'clock', 'focus'],
+  Component: TimerApp,
+}
+```
+
+- [ ] **Step 3: Register it**
+
+In `src/renderer/src/apps/registry.ts`:
+
+```ts
+import type { AppDefinition } from '@renderer/apps/types'
+
+import { timerApp } from '@renderer/apps/timer'
+
+export const APPS: AppDefinition[] = [timerApp]
+
+export const APP_BY_ID = new Map<string, AppDefinition>(APPS.map(app => [app.id, app]))
+```
+
+- [ ] **Step 4: Verify the portability constraint**
+
+```bash
+grep -rn "@renderer/" src/renderer/src/apps/timer/
+```
+
+Expected: **exactly two matches**, both importing `apps/api/types` or `apps/types` — which are the ABI, not app internals. Any other `@renderer/*` import is a violation and must be removed before committing.
+
+- [ ] **Step 5: Verify build**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Manual smoke**
+
+```bash
+npm run dev
+```
+
+In DevTools console, open it directly (the palette command lands in Task 5):
+
+```js
+// the store is not exposed globally; instead verify via Task 5.
+```
+
+Since there is no opener yet, temporarily verify by setting the initial value in `uiShell/slice.ts` to `openAppId: 'timer'`, running `npm run dev`, confirming the Timer renders, then **reverting that line**. Confirm:
+- the digits use the theme ink color and switch with Cmd+Shift+ theme changes
+- clicking `5m` counts down
+- `Stop` resets
+- `Close` dismisses the dialog
+- Escape dismisses the dialog
+
+`TEST-SITE:` `src/renderer/src/apps/timer/ui/TimerApp.renderer.test.tsx` — `formatRemaining` boundaries; deadline math does not drift under fake timers.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/renderer/src/apps/timer/ src/renderer/src/apps/registry.ts
+git commit -m "feat(extensions): Timer app, the first AgentCodeApiV1 consumer
+
+Imports react and the ABI type. Nothing else — verified by grep, and that
+grep is the migration test: this directory should move to its own repo in
+Stage 2 without a single edit inside it.
+
+Styles use var(--theme-*) rather than Tailwind utilities on purpose. The
+utilities are a build-time binding that will not exist out-of-tree; the token
+names will, and the host can push them across a frame boundary.
+
+Countdown is deadline-based, not decrement-based: a per-tick subtraction
+drifts under renderer throttling and breaks outright across sleep.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 5: Palette commands
+
+**Files:**
+- Create: `src/renderer/src/apps/commands/appCommands.ts`
+- Modify: `src/renderer/src/features/command-palette/types.ts`
+- Modify: `src/renderer/src/features/command-palette/registry.ts`
+
+**Interfaces:**
+- Consumes: `APPS` (Task 3/4), `CommandDef` from the palette.
+- Produces: `appCommands: CommandDef[]`, and `openApp` on `CommandContext.ui`.
+
+- [ ] **Step 1: Extend the command context type**
+
+In `src/renderer/src/features/command-palette/types.ts`, inside the `ui: { … }` block, next to `openRewindPrompt`:
+
+```ts
+    /** Open a built-in app by AppDefinition id. The host surface resolves the
+     *  id; an unknown id closes rather than throws. */
+    openApp: (appId: string) => void
+```
+
+- [ ] **Step 2: Write the derived commands**
+
+Create `src/renderer/src/apps/commands/appCommands.ts`:
+
+```ts
+import type { CommandDef } from '@renderer/features/command-palette/types'
+
+import { APPS } from '@renderer/apps/registry'
+
+// Derived, not hand-written: N apps produce N commands with zero per-app
+// boilerplate, and an app physically cannot ship without a way to open it. This
+// mapping is the whole "one command module supports N apps" claim, and it is what
+// keeps adding an app to one import plus one array entry.
+export const appCommands: CommandDef[] = APPS.map(app => ({
+  id: `app.open.${app.id}`,
+  title: `Open ${app.title}`,
+  description: app.description,
+  surface: 'app',
+  keywords: app.keywords ?? [],
+  run: ({ ui }) => {
+    ui.openApp(app.id)
+    ui.closePalette()
+  },
+}))
+```
+
+- [ ] **Step 3: Register them**
+
+In `src/renderer/src/features/command-palette/registry.ts`, add the import and spread it after `...usageCommands`:
+
+```ts
+import { appCommands } from '@renderer/apps/commands/appCommands'
+// …
+  ...usageCommands,
+  ...appCommands,
+]
+```
+
+- [ ] **Step 4: Wire the callback**
+
+`CommandContext.ui` is built in `src/renderer/src/features/command-palette/ui/CommandPalette.tsx`. Two edits in that file.
+
+First, next to the other store selectors around **line 193** (`const openRewindPrompt = useAppStore(state => state.openRewindPrompt)`):
+
+```ts
+  const openApp = useAppStore(state => state.openApp)
+```
+
+Second, in the `ui: { … }` object literal that ends at **line 525** with `closePalette: onClose,` — the literal uses shorthand for every store action, so add the shorthand alongside them, immediately before `closePalette`:
+
+```ts
+        openApp,
+        closePalette: onClose,
+```
+
+- [ ] **Step 5: Verify**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS. If `openApp` is missing from any object literal implementing `CommandContext['ui']`, TypeScript will name the file — that is the intended safety net.
+
+- [ ] **Step 6: Manual smoke — the end-to-end check**
+
+```bash
+npm run dev
+```
+
+1. Cmd+Shift+P → type `timer` → **`Open Timer` appears**
+2. Enter → palette closes, Timer opens
+3. Click `15m` → counts down
+4. Escape → closes
+5. Reopen → **presets persisted** (set one via DevTools `window.api.extensionStorageSet('timer','presets',[1,2,3])` first, then reopen)
+6. Let a 1-minute timer finish → **toast appears**
+7. With the Timer open, press Cmd+W → **the pane closes, the window does not** (confirms the interaction-ownership marker is doing its job)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/renderer/src/apps/commands/ \
+        src/renderer/src/features/command-palette/types.ts \
+        src/renderer/src/features/command-palette/registry.ts
+git commit -m "feat(extensions): derive palette commands from the app registry
+
+One .map over APPS, so an app cannot ship without an opener and adding an app
+stays one import plus one array entry. buildCommandRegistry already recomputes
+per context change, so nothing else needed touching.
+
+Adding openApp to CommandContext.ui makes the compiler name every object
+literal that implements the context — the intended safety net rather than a
+runtime surprise.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Task 6: Settings → Apps row
+
+**Files:**
+- Modify: `src/renderer/src/features/settings/lib/settingsRegistry.ts`
+- Modify: `src/renderer/src/features/settings/lib/settingsCategories.ts:1-7`
+- Create: `src/renderer/src/apps/ui/AppsSettingsRow.tsx`
+- Modify: `src/renderer/src/features/settings/ui/SettingsList.tsx:220`
+
+**Interfaces:**
+- Consumes: `APPS` (Task 3/4), store `openApp`.
+- Produces: an `{ type: 'apps' }` settings control.
+
+- [ ] **Step 1: Read the marker pattern before writing anything**
+
+```bash
+sed -n '95,140p' src/renderer/src/features/settings/lib/settingsRegistry.ts
+sed -n '570,600p' src/renderer/src/features/settings/lib/settingsRegistry.ts
+sed -n '210,230p' src/renderer/src/features/settings/ui/SettingsList.tsx
+cat src/renderer/src/features/cli-updates/CliUpdateBehaviorRow.tsx
+```
+
+Three existing markers (`cli-update-behavior`, `theme-picker`, `dictation-api-key`) have a value living outside the `Settings` store and are rendered by self-subscribing components. `CliUpdateBehaviorRow.tsx:18` documents the pattern explicitly. This task adds a fourth instance — **read all of the above before writing** and match `cli-update-behavior`, which is the closest in shape (a marker with no `getValue`/`onChange` at all).
+
+- [ ] **Step 2: Add the control type and registry entry**
+
+Add `'apps'` to the control-type union in `settingsRegistry.ts`, then add the entry:
+
+```ts
+  {
+    id: 'apps.installed',
+    category: 'apps',
+    title: 'Apps',
+    description: 'Built-in apps available from the command palette.',
+    // Marker: the row is rendered by AppsSettingsRow, which reads the compiled-in
+    // registry directly. There is no getValue/onChange because there is no setting
+    // — this is a listing. Stage 3 turns it into the install/enable surface.
+    control: { type: 'apps' },
+  },
+```
+
+Then add `'apps'` to the `SettingCategoryId` union in `settingsCategories.ts:1-7`, which currently reads:
+
+```ts
+export type SettingCategoryId =
+  | 'appearance'
+  | 'workspace'
+  | 'commands'
+  | 'dictation'
+  | 'experimental'
+  | 'safety'
+  | 'apps'
+```
+
+and add the matching entry to the `SettingCategory[]` array in the same file:
+
+```ts
+  {
+    id: 'apps',
+    label: 'Apps',
+    description: 'Built-in apps available from the command palette.',
+  },
+```
+
+- [ ] **Step 3: Write the row**
+
+Create `src/renderer/src/apps/ui/AppsSettingsRow.tsx`:
+
+```tsx
+import { useAppStore } from '@renderer/app-state/hooks'
+import { APPS } from '@renderer/apps/registry'
+
+// Stage 1 is a listing, not a manager: apps are compiled in, so there is nothing
+// to install, enable, or remove. Building toggles now would be UI for a state that
+// cannot vary. Stage 3 replaces the body of this component and keeps its slot.
+export function AppsSettingsRow() {
+  const openApp = useAppStore(state => state.openApp)
+
+  return (
+    <div className="flex flex-col gap-1">
+      {APPS.map(app => (
+        <div key={app.id} className="flex items-center justify-between gap-4 py-1">
+          <div className="min-w-0">
+            <div className="text-[13px] text-ink">{app.title}</div>
+            <div className="truncate text-[12px] text-muted">{app.description}</div>
+          </div>
+          <button
+            type="button"
+            onClick={() => openApp(app.id)}
+            className="shrink-0 border border-control-border bg-control-bg px-3 py-1 text-[12px] text-control-fg outline-none hover:border-control-border-hover"
+          >
+            Open
+          </button>
+        </div>
+      ))}
+      {APPS.length === 0 ? <div className="text-[12px] text-muted">No apps installed.</div> : null}
+    </div>
+  )
+}
+```
+
+This file is host UI, not app code, so it uses Tailwind utilities normally — the portability rule applies to `apps/<id>/`, not to `apps/ui/`.
+
+- [ ] **Step 4: Render the marker**
+
+In `src/renderer/src/features/settings/ui/SettingsList.tsx`, next to line 220 which reads:
+
+```tsx
+          {control.type === 'cli-update-behavior' ? <CliUpdateBehaviorRow /> : null}
+```
+
+add the sibling branch:
+
+```tsx
+          {control.type === 'apps' ? <AppsSettingsRow /> : null}
+```
+
+and the import at the top of that file:
+
+```tsx
+import { AppsSettingsRow } from '@renderer/apps/ui/AppsSettingsRow'
+```
+
+- [ ] **Step 5: Verify**
+
+```bash
+npm run typecheck
+```
+
+Expected: PASS — the control-type union is closed, so a missing branch is a compile error.
+
+- [ ] **Step 6: Manual smoke**
+
+`npm run dev` → open Settings → **Apps** category → Timer listed with its description → `Open` launches it → Settings' own Escape still closes Settings and not something else.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/renderer/src/apps/ui/ src/renderer/src/features/settings/
+git commit -m "feat(extensions): Settings > Apps listing
+
+Fourth instance of the existing self-subscribing marker pattern
+(cli-update-behavior, theme-picker, dictation-api-key) — the value lives
+outside the Settings store, so there is no getValue/onChange to hoist.
+
+A listing, not a manager: apps are compiled in, so enable/remove toggles
+would be UI for state that cannot vary. Stage 3 replaces this component's
+body and keeps its slot.
+
+Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>"
+```
+
+---
+
+## Done — and the test that decides whether Stage 1 was honest
+
+After Task 6, run the migration rehearsal. It costs five minutes and it is the only real check on this whole design:
+
+```bash
+grep -rn "@renderer/" src/renderer/src/apps/timer/
+```
+
+**Expected: only imports of `apps/api/types` and `apps/types`.**
+
+If that holds, the Timer directory can be lifted into its own repository in Stage 2 and loaded through `agent-code-ext://` with **no edits inside it**. If it does not hold, Stage 1 built a substrate that Stage 2 would have to tear out — fix it now, while there is exactly one app, rather than later when there are six.
+
+---
+
+## Stage 2 — deliberately not planned here
+
+Stage 2 (runtime loading via a privileged `agent-code-ext://` scheme) is **conditional, not scheduled**. Its trigger is specific: *extensions shipping to people who run packaged releases.* The owner runs `npm start` against a local build and rebuilds routinely, so Stage 1 is sufficient for personal use indefinitely.
+
+When it is triggered, the investigation and consultation already established:
+
+- The loader is one line — `await import(/* @vite-ignore */ \`agent-code-ext://${id}/${entry}\`)`. Monaco already performs a fully runtime-variable dynamic import in the shipped bundle (`out/renderer/assets/editor.main-*.js`), and 92 language chunks load via ESM dynamic import from `file://` in production, so both halves of the risk are empirically retired.
+- React is injected through the host object; the extension's own Vite config marks `react` external. ~2 hours.
+- The scheme needs `standard: true, secure: true, supportFetchAPI: true, corsEnabled: true`, registered before `app.whenReady()`, plus a realpath containment check and an explicit `access-control-allow-origin` header — module scripts are always fetched in CORS mode, and missing that header is the single most likely thing to burn a day.
+- CSP becomes `script-src 'self' agent-code-ext:` (plus `connect-src` if apps fetch their own assets). `worker-src` must not be touched — the #513 comment above it is load-bearing.
+
+**Before any of that, run a half-day spike** proving a hello-world module loads through the scheme in **both** `npm run dev` (http://localhost origin) and a packaged build (file:// origin). Dev-only success is the trap this whole design is shaped around avoiding.
+
+The iframe option (Option C) remains available and was priced at ~350–650 LOC of bridge — keyboard routing and default suppression being the bulk, since every host shortcut dies while focus is inside a frame and Cmd+W would close the window. It becomes the right answer only when extensions come from people the owner does not trust, because it is the only option that contains an infinite loop in extension code.
diff --git a/docs/superpowers/plans/2026-07-20-extension-platform.md b/docs/superpowers/plans/2026-07-20-extension-platform.md
new file mode 100644
index 000000000..c845e98f8
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-20-extension-platform.md
@@ -0,0 +1,814 @@
+# Extension Platform — Full Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development or superpowers:executing-plans. Steps use checkbox (`- [ ]`) syntax.
+>
+> **Supersedes** `2026-07-20-extension-platform-stage1.md`, which planned a compiled-in
+> apps folder. That was built, reviewed, and the app it produced was deleted — see
+> §0. This document plans the actual product: extensions installed from a repository
+> and loaded at runtime.
+
+**Goal:** A user can paste `owner/repo` into Settings, install an extension, and run
+it — with its own UI, its own persisted state, and a documented API — without that
+extension living in this repository or requiring a rebuild.
+
+**Architecture:** The VS Code model. Extensions are ES modules on disk under
+`~/.config/agent-code/extensions/<id>/`, served to the renderer over a privileged
+`agent-code-ext://` scheme and loaded with a runtime `import()`. A manifest declares
+*contribution points* (commands, views, settings, keybindings) that reach the palette
+and Settings **without the module being loaded**; the module exports
+`activate(context)` / `deactivate()` and is imported lazily on a declared activation
+event. Views mount at the DOM level, so React is available but optional and the
+contract survives a later move into an iframe.
+
+**Tech Stack:** Electron 43 `protocol.handle`, native ESM dynamic import, zod, React 18
+(host-side only), TypeScript.
+
+---
+
+## Global Constraints
+
+- **No new committed test files.** Standing repo rule. Verification is
+  `npm run typecheck`, `npm test`, `npm run build`, and explicit manual smoke steps.
+  `TEST-SITE:` notes mark where tests would go if the rule is lifted.
+- **Every `AgentCodeApiV1` method returns a `Promise`.** No exceptions. A future
+  postMessage transport cannot be made synchronous, and widening a signature later
+  touches every call site in every extension.
+- **The renderer's `script-src` gains exactly one source: `agent-code-ext:`.**
+  Not `unsafe-eval`, not `blob:`, not `file:`. `worker-src` is not touched — the
+  `#513` comment above it is load-bearing and unrelated.
+- **An extension is never handed `window.api`.** It receives `AgentCodeApiV1`.
+- **Extension state is never in the zustand-persist `Settings` store** (#249).
+- **Bundles and state stay in separate roots.** `extensions/<id>/` is replaced
+  wholesale on update; `extension-state/<id>/` must survive it.
+- **Node 24, Electron 43.1.1.** Verify with `node -p "require('electron/package.json').version"`.
+
+---
+
+## 0. What already exists on this branch
+
+Built, typechecked, tested, and reviewed by two agents. **Do not rebuild these.**
+
+| Piece | Path | State |
+|---|---|---|
+| Host ABI | `renderer/src/apps/api/types.ts` | `AgentCodeApiV1`, Tier 0 |
+| ABI instance factory | `renderer/src/apps/api/useAppHostApi.ts` | per-extension, closes over id |
+| Resolved definition | `renderer/src/apps/types.ts` | `AppDefinition` |
+| Registry | `renderer/src/apps/registry.ts` | `APPS` — **empty, static** |
+| Host surface | `renderer/src/apps/surfaces/AppHostSurface.tsx` | Dialog + ownership marker |
+| Palette commands | `renderer/src/apps/commands/appCommands.ts` | derived from `APPS` |
+| Per-extension storage | `main/extensions/storage.ts` | serialized writes, unique temps |
+| Manifest validation | `main/extensions/manifest.ts` | zod, `SUPPORTED_API_VERSION = 1` |
+| Installer | `main/extensions/install.ts` | fetch → verify → atomic rename |
+| Install ledger | `main/extensions/ledger.ts` | `extensions.json` |
+| Settings UI | `renderer/src/apps/ui/AppsSettingsRow.tsx` | install / update / remove |
+
+### Corrections to the superseded plan, recorded so they are not repeated
+
+The Stage 1 plan claimed Stage 2 would be *"a registry swap plus a five-line
+`commandDefs` change."* An adversarial audit found that **false**. The honest list is
+§2 of this document. Specifically wrong were:
+
+- `APP_BY_ID` is a module-scope snapshot; updating `APPS` alone leaves it stale.
+- `appCommands` is a second module-scope snapshot, copied again into `commandDefs`,
+  and read a third time by `listPickerCommandMeta()` which Settings consumes.
+- `AppsSettingsRow` mapped static `APPS` (already rewritten).
+- The renderer bootstrap is synchronous — there is no point at which a loader
+  could await.
+- The plan asserted React would be *"injected through the host object"*, but
+  `AgentCodeApiV1` has no react field. §1 resolves this.
+
+### Known defects inherited from Stage 1, to fix in Phase B
+
+- **Toast is invisible.** `GlobalToast` is `z-50`; the dialog scrim is `z-[1100]` at
+  88% opacity. `api.ui.showToast` can only fire while an extension is open, so it is
+  hidden 100% of the time. Fix in Task B6.
+- **`theme.tokens()` misses runtime-only tokens.** `--theme-app-font` and
+  `--theme-font-code` are assigned by `theme.ts` at runtime and never appear in a
+  stylesheet, so the stylesheet walk in `useAppHostApi.ts` cannot find them. Fix in
+  Task B6.
+- **`JsonValue` permits `NaN`/`Infinity`**, which `JSON.stringify` silently turns
+  into `null`. Fix in Task B6.
+- **`openApp` missing from `CommandPalette`'s `useMemo` deps.** Benign today
+  (zustand actions are stable) but a stale-closure bug the moment that changes.
+
+---
+
+## 1. The contracts, decided
+
+The model is **VS Code's**: a manifest declares *contribution points*, the module
+exports `activate`/`deactivate`, activation is lazy and event-driven, and custom UI
+is a registered view rather than a single implicit page.
+
+An earlier draft of this plan proposed a single `mount(element, api)` export with the
+host auto-generating one "Open X" command. That is a degenerate case of the model
+below — one extension, one view, one command, no declarations — and it was too narrow:
+it gives an extension no way to contribute more than one command, no way to add a
+setting, no way to register a keybinding, and no way to do work without a window open.
+Recorded here because the narrower design is the tempting one and the reasons it fails
+are not obvious until you try to write a second extension.
+
+### 1.1 The manifest declares contributions
+
+`agent-code.extension.json` gains a `contributes` block. Everything an extension adds
+to the app is **declared statically**, not discovered by running it.
+
+```jsonc
+{
+  "id": "timer",
+  "name": "Timer",
+  "description": "Countdown timer with presets.",
+  "version": "1.0.0",
+  "apiVersion": 1,
+  "entry": "dist/index.js",
+
+  "activationEvents": ["onCommand:timer.start", "onView:timer.panel"],
+
+  "contributes": {
+    "commands": [
+      { "id": "timer.start",  "title": "Start Timer",  "keywords": ["pomodoro"] },
+      { "id": "timer.cancel", "title": "Cancel Timer" }
+    ],
+    "views": [
+      { "id": "timer.panel", "title": "Timer", "mount": "modal" }
+    ],
+    "settings": [
+      { "id": "timer.defaultMinutes", "title": "Default duration",
+        "type": "number", "default": 25 }
+    ],
+    "keybindings": [
+      { "command": "timer.start", "key": "cmd+shift+t" }
+    ]
+  }
+}
+```
+
+**WHY declarations rather than registration-by-execution:** the palette, Settings, and
+the keybinding router must know what exists *before* the extension has run — otherwise
+every extension has to be loaded at startup just to populate a command list, and lazy
+activation becomes impossible. This is the same reason VS Code puts `contributes` in
+`package.json` rather than making everything an `activate()` side effect. It also
+means a broken extension still shows its commands, greyed out with a reason, instead
+of silently vanishing.
+
+**WHY `mount` is an enum (`modal` | `panel` | `tab`) rather than free-form:** the host
+owns where things go. An extension declares the *kind* of surface it wants and the
+host decides the chrome, which is what keeps every extension feeling native and is why
+the interaction-ownership and paint-order contracts hold. v1 implements `modal`;
+`panel` and `tab` are the same registration with a different host shell.
+
+### 1.2 The module contract is `activate` / `deactivate`
+
+```ts
+export function activate(context: ExtensionContext): void | Promise<void>
+export function deactivate?(): void | Promise<void>
+
+type ExtensionContext = {
+  readonly api: AgentCodeApiV1
+  /** Register the handler for a command declared in `contributes.commands`. */
+  registerCommand(id: string, run: () => void | Promise<void>): Disposable
+  /** Register the renderer for a view declared in `contributes.views`. */
+  registerView(id: string, mount: ViewMount): Disposable
+  /** Anything pushed here is disposed on deactivate. */
+  readonly subscriptions: Disposable[]
+}
+
+type ViewMount = (element: HTMLElement) => void | (() => void)
+type Disposable = { dispose(): void }
+```
+
+**WHY `activate(context)` and not `mount(element, api)`:**
+
+1. **An extension is not always a window.** A watcher that reacts to an agent going
+   idle has no UI at all. `mount` cannot express it.
+2. **One extension, many contributions.** `mount` gives exactly one view and one
+   command. Real extensions have several of each.
+3. **`subscriptions` is the lifecycle primitive that scales.** Every registration
+   returns a `Disposable`; `deactivate` disposes the array. This is the single
+   mechanism that handles commands, views, event listeners and timers uniformly.
+4. **It is the shape extension authors already know.** VS Code, and every system
+   modelled on it. Being unfamiliar buys nothing here.
+
+**WHY the view mount is still DOM-level** (`(element) => cleanup`) rather than a React
+component: it keeps React optional (plain DOM, Preact, Svelte, canvas all work), and
+it survives the iframe transport unchanged — a React component reference cannot cross
+a frame boundary, but "call mount with this element" can be reimplemented on the far
+side. A React author writes `createRoot(element).render(<App/>)` in one line.
+
+### 1.3 Activation is lazy
+
+`activationEvents` decides when the module is imported:
+
+| Event | Fires when |
+|---|---|
+| `onCommand:<id>` | a declared command is invoked |
+| `onView:<id>` | a declared view is opened |
+| `onStartupFinished` | after the window is interactive |
+| `*` | immediately at startup — discouraged, and the Settings row says so |
+
+**WHY lazy:** the alternative is importing every installed extension's module at
+startup. Ten extensions become ten third-party module evaluations before the app is
+usable, and one slow or broken one degrades launch for everything. Declared
+contributions are exactly what makes deferral possible — the palette can list a
+command whose module has never been loaded, and importing happens on first use.
+
+`AppDefinition.Component` stays as it is internally. The host wraps a registered
+`ViewMount` in a React component (Task B4), so `AppHostSurface`, the command registry
+and the storage machinery are unchanged by extensions being loaded rather than
+compiled in.
+
+### 1.2 React is provided, not injected through the API
+
+Before loading any extension, the host publishes:
+
+```ts
+globalThis.__agentCodeHost = Object.freeze({
+  react: React,
+  reactDom: ReactDOM,        // createRoot
+  jsxRuntime: ReactJsxRuntime,
+  apiVersion: 1,
+})
+```
+
+An extension that wants React marks `react`, `react-dom` and `react/jsx-runtime`
+**external** in its own build, and ships a five-line shim that re-exports from that
+global. The SDK template (Phase C) provides both, so an author copies rather than
+derives.
+
+**WHY a namespaced global rather than an import map:** an import map must be declared
+before the first module in the document loads, and would have to resolve `react` to a
+URL. The host's React lives inside a content-hashed chunk with no stable URL, so the
+map would have to point at a shim that reads a global anyway — the same mechanism
+with an extra indirection and a load-order constraint. **WHY frozen:** the object is
+reachable from any renderer code, so freezing removes the trivial footgun of an
+extension replacing the host's React for everyone.
+
+**WHY this is not a security boundary:** a same-realm extension can already reach
+`window.api` directly. The boundary in this phase is convention, and the plan says so
+rather than implying otherwise. Real isolation requires the iframe transport
+(Phase D), and the DOM-level mount contract is what keeps that door open.
+
+---
+
+## 2. Phase B — the loader
+
+Six tasks. At the end, an installed extension runs.
+
+### Task B1: The privileged scheme
+
+**Files:**
+- Create: `src/main/extensions/scheme.ts`
+- Modify: `src/main/index.ts`
+- Modify: `src/renderer/index.html`
+
+**Interfaces:**
+- Consumes: `EXTENSIONS_DIR` from `@main/storage/paths.js`.
+- Produces: `registerExtensionScheme()` (module scope, pre-ready) and
+  `handleExtensionScheme()` (post-ready). URLs of the form
+  `agent-code-ext://<id>/<path>`.
+
+- [ ] **Step 1: Write the scheme module**
+
+```ts
+// src/main/extensions/scheme.ts
+import { net, protocol } from 'electron'
+import { realpath } from 'fs/promises'
+import { join, resolve as resolvePath, sep } from 'path'
+import { pathToFileURL } from 'url'
+
+import { EXTENSIONS_DIR } from '@main/storage/paths.js'
+
+export const EXTENSION_SCHEME = 'agent-code-ext'
+
+// WHY these exact privileges:
+//   standard        — gives the scheme real origin semantics so a relative
+//                     specifier inside a bundle (`./util.js` next to `index.js`)
+//                     resolves. Without it every import must be absolute.
+//   secure          — module scripts and most web APIs require a secure context.
+//   supportFetchAPI — lets an extension fetch its own assets (JSON, CSS).
+//   corsEnabled     — module scripts are ALWAYS fetched in CORS mode, and
+//                     `standard` makes this a distinct origin from the document.
+//
+// MUST run at module scope, before app.whenReady(). Electron silently treats the
+// scheme as opaque if registration happens after ready, and the failure looks like
+// a CSP problem rather than an ordering one.
+export function registerExtensionScheme(): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme: EXTENSION_SCHEME,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+        stream: true,
+      },
+    },
+  ])
+}
+
+export function handleExtensionScheme(): void {
+  protocol.handle(EXTENSION_SCHEME, async request => {
+    const url = new URL(request.url)
+    const extensionId = url.hostname
+    const relative = decodeURIComponent(url.pathname).replace(/^\/+/, '')
+
+    // The id in the URL is a NAME, not authority — the same invariant
+    // EditorFsRootRegistry enforces for filesystem roots. Resolve it against the
+    // install root and then prove the realpath is still inside.
+    const root = join(EXTENSIONS_DIR, extensionId)
+    let rootReal: string
+    try {
+      rootReal = await realpath(root)
+    } catch {
+      return new Response('not found', { status: 404 })
+    }
+
+    let targetReal: string
+    try {
+      targetReal = await realpath(resolvePath(rootReal, relative))
+    } catch {
+      return new Response('not found', { status: 404 })
+    }
+
+    // Containment. Without this, `..%2f..%2f.ssh/id_rsa` reads arbitrary files
+    // through a scheme the renderer is permitted to load SCRIPTS from — the worst
+    // possible combination. Install-time validation already checks the manifest's
+    // entry, but this handler serves arbitrary paths, so it needs its own check.
+    if (targetReal !== rootReal && !targetReal.startsWith(rootReal + sep)) {
+      return new Response('forbidden', { status: 403 })
+    }
+
+    const response = await net.fetch(pathToFileURL(targetReal).toString())
+    return new Response(response.body, {
+      headers: {
+        'content-type': contentTypeFor(targetReal),
+        // Required. Module scripts are fetched in CORS mode and this is a distinct
+        // origin from the document; without this header the import() fails with an
+        // opaque CORS error that looks nothing like the actual cause.
+        'access-control-allow-origin': '*',
+      },
+    })
+  })
+}
+
+function contentTypeFor(path: string): string {
+  if (/\.m?js$/.test(path)) return 'text/javascript'
+  if (path.endsWith('.json')) return 'application/json'
+  if (path.endsWith('.css')) return 'text/css'
+  if (path.endsWith('.svg')) return 'image/svg+xml'
+  if (path.endsWith('.png')) return 'image/png'
+  if (path.endsWith('.woff2')) return 'font/woff2'
+  return 'application/octet-stream'
+}
+```
+
+- [ ] **Step 2: Wire it into main**
+
+In `src/main/index.ts`, at module scope (before any `app.whenReady()`):
+
+```ts
+import { handleExtensionScheme, registerExtensionScheme } from '@main/extensions/scheme.js'
+
+registerExtensionScheme()
+```
+
+and inside the ready handler, before the window is created:
+
+```ts
+  handleExtensionScheme()
+```
+
+- [ ] **Step 3: Amend the CSP**
+
+`src/renderer/index.html` — change exactly one directive:
+
+```
+script-src 'self' agent-code-ext:;
+```
+
+and add, because `default-src 'self'` currently backstops it and an extension
+fetching its own JSON would otherwise fail:
+
+```
+connect-src 'self' agent-code-ext:;
+```
+
+Leave `worker-src` alone.
+
+- [ ] **Step 4: Verify — dev**
+
+```bash
+npm run dev
+```
+
+DevTools console:
+
+```js
+const r = await fetch('agent-code-ext://nonexistent/index.js')
+r.status   // → 404, NOT a CSP violation or a scheme error
+```
+
+A `net::ERR_UNKNOWN_URL_SCHEME` here means Step 2 ran after ready.
+
+- [ ] **Step 5: Verify — packaged. This is the step that catches the real trap.**
+
+```bash
+npm run build && npm start
+```
+
+Repeat the same console check. Dev serves from `http://localhost`, production from
+`file://` — a scheme that works in one and not the other is the specific failure this
+whole design is shaped to avoid. **Do not proceed to B2 until both pass.**
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/main/extensions/scheme.ts src/main/index.ts src/renderer/index.html
+git commit -m "feat(extensions): privileged agent-code-ext:// scheme"
+```
+
+---
+
+### Task B2: Host globals
+
+**Files:**
+- Create: `src/renderer/src/apps/api/hostGlobal.ts`
+- Modify: `src/renderer/src/app/main.tsx`
+
+- [ ] **Step 1: Publish the globals**
+
+```ts
+// src/renderer/src/apps/api/hostGlobal.ts
+import * as React from 'react'
+import * as ReactDOM from 'react-dom/client'
+import * as ReactJsxRuntime from 'react/jsx-runtime'
+
+// Published before any extension module is imported, so an extension's react shim
+// can resolve. See the plan's §1.2 for why this is a global rather than an import
+// map or an ABI field.
+//
+// Frozen because this object is reachable from all renderer code: freezing removes
+// the trivial footgun of one extension swapping the host's React out from under
+// every other consumer. It is NOT a security boundary — a same-realm extension can
+// reach window.api directly, and only the iframe transport changes that.
+export function installHostGlobal(): void {
+  Object.defineProperty(globalThis, '__agentCodeHost', {
+    value: Object.freeze({
+      react: React,
+      reactDom: ReactDOM,
+      jsxRuntime: ReactJsxRuntime,
+      apiVersion: 1,
+    }),
+    writable: false,
+    configurable: false,
+    enumerable: false,
+  })
+}
+```
+
+- [ ] **Step 2: Call it first thing in `main.tsx`**, before `createRoot`.
+
+- [ ] **Step 3: Verify** — `npm run dev`, console: `__agentCodeHost.apiVersion` → `1`,
+  and `__agentCodeHost.react = null` throws.
+
+- [ ] **Step 4: Commit.**
+
+---
+
+### Task B3: Extend the manifest with contributions
+
+**Files:**
+- Modify: `src/main/extensions/manifest.ts`
+- Modify: `src/shared/types/extensions.ts`
+
+The manifest schema built in the install phase covers identity and `entry` only. It
+now needs `contributes` and `activationEvents`.
+
+- [ ] **Step 1: Add the contribution schemas.** `commands[]` (`id`, `title`,
+  `description?`, `keywords?`), `views[]` (`id`, `title`, `mount: 'modal'`),
+  `settings[]` (`id`, `title`, `type: 'boolean'|'number'|'string'`, `default`),
+  `keybindings[]` (`command`, `key`). All optional; an extension with no
+  contributions is legal and does nothing visible.
+
+- [ ] **Step 2: Namespace-check every contributed id.** A command id must start
+  `<extensionId>.`. **WHY enforced rather than conventional:** ids land in one global
+  command registry alongside ~95 first-party commands, and an extension declaring
+  `session.kill` would shadow a real one. Rejecting at install is the only point where
+  the user can still act on it.
+
+- [ ] **Step 3: Reject duplicate ids within a manifest**, and record that
+  cross-extension collisions are resolved at load time (first wins, second reported).
+
+- [ ] **Step 4: Validate `activationEvents`** against the known set, allowing
+  `onCommand:<id>` / `onView:<id>` only for ids this manifest declares. An activation
+  event referencing a command the extension does not contribute is always an authoring
+  mistake and is silently dead otherwise.
+
+- [ ] **Step 5: Verify + commit.** Existing installs keep working — every new field is
+  optional.
+
+`TEST-SITE:` `manifest.test.ts` — namespace enforcement, duplicate ids, unknown
+activation events.
+
+---
+
+### Task B4: The extension host
+
+**Files:**
+- Create: `src/shared/types/extensionModule.ts`
+- Create: `src/renderer/src/apps/host/ExtensionHost.ts`
+- Create: `src/renderer/src/apps/host/context.ts`
+
+- [ ] **Step 1: Define the module contract**
+
+```ts
+// src/shared/types/extensionModule.ts
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+export type Disposable = { dispose(): void }
+
+/** A view's renderer. DOM-level so React stays optional and the contract
+ *  survives a future iframe transport — see plan §1.2. */
+export type ViewMount = (element: HTMLElement) => void | (() => void)
+
+export type ExtensionContext = {
+  readonly api: AgentCodeApiV1
+  registerCommand(id: string, run: () => void | Promise<void>): Disposable
+  registerView(id: string, mount: ViewMount): Disposable
+  readonly subscriptions: Disposable[]
+}
+
+/** What an extension's entry module must export. See plan §1.2. */
+export type ExtensionModule = {
+  activate(context: ExtensionContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
+```
+
+- [ ] **Step 2: Write the context factory** (`host/context.ts`). Creates one
+  `ExtensionContext` per extension. `registerCommand`/`registerView` write into
+  host-owned maps keyed by `extensionId`, return a `Disposable` that removes the
+  entry, and **reject an id the manifest did not declare** — a registration the
+  palette never heard of would be invisible, so failing loudly at registration is the
+  only way the author finds out.
+
+- [ ] **Step 3: Write `ExtensionHost`** (`host/ExtensionHost.ts`), owning the whole
+  lifecycle:
+
+```ts
+// The one line of actual loading. @vite-ignore is required so Vite does not try to
+// analyze a runtime specifier; Rollup passes a variable import() through untouched
+// either way — Monaco's own foreign-module loader does exactly this in the shipped
+// bundle, which is what retired the risk that it would not survive the build.
+const url = `agent-code-ext://${id}/${manifest.entry}`
+const module = (await import(/* @vite-ignore */ url)) as ExtensionModule
+```
+
+  Responsibilities:
+  - `activate(id)` — import once, call `module.activate(context)`, memoize the
+    in-flight promise so two concurrent triggers activate once.
+  - `deactivate(id)` — call `deactivate?.()`, then dispose `subscriptions` in reverse
+    order, then drop the module reference.
+  - **Every failure is a value, never a throw.** A module that fails to import, has
+    no `activate`, or throws inside it, records `{ id, error }` and leaves every
+    other extension running. A broken third-party module must not be able to blank
+    the app.
+  - Activation-event dispatch: `onStartupFinished` after mount, `onCommand:` /
+    `onView:` on first use, `*` immediately.
+
+- [ ] **Step 4: Verify** typecheck. **Step 5: Commit.**
+
+`TEST-SITE:` `ExtensionHost.renderer.test.ts` — double-activation memoization,
+disposal order, a throwing `activate` isolated from siblings.
+
+---
+
+### Task B5: The view bridge
+
+**Files:**
+- Create: `src/renderer/src/apps/host/viewBridge.tsx`
+
+- [ ] **Step 1**
+
+```tsx
+// src/renderer/src/apps/host/viewBridge.tsx
+import { useEffect, useRef } from 'react'
+
+import type { ViewMount } from '@shared/types/extensionModule'
+
+/**
+ * Wraps a registered ViewMount in a host-owned React component, so everything
+ * downstream — AppHostSurface, AppDefinition, the command registry — is unchanged by
+ * extensions being loaded at runtime rather than compiled in.
+ *
+ * This component is the entire adapter between the host's React world and the
+ * extension's DOM world, and it is the piece that gets REPLACED (not rewritten) if
+ * extensions later move into an iframe: `mount(element)` is exactly what the
+ * child-side bootstrap calls over there.
+ */
+export function viewComponentFor(mount: ViewMount) {
+  return function ExtensionView() {
+    const hostRef = useRef<HTMLDivElement | null>(null)
+
+    useEffect(() => {
+      const element = hostRef.current
+      if (!element) return
+
+      let cleanup: void | (() => void)
+      try {
+        cleanup = mount(element)
+      } catch (error) {
+        // A throw from third-party code during mount. Contained here rather than
+        // allowed to unwind into the host tree, where React would unmount to the
+        // root and blank the entire application.
+        element.textContent = `Extension view failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`
+        return
+      }
+
+      return () => {
+        try {
+          cleanup?.()
+        } catch {
+          // A throwing cleanup must not prevent the host from unmounting. The
+          // extension leaks whatever it leaked; the app stays usable.
+        }
+        element.replaceChildren()
+      }
+    }, [])
+
+    return <div ref={hostRef} style={{ display: 'contents' }} />
+  }
+}
+```
+
+`TEST-SITE:` `viewBridge.renderer.test.tsx` — cleanup runs on unmount; a throwing
+`mount` renders the error instead of propagating.
+
+- [ ] **Step 2: Verify** typecheck. **Step 3: Commit.**
+
+---
+
+### Task B6: Wire declarations into the app
+
+Declared contributions must reach the palette, Settings and the keybinding router
+**without the extension having been activated**. This is the task the superseded plan
+under-priced: `APPS`, `APP_BY_ID`, `appCommands`, `commandDefs` and
+`listPickerCommandMeta()` are all module-scope snapshots.
+
+**Files:**
+- Modify: `src/renderer/src/apps/registry.ts`
+- Modify: `src/renderer/src/apps/commands/appCommands.ts`
+- Modify: `src/renderer/src/features/command-palette/registry.ts`
+- Modify: `src/renderer/src/app-state/uiShell/{types,slice}.ts`, `app-state/types.ts`
+- Modify: `src/renderer/src/app/App.tsx`
+- Modify: `src/renderer/src/apps/ui/AppsSettingsRow.tsx`
+
+- [ ] **Step 1: Put the installed set in the store.** `installedExtensions:
+  ExtensionListEntry[]`, `extensionErrors: {id,name,error}[]`, and a setter on the
+  uiShell slice. **WHY the store and not a module variable:** the palette and Settings
+  must re-render when the set changes, and a module-scope array cannot notify them.
+  `apps/registry.ts` keeps only a `BUILTIN_APPS: AppDefinition[] = []` seam.
+
+- [ ] **Step 2: Derive commands from DECLARATIONS, not from loaded modules.**
+  `buildExtensionCommands(installed)` maps every `contributes.commands[]` entry to a
+  `CommandDef` whose `run` calls `extensionHost.executeCommand(extId, cmdId)` — which
+  activates the extension first if needed. **This is what makes lazy activation
+  work**: the command is listed and invocable before a single byte of the extension
+  has been imported.
+
+- [ ] **Step 3: Derive views the same way.** A `contributes.views[]` entry with
+  `mount: 'modal'` produces an `AppDefinition` whose `Component` activates on first
+  render and then renders the registered `ViewMount` through `viewComponentFor`.
+  Derive `APP_BY_ID` at the point of use, not at module scope — a module-scope map
+  against a live array is a silently-missing extension.
+
+- [ ] **Step 4: Make `commandDefs` a function.** `buildCommandDefs(extensionCommands)`,
+  called from `buildCommandRegistry`. Check `listPickerCommandMeta()` — Settings'
+  command-visibility row consumes it, so extension commands should appear there and be
+  hideable like any other.
+
+- [ ] **Step 5: Contributed settings.** Render `contributes.settings[]` under the
+  extension's own section, persisted through `extensionStorage*` under a reserved
+  `__settings` key. **WHY not the Settings store:** third-party-declared fields must
+  never enter the zustand-persist blob (#249), and per-extension storage already
+  exists and is namespaced.
+
+- [ ] **Step 6: Contributed keybindings.** `useKeybinds.ts` is one hardcoded
+  capture-phase listener with no registry. Add a single consulted map of
+  extension bindings, checked **after** every first-party branch. **WHY after:** an
+  extension must not be able to shadow ⌘W or ⌘T. Conflicts are reported in Settings,
+  not silently resolved.
+
+- [ ] **Step 7: Load the list on startup and after install/remove.** In `App.tsx`, one
+  effect reads `extensionsList()` into the store and fires `onStartupFinished`
+  activations. `AppsSettingsRow` refreshes the same store after install/remove, so an
+  extension is usable without a restart — the thing that makes this an extension
+  system rather than a config file. **WHY an effect rather than blocking bootstrap:**
+  the renderer mounts synchronously, and making the app wait on third-party module
+  evaluation lets one slow extension delay startup for everything.
+
+- [ ] **Step 8: Verify** typecheck + `npm test` + build.
+
+- [ ] **Step 9: Commit.**
+
+---
+
+### Task B7: Fix the inherited defects
+
+**Files:**
+- Modify: `src/renderer/src/ui/GlobalToast.tsx`
+- Modify: `src/renderer/src/apps/api/useAppHostApi.ts`
+- Modify: `src/renderer/src/apps/api/types.ts`
+- Modify: `src/renderer/src/features/command-palette/ui/CommandPalette.tsx`
+
+- [ ] **Step 1: Toast above modals.** Raise `GlobalToast` from `z-50` to above
+  `z-[1100]`. **WHY the toast and not the dialog:** a toast is by definition the
+  topmost transient layer — every other caller is non-modal chrome that is
+  unaffected by raising it, whereas lowering the dialog would break the modal
+  stacking the whole surface registry depends on.
+
+- [ ] **Step 2: `theme.tokens()` must include runtime-only tokens.** Union the
+  stylesheet-discovered names with an explicit list of the tokens `theme.ts` assigns
+  at runtime (`--theme-app-font`, `--theme-font-code`, accent pair). **WHY explicit:**
+  they are set via `style.setProperty` on the root and never appear in any
+  stylesheet, so no amount of walking `document.styleSheets` will find them.
+
+- [ ] **Step 3: `JsonValue` must not admit non-finite numbers.** Document that
+  `JSON.stringify` turns `NaN`/`Infinity` into `null`, and reject them in
+  `extensionStorageSet` with a clear error rather than silently corrupting.
+
+- [ ] **Step 4: Add `openApp` to the `useMemo` dep array** in `CommandPalette.tsx`.
+
+- [ ] **Step 5: Verify + commit.**
+
+---
+
+## 3. Phase C — the SDK and a real extension
+
+Phase B is unverifiable without something to install. This phase produces it, and it
+is the honest end-to-end test.
+
+- [ ] **Task C1 — `agent-code-extension-api` package.** A published (or
+  git-installable) package exporting the `AgentCodeApiV1` and `ExtensionModule`
+  types, the react shim, and a Vite config preset that marks react external and
+  points bare specifiers at `globalThis.__agentCodeHost`. **WHY a package rather than
+  documentation:** the shim and the externals config are exactly the parts an author
+  will get wrong, and they are copy-paste identical for everyone.
+
+- [ ] **Task C2 — `Juliusolsson05/timer-extension`.** A separate repository. The
+  timer that was deleted from this one, rebuilt against the SDK:
+  `agent-code.extension.json`, `src/index.tsx` exporting `mount`, a build producing
+  `dist/index.js`, and a release tag. The SVG ring, presets, pause/resume and
+  deadline-based countdown from the deleted version are a reasonable starting point.
+
+- [ ] **Task C3 — the end-to-end run.** Settings → paste `Juliusolsson05/timer-extension`
+  → Install → `Open Timer` in the palette → it runs. **This is the acceptance test
+  for the entire platform**, and until it passes, nothing above is verified.
+
+- [ ] **Task C4 — `docs/extensions/authoring.md`.** Manifest reference, the `mount`
+  contract, the Tier 0 API, the theme tokens, and how to publish. Generated from the
+  zod schema where possible so it cannot drift.
+
+---
+
+## 4. Phase D — beyond Tier 0
+
+Deliberately unplanned in detail; each item needs a real consumer before its contract
+is designed. Recorded so the sequencing is not re-derived.
+
+- **Tier 1 (`workspace.observe`, `sessions.observe`, `panes.observe`)** — metadata
+  and status events, no transcripts. `main/remote/SessionFeedSource.ts` already
+  projects session state for the mobile client and is the template.
+- **Tier 2 (`fs.read`, `transcript.read`, `git.read`)** — requires a consent flow.
+  `WorkflowSourceApprovalStore` is the in-repo precedent.
+- **Tier 3 (`sessions.prompt`, `fs.write`, `git.commit`, `network.fetch`)** —
+  requires per-extension identity that is *enforceable*, which same-realm loading
+  cannot provide. **This is the gate that forces Phase D2.**
+- **D2 — iframe isolation.** Priced at ~350–650 LOC by the frame-boundary audit:
+  keyboard routing and default suppression are the bulk (every host shortcut dies
+  while focus is in a frame, and Cmd+W closes the window), plus an unhandled-Escape
+  bridge, a splitter drag shield, and a theme stylesheet contract. The DOM-level
+  `mount` contract from §1.1 is what makes this a transport change rather than a
+  rewrite.
+- **Background extensions.** An extension that only runs while its modal is open
+  cannot be a timer, a watcher, or a notifier. Needs extension state to live above
+  the surface, and a decision about what a backgrounded extension may do. **This is
+  a product decision, not a technical one, and it should be made deliberately rather
+  than falling out of an implementation.**
+
+---
+
+## 5. Acceptance for the platform as a whole
+
+- [ ] `agent-code-ext://` resolves in `npm run dev` **and** in a packaged build.
+- [ ] A path-traversal URL returns 403, verified by hand.
+- [ ] An extension installs from a repo with no releases and one with releases.
+- [ ] An extension with a bad manifest fails with a message naming the problem.
+- [ ] An extension whose entry throws shows an error and does not blank the app.
+- [ ] Removing an extension removes its command and its bundle, and keeps its state.
+- [ ] Reinstalling restores it without a restart.
+- [ ] `npm run typecheck`, `npm test`, `npm run build` all pass.
+- [ ] The timer extension runs from its own repository, and no extension source
+      exists anywhere in this one.
diff --git a/docs/superpowers/plans/2026-07-22-extension-contributions-into-merged-systems.md b/docs/superpowers/plans/2026-07-22-extension-contributions-into-merged-systems.md
new file mode 100644
index 000000000..691fbece8
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-22-extension-contributions-into-merged-systems.md
@@ -0,0 +1,200 @@
+# Extension contributions into the merged command / keybinding / settings systems
+
+**Status:** planned · **Branch:** `feat/extension-platform` · **Date:** 2026-07-22
+**Depends on:** the `origin/main` merge (`68c1b34a`) that brought the refactored
+command catalog, keybinding resolver, and settings registry onto this branch.
+
+## Why this is the first implementation commit
+
+While this branch sat open, `main` refactored the three systems an extension
+platform must plug into — and refactored them into *exactly* the contribution
+shapes we need:
+
+- The command list moved out of the palette into a **context-free catalog**
+  (`command-palette/catalog.ts`), and `buildCommandRegistry` now resolves
+  keybindings and gates via `commandApplicable` + `PALETTE_SELF_EXCLUDED_COMMAND_IDS`.
+- Keybindings became a **separate id-keyed registry**
+  (`command-keybindings/{defaults,resolve,reservations}.ts`) that resolves
+  `commandId → chord`, decoupled from command definitions — the VS Code model.
+- Settings rows are a **discriminated-union registry** (`settingsRegistry.ts`)
+  whose `'apps'` marker variant this branch already added.
+
+So the first real work is not new infrastructure. It is **bridging the branch's
+declarative contribution model onto these merged registries.** It needs **no
+sandbox** — every item here is declarative (the manifest already validates it;
+nothing runs extension code at registration time), which is why it is the safest,
+highest-value place to start. Imperative service access and the iframe boundary
+come later (see the full-platform plan).
+
+## Current state after the merge (verified)
+
+| Contribution | Manifest schema | Wired? | Evidence |
+| --- | --- | --- | --- |
+| `contributes.commands` | `manifest.ts:65` | **YES** | `CommandPalette.tsx:808` passes `deriveExtensionCommands(...)` into `buildCommandRegistry(ctx, extensionCommands)` (`registry.ts`); derivation at `derive.ts:57`. Extension commands appear in the palette and fire. |
+| `contributes.keybindings` | `manifest.ts:108` | **NO — dead** | Validated at `manifest.ts:230-237` (target command must exist), zero consumers. Never merged into `buildDefaultKeybindings()` / `resolveEffectiveKeybindings()`. |
+| `contributes.settings` | `manifest.ts:82` | **NO — dead** | Validated only. Never turned into a `SettingDefinition`; no namespaced value store exists. |
+| `contributes.views` | `manifest.ts:72` | partial | `mount: z.enum(['modal'])` only; modal surface works. Grid/dispatch panes are the *next* plan, not this one. |
+
+The three gaps, precisely:
+
+1. **Extension commands are invisible to the "Commands" settings category.**
+   `listPickerCommandMeta()` (`registry.ts`) takes an optional
+   `extensionCommands = []` (preserved through the merge) but the Settings caller
+   passes nothing, so an extension command cannot be shown or hidden — and, more
+   importantly, cannot be assigned a keybinding through the keybind editor, which
+   iterates the same catalog.
+
+2. **`contributes.keybindings` goes nowhere.** An extension can declare
+   `{command, key}` and it validates, but the chord never reaches
+   `resolveEffectiveKeybindings`, so it never fires and never shows in the editor.
+
+3. **`contributes.settings` goes nowhere.** No `SettingDefinition` is produced,
+   and there is no per-extension value store (the app's `Settings` is one flat
+   first-party blob; extension storage is the separate main-owned namespace at
+   `EXTENSION_STATE_DIR`).
+
+## Scope of this commit series (no sandbox)
+
+Three ordered pieces. Commands first because the other two hang off command ids.
+
+### Piece 1 — extension commands into the Settings "Commands" category
+
+**Goal:** extension commands are listable and hide-able in Settings, and therefore
+bindable in the keybind editor, exactly like first-party commands.
+
+**Do:**
+- Find the Settings caller of `listPickerCommandMeta()` (the `command-visibility`
+  marker row builder in `settingsRegistry.ts`, and the keybind editor's catalog
+  iteration in `CommandKeybindingsRow.tsx`). Thread the same
+  `deriveExtensionCommands(...)` list into it that `CommandPalette.tsx:808` already
+  builds.
+- Confirm `deriveExtensionCommands` output satisfies the **post-refactor**
+  `CommandDef` contract that `catalog.ts`'s `findCatalogDefects` guards
+  (`VALID_SURFACES`, required `surface`, a real `description`, a `declaredTier`).
+  `derive.ts:87` already notes `buildCommandRegistry` throws on a blank
+  description — verify the same fields the catalog now requires.
+
+**Constraints:**
+- Extension commands must keep sorting **last** (browse order); `allCommandDefs`
+  already does this — do not reorder.
+- Do **not** put extension commands into `builtInCommandCatalog` itself. The
+  catalog is a frozen module-scope array; an installed extension must add a command
+  without a reload, which is why the concat is per-call.
+
+**Done when:** installing an extension with a command shows that command in
+Settings → Commands, and the keybind editor lists it as bindable.
+
+### Piece 2 — `contributes.keybindings` into the resolver
+
+**Goal:** an extension's declared default chord fires and shows in the editor.
+
+**Do:**
+- Derive `CommandBindingDefault[]` (`command-keybindings/defaults.ts` shape:
+  `{ commandId, bindings, context }`) from installed manifests' `keybindings`,
+  the mirror of `deriveExtensionCommands`. Put it in `derive.ts`.
+- Merge those into what `resolveEffectiveKeybindings` consumes. Match the
+  first-party path: extension defaults are *defaults*, user overrides in
+  `commandKeybindingOverrides` still win. Note `coerceCommandKeybindingOverrides`
+  already **preserves unknown command ids** "for an extension temporarily
+  uninstalled" — the store was built for this.
+- Choose a `BindingContext` for extension bindings. Default to `'global'` unless
+  the extension's view runs in a specific surface. (Contexts: `global | grid |
+  dispatch | editor | feed`.)
+- Run the contributed chord through `findBindingCollisions` /
+  `findBindingOwners` (`reservations.ts`). Decision needed (see open questions):
+  reject at install, or accept-and-report like cross-extension command-id
+  collisions already do at load time.
+
+**Constraints:**
+- A binding whose `commandId` is not a contributed/known command must not silently
+  vanish — the manifest cross-check (`manifest.ts:230`) already rejects an
+  extension binding targeting a command it does not contribute, so at minimum the
+  intra-extension case is safe.
+- Keybindings live in the `Settings` blob (`commandKeybindingOverrides`), **not**
+  a `~/.claude` file — do not invent a JSON-file path.
+
+**Done when:** an extension shipping `{command, key}` fires that key, the editor
+shows the chord, and a conflicting chord is surfaced (not silently dropped).
+
+### Piece 3 — `contributes.settings` into the registry
+
+**Goal:** an extension's declared settings render as real rows and persist.
+
+**The real decision — where does an extension setting's VALUE live?** The app's
+`Settings` is one flat first-party blob owned by zustand-persist, and
+`app-state/store.ts` records that adding a field without a version bump
+black-screened launch twice (#249). Extension settings are authored outside the
+release cycle, so they **must not** enter that blob — the same rule that put
+extension state in the main-owned `EXTENSION_STATE_DIR`.
+
+**Recommended shape:**
+- Add one `SettingDefinition` control variant, `'extension'` (sits beside the
+  existing `'apps'` marker variant in the union you just merged), OR map the three
+  manifest setting types (`boolean`/`number`/`string`) onto the existing
+  `toggle` / `select-free` / `action` controls. Prefer a dedicated `'extension'`
+  variant: it keeps the read/write path pointed at extension storage instead of
+  the first-party `setSettings`.
+- Back the value with the **existing** per-extension storage
+  (`extension:storage-get/set`, `EXTENSION_STATE_DIR`) keyed by the setting's
+  contribution id — reusing the one capability whose isolation is already
+  acceptable, rather than opening a second store.
+- Derive the rows from installed manifests (a `deriveExtensionSettings`, mirroring
+  the command derivation) and concatenate into `getSettingsRegistry()` under an
+  "Extensions" category or each extension's own section.
+
+**Constraints:**
+- Setting ids are already namespaced `<extensionId>.<name>` and validated.
+- A `number` default is `.finite()` in the schema — NaN can't reach storage.
+- Do not route extension setting writes through `setSettings`/the persisted blob.
+
+**Done when:** an extension shipping a `boolean`/`number`/`string` setting renders
+an editable row whose value survives a reload, stored under extension state.
+
+## Cross-cutting constraints (do not break)
+
+- **`AppDefinition` stays a manifest superset-by-one** (`apps/types.ts`). Capabilities
+  never become fields on it — they go through `AgentCodeApiV1`. Contribution
+  *wiring* is host-side derivation from the manifest, not new manifest fields.
+- **Everything here is declarative.** Nothing in this series imports or runs an
+  extension bundle at registration time — the palette, keybind editor, and Settings
+  populate from manifests alone. Keep it that way; the moment a piece needs the
+  loaded module, it has crossed into Stage 2 territory.
+- **First-party callers unchanged.** Every threaded parameter
+  (`extensionCommands`, extension defaults, extension settings) is additive with an
+  empty default, so nothing first-party regresses.
+- **Per-call concat, never module-scope snapshot.** An adversarial audit already
+  found eight module-scope snapshots that could not react to an install; do not add a ninth.
+
+## Verification
+
+- `tsc -b tsconfig.node.json` then `tsc -p tsconfig.web.json --noEmit` — the
+  project's real gate (electron-vite build + vitest do not type-check).
+- Manual: install `Juliusolsson05/agent-code-timer` (or a fixture manifest adding a
+  command + keybinding + setting), then confirm in one session: command in palette
+  and in Settings → Commands; keybinding fires and shows in the editor; setting row
+  renders and persists across reload.
+- This is also the still-outstanding **Stage 1 acceptance test** ("nobody has
+  launched the app and clicked it") — piece it in here rather than deferring again.
+
+## Open questions for the implementer
+
+1. **Keybinding conflict policy** — reject a colliding extension binding at install,
+   or accept-and-report at load (matching cross-extension command-id collisions)?
+   Recommend accept-and-report: an extension cannot see another's manifest, so
+   failing install punishes whoever installed second.
+2. **Settings category placement** — one shared "Extensions" category, or a
+   per-extension section? Recommend per-extension section under an "Extensions"
+   category so uninstalling cleanly removes a whole block.
+3. **Uninstall cleanup** — when an extension is removed, do its stored setting
+   values and keybind overrides get purged, or preserved for reinstall? The keybind
+   store already preserves unknown ids deliberately; mirror that for settings
+   (preserve), and document it.
+
+## What this explicitly is NOT
+
+- Not the sandbox / iframe boundary.
+- Not grid/dispatch pane mounting (that is the next plan; needs the `'panel'`/`'tab'`
+  mount kinds and the multi-mount registry).
+- Not any imperative service API (`agentCode.workspace`, `.session`, etc.).
+- Not fixing #577's three known bugs (Update-button closure, deactivate-on-uninstall,
+  ledger validation) — those are their own small commit, fold in alongside piece 1.
diff --git a/docs/superpowers/plans/2026-07-22-full-extension-platform-buildout.md b/docs/superpowers/plans/2026-07-22-full-extension-platform-buildout.md
new file mode 100644
index 000000000..b50372ea7
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-22-full-extension-platform-buildout.md
@@ -0,0 +1,638 @@
+# Full Extension Platform — Complete Build Plan
+
+**Status:** specification (no code) · **Branch:** `feat/extension-platform` (PR #577) · **Date:** 2026-07-22
+**Base:** the `origin/main` merge `68c1b34a` (178 commits) + piece-1 wiring `c42a47a1`.
+
+## Decisions locked (2026-07-22)
+
+The §9 open questions were resolved by the maintainer:
+
+1. **Iframe fork → Option A** (plain `<iframe>` + `MessagePortMain`). Not Option B.
+2. **Keybinding conflict → accept-and-report at load.** Both extensions install; the clash
+   is reported; first-party wins.
+3. **Settings placement → a per-extension section** under an "Extensions" category, so
+   uninstall removes a clean block.
+4. **Uninstall → preserve** setting values + keybind overrides for reinstall.
+5. **Custom feed / tool renderers → CUT.** Extensions may ship an MCP tool, but its output
+   renders through the **standard MCP rendering** (the generic `ToolResultRow` fallback the
+   app already applies to any MCP tool). No extension-authored feed rows. WHY: a custom
+   renderer would put third-party synchronous React into the feed — the most trusted surface
+   — and the feed rendering pipeline has been a repeated problem area (the renderer rewrite,
+   provider plug-and-play #394). The safety cost is not worth the differentiation. This
+   removes the hardest, most dangerous piece of WS7 entirely.
+6. **SDK → a separate submodule repo**, matching the other `packages/*`.
+
+## 0. How to read this, and where it comes from
+
+This is the exhaustive build specification for turning the extension platform from a
+working *app-in-a-modal* demo into a *VS Code-grade contribution system*. It is written
+for the engineer who implements it, so it carries every constraint, invariant, file:line
+anchor, and decision — not a summary.
+
+**Provenance.** It synthesizes nine independent research passes over the merged tree
+(three surface/API/service maps plus six deep spec passes: sandbox, capability, keybind/
+settings wiring, pane model, advanced registries, lifecycle/SDK). Every file:line below
+is relative to this branch *after* the merge; re-grep after any further rebase.
+
+**Relationship to the other docs in this folder:**
+
+- `2026-07-20-extension-platform-investigation.md` — **superseded / stale.** Its findings
+  reasoning still holds, but its snapshot drifted with the 178-commit merge: the CSP block
+  it quotes (its §3.1) predates `agent-code-ext:` being added to CSP (now at
+  `src/renderer/index.html:28`); its "~153 methods / 27 modules" undercounts (30 modules
+  now); and its central §8 "architecture decision A/B/C is open" is **answered** — option B
+  (runtime bundle over the `agent-code-ext://` scheme) shipped. Do not treat it as
+  current-state.
+- `2026-07-20-extension-platform.md` — the original full plan. **This doc aligns with and
+  extends it**, re-anchored to the merged tree. Its Phase D (Tiers 1-3, iframe) is the
+  spine of workstreams 4-7 here.
+- `2026-07-20-extension-platform-stage1.md` — superseded by its own header; kept for §0-§3
+  reasoning. Its Task 5/6 (palette commands, Settings row) targeted the *old* palette and
+  are obsolete after the merge.
+- `2026-07-22-extension-contributions-into-merged-systems.md` — the active near-term
+  plan; **workstreams 1-3 here are its three pieces**, expanded to spec-completeness with
+  the deep-pass findings (notably the keybind-editor correction in WS2).
+
+## 1. Goal and the parity target
+
+Let user-authored extensions, installed from a GitHub repo, integrate as first-class
+citizens of the app: contribute **commands, keybindings, settings, views, grid/dispatch
+panes, and themes**, and — behind consent — reach app **services**
+(workspace, sessions, filesystem, network). The bar is VS Code: declarative `contributes`
++ lazy `activate`/`deactivate` + a capability/consent model + process-level isolation.
+
+**The VS Code mental model, mapped to this app.** Commands are the universal invocation
+currency: a keybinding, a palette entry, a menu item, and a button all resolve one command
+*id*, never bind to code directly. Contribution points are declarative in the manifest and
+wired host-side; only *live UI* and *service calls* need the extension's running code. That
+split is the organizing principle of this whole plan.
+
+## 2. The organizing principle: the declarative / imperative fault line
+
+Every capability an extension could want falls on one side of a single line, and that line
+decides sequencing and risk:
+
+- **Declarative / data contributions** — commands, keybindings, settings, themes, menu
+  entries. These are populated host-side *from the manifest alone*; no extension code runs
+  at registration time. **They open cleanly now, with no sandbox.** (Research pass 6 & 8
+  confirm the manifest already validates all of them; three are still dead consumers.)
+
+- **Imperative + synchronous-React contributions** — a view mounted into a modal/pane, a
+  contributed surface. These render the extension's own React/
+  DOM *synchronously into the host tree* and/or call app services at runtime. **These
+  require the iframe sandbox** — because a same-realm extension already reaches
+  `window.api`'s ~153 methods directly (`ExtensionHost.ts:87-88`), so any capability gate
+  on them is advisory until each extension has a distinct frame identity.
+
+Contributed surfaces need "a React component rendered synchronously into the host tree,"
+which collides head-on with the ABI's all-async, no-`@renderer/*`, frame-boundary rule
+(`apps/api/types.ts:9-41`). That collision is the sandbox, and it is the gate for the
+powerful half of the platform. (Custom *feed* renderers were the sharpest version of this
+collision; they are **cut** — Decision 5 — so extension tool output uses standard MCP
+rendering and never returns third-party React into the feed.)
+
+**Consequence for the roadmap:** build every declarative contribution first (WS1-3), then
+the sandbox (WS4) and its capability model (WS5), then the imperative surfaces that depend
+on it (WS6-7), with the SDK/versioning (WS8) threaded alongside.
+
+## 3. Current state — verified
+
+The manifest schema (`src/main/extensions/manifest.ts:131-148`) already validates every
+contribution type. What is actually *consumed*:
+
+| Contribution | Schema | Wired today | Evidence |
+| --- | --- | --- | --- |
+| `commands` | `manifest.ts:65` | **YES** (palette) + **partial** (Settings) | `CommandPalette.tsx:808/813` passes `deriveExtensionCommands` into `buildCommandRegistry`; piece-1 `c42a47a1` threads them into the Settings "Commands" *visibility* list via `getSettingsRegistry(extensionCommands)` → `listPickerCommandMeta(extensionCommands)` (`settingsRegistry.ts:394`). **But NOT the keybind editor** — see WS2. |
+| `views` | `manifest.ts:72` | **partial** — `mount: z.enum(['modal'])` only | Modal host works (`AppHostSurface.tsx`). `'panel'`/`'tab'` reserved (`manifest.ts:75-78`). |
+| `keybindings` | `manifest.ts:108` | **NO — dead** | Validated (`manifest.ts:229-237`), zero consumers. No `deriveExtensionKeybindings`. |
+| `settings` | `manifest.ts:82` | **NO — dead** | Validated, zero consumers. No `deriveExtensionSettings`, no `SettingDefinition` produced. |
+
+The runtime host (load/activate/deactivate/failure capture) is real and good: `ExtensionHost.ts`,
+`ExtensionHostProvider.tsx`, `viewBridge.tsx`. Install/update/ledger is real:
+`install.ts`, `ledger.ts`. What is missing is (a) three declarative consumers, (b) the
+sandbox, (c) the capability model, (d) the pane host shell, (e) the SDK.
+
+## 4. The architecture spine
+
+### 4a. Commands are the currency
+Palette, native menu, keybinding, and programmatic callers all funnel through one gateway,
+`dispatchCommand` (`executeCommand.ts:131`), resolving a command *id*. Extension commands
+already flow into the palette. Everything id-keyed (keybindings, menu entries) hangs off
+this. This is the VS Code model and it is already the app's model — build on it, don't
+reinvent it.
+
+### 4b. The ONE registry pattern to standardize on
+For every *open* contribution surface (unknown, third-party key set), copy the
+**condition-view registry idiom** — the only pattern in the codebase already built for open
+contribution (research pass 5):
+
+- `defineView<K,S>({...})` authoring helper that infers types from the literal
+  (`src/shared/conditions-core/view.ts:67-71`).
+- An **open** `Record<string, Contribution>` — never `Record<ClosedUnion, FatBag>`.
+- A **single generic host** that does `const c = registry[key]; if (!c) continue;` — routes
+  by key, **skips unknown keys**, never throws (`ConditionOutlet.tsx:57-73`). Contrast the
+  provider registries, which `throw` on unknown (`registry.renderer.capabilities.ts:333`) —
+  correct for a closed first-party set, fatal for third-party contribution.
+- **One audited erasure seam** (`eraseRegistry`, `view.ts:139-143`) converting precise
+  contributor types to the host's erased type, sound because the host only routes by key.
+- A **namespacing guard** at admission (`CONTRIBUTION_ID` already enforces
+  `<extensionId>.<name>`, `manifest.ts:60-68`).
+
+Where semantics are *ordered probe* rather than exact-key (feed/tool renderers, formatters),
+keep the keyed-registration ergonomics but consume via the `COMMAND_FORMATTERS`
+first-non-decline-wins loop (`formatters/index.ts:39-43`), with extension entries assembled
+at runtime and ordered **last** (exactly as `deriveExtensionCommands` already appends).
+
+### 4c. The isolation decision — the crux, and it is a fork
+An extension today `await import('agent-code-ext://…')`s **into the renderer's own realm**
+(`ExtensionHost.ts:87-88`) — same WebContents, same `window`, full `window.api` in reach.
+Every guard is a mistake-guard, not an attacker-guard (`hostGlobal.ts:38-42`,
+`ipc/extensions.ts:14-30`). Real isolation requires each extension in its own frame so the
+host can derive identity from the sender. **The fork (research pass 1):**
+
+- **Option A — plain `<iframe src="agent-code-ext://…">` + postMessage.** Own origin, own
+  CSP, true isolation; **no preload** (a same-process iframe shares the parent's), so the
+  host talks to it *only* over `window.postMessage`/`MessagePortMain`. The entire
+  `AgentCodeApiV1` "everything is a Promise" discipline (`types.ts:20-28`) was built for
+  exactly this transport.
+- **Option B — `WebContentsView`/`<webview>`.** Own WebContents → own preload + own session
+  partition (strongest identity via `webContents.id`), but heavier, and it reintroduces the
+  native-surface paint/z-order mismatch that killed the overlay window (#518).
+
+**Recommendation: Option A (plain iframe + `MessagePortMain`).** It matches the pre-built
+all-async ABI, gives a real origin + per-document CSP, and `event.senderFrame`/a per-frame
+`MessagePortMain` yields unforgeable identity without a second WebContents. Reserve Option B
+only if a capability genuinely needs a preload-level Node bridge. This is the one decision
+that is expensive to reverse — see §9.
+
+## 5. Workstreams
+
+Each: goal, files (file:line), the contract to define, constraints, gotchas, done-when,
+rough effort. Effort assumes one focused engineer; parallelizable where noted.
+
+### WS0 — Foundations: rebase (done) + the three #577 bugs + ledger hardening
+**Goal:** land the merged branch clean and fix the known defects before building on them.
+
+1. **Rebase** — DONE (`68c1b34a`), both tsc projects green.
+2. **Update-button no-op** — `AppsSettingsRow.tsx:179-182`. `onClick` does
+   `setRepo(entry.repo); void install()`, but `install` (`:54`, `useCallback` deps
+   `[repo,busy,refresh]`) reads the *previous* `repo` (async `setState`), so it early-returns
+   or installs the wrong repo. **Fix:** `install(target?: string)` defaulting to `repo`;
+   Update calls `install(entry.repo)` directly.
+3. **Uninstall never deactivates** — verified: `AppsSettingsRow.remove` (`:80-94`) calls
+   `window.api.extensionsRemove` + `refresh()` and holds **no** `ExtensionHost` reference;
+   main has no handle on the renderer host; `grep '\.deactivate'` shows only
+   `deactivateAll` on provider unmount. So a removed extension's intervals/listeners/
+   registrations leak for the session. **Fix:** `remove` (and the Update path) must call
+   `useExtensionHost().deactivate(entry.manifest.id)` before/after the IPC. **Must be in the
+   renderer** — main cannot reach the host.
+4. **Ledger cast** — `ledger.ts:30` `return parsed as InstalledExtension[]` (no per-row
+   validation) flows unchecked into the `import()` URL and the palette. Deliberately
+   tolerated, but a legitimate hardening item: validate rows with a zod mirror of
+   `InstalledExtension`, drop malformed rows individually (not the whole ledger).
+
+**Constraint:** the #577 triple is already assigned "alongside piece 1" by the 2026-07-22
+plan (`:199-200`). **Effort:** ~1 day.
+
+### WS1 — Command spine (finish it)
+**Goal:** extension commands fully first-class in every command surface.
+
+Piece 1 (`c42a47a1`) wired them into the palette and the Settings *visibility* row. **The
+gap (research pass 3, correcting the piece-1 commit message):** the keybind editor
+`CommandKeybindingsRow` iterates `builtInCommandCatalog` **directly** (`:121`), takes **no
+props** (`:92`, rendered `<CommandKeybindingsRow />` at `SettingsList.tsx:234`), and never
+sees extension commands. It also filters by `command.category` (`:124`) grouped by an
+**exhaustive** `Record<CommandCategory, number>` (`:59-71`), and `deriveExtensionCommands`
+sets **no category** (`derive.ts:84-108`) — so extension commands would be filtered out even
+if listed.
+
+**Do:** give `CommandKeybindingsRow` the derived extension commands as props (from
+`SettingsPage`, which already computes them at `:69-75`); iterate catalog **plus** those;
+assign extension commands a category — a new `'extensions'` `CommandCategory` member (add to
+the union `types.ts:51` + `CATEGORY_LABELS`/`CATEGORY_RANK`) or a bucket in derivation.
+Capture/conflict-UI/commit are keyed by command-id string and work unchanged.
+
+**Done when:** an extension command appears in the keybind editor and can be bound.
+**Effort:** ~2-3 days. **No sandbox.**
+
+### WS2 — Keybindings (`contributes.keybindings` → the resolver)
+**Goal:** an extension's declared chord fires and shows in the editor.
+
+**The system (research pass 3):** `CommandBindingDefault = {commandId, bindings, context}`
+(`defaults.ts:55-59`); `buildDefaultKeybindings()` (`:77-283`) is the shipped table;
+`resolveEffectiveKeybindings(overrides, defaults, contextForCommand)` (`resolve.ts:93-143`)
+resolves id→chord with user overrides winning; `coerceCommandKeybindingOverrides` **already
+preserves unknown ids** "for an extension temporarily uninstalled" (`resolve.ts:29-38`);
+storage is the Settings blob key `commandKeybindingOverrides` (**not** a `~/.claude` file);
+firing is `useKeybinds.ts` → `pendingCommandInvocation` → `dispatchCommand`.
+
+**The insertion point:** an extension binding is a **default**, concatenated onto
+`buildDefaultKeybindings()`'s output. It must be threaded at **all three** call sites, or it
+half-works:
+1. `useKeybinds.ts:243` (`buildBindingIndex`) — hardcodes `buildDefaultKeybindings()`.
+   Without this, **the chord never fires.** The hook must also subscribe to
+   `installedExtensions`.
+2. `registry.ts:183` (`buildCommandRegistry`) — calls `resolveEffectiveKeybindings(...)`
+   with no `defaults` arg. Without this, the palette row shows no shipped chord.
+3. `CommandKeybindingsRow.tsx:101/105/115` — the editor. Without this, no default/conflict.
+
+**The derivation:** new `deriveExtensionKeybindings(installed): CommandBindingDefault[]` in
+`derive.ts` (mirroring `deriveExtensionCommands`). Per contributed `{command, key}`:
+`{ commandId: binding.command, bindings: [tryNormalizeKeybinding(binding.key)].filter(Boolean),
+context: 'global' }`. **Key-format gotcha:** the manifest `key` is freeform
+`z.string().max(64)` (`manifest.ts:110`) but the resolver needs the canonical `Keybinding`
+form (fixed modifier order `Cmd,Ctrl,Alt,Shift`, `normalize.ts:40`). Use
+`tryNormalizeKeybinding` (returns `null`, `normalize.ts:181-188`) at the boundary so one bad
+manifest key doesn't throw the whole table. `context: 'global'` is strictest for collision
+(overlaps every context), erring toward reporting conflicts.
+
+**Conflict policy:** run each chord through `findBindingOwners({binding, context:'global',
+commandDefaults, dictationBinding, excludeCommandId})` (`reservations.ts:356-387`).
+Non-empty = collision. **Accept-and-report at load** (like cross-extension command-id
+collisions, `derive.ts:16-18`), not reject-at-install — an extension can't see another's
+manifest. `ExtensionKeybindingContribution` already documents "Consulted AFTER every
+first-party binding, so an extension can never shadow ⌘W" (`extensions.ts:37-39`): on
+collision the first-party owner wins, the extension chord is dropped and reported.
+
+**Done when:** an extension shipping `{command,key}` fires the key, the editor shows it, a
+conflict is surfaced not silently dropped. **Effort:** ~3-5 days. **No sandbox.**
+
+### WS3 — Settings rows (`contributes.settings` → the registry)
+**Goal:** an extension's declared settings render as real rows and persist.
+
+**The hard rule (#249):** the app's `Settings` is one flat zustand-persist blob; a forgotten
+persist-version bump black-screened launch twice (`settingsRegistry.ts:962-975` states it
+verbatim). Extensions are authored outside the release cycle, so **extension setting values
+must never enter the Settings blob.**
+
+**The shape:** add an `'extension'` **marker** variant to the `SettingDefinition`
+discriminated union (`settingsRegistry.ts:92-287`), beside the existing `'apps'` marker,
+rendered by a new self-subscribing component in `SettingsList.tsx` (mirroring the
+`'command-keybindings' ? <CommandKeybindingsRow/>` / `'apps' ? <AppsSettingsRow/>` dispatch
+at `:234/:248`). The variant carries `{ type:'extension', extensionId, settingId,
+valueType:'boolean'|'number'|'string', default }`. `boolean` → toggle; `number`/`string` →
+inputs the generic union lacks (there is no free number/text control today).
+
+**The value store:** per-extension storage keyed by contribution id — `window.api.
+extensionStorageGet/Set(extensionId, key, value)` → `EXTENSION_STATE_DIR/<id>/state.json`
+(`storage.ts:116-177`, non-finite numbers already rejected). The row is self-subscribing
+(async read on mount, write-through on edit) exactly like `DictationApiKeyRow`. **Writes go
+to extension storage, never `setSettings`** (which also re-runs `applyTheme` every write,
+`slice.ts:29`).
+
+**The derivation:** `deriveExtensionSettings(installed): SettingDefinition[]` in `derive.ts`,
+concatenated into `getSettingsRegistry(...)` (`:396-988`); thread `installed` from
+`SettingsPage` (already reads it). Category: reuse the existing `'apps'` category labeled
+"Extensions" (`settingsCategories.ts:57-61`) or add a per-extension section (open question
+§9). Uninstall cleanup: **preserve** values (mirror the keybind store's unknown-id
+preservation; `ledger.ts:70-77` already keeps `EXTENSION_STATE_DIR` on uninstall).
+
+**Done when:** an extension's `boolean`/`number`/`string` setting renders an editable row
+whose value survives reload, stored under extension state. **Effort:** ~3-5 days. **No
+sandbox.**
+
+> WS1-3 together are the "no sandbox, high value" tranche and should be one coherent series.
+> They also complete the still-outstanding Stage-1 acceptance test ("nobody has launched the
+> app and clicked it") — do the manual run here.
+
+### WS4 — The sandbox substrate (iframe + RPC + identity)
+**Goal:** each extension's UI runs in a sandboxed iframe with the host holding all real
+power; the extension asks over a validated message bus; the host derives identity from the
+frame. This is the foundation the powerful half of the platform sits on.
+
+**Already half-built (research pass 1):**
+- `agent-code-ext://` scheme with all five privileges + realpath containment
+  (`scheme.ts`), registered pre-`whenReady` (`index.ts:229`), handled at `:465`.
+- CSP already whitelists `agent-code-ext:` in script/img/style/font/connect
+  (`index.html:28`).
+- `AgentCodeApiV1` all-async curated surface + `createAppHostApi` id-closure — the exact
+  shape a per-frame facade should expose.
+- `ViewMount` DOM-level contract + `viewBridge.tsx` isolated to one replaceable component.
+- **The RPC template to copy verbatim:** the remote mobile protocol
+  (`src/main/remote/protocol/messages.ts` + `scope.ts`) — a production zod-discriminated-
+  union-as-allow-list with per-message auth and request/response correlation ids
+  (`{token, id?, message}` → reply echoes `id`). "The schema IS the allow-list; out-of-scope
+  operations are unrepresentable." This is the frame bus.
+
+**Hard blockers to build:**
+1. **No `frame-src` in host CSP**, and CSP is per-document — the child frame needs its own
+   CSP header, which the scheme handler does not emit today (`scheme.ts`).
+2. **The scheme serves modules, not an HTML document entry** — the manifest `entry` is a
+   `.js`/`.mjs` (`ENTRY_PATH`, `manifest.ts:34-44`). Need a frame bootstrap HTML document +
+   child-document CSP emission in the handler.
+3. **Preload-per-frame requires a WebContents** — a plain iframe gets no preload
+   (postMessage-only, Option A); `WebContentsView` gets one + a partition (Option B). This is
+   the §4c fork.
+4. **Single preload build, single session/partition, single window**
+   (`mainWindow.ts:316-349`, `sandbox:false`, `contextIsolation:true`, `nodeIntegration:
+   false`). Option A needs no second preload; Option B needs a second electron-vite preload
+   entry + a partition model.
+5. **DOM-level host contracts don't cross frames** — the interaction-ownership attribute
+   (`lib/interaction-ownership.ts`), paint-order-by-sibling-index
+   (`app/surfaces/registry.tsx`), the theme cascade, and the **entire keyboard system**
+   (`useKeybinds.ts` single capture-phase listener — every host shortcut dies while focus is
+   in a frame; Cmd+W would close the window) must be re-plumbed over postMessage. The prior
+   plan prices this at **~350-650 LOC, keyboard routing being the bulk** (`2026-07-20-
+   extension-platform.md:789-794`).
+
+**Identity (research pass 2):** with a frame, `appId` stops being a caller argument and
+becomes `deriveExtensionId(event.senderFrame.url)` (the hostname the scheme already keys on)
+or the owning `MessagePortMain` (the cleanest — "the port IS the capability"). This converts
+the storage namespace into a real authority boundary and is the precondition for every
+Tier 1-3 capability.
+
+**What `viewBridge.tsx` changes vs keeps (research pass 1):** the status machine, the
+per-mount child div StrictMode fix, and error containment stay host-side. What changes:
+`mount(element)` becomes "attach the iframe, postMessage `mount`, child runs `mount` on its
+side"; the disposer becomes a postMessage + teardown; `getView` returns a *handle*, not a
+live function; theme tokens must be **pushed** over postMessage since the cascade doesn't
+cross. `hostGlobal.ts` (the React injection) becomes unnecessary in the frame model — the
+child bundles its own React — a genuine simplification.
+
+**Done when:** the timer extension renders in an iframe over `agent-code-ext://`, calls
+`api.storage`/`api.ui` over the `MessagePortMain` bus, and the host derives its id from the
+frame. **Effort:** ~2 weeks. The single hardest workstream. **Version note:** Electron 43 —
+`event.senderFrame`, `MessageChannelMain`/`MessagePortMain`, `WebContentsView` all available.
+
+### WS5 — Capability + consent model
+**Goal:** an extension declares the powers it needs; the user grants them; the host enforces
+per-call.
+
+**Schema (research pass 2):** add a top-level `permissions` field to
+`extensionManifestSchema` (a `z.enum` closed set narrowed by transform, exactly like
+`activationEvent`, `manifest.ts:118-129`), so an unknown capability is *unrepresentable* at
+install. The tier taxonomy is not invented — it is in `2026-07-20-extension-platform.md:781-
+788`: Tier 1 `workspace.observe`/`sessions.observe`/`panes.observe`; Tier 2 `fs.read`/
+`transcript.read`/`git.read`; Tier 3 `sessions.prompt`/`fs.write`/`git.commit`/
+`network.fetch`.
+
+**Mapping to real IPC (baseline: everything is trusted equally today):** `fs.read` →
+`fs:list-directory` (`fs.ts:30`, unbounded now); `git.read` → `git:status` (`git.ts:522`);
+`sessions.prompt` → `session:send-prompt` (`session.ts:98+`); the **one existing per-caller
+gate** is `EditorFsRootRegistry` (`editorFsRootRegistry.ts:9-98`) — grants keyed by
+`sender.id`, admit only if the named path canonically matches a live session cwd, revoked on
+navigation. **This is the grant-registry template.**
+
+**Consent flow:** install has zero consent today (`AppsSettingsRow.tsx:19-23` — "the repo
+name IS the trust decision"), valid only while the API is Tier 0. A grant step inserts
+between manifest parse and ledger write (`install.ts:218` has the manifest in hand before
+the bundle moves at `:229`). **Template:** `WorkflowSourceApprovalStore.authorize(request,
+prompt)` (`store.ts:35-61`) — grant bound to a **content hash**, not a name, so an update
+that widens permissions re-prompts (install already computes the tarball sha256,
+`install.ts:115`, stored in the ledger). Key the grant on `(extensionId, sha256,
+capability)`. The renderer dialog uses the `closeConfirmationBroker` promise-broker pattern.
+
+**Enforcement point:** the RPC router, dispatched by frame identity, gated per-capability
+(coarse, per method-group). Three layers: (1) parse gate — the message round-trips the
+allow-list union (unrepresentable = rejected); (2) grant gate — a per-frame grant registry
+populated from the consent store; (3) apply-time state check where needed (e.g.
+`sessions.prompt` validates against live entitlement, like the remote `pty` action).
+
+**The forced sequencing:** Tier 1 (metadata) can ship *advisory* same-realm. Tier 2 needs
+the consent store (buildable now). **Tier 3 enforcement is meaningless until WS4** gives
+each extension a distinct sender — the schema, store, and registry can all be built first,
+but the teeth only bite once identity is real. **Effort:** ~1 week (schema + store + registry)
++ enforcement that lands with WS4.
+
+### WS6 — Extension-view panes (grid / dispatch)
+**Goal:** an extension view mounts as a first-class pane, modeled on a terminal (durable
+host-side session + thin renderer attach view). "Attach like a terminal list."
+
+**The one render seam:** `renderWorkspaceLeaf` (`TileTree.tsx:96-171`) — the single switch
+on `SessionMeta.kind` that grid, both dispatch layouts, spotlight, and tile-tabs all funnel
+through. Add an `if (kind === 'extension-view')` short-circuit **before** the
+`getRendererProvider(kind)` throw at `:130`, sibling to the terminal branch at `:118`,
+returning `<ExtensionViewLeaf .../>`. This one edit lights up every mode.
+
+**The type seam:** extend `SessionKind` (`providerKind.ts:47`) — an extension view is **not**
+an `AgentProviderKind` (no transcript/resume/conditions/process), so add `'extension-view'`
+alongside `'terminal'`. Every `Record<AgentProviderKind,…>` registry correctly excludes it
+(and correctly throws if handed it — which is why the render short-circuit is mandatory).
+Update the `Exclude<SessionKind,'terminal'>` agent-only signatures (`pane.ts:292,296,541,641`)
+to also exclude `'extension-view'`, and audit `kind !== 'terminal'` agent guards toward
+`isAgentProviderKind(kind)`.
+
+**The session model — answer: (a) ride a real main-minted "extension-host session".** The
+id-minted-by-main invariant (`types.ts:15-17`) is load-bearing across replace/bury/lane/pin/
+recover; a renderer-minted id (option b) would force an "is this an extension leaf?" bypass
+into every `ensureSessionLive`/rehydrate path — the scattered-conditional smell the codebase
+fights. So: extend `SessionSpawnOptions.kind` to accept `'extension-view'` and add a spawn
+branch in `sessionManager.ts` (sibling to terminal at `:515`/`:1161`) that mints an id and
+registers a minimal `ExtensionHostSession` (no PTY, no provider) carrying `viewId`; `recover`
+is a trivial re-register. `getMainProvider` is never called (returns before it, like
+terminal).
+
+**The terminal template made concrete:** the authoritative state (for terminal, PTY + rolling
+buffer in main; for an extension, the mounted `ViewMount` DOM subtree in the renderer) is
+durable; the leaf component is a disposable attach point keyed on `sessionId` only
+(`TerminalLeaf.tsx:404`) so renderer churn never remounts it. **The extension case is harder
+on one axis:** an xterm can be cheaply re-created from main's buffer, but re-running
+`mount(element)` tears down and re-inits the extension (mount-once, `viewBridge.tsx:117-121`).
+So the durable ViewMount DOM must survive remounts.
+
+**The multi-mount / single-slot problem:** today `openAppId: string|null`
+(`uiShell/types.ts:308`) permits one open app. A pane model needs N views addressed by
+session id. Replace the single slot for the *pane* path (the modal path can keep `openAppId`)
+with: (1) **address** via `SessionMeta.extensionViewId` (rides the existing per-session
+metadata map, no new slice); (2) **durable mount** via a renderer-side ViewMount registry
+keyed by `sessionId` that owns a detached DOM node per session — `ExtensionViewLeaf` adopts
+the node on mount, re-detaches (not disposes) on unmount, the renderer analogue of main's
+survive-across-remount buffer. Same-view-in-many-panes ships as N independent mounts first
+(independent state), a shared-state mirror later — exactly parallel to the documented
+terminal multi-attach caveat (`workspace/types.ts:266-280`).
+
+**Manifest + derive:** add `'panel'` to `mount: z.enum([...])` (`manifest.ts:79`) and the
+`shared/types/extensions.ts` mirror. `deriveAppDefinitions`/`deriveExtensionCommands`
+(`derive.ts:21-113`) branch on `view.mount`: `modal` → current `openApp`/`AppHostSurface`;
+`panel` → a command whose `run` spawns an extension-view session and splits it into the grid
+(`workspace.spawnExtensionViewPane(view.id)`), not `openApp`. `viewComponentFor`
+(`viewBridge.tsx`) is mount-agnostic — reused unchanged; only the host container differs (a
+grid leaf div vs `DialogContent`). This is the payoff of the DOM-level `ViewMount` contract.
+
+**Persistence + forward-compat:** an extension pane persists like any leaf (id in the
+`TileNode` tree + `SessionMeta` in the flat map). `SessionMeta` gains
+`extensionViewId: string` (the durable mount identity, analogous to a terminal's `tmuxName`).
+`rehydrate.ts:615-632` — once `'extension-view'` is a known `SessionKind` it is no longer
+caught by the unknown-kind guard, so add an explicit branch: **installed** → metadata-restore
++ lazy-materialize on attach; **not installed** → apply the exact unknown-kind-preserved
+policy (dead-but-closable leaf with a message, metadata kept for a future install, never
+dropped). `ExtensionViewLeaf` must render that uninstalled/failed state too (an extension can
+be removed while a pane is open — `AppHostSurface.tsx:43-49` documents the stale-id reality).
+
+**Depends on:** WS4 for the isolated mount (a pane runs an extension's synchronous UI — same
+sandbox requirement as a modal view, more surface area). **Effort:** ~2 weeks. **Build order
+(research pass 4):** `providerKind` → manifest enum → `SessionMeta`/spawn opts →
+`sessionManager` branch → `ExtensionViewLeaf` + ViewMount registry + render short-circuit →
+`derive` modal/panel branch → `rehydrate` branch → the `Exclude` signature updates.
+
+### WS7 — Contributed surfaces (modals / overlays)
+**Goal:** an extension renders its own modal/overlay surface. (Feed/tool renderers are **cut**
+— see below and Decision 5.)
+
+**Surfaces registry:** `app/surfaces/registry.tsx` — `{id, Component}` arrays where "add a
+surface = one entry, App.tsx never edited." Mechanically extension-friendly, but the
+**load-bearing manual paint-order** (`:35-42`, z-50 ties resolved by array index; PR #505
+regressed exactly this) blocks a raw extension entry. **Contract needed:** an explicit
+`layer`/`priority` field on `SurfaceEntry` (the escape hatch `ConditionOutlet.tsx:47-54`
+already prescribes) + a bounded z-band for extension surfaces so a contributed surface
+*cannot* cover a first-party modal by tie-break. Extensions ride inside the one `app-host`
+slot (hosted through `AppHostSurface`), not as peer `SurfaceEntry`s, because contributed
+components can't read `useAppStore`/`useWorkspaceContext` (host internals the ABI forbids).
+
+**Feed / tool renderers — CUT (Decision 5).** Extensions do NOT render custom feed rows.
+An extension may ship an MCP tool, and its output renders through the **standard MCP
+rendering** the feed already applies to any MCP tool — the provider-neutral `ToolResultRow`
+fallback (`src/renderer/src/features/feed/ui/rows/ToolResultRow.tsx`), which runs its own
+ordered JSON/MCP/structured/plain probe and "must never branch on provider tool names."
+
+WHY cut: a custom renderer would return third-party React **synchronously into the feed** —
+the most trusted, central surface, inline with the user's real work. That both collides with
+the ABI's all-async/no-`@renderer/*`/frame-boundary rule *and* reopens a rendering pipeline
+that has been a repeated problem area (the renderer rewrite, provider plug-and-play #394).
+The safety and complexity cost far outweighs the differentiation. Extension tool output
+looking like standard MCP output is an acceptable, safe outcome. Do NOT build the
+`ToolRendererContribution` registry the research pass sketched; it is intentionally
+out of scope. Cutting it also removes WS7's only sandbox-synchronous-React problem — the
+remaining surface path rides the existing `app-host` slot.
+
+**Depends on:** WS4 (surfaces run extension UI through the iframe host). **Effort:** ~3-5 days
+(surfaces only, down from ~2-3 weeks once feed renderers are cut).
+
+### WS8 — SDK package + API versioning (threaded alongside)
+**Goal:** remove the authoring friction and make v2 cheap.
+
+**No SDK exists** (`grep agent-code-extension-api` = one hit, the planned Task C1). Authors
+today hand-roll (research pass 6, `docs/extensions/authoring.md §3-4`): 4 React/jsx/react-dom
+shim files reading `globalThis.__agentCodeHost`; a vite config with aliases (not `external`)
++ `lib` + `inlineDynamicImports` + `cssCodeSplit:false` + `define:{'process.env.NODE_ENV':
+'"production"'}` (missing it → `process is not defined` at `activate()`); and **committing
+`dist/`** (install is a source tarball, not a release asset). **Build:** a
+`packages/agent-code-extension-api` submodule (modeled on the other `packages/*` repos)
+exporting the typed `AgentCodeApiV1` + `ExtensionModule`/`Context`/`ViewMount` (canonical
+source `apps/api/types.ts` + `moduleContract.ts`), the `AgentCodeHostGlobal` type + the 4
+shims, the vite preset, a manifest type + zod mirror, and a scaffold (the `agent-code-timer`
+repo is the de-facto reference). **In the frame model (WS4)** the React-from-host shims
+largely dissolve (the child bundles its own React) — so sequence the SDK's shim story after
+the isolation decision.
+
+**Versioning:** `SUPPORTED_API_VERSION=1` (`manifest.ts:17`), rejected with a clear message
+if mismatched (`:184-188`). v1 freezes once an out-of-repo extension depends on it. **v2 =
+~30 lines:** a new `AgentCodeApiV2` interface, a `createHostV2` alongside `createAppHostApi`,
+dispatch on manifest `apiVersion`, `SUPPORTED_API_VERSION` → a supported *set* `{1,2}`. No
+edit to the v1 file — the reason the surface is one nested object, not 153 flat methods.
+**Effort:** ~3-5 days, threaded.
+
+## 6. Cross-cutting invariants — the do-not-break list
+
+1. **Extension state / settings / keybindings never enter the zustand-persist `Settings`
+   blob** (#249 black-screened launch twice). Values live in `EXTENSION_STATE_DIR` via
+   `extension:storage-*`, or in the `commandKeybindingOverrides` map (which is designed to
+   preserve unknown ids).
+2. **`AppDefinition` stays a manifest superset-by-one** (`apps/types.ts`). Capabilities go
+   through `AgentCodeApiV1`, never as fields on `AppDefinition` — adding host state to it
+   breaks the Stage-2 frame swap.
+3. **Every `AgentCodeApiV1` method returns a Promise** — the highest-value forward-compat
+   decision; never make one synchronous "because it obviously is."
+4. **The runtime React handshake stays OFF the ABI** (`__agentCodeHost`, not an API field) —
+   a host React-major bump must not be an ABI break.
+5. **Per-call concat, never a module-scope snapshot** — an adversarial audit found eight
+   module-scope snapshots that couldn't react to an install; don't add a ninth.
+6. **First-party callers unchanged** — every threaded parameter is additive with an empty
+   default.
+7. **CSP: amend only `script-src`/`connect-src` etc. with `agent-code-ext:`; never add
+   `unsafe-eval`/`blob:`/`file:` to script-src, and never touch `worker-src`** (the #513
+   Monaco-blob-worker comment is load-bearing).
+8. **New surface-registry entries go at the END of their array** (paint order; PR #505
+   regression) — until WS7 adds the explicit `layer`/`priority` field.
+9. **Declarative contributions import no extension bundle at registration time** — the
+   palette/editor/Settings populate from manifests alone; the moment a piece needs the loaded
+   module, it has crossed into WS4 territory.
+10. **Update path is intentionally the install path** (`rm`+`rename`, ledger row replaced by
+    id) — don't add a separate updater; do add deactivation before the swap.
+
+## 7. Security model & threat evolution
+
+- **Today:** single-user desktop, all code from this repo. Threat model = "mistake, not
+  attack." Same-realm extensions reach `window.api` directly; every guard is an accident
+  guard. Accepted worst case: storage-namespace confusion.
+- **After WS4:** each extension in its own frame; identity from `event.senderFrame`/
+  `MessagePortMain`. The storage namespace becomes a real authority boundary.
+- **After WS5:** declared `permissions`, consent bound to `(extensionId, sha256, capability)`,
+  enforced at the RPC router. Tier 1 advisory same-realm; Tier 2 consent-gated; Tier 3
+  enforceable only post-frame.
+- **Never (deliberately):** OS notifications (Tier 3, interrupt risk), a marketplace (repo
+  name = trust), background extensions by default (a product decision).
+
+## 8. Sequencing & dependency graph
+
+```
+WS0 (bugs) ─┬─► WS1 (command spine) ─► WS2 (keybinds) ─► WS3 (settings)   [no sandbox]
+            │        (declarative tranche — ship first, high value, low risk)
+            │
+            └─► WS4 (sandbox) ─┬─► WS5 (capability/consent)
+                               ├─► WS6 (panes)              [needs isolated mount]
+                               └─► WS7 (contributed surfaces)
+WS8 (SDK + versioning) ── threaded; its shim story sequences AFTER WS4's fork decision.
+```
+WS1-3 are independent of the sandbox and should land first. WS4 is the pivot. WS5/6/7 fan out
+from it. The §9 fork decision (Option A vs B) gates WS4's whole shape and should be settled
+before WS4 starts.
+
+## 9. Decisions — RESOLVED
+
+All six are settled; see the **Decisions locked** block at the top of this doc. Summary:
+
+1. Iframe fork → **Option A** (plain iframe + `MessagePortMain`).
+2. Keybinding conflict → **accept-and-report at load**.
+3. Settings placement → **per-extension section**.
+4. Uninstall → **preserve** values/overrides.
+5. Feed/tool renderers → **CUT**; extension MCP tools use standard MCP rendering.
+6. SDK → **separate submodule repo**.
+
+## 10. Effort summary
+
+| Workstream | Sandbox? | Effort |
+| --- | --- | --- |
+| WS0 bugs + ledger | no | ~1 day |
+| WS1 command spine | no | ~2-3 days |
+| WS2 keybindings | no | ~3-5 days |
+| WS3 settings rows | no | ~3-5 days |
+| WS4 sandbox substrate | — | ~2 weeks |
+| WS5 capability + consent | needs WS4 for teeth | ~1 week |
+| WS6 panes | needs WS4 | ~2 weeks |
+| WS7 contributed surfaces (feed renderers cut) | needs WS4 | ~3-5 days |
+| WS8 SDK + versioning | threaded | ~3-5 days |
+
+**Total: ~7-10 weeks** for the platform, one engineer, compressible
+with parallel work on the independent declarative tranche (WS1-3) and the SDK.
+
+## 11. Key file:line anchors (quick reference)
+
+- Manifest schema + contributes: `src/main/extensions/manifest.ts:65,72,82,108,131-148`
+- The ABI + tiers: `src/renderer/src/apps/api/types.ts:9-85`
+- Mount contract + context: `src/renderer/src/apps/host/moduleContract.ts:24,36-47`
+- The bridge: `src/renderer/src/apps/host/viewBridge.tsx:20-141`
+- The host: `src/renderer/src/apps/host/ExtensionHost.ts:65,86-104,111-141`
+- Install/ledger: `src/main/extensions/install.ts:205-246`; `ledger.ts:16,30,54,78`
+- Command wiring: `registry.ts:183` (`buildCommandRegistry`), `catalog.ts`,
+  `CommandPalette.tsx:808`, `derive.ts:57`
+- Keybinds: `command-keybindings/{defaults,resolve,reservations,normalize}.ts`;
+  `useKeybinds.ts:243`; `CommandKeybindingsRow.tsx`
+- Settings: `settingsRegistry.ts:92-287,384`, `SettingsList.tsx:234,248`, `storage.ts:116-177`
+- Panes: `TileTree.tsx:96-171`, `providerKind.ts:47`, `TerminalLeaf.tsx`,
+  `sessionManager.ts:515,1161`, `rehydrate.ts:615-632`, `uiShell/types.ts:308`
+- Isolation: `scheme.ts`, `mainWindow.ts:316-349`, `preload/index.ts:23`,
+  `remote/protocol/{messages,scope}.ts`, `index.html:28`, `ipc/extensions.ts:14-30`
+- Capability/consent: `editorFsRootRegistry.ts:9-98`, `WorkflowSourceApprovalStore.ts:18-61`
+- Registries to copy/avoid: `conditions-core/view.ts:67-143`, `ConditionOutlet.tsx:41-77`;
+  `registry.renderer.capabilities.ts:320-337`; `formatters/index.ts:17-43`
+- Theme: `settings/theme.ts:26,83-135`, `savedThemes.ts`, `customAppearance.ts:344-481`
+
+## Appendix — prior doc status
+
+| Doc | Status |
+| --- | --- |
+| `2026-07-20-extension-platform-investigation.md` | Stale snapshot; findings valid, anchors/§8 obsolete. **Superseded by this doc.** |
+| `2026-07-20-extension-platform.md` | Original full plan; **aligned + extended** here, re-anchored to the merge. |
+| `2026-07-20-extension-platform-stage1.md` | Superseded (its own header); Task 5/6 obsolete post-merge. |
+| `2026-07-22-extension-contributions-into-merged-systems.md` | Active near-term plan; **its 3 pieces = WS1-3 here**, expanded with the keybind-editor correction. |
diff --git a/docs/superpowers/specs/2026-07-20-extension-platform-investigation.md b/docs/superpowers/specs/2026-07-20-extension-platform-investigation.md
new file mode 100644
index 000000000..ebf67c6ed
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-20-extension-platform-investigation.md
@@ -0,0 +1,305 @@
+# Extension Platform — Investigation Findings
+
+> **Status:** live. This is the *evidence* the design will be argued from, not the design.
+> The architecture decision is deliberately **still open** at the bottom of this file —
+> four consultants are being run against it. The plan file lands after they report.
+
+**Date:** 2026-07-20
+**Branch:** `feat/extension-platform`
+
+---
+
+## 1. What is being built, in the user's words
+
+Personal workflow tools that live inside Agent Code — *not* product features, *not* MCP
+tools for the agent to call.
+
+- Installed and managed **from Settings**, sourced from GitHub.
+- Invoked by a palette command (`Open Timer`).
+- Opens **"a VS Code like custom page"** for that extension.
+- Backed by an API with **access to a lot of app features** — the reference example (a
+  timer) needs almost none of it, but "app-integrated extensions" are the point.
+
+The timer is the forcing function, not the goal. The goal is a platform where the user
+(and later others) can add workflow tools without touching core app source.
+
+---
+
+## 2. The single most important finding
+
+**Agent Code already ships an extension host.** `packages/workflow-mcp` executes
+user-authored JavaScript in production today, with every hard problem already solved:
+
+| Extension-host problem | Where it is already solved |
+|---|---|
+| Discover user code on disk | user-level + project-level workflow dirs |
+| Read metadata without executing it | `acorn` parses the `meta` export as a pure AST literal |
+| Integrity | SHA-256 of source bytes; 512 KB size cap |
+| Consent | Electron dialog keyed to `canonicalIdentity + sourceHash` (`WorkflowSourceApprovalStore`) |
+| Sandbox | `node:vm`, null-prototype global, `codeGeneration: { strings: false, wasm: false }` |
+| Determinism | `Date.now()` / `Math.random()` removed from the realm |
+| Process isolation | separate Electron `utilityProcess` — *"Agent Code Workflow Evaluator"* |
+| Lifecycle | heartbeats, timeouts, cancel, kill |
+
+**Implication:** the question was never "how do we host user code." That is done. The
+only open question is **how user-authored UI reaches the screen.**
+
+What workflow-mcp does *not* have: any UI contribution story at all.
+
+---
+
+## 3. Renderer constraints (verified, with evidence)
+
+### 3.1 Content-Security-Policy
+
+`src/renderer/index.html:15-18` — the app's only CSP:
+
+```
+default-src 'self';
+img-src 'self' data: blob:;
+style-src 'self' 'unsafe-inline' https://fonts.googleapis.com;
+font-src 'self' data: https://fonts.gstatic.com;
+script-src 'self';
+worker-src 'self' blob:
+```
+
+- No `'unsafe-eval'`, no `blob:` for scripts → the "read source text and evaluate it"
+  family of workarounds is closed.
+- `worker-src 'self' blob:` was tuned **deliberately** (the inline comment cites #513 —
+  Monaco's blob workers were dying silently). This policy is load-bearing, not incidental.
+- `src/remote-client/index.html` has **no** CSP at all — a second renderer surface that
+  any UI contribution model has to account for.
+
+**Correction worth recording:** one investigation agent reported "no CSP is set anywhere"
+— a grep miss that did not cover `.html`. That conclusion was wrong and its downstream
+reasoning ("no browser-level containment to build on") must not be reused.
+
+### 3.2 Document origin differs between dev and prod
+
+`src/main/window/mainWindow.ts:424-428`
+
+```ts
+if (process.env['ELECTRON_RENDERER_URL']) {
+  mainWindow.loadURL(process.env['ELECTRON_RENDERER_URL'])   // dev: http://localhost
+} else {
+  mainWindow.loadFile(join(__dirname, '../renderer/index.html'))  // prod: file://
+}
+```
+
+A design that works in one mode and not the other is the trap here. A `file://` import of
+a home-directory bundle plausibly passes in prod and is double-blocked in dev. **Any
+loading scheme must be identical in both modes** — which a custom protocol satisfies and
+a raw filesystem path does not.
+
+### 3.3 Window hardening
+
+`src/main/window/mainWindow.ts:334-336` — `sandbox: false`, `contextIsolation: true`,
+`nodeIntegration: false`. Renderer-hosted code gets no Node, no `require`, no fs. This is
+correct and should not change.
+
+### 3.4 Everything in the UI layer is statically registered
+
+| Registry | Shape | Evidence |
+|---|---|---|
+| Surfaces | 3 module-scope `const` arrays, 25 static imports | `app/surfaces/registry.tsx:41,:87,:92` |
+| Commands | one `const commandDefs` from 14 imported arrays (~95 defs) | `features/command-palette/registry.ts:26` |
+| Pane kinds | exhaustive `Record<AgentProviderKind, …>` that `throw`s on unknown | `providers/registry.renderer.ts:53` |
+| Keybinds | one hardcoded capture-phase `document` listener | `workspace/tile-tree/useKeybinds.ts:897` |
+
+There is **no add/remove/register function anywhere** in the renderer UI layer.
+
+The *consumption* side is already generic, though — `GlobalModals` / `GlobalOverlays` /
+`SidePanels` just `.map()` an array, and `buildCommandRegistry` is recomputed per context
+change. A second array concatenated into each map is a small change.
+
+### 3.5 A "page" cannot be a split pane
+
+`workspace/types.ts:38-39` — `TileNode` leaves are `{ type: 'leaf'; sessionId }`. Content
+dispatch runs through a closed `SessionKind` union that throws on unknown ids.
+
+Custom UI therefore mounts as **modal / overlay / side-panel**, not as a tile, unless a new
+non-session `TileNode` variant is added — which touches treeOps, geometry, persistence and
+keybinds. Out of scope for v1.
+
+### 3.6 Two integration contracts that do not cross a frame boundary
+
+This is the finding that most threatens the iframe design:
+
+- **Interaction ownership is a DOM attribute query** —
+  `lib/interaction-ownership.ts:22-36` reads `data-agent-code-interaction-owner="app"`
+  from the DOM.
+- **Paint order is DOM sibling index** — `app/surfaces/registry.tsx:33-38,:44-59`
+  documents that array position *is* z-order, and that a prior PR (#505) shipped a
+  stacking regression by grouping semantically instead of by paint order.
+
+An iframed surface participates in neither. It would need theme tokens piped over
+`postMessage` to avoid looking foreign, and would fight the keyboard system rather than
+join it.
+
+Also relevant: there is currently **zero** `<iframe>` / `<webview>` / `BrowserView` /
+`WebContentsView` anywhere in `src/`, and `shared/performance/types.ts:147` treats their
+appearance as an *anomaly* in the perf baseline.
+
+---
+
+## 4. Main-process / API constraints
+
+### 4.1 `window.api` cannot be handed to an extension
+
+`src/preload/index.ts:23` exposes exactly one global, built by flattening 27 per-domain
+modules into a single flat object — roughly **153 methods**, no namespacing, including
+`spawnSession`, `killSession`, `editor-fs:*` writes and `git:*`. Name collisions are
+caught only by TypeScript at compile time (`preload/api/index.ts:38-42`), a guarantee that
+means nothing for out-of-tree code.
+
+There is **no IPC channel allowlist, no sender validation, and effectively no argument
+validation** on the desktop path (~130 raw `ipcMain.handle('<literal>', …)` registrations,
+zero `validateSender` hits).
+
+**Therefore:** extensions must get a separate, narrow, schema-validated bridge — never a
+filtered view of `window.api`.
+
+### 4.2 Prior art for capability boundaries already exists
+
+Two real precedents, and they are the templates:
+
+- `EditorFsRootRegistry` — per-`WebContents` filesystem root grants. *The extension may
+  name a path, but the name is not authority.*
+- `src/main/remote/protocol/messages.ts` — a zod discriminated union where **the union is
+  the allow-list**. Unrepresentable rather than denied.
+
+### 4.3 Persistence has a landmine
+
+Renderer settings live in one zustand-persist `localStorage` key with a manually bumped
+version. `app-state/store.ts:35-57` documents that forgetting the bump **shipped a
+black-screen launch bug twice** (#249).
+
+**Therefore:** extension settings must not go in the `Settings` store. Use main-owned
+state under `STATE_DIR` plus the existing self-subscribing settings-row marker pattern
+(`cli-update-behavior` / `dictation-api-key` are the precedents).
+
+### 4.4 No runtime capability registry
+
+`src/mcp/shared/types.ts:1-15` — MCP domains are a closed TypeScript union
+(`'ping' | 'orchestration' | 'ai_workspace' | 'agent_transcripts' | 'workflows'`), gated by
+five hand-written `if` blocks. An extension-contributed capability cannot be *expressed*
+today without introducing a runtime registry keyed by string id.
+
+---
+
+## 5. Distribution precedent
+
+Two existing models in-repo:
+
+- **`third_party/<tool>/manifest.json`** — pinned version + per-arch sha256 + URL template;
+  binaries never committed; a fetch script verifies the hash before use. **This is directly
+  reusable as an extension distribution model.**
+- **`packages/*`** — git submodules consumed as `file:` deps with build-time Vite aliases.
+  **Not** a packaging model: there is no artifact resolution, version negotiation, or
+  integrity check anywhere for `packages/*`.
+
+Install should use a **release tarball, not `git clone`** — `git` is `required: false` and
+`src/main/ipc/git.ts:115-118` launders its failures into `''` (issue #495/A5).
+
+---
+
+## 6. Theming — the one part that is unambiguously easy
+
+`src/renderer/src/styles.css` defines a two-layer token system:
+
+```css
+:root, [data-mode="dark"] {
+  --theme-canvas: #0a0a0a;
+  --theme-surface: #111113;
+  --theme-ink: #e8e8e6;
+  /* … */
+}
+
+@theme inline {                              /* Tailwind binding */
+  --color-surface: var(--theme-surface);
+}
+```
+
+The `--theme-*` layer is exactly the shape VS Code exposes to webviews as `--vscode-*`.
+Whatever hosting model wins, extensions consume these token names and re-theme live when
+the host re-pushes on mode/accent/font change.
+
+---
+
+## 7. Environment note
+
+`package.json` declares `electron: ^43.1.0`; `package-lock.json` pins **43.1.1**; CI runs
+`npm ci --include=dev` on Node 24 and has been green on `main` since the bump landed
+2026-07-12 (`23205144`).
+
+The local `node_modules` in this checkout is stale at **31.7.7** — an install artifact, not
+a real version disagreement. Any spike touching `protocol.handle`, custom schemes, or
+iframes **must** run against 43.1.1 or its result is meaningless. Fix with `nvm use` +
+`unset NODE_ENV` + `npm ci --include=dev`, and note that `node_modules` is shared by ~30
+worktrees via symlink.
+
+---
+
+## 8. The open architecture decision
+
+Hosting is solved (§2). Everything below is about **how extension UI reaches the screen**,
+and it is genuinely unresolved. Estimates are from the read-only investigation and have not
+been validated by a spike.
+
+### Option A — compiled-in apps folder (`src/apps/<id>/`)
+An app is a repo directory exporting a definition object; one generic host surface, one
+generic `openAppId` field, one command module that maps the app list. Adding an app is one
+import plus one array entry.
+
+- **Effort:** 1–2 days host, ~half a day for the timer.
+- **Unlocks:** full React, full store access, full type safety, native theming, zero new
+  security surface.
+- **Costs:** rebuild to add or update an app. **Does not satisfy "install from Settings."**
+
+### Option B — runtime-loaded JS bundle
+Extension bundle in `~/.config/agent-code/extensions/<id>/`, loaded into the renderer via a
+privileged custom scheme.
+
+- **Effort:** 2–4 weeks, *"and it never really finishes."*
+- **Blocker named by the synthesis:** a **stable injected host ABI**. Extension code cannot
+  `import react` (two copies ⇒ broken hooks) and cannot import app modules
+  (`electron-builder.yml` strips `!src/**`; chunks are content-hashed —
+  `./assets/index-BK1aliEx.js` rotates every build). Every host object must be *passed in*,
+  which means designing and versioning that object before the first extension exists.
+- **Less hard than folklore:** the renderer emits native ESM with no `output.format`
+  override, so `import(variable)` survives Rollup. Bundling is the weakest constraint here,
+  not the strongest.
+
+### Option C — iframe on a custom scheme or local origin
+Extension owns its own document, own origin, own CSP.
+
+- **Effort:** 1.5–3 weeks.
+- **Unlocks:** true isolation, arbitrary pixels, any framework, no host `script-src` change
+  (an iframe needs `frame-src`, since CSP is per-document).
+- **Costs:** §3.6 — interaction ownership and paint order are DOM-level contracts that do
+  not cross a frame boundary. Plus a postMessage RPC layer, a per-frame CSP, and a perf
+  baseline update. `RemoteServer` + `src/remote-client` prove the "second built surface over
+  local HTTP" half already works.
+
+### The question the consultants must answer
+
+> The user wants (a) install-from-Settings, (b) a custom page, and (c) a broad app API.
+> Option A satisfies (b) and (c) in 1–2 days but fails (a). Options B and C satisfy (a) at
+> 10–20× the cost, and C specifically trades away the two DOM-level contracts that make a
+> surface feel native.
+>
+> **Is there a staging that delivers a working timer fast without building a substrate the
+> real answer has to tear out?**
+
+---
+
+## 9. Deliberately not decided here
+
+- Whether v1 is desktop-only (`src/remote-client` is a second renderer build).
+- Whether extensions ever get a tile/pane mount, or stay modal/panel/overlay forever.
+- Relationship to issue **#244** (host user-authored *MCP servers* as extensions). That
+  issue gives extensions **agent** capabilities; this work gives them **app** capabilities.
+  Sibling systems or one system is an open call.
+- Whether `components/ui/README.md`'s "no surface factories" guardrail is contradicted by
+  this work. If a design lands that looks like a surface factory, that README must be
+  updated in the same PR with the reasoning — not quietly bypassed.
diff --git a/packages/agent-code-extension-api b/packages/agent-code-extension-api
new file mode 160000
index 000000000..5efa6c3b4
--- /dev/null
+++ b/packages/agent-code-extension-api
@@ -0,0 +1 @@
+Subproject commit 5efa6c3b464bafcbe295aab185df398e6a13016f
diff --git a/src/main/extensions/bundleHash.system.test.ts b/src/main/extensions/bundleHash.system.test.ts
new file mode 100644
index 000000000..be510e28d
--- /dev/null
+++ b/src/main/extensions/bundleHash.system.test.ts
@@ -0,0 +1,97 @@
+import { mkdtemp, mkdir, rm, symlink, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { computeBundleHash } from '@main/extensions/bundleHash.js'
+
+// `.system.test.ts` because this crosses a real filesystem boundary: the whole
+// point of the function is what it reads off disk, and a mocked fs would test
+// the mock's traversal rather than the one that runs in production.
+
+const temporaryRoots: string[] = []
+
+async function makeBundle(files: Record<string, string>): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'agent-code-bundle-hash-'))
+  temporaryRoots.push(root)
+  for (const [relative, contents] of Object.entries(files)) {
+    const absolute = join(root, relative)
+    await mkdir(join(absolute, '..'), { recursive: true })
+    await writeFile(absolute, contents, 'utf8')
+  }
+  return root
+}
+
+afterEach(async () => {
+  // try/finally-equivalent cleanup: a failed assertion must not leak a temp tree
+  // into the next run, where a leftover directory would change a later digest.
+  await Promise.all(temporaryRoots.splice(0).map(root => rm(root, { recursive: true, force: true })))
+})
+
+describe('computeBundleHash', () => {
+  it('is stable for identical content in two different directories', async () => {
+    // The property the grant check depends on: the digest is a function of the
+    // bundle's CONTENT, not of where it happens to live or when it was written.
+    // Without this, a reinstall of identical bytes would look like a change and
+    // force pointless re-consent.
+    const a = await makeBundle({ 'agent-code.extension.json': '{}', 'dist/index.js': 'export {}' })
+    const b = await makeBundle({ 'agent-code.extension.json': '{}', 'dist/index.js': 'export {}' })
+    expect(await computeBundleHash(a)).toBe(await computeBundleHash(b))
+  })
+
+  it('changes when a NON-entry file changes', async () => {
+    // ── THE REGRESSION THIS FILE EXISTS FOR ──
+    // The grant used to bind to the tarball digest (unrecomputable) and, on the
+    // local-folder path, to the ENTRY file's bytes alone. Both let a sibling
+    // chunk be swapped while the grant still matched — and the entry can
+    // `import('./util.js')` at runtime, so that sibling is executed code holding
+    // capabilities the user approved for something else.
+    const before = await makeBundle({ 'dist/index.js': 'export {}', 'dist/util.js': 'export const a = 1' })
+    const hashBefore = await computeBundleHash(before)
+    await writeFile(join(before, 'dist/util.js'), 'export const a = 2', 'utf8')
+    expect(await computeBundleHash(before)).not.toBe(hashBefore)
+  })
+
+  it('changes when a file is renamed but its bytes are not', async () => {
+    // Guards the length-framed encoding. Digesting bare concatenated paths and
+    // contents would let ("a/b","c") collide with ("a","/bc"), so a rename could
+    // be crafted to preserve the hash.
+    const original = await makeBundle({ 'a/b.js': 'x', 'c.js': 'y' })
+    const renamed = await makeBundle({ 'a.js': 'x', 'b/c.js': 'y' })
+    expect(await computeBundleHash(original)).not.toBe(await computeBundleHash(renamed))
+  })
+
+  it('changes when a file is added or removed', async () => {
+    const base = await makeBundle({ 'dist/index.js': 'export {}' })
+    const hashBase = await computeBundleHash(base)
+    await writeFile(join(base, 'dist/extra.js'), 'export {}', 'utf8')
+    expect(await computeBundleHash(base)).not.toBe(hashBase)
+  })
+
+  it('hashes a symlink by its target string and never follows it', async () => {
+    // Following would (a) make the digest depend on a file outside the bundle and
+    // (b) turn this function into an arbitrary-file read for anything that can
+    // commit a symlink to a repository.
+    const root = await mkdtemp(join(tmpdir(), 'agent-code-bundle-hash-'))
+    temporaryRoots.push(root)
+    const outside = join(root, 'outside.txt')
+    await writeFile(outside, 'secret', 'utf8')
+    const bundle = join(root, 'bundle')
+    await mkdir(bundle, { recursive: true })
+    await symlink(outside, join(bundle, 'link.js'))
+
+    const hashBefore = await computeBundleHash(bundle)
+    // Changing the TARGET's contents must not move the bundle's hash: the target
+    // is not part of the bundle.
+    await writeFile(outside, 'different secret entirely', 'utf8')
+    expect(await computeBundleHash(bundle)).toBe(hashBefore)
+  })
+
+  it('rejects a missing directory rather than returning a hash', async () => {
+    // Callers treat a throw as "no capabilities". A function that returned some
+    // sentinel digest for an absent bundle would let a deleted extension keep its
+    // grant, which is the fail-open the whole change removes.
+    await expect(computeBundleHash(join(tmpdir(), 'agent-code-bundle-hash-does-not-exist'))).rejects.toThrow()
+  })
+})
diff --git a/src/main/extensions/bundleHash.ts b/src/main/extensions/bundleHash.ts
new file mode 100644
index 000000000..90c8e645b
--- /dev/null
+++ b/src/main/extensions/bundleHash.ts
@@ -0,0 +1,142 @@
+import { createHash } from 'node:crypto'
+import { lstat, readdir, readFile, readlink } from 'fs/promises'
+import { join, relative, sep } from 'path'
+
+// The content hash of an INSTALLED extension bundle.
+//
+// ── WHY THIS EXISTS ──
+// The capability grant is supposed to bind to the exact code the user consented
+// to: "when the bytes change, the grant no longer matches and the capabilities
+// must be re-approved" (grants.ts). That invariant was documented but not
+// implemented. The grant recorded the ledger's `sha256` and the check read the
+// ledger's `sha256` — both written by the same finalizeInstall() call, so the
+// comparison could never fail. Nothing ever looked at the bundle on disk again,
+// so editing a file under EXTENSIONS_DIR kept every granted capability.
+//
+// The tarball hash cannot fix that: the tarball is deleted after extraction, so
+// it is unrecomputable by construction. It answers a real but DIFFERENT question
+// ("which bytes did GitHub hand me"), which is why it is kept as provenance
+// rather than repurposed. This hash answers "what am I about to run", and it is
+// the only one that can be recomputed later — which is the entire requirement.
+//
+// ── WHY THE WHOLE BUNDLE AND NOT JUST `entry` ──
+// The entry module is one file, but the scheme handler serves EVERY file under
+// the bundle root and the entry can `import('./util.js')` at runtime. Hashing
+// only the entry would let a swapped sibling chunk keep a matching grant, so the
+// capabilities would be held by code the user never approved — the exact failure
+// this is meant to close.
+//
+// ── WHY THIS SHAPE OF DIGEST ──
+// Sorted relative paths, with an explicit length prefix on every field. Sorting
+// makes the result independent of readdir order, which is filesystem- and
+// platform-dependent. The length prefixes make the encoding unambiguous: without
+// them the pair ("a/b", "c") and the pair ("a", "/bc") digest identically, so a
+// rename could be made to collide with an edit.
+//
+// ── WHY SYMLINKS ARE HASHED AS THEIR TARGET STRING ──
+// Following them would read files outside the bundle: a hash that changes for
+// reasons unrelated to the extension, and a way to turn this function itself
+// into an arbitrary-file read. The link's own target text is the part that
+// belongs to the bundle, so that is what is hashed.
+
+/** Field separator for the digest framing. Any byte works; the length prefixes
+ *  are what make the encoding unambiguous, this only keeps it readable. */
+const FIELD = ' '
+
+// ── THIS FUNCTION RUNS ON EVERY FRAME OPEN, IN MAIN, SO IT MUST BE BOUNDED ──
+//
+// The installer's caps do not imply a bound here. MAX_TARBALL_BYTES bounds a
+// COMPRESSED download on the GitHub path only; the local-folder path has no size
+// limit at all; and a bundle can also grow after install by any means outside the
+// app. Meanwhile every capability check re-reads the whole tree in the process
+// that holds every agent session.
+//
+// So the limits live with the walk, not with the installer. Exceeding any of them
+// THROWS, which is the correct failure: every caller already treats a throw as "no
+// capabilities", so an implausible bundle degrades to Tier-0 instead of wedging the
+// main process. The values are ~50x the largest plausible real extension.
+const MAX_FILES = 10_000
+const MAX_TOTAL_BYTES = 64 * 1024 * 1024
+const MAX_DEPTH = 32
+
+export class BundleTooLargeError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'BundleTooLargeError'
+  }
+}
+
+async function collectFiles(dir: string, out: string[], depth: number): Promise<void> {
+  if (depth > MAX_DEPTH) {
+    throw new BundleTooLargeError(`bundle nests deeper than ${MAX_DEPTH} directories`)
+  }
+  const dirents = await readdir(dir, { withFileTypes: true })
+  for (const dirent of dirents) {
+    const absolute = join(dir, dirent.name)
+    // lstat, never stat: a symlink must be recorded AS a symlink (see header).
+    const stats = await lstat(absolute)
+    if (stats.isDirectory()) {
+      await collectFiles(absolute, out, depth + 1)
+    } else if (stats.isSymbolicLink() || stats.isFile()) {
+      if (out.length >= MAX_FILES) {
+        throw new BundleTooLargeError(`bundle contains more than ${MAX_FILES} files`)
+      }
+      out.push(absolute)
+    }
+    // Sockets, FIFOs and devices are deliberately skipped: they have no stable
+    // content, and a bundle containing one is already malformed.
+  }
+}
+
+/**
+ * SHA-256 over every file in `bundleDir`, path-sensitive and order-independent.
+ *
+ * Throws if the directory cannot be read, is empty, or exceeds the bounds above.
+ * Callers MUST treat every throw as "no valid hash", never as "unchanged" — a
+ * missing bundle with a passing grant check is precisely the fail-open this
+ * function exists to remove.
+ */
+export async function computeBundleHash(bundleDir: string): Promise<string> {
+  const files: string[] = []
+  await collectFiles(bundleDir, files, 0)
+
+  // An EMPTY directory would otherwise digest to SHA-256(""), a perfectly
+  // well-formed hash for a bundle that contains nothing. That is the one input for
+  // which a valid-looking digest is worse than an error: it is what a half-deleted
+  // or not-yet-populated directory looks like, and a grant must never match one.
+  // Callers treat a throw as "no capabilities", which is the right answer here.
+  if (files.length === 0) {
+    throw new Error(`extension bundle at ${bundleDir} contains no files`)
+  }
+
+  // Sort by the POSIX-normalized relative path so the digest is identical
+  // regardless of readdir order or the platform's path separator. `stats` is
+  // carried from the walk rather than re-lstat'd: the second stat doubled the
+  // syscall count and, more importantly, widened the window in which the tree can
+  // change between deciding what to hash and hashing it.
+  const entries = await Promise.all(
+    files.map(async absolute => ({
+      absolute,
+      rel: relative(bundleDir, absolute).split(sep).join('/'),
+      link: (await lstat(absolute)).isSymbolicLink(),
+    })),
+  )
+  entries.sort((a, b) => (a.rel < b.rel ? -1 : a.rel > b.rel ? 1 : 0))
+
+  const digest = createHash('sha256')
+  let totalBytes = 0
+  for (const { absolute, rel, link } of entries) {
+    const payload = link ? Buffer.from(await readlink(absolute), 'utf8') : await readFile(absolute)
+    totalBytes += payload.byteLength
+    if (totalBytes > MAX_TOTAL_BYTES) {
+      throw new BundleTooLargeError(
+        `bundle exceeds ${Math.round(MAX_TOTAL_BYTES / 1e6)} MB of hashable content`,
+      )
+    }
+    digest.update(`${link ? 'l' : 'f'}${FIELD}`)
+    digest.update(`${rel.length}${FIELD}${rel}${FIELD}`)
+    digest.update(`${payload.byteLength}${FIELD}`)
+    digest.update(payload)
+  }
+  return digest.digest('hex')
+}
diff --git a/src/main/extensions/frameDocument.test.ts b/src/main/extensions/frameDocument.test.ts
new file mode 100644
index 000000000..408afb9a2
--- /dev/null
+++ b/src/main/extensions/frameDocument.test.ts
@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest'
+
+import { buildFrameDocument, childFrameCsp } from '@main/extensions/frameDocument.js'
+
+// Guards for the extension frame's containment boundary. Every case here is a defect
+// an adversarial review actually demonstrated against this file — they are regression
+// locks, not hypotheticals.
+
+const base = {
+  extensionId: 'victim',
+  viewId: 'victim.main',
+  entry: 'dist/index.js',
+  declaredCommands: ['victim.start'],
+  declaredViews: ['victim.main'],
+  nonce: 'test-nonce',
+}
+
+/** Every inline <script> body in the document. */
+function scriptBodies(html: string): string[] {
+  return [...html.matchAll(/<script[^>]*>([\s\S]*?)<\/script>/g)].map(m => m[1])
+}
+
+/**
+ * ── THE ASSERTION THAT WOULD HAVE CAUGHT A SHIPPED, TOTAL FAILURE ──
+ *
+ * The bootstrap contained a literal script closing tag inside one of its own
+ * comments — the comment explaining how a closing tag breaks the document quoted
+ * the payload verbatim. An HTML tokenizer ends a script element at the first
+ * `</script` it sees with no regard for JavaScript context, so in a real browser
+ * the frame's module script terminated after ~300 characters of comment and the
+ * entire runtime — the API proxy, mount, the dynamic import, teardown — became
+ * inert text in the body. No extension frame could ever have worked.
+ *
+ * Nothing caught it. Source review does not surface it (the file is valid
+ * TypeScript and the string is valid JavaScript), the existing "parses as
+ * JavaScript" test passed because `new Function` on a comment-only prefix parses
+ * fine, and `scriptBodies` above is itself non-greedy, so every assertion built on
+ * it was quietly examining a truncated prefix.
+ *
+ * This checks the property directly on the emitted document: the number of closing
+ * tags must equal the number of opening tags. One extra means some script body
+ * contains a close tag, which means that script is truncated in a browser.
+ */
+function assertNoPrematureScriptClose(html: string): void {
+  const opens = (html.match(/<script/g) ?? []).length
+  const closes = (html.match(/<\/script>/g) ?? []).length
+  expect(closes).toBe(opens)
+}
+
+describe('childFrameCsp', () => {
+  it('names the extension origin explicitly and never the bare scheme', () => {
+    const csp = childFrameCsp('n', 'alpha')
+    // A bare `agent-code-ext:` scheme-source matches EVERY extension's origin. Since
+    // 'self' already covers the document's own origin, the bare scheme would grant
+    // only the cross-extension case — letting one extension fetch and execute another's
+    // bundle.
+    expect(csp).not.toMatch(/(^|[; ])agent-code-ext:(?!\/\/)/)
+    expect(csp).toContain('agent-code-ext://alpha')
+  })
+
+  it('sets base-uri and form-action, which do NOT fall back to default-src', () => {
+    const csp = childFrameCsp('n', 'alpha')
+    // Without base-uri, an injected <base> repoints the bootstrap's relative import().
+    // Without form-action, a form POST is an egress channel connect-src cannot see.
+    expect(csp).toContain("base-uri 'none'")
+    expect(csp).toContain("form-action 'none'")
+  })
+
+  it('does not allow another extension origin', () => {
+    expect(childFrameCsp('n', 'alpha')).not.toContain('agent-code-ext://beta')
+  })
+})
+
+describe('buildFrameDocument', () => {
+  it('cannot be escaped by a </script> payload in viewId or entry', () => {
+    // This exact payload passes every one of the manifest schema's path refinements:
+    // not absolute, no backslash, no `..` segment, ends in .js, under 256 chars.
+    const payload = 'a</script><script src="agent-code-ext://evil/p.js"></script>b.js'
+    const html = buildFrameDocument({ ...base, viewId: payload, entry: payload })
+
+    // Exactly two script elements: the JSON config island and the nonced bootstrap.
+    expect(scriptBodies(html)).toHaveLength(2)
+    expect(html).not.toContain('<script src="agent-code-ext://evil/p.js">')
+  })
+
+  it('round-trips the config values through the JSON island', () => {
+    const html = buildFrameDocument(base)
+    const island = html.match(
+      /<script type="application\/json" id="agent-code-ext-cfg">([\s\S]*?)<\/script>/,
+    )
+    expect(island).not.toBeNull()
+    const cfg = JSON.parse(island![1]) as Record<string, unknown>
+    expect(cfg.viewId).toBe(base.viewId)
+    expect(cfg.entry).toBe(base.entry)
+    // Only what the bootstrap actually reads. A `parentOrigin` was carried here
+    // and never used; a required, attacker-supplied, unused field reads as a
+    // security control that is doing nothing.
+    expect(Object.keys(cfg).sort()).toEqual([
+      'declaredCommands',
+      'declaredViews',
+      'entry',
+      'viewId',
+    ])
+  })
+
+  it('escapes < in the config island so no value can open or close an element', () => {
+    const html = buildFrameDocument({ ...base, viewId: 'x<y' })
+    const island = html.match(
+      /<script type="application\/json" id="agent-code-ext-cfg">([\s\S]*?)<\/script>/,
+    )!
+    expect(island[1]).not.toContain('<')
+    // …and JSON.parse still reads it back exactly.
+    expect((JSON.parse(island[1]) as { viewId: string }).viewId).toBe('x<y')
+  })
+
+  it('emits a bootstrap that parses as JavaScript', () => {
+    // The bootstrap is a string in main and is never type-checked; a syntax error
+    // would only ever surface inside a live frame.
+    const bodies = scriptBodies(buildFrameDocument(base))
+    const bootstrap = bodies.find(b => !b.trim().startsWith('{'))!
+    expect(() => new Function(bootstrap)).not.toThrow()
+  })
+
+  it('carries the per-origin CSP in the document meta tag too', () => {
+    const html = buildFrameDocument({ ...base, extensionId: 'alpha' })
+    expect(html).toContain('agent-code-ext://alpha')
+  })
+})
+
+describe('the declared-contributions contract', () => {
+  it('carries the manifest\'s declared ids into the frame', () => {
+    // The frame is the only place an extension registers anything, so it is the
+    // only place that can reject an undeclared id. It cannot ask anyone — the ids
+    // have to arrive with the document.
+    const html = buildFrameDocument(base)
+    const island = html.match(
+      /<script type="application\/json" id="agent-code-ext-cfg">([\s\S]*?)<\/script>/,
+    )!
+    const cfg = JSON.parse(island[1]) as { declaredCommands: string[]; declaredViews: string[] }
+    expect(cfg.declaredCommands).toEqual(['victim.start'])
+    expect(cfg.declaredViews).toEqual(['victim.main'])
+  })
+
+  it('emits a bootstrap that refuses an undeclared registration', () => {
+    // ── THE REGRESSION THIS PINS ──
+    // The check lived in the host-realm ExtensionHost, which imported the module
+    // and compared against the manifest it held. That host was deleted when
+    // activation moved into the frame, and the check went with it silently — the
+    // bootstrap just wrote into its maps, while the type, the module contract and
+    // the authoring guide all still promised rejection. The failure it prevents is
+    // invisible: a handler registered under an id the manifest does not declare can
+    // never be invoked by anything, so a typo produced a command that did nothing,
+    // with no error anywhere.
+    const bootstrap = scriptBodies(buildFrameDocument(base)).find(
+      body => !body.trim().startsWith('{'),
+    )!
+    expect(bootstrap).toContain('assertDeclared')
+    expect(bootstrap).toContain('not declared in contributes.')
+  })
+})
+
+describe('the emitted document is not truncated by its own contents', () => {
+  it('has exactly one closing tag per script element', () => {
+    assertNoPrematureScriptClose(buildFrameDocument(base))
+  })
+
+  it('stays intact for values that carry a closing tag', () => {
+    // The config island escapes `<`, so even a hostile entry/viewId cannot add one.
+    // This is the same payload the injection test uses, checked for a different
+    // property: not "does it inject", but "does it truncate".
+    const payload = 'a</scr' + 'ipt><scr' + 'ipt>b.js'
+    assertNoPrematureScriptClose(buildFrameDocument({ ...base, viewId: payload, entry: payload }))
+  })
+
+  it('the module script survives to its final statement', () => {
+    // The end of the bootstrap is the pagehide teardown. If the element is being cut
+    // short anywhere, this is what notices — counting tags proves the document is
+    // well-formed, and this proves the RUNTIME is whole.
+    const html = buildFrameDocument(base)
+    const moduleStart = html.indexOf('<script type="module"')
+    const body = html.slice(moduleStart, html.indexOf('</script>', moduleStart))
+    expect(body).toContain("addEventListener('pagehide'")
+    expect(body).toContain("import('./' + ENTRY)")
+  })
+})
\ No newline at end of file
diff --git a/src/main/extensions/frameDocument.ts b/src/main/extensions/frameDocument.ts
new file mode 100644
index 000000000..3c3166b29
--- /dev/null
+++ b/src/main/extensions/frameDocument.ts
@@ -0,0 +1,463 @@
+// The HTML document a sandboxed extension frame loads (WS4, Decision A).
+//
+// The scheme handler serves this for the reserved path `__agent-code-frame__.html`.
+// It is a DISTINCT document, at the extension's own origin, framed by the host — so
+// it cannot reach `window.api`, the parent DOM, or another extension. Its only
+// channel is postMessage to `window.parent`, brokered by frameHost.ts.
+//
+// WHY generated in main rather than shipped as a static file: the document embeds
+// the extension's own `entry` path (from its validated manifest) and a per-load
+// nonce, neither of which a static file can carry. `entry` has already passed the
+// manifest's path refinements + install-time realpath containment, so it is safe to
+// interpolate; it is JSON-encoded here anyway as defence in depth.
+//
+// RUNTIME NOTE: the bootstrap below is the one part of WS4 that cannot be
+// type-checked into correctness — it runs only inside a live frame. It is
+// deliberately minimal (Tier-0 API proxy + activate + mount) and converges with the
+// SDK's child runtime (WS8); treat a real in-frame load as its acceptance test.
+
+export type FrameDocumentInput = {
+  /** The extension this frame belongs to. Already validated by the scheme handler —
+   *  used to build a per-ORIGIN CSP rather than a per-scheme one (see childFrameCsp). */
+  extensionId: string
+  /** The contributed view id to mount once the parent sends the mount message. */
+  viewId: string
+  /** The manifest `entry`, relative to the bundle root (already path-validated). */
+  entry: string
+  /** Contributed command ids from the manifest. The frame refuses to register a
+   *  handler for anything outside this list — see assertDeclared in the bootstrap. */
+  declaredCommands: string[]
+  /** Contributed view ids, same contract. */
+  declaredViews: string[]
+  /** Per-load nonce authorizing exactly the one inline bootstrap script. */
+  nonce: string
+}
+
+/**
+ * The child Content-Security-Policy — far stricter than the host's.
+ *
+ * ── PER-ORIGIN, NOT PER-SCHEME ──
+ * Every source below names THIS extension's origin explicitly. The previous version
+ * used the bare `agent-code-ext:` scheme-source, which matches
+ * `agent-code-ext://<any-other-id>` — and since `'self'` already covers the document's
+ * own origin, the bare scheme granted ONLY the cross-extension case. Extension A could
+ * fetch and, worse, `<script src>`-execute extension B's bundle. That is what turned
+ * an HTML-injection bug into arbitrary code execution across extension identities.
+ *
+ * `base-uri` and `form-action` are listed explicitly because NEITHER falls back to
+ * `default-src`. Without `base-uri 'none'`, an injected `<base>` repoints the
+ * bootstrap's relative `import()`; without `form-action 'none'`, a form can POST to
+ * any origin — an egress channel the connect-src restriction does not cover.
+ *
+ * Note what CSP still cannot do: it has no directive governing `window.open`
+ * (`navigate-to` was never shipped). That hole is closed by the iframe's `sandbox`
+ * attribute in viewBridge.tsx, not here.
+ *
+ * ── WHY THERE IS NO `frame-ancestors` ──
+ * Genuinely absent, not overlooked. It would name who may EMBED this document, and
+ * no value expresses "the Agent Code renderer": the host origin is
+ * `http://localhost:<port>` in dev and an opaque `file://` in production, so any
+ * literal list is either wrong in one mode or so wide it asserts nothing. (It also
+ * only takes effect as a response header — the meta form is ignored — so writing it
+ * into the document would silently do nothing.)
+ *
+ * What actually prevents cross-embedding is `default-src 'none'`: `frame-src` and
+ * `child-src` both fall back to it, so no extension frame can create a nested frame,
+ * and one extension therefore cannot embed another's view. The only embedder that
+ * exists is the host, which is trusted. If the host ever gains a stable origin, add
+ * the header — until then this is the record that the absence was reasoned about.
+ */
+export function childFrameCsp(nonce: string, extensionId: string): string {
+  const self = `agent-code-ext://${extensionId}`
+  return [
+    "default-src 'none'",
+    "base-uri 'none'",
+    "form-action 'none'",
+    `script-src '${`nonce-${nonce}`}' ${self}`,
+    `style-src 'unsafe-inline' ${self}`,
+    `img-src ${self} data: blob:`,
+    `font-src ${self} data:`,
+    `connect-src ${self}`,
+  ].join('; ')
+}
+
+export function buildFrameDocument(input: FrameDocumentInput): string {
+  const { extensionId, viewId, entry, declaredCommands, declaredViews, nonce } = input
+  // The bootstrap. Everything the child needs to (a) expose a Tier-0 API that
+  // proxies to the parent over postMessage, (b) import and activate the extension,
+  // (c) mount its view on the parent's signal. Kept in one nonced module.
+  const bootstrap = `
+// ── CONFIG COMES FROM A JSON BLOCK, NOT FROM INTERPOLATED JS ──
+// These values used to be spliced straight into this script as
+// \`const VIEW_ID = \${JSON.stringify(viewId)}\`. JSON.stringify escapes quotes and
+// backslashes but NOT \`<\` or \`/\`, so a value carrying a script CLOSING TAG ended
+// this element from inside a string literal and everything after it became markup.
+// The entry path passed all four of the manifest's negative refinements with that
+// payload embedded, and viewId was taken from the query string unchecked.
+//
+// Parsing a JSON island removes the sink entirely: a closing tag inside JSON text is
+// still just text to the JS parser, and the HTML tokenizer never sees it because
+// buildFrameDocument escapes \`<\` when emitting the block.
+//
+// NOTE TO ANYONE EDITING THIS FILE: never write a literal script closing tag
+// anywhere inside this template, not even in a comment. The HTML tokenizer ends a
+// script element at the first one it sees, with no regard for JavaScript context —
+// which is the entire bug described above, and which this very comment previously
+// caused by quoting the payload verbatim.
+const CFG = JSON.parse(document.getElementById('agent-code-ext-cfg').textContent);
+const VIEW_ID = CFG.viewId;
+const ENTRY = CFG.entry;
+const DECLARED_COMMANDS = CFG.declaredCommands;
+const DECLARED_VIEWS = CFG.declaredViews;
+
+// ── ANNOUNCE THAT THIS DOCUMENT IS THE REAL FRAME, IMMEDIATELY ──
+// The host cannot tell a successful load from a failed one any other way. An
+// iframe fires 'load' for an HTTP ERROR BODY just as it does for a real page, and
+// never fires 'error' for one — so the host's onError handler was dead code, and a
+// 404/403 from the scheme handler (missing bundle, unknown view id, an id that
+// failed validation) rendered as a permanently blank "ready" frame with no message
+// anywhere. This is the first statement that runs, before the dynamic import can
+// throw, so its ARRIVAL means "the host's own document is executing" and its
+// ABSENCE within the host's timeout means the load failed for any reason at all —
+// including a CSP violation that stops the bootstrap outright.
+window.parent.postMessage({ kind: 'agent-code-ext:boot' }, '*');
+
+// Correlate replies to requests over the single channel to the parent.
+let seq = 0;
+const pending = new Map();
+window.addEventListener('message', (event) => {
+  // Authenticate the SENDER by window reference, not by origin string. When the
+  // host renderer is loaded from file:// (the packaged/preview build), its origin
+  // is opaque: a message it posts arrives here with event.origin === "null" (or a
+  // non-matching serialization), so an === PARENT_ORIGIN check silently drops
+  // every reply and mount signal — the view then never mounts and there is no
+  // error anywhere. event.source is a live WindowProxy the child cannot forge and
+  // the browser never rewrites, so it holds across every origin quirk. This is the
+  // exact mirror of frameHost.ts's inbound gate (event.source === iframe.contentWindow).
+  if (event.source !== window.parent) return;
+  const msg = event.data;
+  if (!msg || typeof msg !== 'object') return;
+  if (msg.kind === 'agent-code-ext:reply') {
+    const p = pending.get(msg.id);
+    if (!p) return;
+    pending.delete(msg.id);
+    if (msg.ok) p.resolve(msg.result); else p.reject(new Error(msg.error));
+  } else if (msg.kind === 'agent-code-ext:mount') {
+    mountView(msg.viewId);
+  } else if (msg.kind === 'agent-code-ext:theme') {
+    for (const [name, value] of Object.entries(msg.tokens || {})) {
+      document.documentElement.style.setProperty(name, value);
+    }
+  } else if (msg.kind === 'agent-code-ext:command') {
+    // Invoke a contributed command's handler, registered by the extension in
+    // activate() via context.registerCommand. This is the whole point of unifying
+    // activation onto the frame: the handler runs HERE, against the same engine the
+    // view shows, not a second host-realm instance. A missing handler is silent —
+    // an "open my view" command is routed by the host and never dispatched here.
+    const handler = commands.get(msg.commandId);
+    if (handler) {
+      try {
+        Promise.resolve(handler()).catch((e) => console.error('[extension] command failed:', msg.commandId, e));
+      } catch (e) {
+        console.error('[extension] command failed:', msg.commandId, e);
+      }
+    }
+  } else if (msg.kind === 'agent-code-ext:event') {
+    // A change nudge for a Tier-1 observe topic. Fan out to registered listeners;
+    // each typically re-reads via observe(). Snapshot the set before iterating so a
+    // listener that unsubscribes mid-notify does not skip a sibling.
+    const set = eventListeners.get(msg.topic);
+    if (set) {
+      for (const cb of Array.from(set)) {
+        try { cb(); } catch (e) { console.error('[extension] observe listener failed:', msg.topic, e); }
+      }
+    }
+  }
+});
+
+function request(method, extra) {
+  const id = 'q' + (++seq);
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    // targetOrigin '*' rather than PARENT_ORIGIN: a file:// parent's origin does
+    // not reliably match a specific-string targetOrigin, so pinning it to
+    // "file://" makes the browser refuse to deliver the request and activate()
+    // hangs on its first storage read. This is safe because the message is sent to
+    // window.parent EXPLICITLY (only the host receives it — the child CSP forbids
+    // nested frames, so there is no other embedder) and the requests carry no host
+    // secrets; the host's frameHost re-authenticates every request by the child's
+    // own unforgeable agent-code-ext://<id> origin before performing it.
+    window.parent.postMessage(
+      { kind: 'agent-code-ext:request', id, request: Object.assign({ method }, extra) },
+      '*',
+    );
+  });
+}
+
+// The Tier-0 AgentCodeApiV1, proxied. Same method names as the same-realm object.
+const api = {
+  // id from the frame's own origin host (agent-code-ext://<id>) — unforgeable and
+  // exactly the id the host attributes this frame to. AgentCodeApiV1 promises it;
+  // the same-realm createAppHostApi already provided it, this closes the frame gap.
+  extension: { id: location.hostname, apiVersion: 1 },
+  storage: {
+    get: (key) => request('storage.get', { key }),
+    set: (key, value) => request('storage.set', { key, value }),
+    delete: (key) => request('storage.delete', { key }),
+    keys: () => request('storage.keys', {}),
+  },
+  ui: {
+    close: () => request('ui.close', {}),
+    showToast: (message) => request('ui.showToast', { message }),
+  },
+  theme: { tokens: () => request('theme.tokens', {}) },
+  // Tier-1 observe. The host broker gates each on the extension's grant, so a call
+  // here rejects if the capability was not consented to at install. subscribe() is
+  // local: it registers a listener the host wakes with a change nudge (the extension
+  // then re-reads via observe). Returns an unsubscribe, matching AgentCodeApiV1.
+  workspace: { observe: () => request('workspace.observe', {}), subscribe: (cb) => subscribeTopic('workspace', cb) },
+  sessions: { observe: () => request('sessions.observe', {}), subscribe: (cb) => subscribeTopic('sessions', cb) },
+  panes: { observe: () => request('panes.observe', {}), subscribe: (cb) => subscribeTopic('panes', cb) },
+};
+
+// Listeners for host-pushed change nudges (Tier-1 observe live updates), keyed by
+// topic. A function declaration so the api object above can reference it regardless
+// of source order; it is only ever CALLED at runtime, after the whole bootstrap ran.
+const eventListeners = new Map();
+function subscribeTopic(topic, cb) {
+  let set = eventListeners.get(topic);
+  if (!set) { set = new Set(); eventListeners.set(topic, set); }
+  set.add(cb);
+  return function () { set.delete(cb); };
+}
+
+const views = new Map();
+const commands = new Map();
+const subscriptions = [];
+// ── REGISTERING AN UNDECLARED ID IS AN ERROR, AND THE FRAME IS WHERE THAT LIVES ──
+// This check used to be in the host-realm ExtensionHost, which imported the module
+// and could compare against the manifest it already held. That host is gone — the
+// extension runs only here — and the check went with it, silently: the bootstrap
+// just wrote into the maps, while the type, moduleContract and the authoring guide
+// all still promised rejection.
+//
+// It matters because the failure it prevents is invisible. Contributions are
+// DECLARED in the manifest so the palette can list a command before the module is
+// imported; a handler registered under an id the manifest does not declare can
+// therefore never be invoked by anything. Without this, an author who typos an id
+// gets a command that does nothing, no error anywhere, and no way to tell the typo
+// from a broken host.
+//
+// The declared ids are passed in through the config island rather than fetched,
+// because the host already validated them at install and the frame has no way to
+// ask. Throwing here propagates to the import().catch below, which reports the
+// message to the host and shows it on the extension's Settings row.
+function assertDeclared(kind, id, declared) {
+  if (declared.indexOf(id) !== -1) return;
+  throw new Error(
+    'register' + kind + '("' + id + '") — not declared in contributes.' +
+      (kind === 'Command' ? 'commands' : 'views'),
+  );
+}
+
+const context = {
+  api,
+  // Handlers are invoked by the host's 'command' push above — the frame is the ONE
+  // place an extension's command runs, so its handlers must actually be kept.
+  registerCommand: (id, run) => {
+    assertDeclared('Command', id, DECLARED_COMMANDS);
+    commands.set(id, run);
+    return { dispose() { commands.delete(id); } };
+  },
+  registerView: (id, mount) => {
+    assertDeclared('View', id, DECLARED_VIEWS);
+    views.set(id, mount);
+    return { dispose() { views.delete(id); } };
+  },
+  subscriptions,
+};
+
+// Report the mounted view's natural content height to the parent, which sizes
+// the iframe (and therefore the host modal) to it. Without this the iframe has no
+// definite height to give an 'height:100%' child, so it collapses to the host's
+// minimum and a taller extension is clipped. #root is height:auto (see the child
+// CSS), so scrollHeight is the CONTENT height, and growing the iframe never
+// changes it — so the ResizeObserver below cannot enter a resize feedback loop.
+function reportSize() {
+  const root = document.getElementById('root');
+  if (!root) return;
+  // Height comes from #root: it is height:auto, so scrollHeight IS the content height,
+  // and growing the iframe never changes it — no resize feedback loop.
+  const height = root.scrollHeight;
+  // WIDTH MUST BE MEASURED FROM THE CHILDREN, NOT FROM #root.
+  //
+  // #root is width:100%, and scrollWidth is by definition never smaller than clientWidth.
+  // So root.scrollWidth returns at least the CURRENT iframe width, always. The modal
+  // could therefore grow but never shrink: switching from a wide view to a narrow one
+  // (a 892px game to a 375px one) left the modal stuck at the old width with the new
+  // content marooned in the corner — which is exactly the "cropping works weird" report.
+  //
+  // The children carry their own intrinsic width, so measuring them lets the report go
+  // DOWN as well as up. Fall back to scrollWidth if an extension mounts nothing we can
+  // measure. Note this deliberately reads getBoundingClientRect rather than offsetWidth:
+  // it is sub-pixel accurate and, unlike offsetWidth, correct for transformed children.
+  let width = 0;
+  for (let i = 0; i < root.children.length; i++) {
+    width = Math.max(width, Math.ceil(root.children[i].getBoundingClientRect().width));
+  }
+  if (width <= 0) width = root.scrollWidth;
+  if (height > 0) window.parent.postMessage({ kind: 'agent-code-ext:resize', height: height, width: width }, '*');
+}
+
+let mounted = false;
+// The cleanup a view's mount() returned, if any. The ViewMount contract is
+// (element) => void | (() => void), and the authoring guide documents "a view
+// mount returns its own cleanup; it runs when the view closes" — but the return
+// value was DISCARDED here, so that promise was never kept. An extension whose
+// view starts an interval, an AudioContext or a listener leaked it on every close,
+// and the author had no way to notice, because the documented hook simply never
+// fired. Captured here, called from the pagehide teardown below.
+let unmountView = null;
+function mountView(viewId) {
+  if (mounted) return;
+  const mount = views.get(viewId);
+  if (!mount) return;
+  mounted = true;
+  const root = document.getElementById('root');
+  if (!root) return;
+  const cleanup = mount(root);
+  if (typeof cleanup === 'function') unmountView = cleanup;
+  // Report once now, then on every content change (a picker expands, digits
+  // reflow), so the modal tracks the view instead of freezing at first paint.
+  reportSize();
+  if (typeof ResizeObserver !== 'undefined') {
+    const observer = new ResizeObserver(function () { reportSize(); });
+    // Observing #root alone is NOT enough. It is width:100%, so a content change that
+    // only alters WIDTH never changes #root's own box and the observer stays silent —
+    // the modal would keep a stale width until something happened to change the height
+    // too. Observe the children, whose boxes track the content, and re-sync that list
+    // when the extension swaps its tree (a router switching screens replaces the child).
+    observer.observe(root);
+    const syncChildren = function () {
+      for (let i = 0; i < root.children.length; i++) observer.observe(root.children[i]);
+      reportSize();
+    };
+    syncChildren();
+    if (typeof MutationObserver !== 'undefined') {
+      new MutationObserver(syncChildren).observe(root, { childList: true });
+    }
+  }
+}
+
+// ── ESCAPE IS FORWARDED TO THE HOST, EVERYTHING ELSE IS NOT ──
+// A cross-origin frame consumes every keystroke: the host document never sees
+// them, so while focus is inside an extension view NO application shortcut fires.
+// For most chords that is merely a limitation. For Escape it is a trap — Escape is
+// the universal "get me out of this" in this app, and a user pressing it inside an
+// extension modal got nothing at all, with no indication that the key had been
+// swallowed rather than ignored.
+//
+// Only Escape is forwarded. Forwarding arbitrary chords would mean reconstructing
+// the host's whole keybinding router across a postMessage boundary, and would let a
+// frame synthesize application commands — a capability nothing here should have.
+// Escape carries no argument and can only ever mean "close the thing in front of
+// me", so it is safe to hand over.
+//
+// defaultPrevented is the extension's opt-out and the reason this listens in the
+// BUBBLE phase: an extension that wants Escape for its own popover calls
+// preventDefault(), and the host never hears about it. An extension that does
+// nothing gets the behaviour the rest of the app has.
+window.addEventListener('keydown', (event) => {
+  if (event.key !== 'Escape' || event.defaultPrevented) return;
+  window.parent.postMessage({ kind: 'agent-code-ext:escape' }, '*');
+});
+
+// Import, activate, mount, then announce readiness.
+let extensionModule = null;
+import('./' + ENTRY)
+  .then((mod) => { extensionModule = mod; return mod.activate(context); })
+  .then(() => {
+    mountView(VIEW_ID);
+    // Signal the host that activate() has resolved — meaning registerCommand() has
+    // run and command handlers exist. The host registers this frame's command
+    // dispatcher on this signal and flushes any command queued while the view was
+    // closed, so a flushed command can never arrive before its handler is registered.
+    window.parent.postMessage({ kind: 'agent-code-ext:ready' }, '*');
+  })
+  .catch((error) => {
+    const message = (error && error.message) || String(error);
+    const root = document.getElementById('root');
+    if (root) root.textContent = 'Extension failed to load: ' + message;
+    // ALSO tell the host. Writing the message into this document only put it
+    // inside the frame — and a frame that fails during activate() is often not
+    // even visible (a queued command opened it), so the user saw nothing at all
+    // and Settings showed a healthy row. The host-realm ExtensionHost used to
+    // collect these from its own try/catch around import+activate; that host is
+    // gone, so the frame is now the only thing that can observe the throw.
+    window.parent.postMessage({ kind: 'agent-code-ext:error', message: message }, '*');
+  });
+
+// Run the extension's cleanup when the frame is torn down. The host closes a view
+// by navigating the iframe to about:blank (viewBridge), which fires pagehide on
+// this document; app quit fires it too. Mirrors the same-realm host's deactivate:
+// call the module's deactivate(), THEN dispose registrations in reverse order (so a
+// later subscription built on an earlier one tears down first). Best-effort and
+// synchronous — the document is going away, so async cleanup cannot be awaited; the
+// timer's engine.dispose()/removeStyles() are exactly this shape. Without this an
+// extension leaks its intervals/AudioContext/listeners every time its view closes.
+window.addEventListener('pagehide', () => {
+  // Innermost first: the view's own cleanup, then the module's deactivate(), then
+  // the registered subscriptions in reverse. That is the reverse of the order in
+  // which they were established, which is the only order in which a later hook
+  // cannot depend on something an earlier one already tore down.
+  try {
+    if (typeof unmountView === 'function') unmountView();
+  } catch (e) {
+    console.error('[extension] view cleanup failed:', e);
+  }
+  try {
+    if (extensionModule && typeof extensionModule.deactivate === 'function') extensionModule.deactivate();
+  } catch (e) {
+    console.error('[extension] deactivate failed:', e);
+  }
+  for (const sub of subscriptions.slice().reverse()) {
+    try { sub.dispose(); } catch (e) { /* one bad disposer must not strand the rest */ }
+  }
+});
+`.trim()
+
+  return [
+    '<!doctype html>',
+    '<html>',
+    '<head>',
+    '<meta charset="utf-8" />',
+    `<meta http-equiv="Content-Security-Policy" content="${childFrameCsp(nonce, extensionId)}" />`,
+    // #root is width:100% but height:AUTO on purpose: it sizes to the extension's
+    // content, which reportSize() measures and the host uses to size the iframe.
+    // A height:100% here would make #root track the (initially collapsed) iframe
+    // instead, and the content-height signal would always read the clamp.
+    //
+    // overflow:hidden kills the frame's OWN scrollbars. The host already sizes the
+    // iframe to the reported content height, so there is nothing legitimate to
+    // scroll — but a view whose background bleeds a pixel past the edge (the timer
+    // uses margin:-1px to reach the modal corners) would otherwise raise a stray
+    // horizontal bar, which then steals height and raises a vertical one too. The
+    // measurement reads #root.scrollHeight, which is unaffected by this.
+    '<style>html,body{margin:0;width:100%;overflow:hidden}#root{width:100%}</style>',
+    '</head>',
+    '<body>',
+    '<div id="root"></div>',
+    // The config island. `<` is escaped to \u003c so no value can close this element
+    // (or open another) regardless of what the manifest or query string contained.
+    // JSON.parse reads \u003c back as `<`, so values round-trip exactly.
+    `<script type="application/json" id="agent-code-ext-cfg">${JSON.stringify({
+      viewId,
+      entry,
+      declaredCommands,
+      declaredViews,
+    }).replace(/</g, '\\u003c')}</script>`,
+    `<script type="module" nonce="${nonce}">${bootstrap}</script>`,
+    '</body>',
+    '</html>',
+  ].join('\n')
+}
diff --git a/src/main/extensions/grants.system.test.ts b/src/main/extensions/grants.system.test.ts
new file mode 100644
index 000000000..278ec4014
--- /dev/null
+++ b/src/main/extensions/grants.system.test.ts
@@ -0,0 +1,118 @@
+import { mkdtemp, mkdir, rm, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+// STATE_DIR is resolved at module load from homedir(), so the grant store's file
+// location is fixed before any test can influence it. Mocking the paths module is
+// the narrowest seam that keeps these tests off the developer's real
+// ~/.config/agent-code — which they must be, because they write grants.
+const stateRoot = await mkdtemp(join(tmpdir(), 'agent-code-grants-'))
+vi.mock('@main/storage/paths.js', () => ({
+  STATE_DIR: stateRoot,
+  EXTENSIONS_DIR: join(stateRoot, 'extensions'),
+  EXTENSIONS_LOCKFILE: join(stateRoot, 'extensions.json'),
+  EXTENSION_STATE_DIR: join(stateRoot, 'extension-state'),
+}))
+
+const { grantedCapabilities, recordGrant, revokeGrant } = await import(
+  '@main/extensions/grants.js'
+)
+
+const HASH_A = 'a'.repeat(64)
+const HASH_B = 'b'.repeat(64)
+
+afterEach(async () => {
+  await rm(join(stateRoot, 'extension-grants.json'), { force: true })
+})
+
+describe('grant binding', () => {
+  it('returns the granted capabilities for the hash they were approved at', async () => {
+    await recordGrant('timer', HASH_A, ['workspace.observe', 'sessions.observe'])
+    const granted = await grantedCapabilities('timer', HASH_A)
+    expect([...granted].sort()).toEqual(['sessions.observe', 'workspace.observe'])
+  })
+
+  // ── THE REGRESSION THIS FILE EXISTS FOR ──
+  // The grant used to be checked against a hash READ BACK OUT OF THE LEDGER, which
+  // the same install had just written — so the comparison compared two copies of
+  // one value and could never fail. The documented rule ("different bytes, no
+  // grant") did not exist. This is that rule, stated as a test.
+  it('returns NOTHING for a different hash', async () => {
+    await recordGrant('timer', HASH_A, ['workspace.observe'])
+    expect([...(await grantedCapabilities('timer', HASH_B))]).toEqual([])
+  })
+
+  it('returns nothing for an extension that was never granted anything', async () => {
+    expect([...(await grantedCapabilities('never-installed', HASH_A))]).toEqual([])
+  })
+
+  it('replaces the previous grant rather than accumulating', async () => {
+    // An update that asks for fewer capabilities must not inherit the old set.
+    await recordGrant('timer', HASH_A, ['workspace.observe', 'sessions.observe'])
+    await recordGrant('timer', HASH_B, ['workspace.observe'])
+    expect([...(await grantedCapabilities('timer', HASH_B))]).toEqual(['workspace.observe'])
+    // And the superseded hash grants nothing at all.
+    expect([...(await grantedCapabilities('timer', HASH_A))]).toEqual([])
+  })
+
+  it('revokes', async () => {
+    await recordGrant('timer', HASH_A, ['workspace.observe'])
+    await revokeGrant('timer')
+    expect([...(await grantedCapabilities('timer', HASH_A))]).toEqual([])
+  })
+
+  it('keeps other extensions untouched when one is revoked', async () => {
+    await recordGrant('timer', HASH_A, ['workspace.observe'])
+    await recordGrant('notes', HASH_A, ['panes.observe'])
+    await revokeGrant('timer')
+    expect([...(await grantedCapabilities('notes', HASH_A))]).toEqual(['panes.observe'])
+  })
+})
+
+describe('grant store hostile-file handling', () => {
+  async function writeGrantsFile(contents: string): Promise<void> {
+    await mkdir(stateRoot, { recursive: true })
+    await writeFile(join(stateRoot, 'extension-grants.json'), contents, 'utf8')
+  }
+
+  it('drops a capability the host does not implement', async () => {
+    // The seven Tier 2/3 capabilities were removed from the manifest schema. A
+    // grants file written by an older build still names them, and the store used to
+    // parse capabilities as `z.array(z.string())` — carrying them forward verbatim
+    // into the Set that frameHost checks against. Parsing against the real enum
+    // makes the migration automatic and means the store cannot hold an authorisation
+    // for a power that does not exist.
+    await writeGrantsFile(
+      JSON.stringify([
+        {
+          extensionId: 'timer',
+          sha256: HASH_A,
+          capabilities: ['workspace.observe', 'fs.write', 'network.fetch'],
+          grantedAt: 1,
+        },
+      ]),
+    )
+    expect([...(await grantedCapabilities('timer', HASH_A))]).toEqual(['workspace.observe'])
+  })
+
+  it('survives a corrupt file rather than throwing', async () => {
+    // A throw here would propagate into the capability check, and the check's
+    // callers treat a throw as an error rather than as "no capabilities". Degrading
+    // to an empty store is both fail-closed and recoverable.
+    await writeGrantsFile('{ not json at all')
+    expect([...(await grantedCapabilities('timer', HASH_A))]).toEqual([])
+  })
+
+  it('drops a malformed row without discarding valid siblings', async () => {
+    await writeGrantsFile(
+      JSON.stringify([
+        { extensionId: 'broken', sha256: 'not-a-hash', capabilities: [], grantedAt: 1 },
+        { extensionId: 'timer', sha256: HASH_A, capabilities: ['panes.observe'], grantedAt: 2 },
+      ]),
+    )
+    expect([...(await grantedCapabilities('timer', HASH_A))]).toEqual(['panes.observe'])
+    expect([...(await grantedCapabilities('broken', HASH_A))]).toEqual([])
+  })
+})
diff --git a/src/main/extensions/grants.ts b/src/main/extensions/grants.ts
new file mode 100644
index 000000000..9f174cc9e
--- /dev/null
+++ b/src/main/extensions/grants.ts
@@ -0,0 +1,142 @@
+import { mkdir, readFile, rename, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { z } from 'zod'
+
+import { STATE_DIR } from '@main/storage/paths.js'
+import { EXTENSION_CAPABILITIES } from '@shared/types/extensions.js'
+import type { ExtensionCapability } from '@shared/types/extensions.js'
+
+// The capability grant store (WS5).
+//
+// A grant records that the user approved a specific set of capabilities for a
+// specific extension AT a specific content hash. Keying on the hash — not just
+// the id — is the load-bearing choice, borrowed from WorkflowSourceApprovalStore:
+// an extension can be updated in place (install doubles as update), so a grant
+// that keyed on id alone would let an update silently inherit permissions the
+// user approved for different code.
+//
+// ── WHICH HASH, AND WHY IT MATTERS ──
+// The hash MUST be one that can be recomputed from disk later. This store was
+// originally fed the TARBALL digest, and the caller then read that same digest
+// back out of the ledger row — so `row.sha256 !== sha256` compared two copies of
+// one value written by a single finalizeInstall() call and could never be true.
+// The rule this file documents was, in practice, not enforced at all: editing a
+// file under EXTENSIONS_DIR kept every granted capability.
+//
+// It is now fed `computeBundleHash()` over the installed bundle directory
+// (main/extensions/bundleHash.ts), and the IPC check recomputes that hash from
+// disk on every read. The tarball digest stays in the ledger as PROVENANCE —
+// the tarball is deleted after extraction, so it is unrecomputable by
+// construction and can never gate anything.
+//
+// Tier-0 capabilities (storage/ui/theme) are NOT recorded here — they are granted
+// to every extension without asking, so they never appear in a manifest's
+// `permissions` and never reach this store.
+
+const GRANTS_FILE = join(STATE_DIR, 'extension-grants.json')
+
+const grantSchema = z.object({
+  extensionId: z.string().min(1),
+  /** computeBundleHash() of the installed bundle at the moment consent was given.
+   *  A different hash means the code changed, which means re-consent. */
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  // ── VALIDATED AGAINST THE IMPLEMENTED SET, NOT `z.array(z.string())` ──
+  // The looser shape round-tripped ANY string into a Set that
+  // `frameHost.requireGrant` then does `.includes()` against. Two consequences:
+  // a grants file naming a capability this build does not implement was carried
+  // forward verbatim rather than dropped, and — once the seven unimplemented
+  // capabilities were removed from the manifest schema — every grant recorded for
+  // them under an older build stayed in the file as a live-looking authorisation
+  // for a power that no longer exists. Parsing against the real enum means the
+  // store cannot hold a capability the host cannot perform, and the migration
+  // away from the removed ones is automatic: unknown entries are dropped on read.
+  // Filtered PER ELEMENT, not validated wholesale. `z.array(z.enum(...))` rejects
+  // the entire array when any one member is unknown, which would turn "this grant
+  // mentions a retired capability" into "this extension has no grant at all" —
+  // silently revoking the capabilities the user did approve and still holds.
+  capabilities: z
+    .array(z.string())
+    .transform(values => values.filter(isKnownCapability)),
+  grantedAt: z.number().finite(),
+})
+
+function isKnownCapability(value: string): value is ExtensionCapability {
+  return (EXTENSION_CAPABILITIES as readonly string[]).includes(value)
+}
+
+type Grant = z.infer<typeof grantSchema>
+
+async function readGrants(): Promise<Grant[]> {
+  let raw: string
+  try {
+    raw = await readFile(GRANTS_FILE, 'utf8')
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  const rows: Grant[] = []
+  for (const candidate of parsed) {
+    const result = grantSchema.safeParse(candidate)
+    if (result.success) rows.push(result.data)
+  }
+  return rows
+}
+
+async function writeGrants(rows: Grant[]): Promise<void> {
+  await mkdir(STATE_DIR, { recursive: true })
+  const tmp = `${GRANTS_FILE}.tmp-${process.pid}-${Date.now()}`
+  await writeFile(tmp, `${JSON.stringify(rows, null, 2)}\n`, 'utf8')
+  await rename(tmp, GRANTS_FILE)
+}
+
+/**
+ * Record the user's approval of `capabilities` for one extension at one content
+ * hash. One row per extension id — a re-grant (a new install/update) replaces the
+ * previous row, so a downgrade in requested permissions cannot leave stale ones.
+ */
+export async function recordGrant(
+  extensionId: string,
+  bundleSha256: string,
+  capabilities: readonly ExtensionCapability[],
+): Promise<void> {
+  const rows = await readGrants()
+  await writeGrants([
+    ...rows.filter(row => row.extensionId !== extensionId),
+    { extensionId, sha256: bundleSha256, capabilities: [...capabilities], grantedAt: Date.now() },
+  ])
+}
+
+/**
+ * The capabilities currently granted to an extension, but ONLY if the grant was
+ * given for exactly the bytes now installed. A grant for different bytes returns
+ * nothing — the capabilities were approved for code that is no longer what is
+ * running, so they must not carry over silently.
+ *
+ * `bundleSha256` MUST be a hash the caller just computed FROM DISK, not one read
+ * back out of the ledger. Passing a stored value makes this function compare the
+ * install record against itself, which is exactly how the check came to be a
+ * tautology in the first place.
+ */
+export async function grantedCapabilities(
+  extensionId: string,
+  bundleSha256: string,
+): Promise<Set<ExtensionCapability>> {
+  const rows = await readGrants()
+  const row = rows.find(candidate => candidate.extensionId === extensionId)
+  if (!row || row.sha256 !== bundleSha256) return new Set()
+  return new Set(row.capabilities)
+}
+
+/** Drop an extension's grant. Called on uninstall so a reinstall must re-consent. */
+export async function revokeGrant(extensionId: string): Promise<void> {
+  const rows = await readGrants()
+  const next = rows.filter(row => row.extensionId !== extensionId)
+  if (next.length !== rows.length) await writeGrants(next)
+}
diff --git a/src/main/extensions/install.test.ts b/src/main/extensions/install.test.ts
new file mode 100644
index 000000000..0f4ad69a4
--- /dev/null
+++ b/src/main/extensions/install.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from 'vitest'
+
+import { InstallError, normalizeRepo } from '@main/extensions/install.js'
+
+// `normalizeRepo` is the only pure, network-free part of the installer, and it is
+// the part whose output is interpolated into two URLs and then persisted. The rest
+// of install.ts needs a real filesystem and a real network and is covered by
+// install.system.test.ts.
+
+describe('normalizeRepo — accepted forms', () => {
+  it.each([
+    ['bare', 'owner/repo'],
+    ['https', 'https://github.com/owner/repo'],
+    ['https with www', 'https://www.github.com/owner/repo'],
+    ['http', 'http://github.com/owner/repo'],
+    ['ssh', 'git@github.com:owner/repo'],
+    ['trailing .git', 'https://github.com/owner/repo.git'],
+    ['trailing slash', 'https://github.com/owner/repo/'],
+    ['surrounding whitespace', '  owner/repo  '],
+  ])('normalizes the %s form to owner/repo', (_label, input) => {
+    expect(normalizeRepo(input)).toBe('owner/repo')
+  })
+
+  it('keeps dots and dashes inside a real name', () => {
+    // Real repositories are named this way (`user.name/my-repo.js`), so the
+    // dot-rejection below must not be a blanket ban on the character.
+    expect(normalizeRepo('user.name/my-repo.js')).toBe('user.name/my-repo.js')
+  })
+})
+
+describe('normalizeRepo — rejected forms', () => {
+  // ── THE REGRESSION THIS BLOCK EXISTS FOR ──
+  // The character class `[\w.-]+` matches `.` and `..`, so `../x` parsed cleanly
+  // into owner `..`. The result is interpolated into
+  // `https://api.github.com/repos/${repo}` and into the codeload URL, where the URL
+  // parser NORMALIZES the `..` away — so the request addressed a different GitHub
+  // endpoint than the code believed it was calling, and the bogus value was then
+  // written to the ledger and rendered in Settings.
+  it.each([
+    ['parent traversal as owner', '../repo'],
+    ['parent traversal as repo', 'owner/..'],
+    ['both segments traversal', '../..'],
+    ['single dot as owner', './repo'],
+    ['single dot as repo', 'owner/.'],
+    ['triple dot', '.../repo'],
+  ])('rejects %s', (_label, input) => {
+    expect(() => normalizeRepo(input)).toThrow(InstallError)
+  })
+
+  it.each([
+    ['a non-GitHub host', 'https://gitlab.com/owner/repo'],
+    ['three segments', 'owner/repo/extra'],
+    ['one segment', 'owner'],
+    ['empty', ''],
+    ['a space inside', 'own er/repo'],
+    ['a query string', 'https://github.com/owner/repo?x=1'],
+    ['a URL fragment', 'https://github.com/owner/repo#readme'],
+  ])('rejects %s', (_label, input) => {
+    expect(() => normalizeRepo(input)).toThrow(InstallError)
+  })
+
+  it('names the offending input in the message so the user can fix it', () => {
+    // The user typed this string; an error that does not quote it back is not
+    // actionable in a Settings row that shows nothing else.
+    expect(() => normalizeRepo('not a repo')).toThrow(/"not a repo"/)
+  })
+})
diff --git a/src/main/extensions/install.ts b/src/main/extensions/install.ts
new file mode 100644
index 000000000..27c1c7d9f
--- /dev/null
+++ b/src/main/extensions/install.ts
@@ -0,0 +1,814 @@
+import { spawn } from 'child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  access,
+  constants as fsConstants,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  readFile,
+  realpath,
+  rename,
+  rm,
+  writeFile,
+} from 'fs/promises'
+import { join, relative, resolve as resolvePath, sep } from 'path'
+
+import { EXTENSIONS_DIR } from '@main/storage/paths.js'
+import { computeBundleHash } from '@main/extensions/bundleHash.js'
+import { ManifestError, parseExtensionManifest } from '@main/extensions/manifest.js'
+import { readLedger, withLedgerLock, writeLedger } from '@main/extensions/ledger.js'
+import { recordGrant, revokeGrant } from '@main/extensions/grants.js'
+import type { ExtensionManifest, InstalledExtension } from '@shared/types/extensions.js'
+
+/**
+ * Asked to approve an extension's requested capabilities before it is installed.
+ * Returns true to proceed. Injected (rather than calling an Electron dialog here)
+ * so install stays a pure pipeline — the IPC layer supplies the real prompt.
+ */
+export type ConsentPrompt = (manifest: ExtensionManifest) => Promise<boolean>
+
+const MANIFEST_FILENAME = 'agent-code.extension.json'
+
+// 32 MB. An extension is a built JS bundle plus assets; anything larger is either a
+// mistake (someone committed node_modules) or hostile. The cap exists because the
+// download is buffered in memory to hash it — see downloadTarball.
+const MAX_TARBALL_BYTES = 32 * 1024 * 1024
+
+// How long a request may make NO progress before it is abandoned. Applied as a
+// total deadline to the two small metadata calls, and as an IDLE budget to the
+// download — see downloadTarball for why a total deadline is wrong there.
+const NETWORK_TIMEOUT_MS = 30_000
+
+// The EXTRACTED ceiling, which is a different quantity from MAX_TARBALL_BYTES and
+// the one that actually protects the disk. 256 MB is ~8x the compressed cap and
+// orders of magnitude above any real extension; anything past it is a bomb or a
+// mistake, and either way is not something to unpack into the user's home
+// directory.
+const MAX_EXTRACTED_BYTES = 256 * 1024 * 1024
+
+// A file-COUNT ceiling. Neither byte cap implies one — half a million empty files
+// compress to nothing — and every file costs a stat at install plus a read on every
+// bundle hash. See assertBundleTreeIsSafe.
+const MAX_BUNDLE_FILES = 10_000
+
+export class InstallError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InstallError'
+  }
+}
+
+/**
+ * Accepts what a user is likely to paste and normalizes to `owner/repo`.
+ *
+ * Deliberately permissive about the input format and strict about the output: every
+ * later step (API URL construction, ledger key) assumes `owner/repo` with no path
+ * traversal or query string in it.
+ */
+export function normalizeRepo(input: string): string {
+  const trimmed = input.trim().replace(/\.git$/, '').replace(/\/+$/, '')
+  // https://github.com/owner/repo, git@github.com:owner/repo, or owner/repo
+  const match =
+    /^(?:https?:\/\/(?:www\.)?github\.com\/|git@github\.com:)?([\w.-]+)\/([\w.-]+)$/.exec(trimmed)
+  if (!match) {
+    throw new InstallError(
+      `"${input}" is not a GitHub repository. Use owner/repo or a github.com URL.`,
+    )
+  }
+
+  // ── A SEGMENT OF ONLY DOTS IS NOT A REPOSITORY NAME, IT IS PATH TRAVERSAL ──
+  // `[\w.-]+` matches `.` and `..`, so `../x` parsed happily into owner `..`. The
+  // result is interpolated into `https://api.github.com/repos/${repo}` and into the
+  // codeload URL, where the URL parser NORMALIZES the `..` away — so the request
+  // silently addressed a different GitHub API endpoint than the one this code
+  // believes it is calling, and the bogus value was then recorded in the ledger and
+  // rendered in Settings. GitHub allows neither name, so nothing legitimate is lost
+  // by rejecting them here rather than discovering it from a confusing 404.
+  const [, owner, repo] = match
+  for (const segment of [owner, repo]) {
+    if (/^\.+$/.test(segment)) {
+      throw new InstallError(
+        `"${input}" is not a GitHub repository. Use owner/repo or a github.com URL.`,
+      )
+    }
+  }
+  return `${owner}/${repo}`
+}
+
+type ResolvedSource = { ref: string; tarballUrl: string }
+
+/**
+ * Pick which ref to install.
+ *
+ * Prefers the latest release, because a release is the author saying "this is
+ * ready" — installing the default branch means installing whatever was pushed
+ * thirty seconds ago. Falls back to the default branch so an extension without
+ * releases is still installable, which matters a lot early on when the author and
+ * the user are the same person.
+ */
+async function resolveSource(repo: string): Promise<ResolvedSource> {
+  const headers = {
+    accept: 'application/vnd.github+json',
+    // GitHub rejects API requests without a User-Agent.
+    'user-agent': 'agent-code',
+  }
+
+  try {
+    const res = await fetchWithDeadline(`https://api.github.com/repos/${repo}/releases/latest`, headers)
+    if (res.ok) {
+      const body = (await res.json()) as { tag_name?: string; tarball_url?: string }
+      if (body.tag_name && body.tarball_url) {
+        return { ref: body.tag_name, tarballUrl: body.tarball_url }
+      }
+    }
+  } catch {
+    // Network failure here is not fatal — fall through to the default branch, which
+    // uses a different host (codeload) and may still succeed. A hard failure will
+    // surface there with a better message.
+  }
+
+  const res = await fetchWithDeadline(`https://api.github.com/repos/${repo}`, headers)
+  if (res.status === 404) {
+    throw new InstallError(`Repository ${repo} not found, or it is private.`)
+  }
+  if (!res.ok) {
+    throw new InstallError(`GitHub returned ${res.status} for ${repo}.`)
+  }
+  const body = (await res.json()) as { default_branch?: string }
+  const branch = body.default_branch
+  if (!branch) throw new InstallError(`Could not determine the default branch of ${repo}.`)
+
+  return {
+    ref: branch,
+    tarballUrl: `https://codeload.github.com/${repo}/tar.gz/refs/heads/${branch}`,
+  }
+}
+
+/**
+ * Every network call in this module goes through here.
+ *
+ * WHY A DEADLINE IS NOT OPTIONAL: these are fetches to a host the USER named, made
+ * from the main process. Without one, a server that accepts the connection and then
+ * never responds leaves the install promise pending forever — the Settings row stays
+ * "Installing…", its button stays disabled, and there is no cancel affordance
+ * anywhere in the UI. A hung install is indistinguishable from a slow one and the
+ * only escape is restarting the app.
+ */
+function isAbort(error: unknown): boolean {
+  return error instanceof Error && (error.name === 'TimeoutError' || error.name === 'AbortError')
+}
+
+async function fetchWithDeadline(
+  url: string,
+  headers: Record<string, string>,
+  signal?: AbortSignal,
+): Promise<Response> {
+  try {
+    return await fetch(url, { headers, signal: signal ?? AbortSignal.timeout(NETWORK_TIMEOUT_MS) })
+  } catch (error) {
+    // AbortSignal rejects with a TimeoutError/AbortError DOMException, which reaches
+    // the user as "The operation was aborted" — true and useless. Name the host.
+    if (isAbort(error)) {
+      throw new InstallError(`${new URL(url).host} did not respond in time.`)
+    }
+    throw error
+  }
+}
+
+async function downloadTarball(url: string): Promise<{ bytes: Buffer; sha256: string }> {
+  // ── THE BODY GETS AN IDLE BUDGET, NOT A TOTAL ONE ──
+  // A single AbortSignal.timeout() covering the whole request is wrong here in two
+  // ways. First the arithmetic: 32 MB inside 30 s demands a sustained 8.7 Mbps, so
+  // a legitimate large-but-legal extension fails on an ordinary connection. Second
+  // the error handling: when that signal fires during the body read it throws out
+  // of the `for await` below, which is OUTSIDE fetchWithDeadline's try/catch — so
+  // the translation never ran and the user got exactly the "The operation was
+  // aborted" string the translation exists to prevent.
+  //
+  // An idle timer measures what actually matters — the connection has stopped
+  // making progress — and rearms on every chunk, so a slow but live download
+  // completes however long it legitimately takes.
+  const controller = new AbortController()
+  let idleTimer: ReturnType<typeof setTimeout> | null = null
+  const armIdleTimer = (): void => {
+    if (idleTimer) clearTimeout(idleTimer)
+    idleTimer = setTimeout(() => controller.abort(), NETWORK_TIMEOUT_MS)
+  }
+  armIdleTimer()
+
+  try {
+    return await readTarball(url, controller.signal, armIdleTimer)
+  } catch (error) {
+    if (isAbort(error)) {
+      throw new InstallError(`${new URL(url).host} stopped responding during the download.`)
+    }
+    throw error
+  } finally {
+    if (idleTimer) clearTimeout(idleTimer)
+  }
+}
+
+async function readTarball(
+  url: string,
+  signal: AbortSignal,
+  onProgress: () => void,
+): Promise<{ bytes: Buffer; sha256: string }> {
+  const res = await fetchWithDeadline(url, { 'user-agent': 'agent-code' }, signal)
+  if (!res.ok) throw new InstallError(`Download failed with HTTP ${res.status}.`)
+
+  // ── THE CAP IS ENFORCED WHILE READING, NOT AFTER ──
+  // This used to check `content-length` and then call `res.arrayBuffer()`, which are
+  // two different things. The header is supplied by the server, so it is a HINT, not
+  // a bound: omit it (chunked encoding is enough) or lie about it, and arrayBuffer()
+  // allocates the entire body first — the size check then runs on an allocation that
+  // has already happened. A hostile or merely misconfigured host could therefore
+  // drive the MAIN PROCESS, the one holding every agent session, to an
+  // out-of-memory kill from a URL the user only pasted a repo name for.
+  //
+  // Counting while reading makes the limit real: the abort happens at the moment the
+  // cap is crossed, so peak allocation is bounded by MAX_TARBALL_BYTES plus one
+  // chunk no matter what the server claims.
+  const declared = Number(res.headers.get('content-length') ?? '0')
+  if (Number.isFinite(declared) && declared > MAX_TARBALL_BYTES) {
+    // A cheap early exit WHEN the header is present — which on the primary path it
+    // usually is not, because codeload generates the tarball on the fly and responds
+    // chunked. So this is a bonus, never the bound; the counter below is the bound.
+    throw new InstallError(`Archive is ${Math.round(declared / 1e6)} MB; the limit is 32 MB.`)
+  }
+  if (!res.body) throw new InstallError('Download returned an empty response.')
+
+  const chunks: Buffer[] = []
+  let total = 0
+  for await (const chunk of res.body as unknown as AsyncIterable<Uint8Array>) {
+    onProgress()
+    total += chunk.byteLength
+    if (total > MAX_TARBALL_BYTES) throw new InstallError('Archive exceeds the 32 MB limit.')
+    chunks.push(Buffer.from(chunk))
+  }
+
+  const bytes = Buffer.concat(chunks)
+  return { bytes, sha256: createHash('sha256').update(bytes).digest('hex') }
+}
+
+async function resolveTarBinary(): Promise<string> {
+  try {
+    await access('/usr/bin/tar', fsConstants.X_OK)
+    return '/usr/bin/tar'
+  } catch {
+    // Bare name → spawn resolves through PATH. Mirrors setup/runtimeTools.ts, which
+    // is deliberately not imported: extension install must not depend on the
+    // bundled-runtime-tools subsystem, and the duplication is twenty lines.
+    return 'tar'
+  }
+}
+
+async function extractTarball(archivePath: string, destDir: string): Promise<void> {
+  const tar = await resolveTarBinary()
+  await new Promise<void>((resolveExtract, reject) => {
+    // --strip-components=1 removes GitHub's `<repo>-<sha>/` wrapper directory, so
+    // the manifest lands at destDir/agent-code.extension.json rather than one level
+    // down under a name that changes with every commit.
+    //
+    // --no-same-owner / --no-same-permissions: the archive is attacker-controlled,
+    // and its entries carry a uid/gid and a mode. Honouring either lets the archive
+    // decide what the extracted files look like on disk — a setuid bit, a
+    // group-writable directory, an owner that is not the running user. Neither is
+    // ever wanted for what is supposed to be a bundle of JavaScript. Both flags are
+    // accepted by bsdtar (macOS /usr/bin/tar) and GNU tar.
+    //
+    // NOT relied upon: the extractor's own traversal defences. bsdtar refuses `..`
+    // members and refuses to write THROUGH a symlink by default, and that was
+    // verified empirically — but `resolveTarBinary` can fall back to whatever `tar`
+    // is on PATH, which may be a different implementation with different defaults.
+    // assertBundleTreeIsSafe below is what actually holds the guarantee, because it
+    // does not depend on which binary ran.
+    const child = spawn(
+      tar,
+      [
+        '-xzf',
+        archivePath,
+        '-C',
+        destDir,
+        '--strip-components=1',
+        '--no-same-owner',
+        '--no-same-permissions',
+      ],
+      {
+        stdio: ['ignore', 'ignore', 'pipe'],
+      },
+    )
+
+    // ── THE DOWNLOAD CAP DOES NOT BOUND THE EXTRACTION ──
+    // MAX_TARBALL_BYTES bounds COMPRESSED bytes. gzip on repetitive content runs
+    // 1000:1 and better, so a 32 MB archive that passes every check upstream can
+    // write tens of gigabytes here. EXTENSIONS_DIR is under $HOME, i.e. the boot
+    // volume, so filling it degrades the whole machine rather than just this app —
+    // and a Tier-0 manifest (which is what such a repository would ship) reaches
+    // this point with NO dialog of any kind, from a pasted `owner/repo`.
+    //
+    // Polled rather than streamed through a counting transform: the polling version
+    // is a dozen lines against a rewrite of the extraction path, it needs no
+    // in-process gunzip, and 500 ms of overshoot on a disk write is immaterial next
+    // to a cap this generous. On breach the child is SIGKILLed and the caller's
+    // `finally` removes the partial tree.
+    let settled = false
+    const finish = (run: () => void) => {
+      if (settled) return
+      settled = true
+      clearInterval(sizeTimer)
+      run()
+    }
+
+    const sizeTimer = setInterval(() => {
+      void directorySize(destDir).then(bytes => {
+        if (bytes <= MAX_EXTRACTED_BYTES) return
+        child.kill('SIGKILL')
+        finish(() =>
+          reject(
+            new InstallError(
+              `Archive expands to more than ${Math.round(MAX_EXTRACTED_BYTES / 1e6)} MB; ` +
+                `refusing to install it.`,
+            ),
+          ),
+        )
+      }).catch(() => {
+        // A stat failure mid-extraction is not evidence of a bomb (files come and
+        // go while tar writes); the next tick re-measures.
+      })
+    }, 500)
+
+    // Capped: stderr is attacker-influenced (tar echoes member names), and an
+    // archive with a million bad members would otherwise grow this string without
+    // bound in the main process while the extraction it is reporting on fails.
+    let stderr = ''
+    child.stderr.on('data', chunk => {
+      if (stderr.length < 4096) stderr += String(chunk)
+    })
+    child.once('error', error => finish(() => reject(error)))
+    child.once('exit', code => {
+      finish(() => {
+        if (code === 0) resolveExtract()
+        else
+          reject(
+            new InstallError(`Could not unpack the archive (tar exit ${code}): ${stderr.trim()}`),
+          )
+      })
+    })
+  })
+}
+
+/** Total size of a directory tree, following nothing. Used only as a bomb guard. */
+async function directorySize(dir: string): Promise<number> {
+  let total = 0
+  const walk = async (current: string): Promise<void> => {
+    for (const dirent of await readdir(current, { withFileTypes: true })) {
+      const absolute = join(current, dirent.name)
+      const stats = await lstat(absolute)
+      if (stats.isDirectory()) await walk(absolute)
+      else total += stats.size
+    }
+  }
+  await walk(dir)
+  return total
+}
+
+/**
+ * Reject a staged bundle that contains anything pointing outside itself.
+ *
+ * ── WHY THIS EXISTS EVEN THOUGH THREE OTHER CHECKS LOOK SIMILAR ──
+ * The scheme handler realpath-checks each file it SERVES, and
+ * verifyEntryInsideBundle realpath-checks the ENTRY. Both are per-file checks made
+ * later, and neither says anything about the rest of the tree. This one is about
+ * the bundle as a whole, and it runs at the only moment where refusing is still
+ * free: before the bundle is moved into place, before consent is asked, before a
+ * grant exists.
+ *
+ * What it stops:
+ * - An escaping symlink surviving into the installed directory. Serving it is
+ *   already blocked, but its mere presence means `computeBundleHash` is hashing a
+ *   link whose target the extension does not own, and every future reader of that
+ *   directory (a backup, a sync client, a future feature that walks the bundle)
+ *   inherits a pointer out of the sandbox that nobody put there deliberately.
+ * - The extractor's defences differing by implementation. bsdtar blocks `..`
+ *   members and symlink write-through by default; `resolveTarBinary` may fall back
+ *   to a `tar` on PATH that does not. Checking the RESULT rather than trusting the
+ *   tool makes the guarantee independent of which binary ran.
+ * - Entry types that have no business in a JavaScript bundle at all — sockets,
+ *   FIFOs, devices — which would otherwise be copied into place and then hashed.
+ *
+ * A dangling symlink is fine and stays allowed: it points nowhere, so it can leak
+ * nothing, and rejecting it would break bundles that ship optional artefacts.
+ */
+async function assertBundleTreeIsSafe(bundleDir: string): Promise<void> {
+  const rootReal = await realpath(bundleDir)
+  let seen = 0
+
+  const walk = async (dir: string): Promise<void> => {
+    for (const dirent of await readdir(dir, { withFileTypes: true })) {
+      // ── A FILE-COUNT CAP, BECAUSE THE BYTE CAPS DO NOT IMPLY ONE ──
+      // 500,000 empty files compress to a couple of megabytes and extract to almost
+      // nothing, so they pass both the download and the extraction limits. They
+      // would then cost a readdir+lstat here, a readFile each in computeBundleHash
+      // at install, and another full hash on every frame open — all on the main
+      // process, which already has a documented saturation problem. 10,000 is ~50x
+      // any real bundle.
+      if (++seen > MAX_BUNDLE_FILES) {
+        throw new InstallError(
+          `The repository contains more than ${MAX_BUNDLE_FILES} files. An extension is a ` +
+            `built bundle; this looks like an unbuilt source tree.`,
+        )
+      }
+      const absolute = join(dir, dirent.name)
+      const stats = await lstat(absolute)
+
+      if (stats.isSymbolicLink()) {
+        let targetReal: string
+        try {
+          targetReal = await realpath(absolute)
+        } catch {
+          // Dangling. Points at nothing, so it leaks nothing.
+          continue
+        }
+        if (targetReal !== rootReal && !targetReal.startsWith(rootReal + sep)) {
+          throw new InstallError(
+            `The repository contains a symlink ("${relative(rootReal, absolute)}") that points ` +
+              `outside the extension directory. Refusing to install it.`,
+          )
+        }
+        continue
+      }
+
+      if (stats.isDirectory()) {
+        await walk(absolute)
+        continue
+      }
+
+      if (!stats.isFile()) {
+        throw new InstallError(
+          `The repository contains a special file ("${relative(rootReal, absolute)}") that is not ` +
+            `a regular file, directory or symlink. Refusing to install it.`,
+        )
+      }
+    }
+  }
+
+  await walk(rootReal)
+}
+
+/**
+ * Verify the manifest's `entry` resolves to a real file INSIDE the bundle.
+ *
+ * The schema already rejects absolute paths and `..` segments, but this is the
+ * check that actually matters: a symlink committed to the repository can point
+ * anywhere, and tar will happily recreate it. Resolving the realpath and requiring
+ * it to stay under the bundle root is the only way to catch that. Without it, a
+ * manifest saying `entry: "link.js"` where `link.js` symlinks to `~/.ssh/id_rsa`
+ * would hand that file to a scheme handler that serves extension code.
+ */
+async function verifyEntryInsideBundle(bundleDir: string, entry: string): Promise<void> {
+  const bundleReal = await realpath(bundleDir)
+  const target = resolvePath(bundleReal, entry)
+
+  let targetReal: string
+  try {
+    targetReal = await realpath(target)
+  } catch {
+    throw new InstallError(`Manifest points at "${entry}", which does not exist in the repository.`)
+  }
+
+  if (targetReal !== bundleReal && !targetReal.startsWith(bundleReal + sep)) {
+    throw new InstallError(`Manifest entry "${entry}" resolves outside the extension directory.`)
+  }
+}
+
+async function readManifestFrom(dir: string): Promise<ExtensionManifest> {
+  const manifestPath = join(dir, MANIFEST_FILENAME)
+  let raw: string
+  try {
+    raw = await readFile(manifestPath, 'utf8')
+  } catch {
+    throw new InstallError(
+      `Repository has no ${MANIFEST_FILENAME} at its root — it is not an Agent Code extension.`,
+    )
+  }
+  try {
+    return parseExtensionManifest(raw)
+  } catch (error) {
+    // ManifestError messages are already user-facing; rewrap so callers only have
+    // one error type to present.
+    throw new InstallError(error instanceof ManifestError ? error.message : String(error))
+  }
+}
+
+/**
+ * The shared tail of every install path: consent, move the validated bundle into
+ * place, write the ledger row, bind (or drop) the grant. Both the GitHub and the
+ * local-folder installers converge here once they have a validated manifest in a
+ * staging directory — the ONLY differences between them are how the bundle got
+ * staged and what `repo`/`ref`/`sha256` describe its provenance.
+ *
+ * `bundleDir` is renamed into place (not copied), so it must already be a temp
+ * directory the caller owns; on any failure here the caller's `finally` removes it.
+ */
+/**
+ * A staging directory INSIDE the extensions root, not in the OS temp dir.
+ *
+ * finalizeInstall commits by `rename(staging, finalDir)`. rename cannot cross
+ * filesystems: where /tmp is its own mount — Linux tmpfs, the common case — it fails
+ * with EXDEV. And because the commit deletes the live bundle BEFORE the rename, that
+ * failure mode is not "install didn't work", it is "install destroyed the version you
+ * had". Staging as a sibling of the destination makes the rename same-filesystem by
+ * construction, which is the only way to get atomicity out of it.
+ *
+ * The dot prefix is NOT "kept out of the ledger's view", as this comment used to
+ * claim — nothing in the app enumerates EXTENSIONS_DIR, so there was no scan for it
+ * to be excluded from. What the prefix actually buys is that `.staging-…` can never
+ * be a valid extension id (ids must start with a letter), so `scheme.ts` can never
+ * be tricked into serving a half-extracted tree, and the startup sweep can identify
+ * these directories unambiguously.
+ */
+async function makeStagingDir(): Promise<string> {
+  await mkdir(EXTENSIONS_DIR, { recursive: true })
+  return await mkdtemp(join(EXTENSIONS_DIR, '.staging-'))
+}
+
+async function finalizeInstall(
+  manifest: ExtensionManifest,
+  bundleDir: string,
+  provenance: { origin: 'github' | 'local'; repo: string; ref: string; sha256: string },
+  promptConsent?: ConsentPrompt,
+): Promise<InstalledExtension> {
+  // Consent gate. If the extension requests capabilities beyond Tier 0, the user
+  // must approve them BEFORE the bundle moves into place — declining aborts the
+  // install, so nothing is left behind. A Tier-0-only extension installs with no
+  // prompt, matching the "repo name is the trust decision" stance.
+  const permissions = manifest.permissions ?? []
+  if (permissions.length > 0) {
+    const approved = promptConsent ? await promptConsent(manifest) : false
+    if (!approved) {
+      throw new InstallError(
+        `Installation of ${manifest.name} was declined — its requested capabilities were not granted.`,
+      )
+    }
+  }
+
+  await mkdir(EXTENSIONS_DIR, { recursive: true })
+  const finalDir = join(EXTENSIONS_DIR, manifest.id)
+
+  // ── EVERYTHING FALLIBLE HAPPENS BEFORE ANYTHING IS DESTROYED ──
+  //
+  // The previous ordering was rm(finalDir) → rename(staging) → computeBundleHash
+  // → writeLedger, i.e. it destroyed the installed version and committed the new
+  // one BEFORE its last two fallible steps. Three ordinary failures broke it:
+  //
+  //  - A crash between the rm and the rename left NO bundle and a surviving
+  //    ledger row: the row reads `present: false` and the only recovery is a
+  //    reinstall the user has to work out for themselves.
+  //  - computeBundleHash throwing (a concurrent remove deleting the directory
+  //    under it, ENOSPC, EACCES) left the new bundle on disk with no ledger row.
+  //    Nothing enumerates EXTENSIONS_DIR, so that directory is invisible to the
+  //    UI and unreachable by extensions:remove — a ghost nothing can delete.
+  //  - writeLedger throwing did the same, and is *reachable in combination with
+  //    a disk-filling archive*, which is exactly when it matters most.
+  //
+  // So: hash in staging, then swap. The hash is identical either way — staging is
+  // a sibling of the destination by construction (makeStagingDir), so the rename
+  // moves the same inodes and cannot alter content. The earlier comment argued the
+  // hash had to come from the final location; that was buying a property the
+  // same-filesystem guarantee already provides, at the cost of putting a throwing
+  // call after the point of no return.
+  const bundleSha256 = await computeBundleHash(bundleDir)
+
+  const record: InstalledExtension = {
+    manifest,
+    origin: provenance.origin,
+    repo: provenance.repo,
+    ref: provenance.ref,
+    sha256: provenance.sha256,
+    installedAt: Date.now(),
+  }
+
+  // The previous version is moved ASIDE rather than deleted, so a failure can put
+  // it back. This is what makes a failed update a no-op instead of an uninstall —
+  // the single most important property of an update path, and the one the old
+  // ordering did not have. Extension STATE is untouched throughout: it lives under
+  // EXTENSION_STATE_DIR precisely so neither an update nor a rollback can take a
+  // user's saved data with it.
+  // ── THE SWAP AND THE LEDGER WRITE ARE ONE CRITICAL SECTION ──
+  // Without the lock, two concurrent installs both read the ledger, both write it,
+  // and the first one's row is lost while its bundle sits on disk referenced by
+  // nothing. An install racing a remove of the same id resurrects the extension the
+  // user just uninstalled. See withLedgerLock for the full account.
+  await withLedgerLock(async () => {
+    const backupDir = `${finalDir}.replacing-${randomUUID()}`
+    let hadPrevious = true
+    try {
+      await rename(finalDir, backupDir)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+      hadPrevious = false
+    }
+
+    try {
+      await rename(bundleDir, finalDir)
+      await writeLedger(
+        (await readLedger()).filter(row => row.manifest.id !== manifest.id).concat(record),
+      )
+    } catch (error) {
+      // Roll back to exactly what the user had. Best-effort: if the restore itself
+      // fails there is nothing further to try, and the original error is the one
+      // worth surfacing.
+      await rm(finalDir, { recursive: true, force: true }).catch(() => {})
+      if (hadPrevious) await rename(backupDir, finalDir).catch(() => {})
+      throw error
+    }
+
+    // Committed. The old bundle is now unreferenced; failing to delete it is not
+    // worth failing the install over, so it is swept at startup instead.
+    if (hadPrevious) await rm(backupDir, { recursive: true, force: true }).catch(() => {})
+  })
+
+  // Bind the grant to the INSTALLED BYTES, not to the provenance hash.
+  //
+  // The grant used to key on `provenance.sha256`, which is the tarball digest —
+  // and the tarball is deleted moments later, so the check could only ever
+  // compare the ledger row against the grant row, both written right here. It
+  // could not fail, and editing a file under EXTENSIONS_DIR kept every granted
+  // capability. Keying on the recomputable bundle hash is what turns the
+  // documented "bytes changed, so re-consent" rule into an enforced one.
+  //
+  // A downgrade to Tier-0-only still drops any prior grant, so revoking
+  // capabilities remains as simple as shipping a manifest that stops asking.
+  if (permissions.length > 0) await recordGrant(manifest.id, bundleSha256, permissions)
+  else await revokeGrant(manifest.id)
+
+  return record
+}
+
+/**
+ * Reclaim directories under EXTENSIONS_DIR that no longer belong to anything.
+ *
+ * ── WHY THIS IS NEEDED AND WHY IT RUNS AT STARTUP ──
+ * Installs create two kinds of transient directory: `.staging-XXXX` while the
+ * bundle is being validated, and `<id>.replacing-<uuid>` while the swap is in
+ * flight. Both are removed on the happy path and on a handled failure — but a
+ * crash, a force-quit, or a kill during an install leaves them behind forever,
+ * because nothing else ever looks at this directory. Each one costs up to the
+ * extracted-size cap, so they are not a rounding error.
+ *
+ * Startup is the only safe moment: no install can be in flight, so anything
+ * matching these shapes is definitionally abandoned. Doing it opportunistically
+ * during an install would race a concurrent one.
+ *
+ * Deliberately conservative — it removes ONLY the two transient shapes. A bundle
+ * directory with no ledger row is left alone: that is a different problem with a
+ * different correct answer (the user may want to recover it), and silently deleting
+ * from a directory that holds installed code is not something a sweep should do.
+ */
+export async function sweepAbandonedInstallDirectories(): Promise<void> {
+  let entries: string[]
+  try {
+    entries = await readdir(EXTENSIONS_DIR)
+  } catch {
+    // No extensions directory yet. Nothing to reclaim.
+    return
+  }
+
+  for (const name of entries) {
+    if (!name.startsWith('.staging-') && !/\.replacing-[0-9a-f-]{36}$/.test(name)) continue
+    await rm(join(EXTENSIONS_DIR, name), { recursive: true, force: true }).catch(error => {
+      // Best-effort by design: this is housekeeping on a path that must never be
+      // able to prevent the app from starting.
+      console.warn(`[extensions] could not remove abandoned ${name}:`, error)
+    })
+  }
+}
+
+/**
+ * Install (or reinstall) an extension from a GitHub repository.
+ *
+ * Sequence matters: everything that can fail happens in a temp directory, and the
+ * bundle only moves into place once the manifest has validated and the entry has
+ * been proven to exist inside it. A failed install therefore leaves no partial
+ * directory for the loader to find — the failure mode the runtime-tools extractor
+ * documents at length, reached here by the same route.
+ */
+export async function installExtension(
+  repoInput: string,
+  promptConsent?: ConsentPrompt,
+): Promise<InstalledExtension> {
+  const repo = normalizeRepo(repoInput)
+  const source = await resolveSource(repo)
+  const { bytes, sha256 } = await downloadTarball(source.tarballUrl)
+
+  const work = await makeStagingDir()
+  try {
+    const archivePath = join(work, 'bundle.tar.gz')
+    const staging = join(work, 'unpacked')
+    await writeFile(archivePath, bytes)
+    await mkdir(staging, { recursive: true })
+    await extractTarball(archivePath, staging)
+    await assertBundleTreeIsSafe(staging)
+
+    const manifest = await readManifestFrom(staging)
+    await verifyEntryInsideBundle(staging, manifest.entry)
+
+    return await finalizeInstall(
+      manifest,
+      staging,
+      { origin: 'github', repo, ref: source.ref, sha256 },
+      promptConsent,
+    )
+  } finally {
+    // .catch: `force` only suppresses ENOENT. A staging tree containing a
+    // mode-0000 directory (reachable through Load folder…) makes this throw
+    // EACCES, and a throw in a `finally` REPLACES whatever the try threw — so a
+    // precise InstallError became a raw errno string and the real cause was lost.
+    await rm(work, { recursive: true, force: true }).catch(() => {})
+  }
+}
+
+/**
+ * Install an extension from a LOCAL folder — the "load unpacked" path.
+ *
+ * WHY this exists: the GitHub installer resolves `releases/latest`, so iterating on
+ * an unpublished extension otherwise means cutting a release for every change. This
+ * lets an author point at their built folder and reinstall in one click. It is a
+ * SNAPSHOT (a copy), not a live mount: a rebuild + reinstall is the loop, which is
+ * still vastly cheaper than a release. A live-reference mode (serve straight from
+ * the folder) is a larger change to the scheme handler and is deliberately left for
+ * later — a copy reuses the exact same containment guarantees as the tarball path.
+ */
+export async function installExtensionFromPath(
+  sourceDir: string,
+  promptConsent?: ConsentPrompt,
+): Promise<InstalledExtension> {
+  let sourceReal: string
+  try {
+    sourceReal = await realpath(sourceDir)
+  } catch {
+    throw new InstallError(`Folder "${sourceDir}" does not exist.`)
+  }
+
+  const work = await makeStagingDir()
+  try {
+    const staging = join(work, 'unpacked')
+    await mkdir(staging, { recursive: true })
+
+    // Copy the folder, skipping node_modules and .git: the built bundle plus assets
+    // is what ships; a dev folder's dependencies and history are neither needed nor
+    // small (node_modules would blow past the mental model of "an extension is a JS
+    // bundle"). This is the tarball path minus the download + strip-components.
+    await cp(sourceReal, staging, {
+      recursive: true,
+      // ── verbatimSymlinks: COPY THE LINK TEXT, DO NOT RESOLVE IT ──
+      // Node's default is `verbatimSymlinks: false`, which RESOLVES each symlink's
+      // target to an absolute path while copying. That silently rewrites a bundle's
+      // internal relative link (`alias.js -> dist/index.js`) into an absolute link
+      // into the AUTHOR'S source folder — so a perfectly ordinary bundle came out of
+      // the snapshot pointing at a directory outside itself, which the containment
+      // check below then correctly refuses. The install failed and the message
+      // blamed the author for a link they had written correctly.
+      //
+      // Copying verbatim is also the safer default, not just the working one: an
+      // escaping link stays exactly as escaping as the author wrote it, so
+      // assertBundleTreeIsSafe judges what the repository actually contains rather
+      // than an absolutised rewrite of it.
+      verbatimSymlinks: true,
+      filter: src => {
+        const rel = relative(sourceReal, src)
+        return rel === '' || !rel.split(sep).some(part => part === 'node_modules' || part === '.git')
+      },
+    })
+    await assertBundleTreeIsSafe(staging)
+
+    const manifest = await readManifestFrom(staging)
+    await verifyEntryInsideBundle(staging, manifest.entry)
+
+    // PROVENANCE ONLY. There is no tarball, so the entry digest answers "which
+    // bytes did the source hand me" for a local install. It does NOT bind the
+    // grant — finalizeInstall binds that to computeBundleHash over the whole
+    // installed directory, identically on both paths. An earlier comment here said
+    // the opposite, describing entry-scoped binding as the design; entry-scoped
+    // hashing was in fact half of the original defect, because it let a sibling
+    // chunk be swapped while the grant still matched.
+    const entryBytes = await readFile(join(staging, manifest.entry))
+    const sha256 = createHash('sha256').update(entryBytes).digest('hex')
+
+    return await finalizeInstall(
+      manifest,
+      staging,
+      { origin: 'local', repo: sourceReal, ref: 'local', sha256 },
+      promptConsent,
+    )
+  } finally {
+    // .catch: `force` only suppresses ENOENT. A staging tree containing a
+    // mode-0000 directory (reachable through Load folder…) makes this throw
+    // EACCES, and a throw in a `finally` REPLACES whatever the try threw — so a
+    // precise InstallError became a raw errno string and the real cause was lost.
+    await rm(work, { recursive: true, force: true }).catch(() => {})
+  }
+}
diff --git a/src/main/extensions/installTree.system.test.ts b/src/main/extensions/installTree.system.test.ts
new file mode 100644
index 000000000..616e895e7
--- /dev/null
+++ b/src/main/extensions/installTree.system.test.ts
@@ -0,0 +1,151 @@
+import { mkdtemp, mkdir, rm, symlink, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join } from 'path'
+
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { installExtensionFromPath, InstallError } from '@main/extensions/install.js'
+
+// `.system.` because the guarantee under test IS a filesystem guarantee: what the
+// installer refuses to move into place after a real copy of a real directory tree.
+// A mocked fs would be testing the mock's idea of a symlink.
+//
+// These drive the LOCAL-folder installer rather than the tarball one, because it is
+// the path that needs no network and no `tar` binary while running the identical
+// validation tail (assertBundleTreeIsSafe → readManifestFrom → verifyEntryInsideBundle
+// → finalizeInstall). The tarball path's extra step is extraction, whose output is
+// then handed to exactly these checks.
+
+const temporaryRoots: string[] = []
+
+async function makeSourceFolder(
+  files: Record<string, string>,
+  manifest?: Record<string, unknown>,
+): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), 'agent-code-install-tree-'))
+  temporaryRoots.push(root)
+  const source = join(root, 'source')
+  await mkdir(source, { recursive: true })
+  if (manifest !== undefined) {
+    await writeFile(join(source, 'agent-code.extension.json'), JSON.stringify(manifest), 'utf8')
+  }
+  for (const [relative, contents] of Object.entries(files)) {
+    const absolute = join(source, relative)
+    await mkdir(join(absolute, '..'), { recursive: true })
+    await writeFile(absolute, contents, 'utf8')
+  }
+  return source
+}
+
+/** A manifest that is valid in every respect the tree checks do not care about. */
+function validManifest(): Record<string, unknown> {
+  return {
+    id: 'treetest',
+    name: 'Tree Test',
+    description: 'Fixture extension.',
+    version: '0.0.1',
+    apiVersion: 1,
+    entry: 'dist/index.js',
+  }
+}
+
+// The consent prompt is never reached by any assertion below — every case fails
+// before it — so a prompt that returns false doubles as a guard: if one of these
+// ever DID reach consent, the install would abort rather than write to the real
+// EXTENSIONS_DIR under the developer's home directory.
+const denyConsent = async () => false
+
+afterEach(async () => {
+  await Promise.all(temporaryRoots.splice(0).map(root => rm(root, { recursive: true, force: true })))
+})
+
+describe('install refuses a bundle that points outside itself', () => {
+  it('rejects a symlink whose target escapes the bundle', async () => {
+    // ── THE REGRESSION THIS EXISTS FOR ──
+    // A repository can commit a symlink, and `tar`/`cp` recreate it. Whether the
+    // extractor blocks traversal is implementation-dependent — bsdtar refuses `..`
+    // members and symlink write-through, a `tar` found on PATH may not — so the
+    // guarantee has to come from checking the RESULT, not from trusting the tool.
+    const source = await makeSourceFolder({ 'dist/index.js': 'export function activate() {}' }, validManifest())
+    await symlink('/etc', join(source, 'escape'))
+
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(InstallError)
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(/points outside/)
+  })
+
+  it('names the offending path so the failure is diagnosable', async () => {
+    const source = await makeSourceFolder({ 'dist/index.js': 'export function activate() {}' }, validManifest())
+    await mkdir(join(source, 'nested'), { recursive: true })
+    await symlink('/etc', join(source, 'nested/escape'))
+
+    // Without the path, an author with a large repository has no way to find it.
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(/nested\/escape/)
+  })
+
+  it('allows a RELATIVE symlink that stays inside the bundle', async () => {
+    // Legitimate: bundles do alias files internally. Rejecting these would be a
+    // blanket ban on symlinks, which is a bigger rule than the threat requires.
+    // This reaches the consent prompt and is then declined, which is how the test
+    // asserts it got PAST the tree check without writing to the real state dir.
+    const source = await makeSourceFolder(
+      { 'dist/index.js': 'export function activate() {}' },
+      { ...validManifest(), permissions: ['workspace.observe'] },
+    )
+    await symlink('dist/index.js', join(source, 'alias.js'))
+
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(/declined/)
+  })
+
+  it('rejects an ABSOLUTE symlink into the author\'s own source tree', async () => {
+    // Subtle and worth pinning, because it looks like a false positive and is not.
+    // The local installer SNAPSHOTS the folder: `cp` preserves symlinks verbatim, so
+    // an absolute link to `<source>/dist/index.js` still points at the AUTHOR'S
+    // FOLDER once the bundle has been copied under EXTENSIONS_DIR. At that moment it
+    // is a genuine escape — the installed extension reaches a path outside itself,
+    // the scheme handler would refuse to serve it, and computeBundleHash would be
+    // hashing a link whose target the bundle does not own.
+    //
+    // A relative link (the case above) survives the copy intact and is allowed. So
+    // the rule an author needs is "link relatively", which the message below has to
+    // be good enough to convey.
+    const source = await makeSourceFolder(
+      { 'dist/index.js': 'export function activate() {}' },
+      { ...validManifest(), permissions: ['workspace.observe'] },
+    )
+    await symlink(join(source, 'dist/index.js'), join(source, 'absolute-alias.js'))
+
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(/points outside/)
+  })
+
+  it('allows a dangling symlink, which can leak nothing', async () => {
+    const source = await makeSourceFolder(
+      { 'dist/index.js': 'export function activate() {}' },
+      { ...validManifest(), permissions: ['workspace.observe'] },
+    )
+    await symlink(join(source, 'does-not-exist'), join(source, 'dangling.js'))
+
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(/declined/)
+  })
+})
+
+describe('install validates the manifest before anything is moved into place', () => {
+  it('rejects a folder with no manifest', async () => {
+    const source = await makeSourceFolder({ 'dist/index.js': 'export function activate() {}' })
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(
+      /not an Agent Code extension/,
+    )
+  })
+
+  it('rejects a manifest whose entry does not exist', async () => {
+    const source = await makeSourceFolder({ 'other.js': 'export {}' }, validManifest())
+    await expect(installExtensionFromPath(source, denyConsent)).rejects.toThrow(
+      /does not exist in the repository/,
+    )
+  })
+
+  it('rejects a missing source folder without creating anything', async () => {
+    await expect(
+      installExtensionFromPath(join(tmpdir(), 'agent-code-install-tree-absent'), denyConsent),
+    ).rejects.toThrow(/does not exist/)
+  })
+})
diff --git a/src/main/extensions/ledger.ts b/src/main/extensions/ledger.ts
new file mode 100644
index 000000000..eee1fa1da
--- /dev/null
+++ b/src/main/extensions/ledger.ts
@@ -0,0 +1,189 @@
+import { access, mkdir, readFile, rename, rm, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { z } from 'zod'
+
+import { EXTENSIONS_DIR, EXTENSIONS_LOCKFILE, STATE_DIR } from '@main/storage/paths.js'
+import { isValidExtensionId } from '@shared/types/extensionId.js'
+import type { ExtensionListEntry, InstalledExtension } from '@shared/types/extensions.js'
+
+import { apiVersionMismatch, extensionManifestSchema } from './manifest.js'
+
+// The install ledger.
+//
+// WHY a ledger separate from "whatever directories exist under EXTENSIONS_DIR":
+// scanning the directory would make the filesystem the source of truth, and a
+// half-extracted or hand-copied folder would then look installed. The ledger
+// records what the app *decided* to install, with the repo, ref and hash that
+// produced it — questions the directory cannot answer. The directory is the
+// artifact; this is the record.
+
+// Row shape validation. WHY re-validate a file only writeLedger writes: the
+// `manifest.id` and `manifest.entry` of every row are interpolated into a path
+// (`join(EXTENSIONS_DIR, id, entry)` below) and into the import() URL the host
+// loads code from. A hand-edited extensions.json is the one way an unvalidated
+// id/entry could reach those sinks. The manifest schema already enforces the
+// path-safety refinements (id regex, entry rejects `..`/absolute/backslash), so
+// running each row through it turns "trust the file" into "trust the schema".
+// Rows are dropped INDIVIDUALLY, not the whole ledger — one bad hand-edit must
+// not orphan every other installed extension.
+const installedExtensionSchema = z.object({
+  manifest: extensionManifestSchema,
+  // Optional, and MIGRATED BELOW rather than defaulted here.
+  //
+  // An earlier version defaulted this to 'github' on the reasoning that any row
+  // predating the field came from the GitHub installer. That reasoning was simply
+  // false: `installExtensionFromPath` shipped on this same branch and has been
+  // writing rows with an absolute path in `repo` ever since. Defaulting them to
+  // 'github' sent every one of them down the GitHub Update path, straight into
+  // `normalizeRepo('/Users/…')` — reproducing the exact failure the `origin` field
+  // was added to fix, for precisely the users who had been using Load folder.
+  origin: z.enum(['github', 'local']).optional(),
+  repo: z.string().min(1),
+  ref: z.string().min(1),
+  sha256: z.string().regex(/^[a-f0-9]{64}$/),
+  installedAt: z.number().finite(),
+})
+
+export async function readLedger(): Promise<InstalledExtension[]> {
+  let raw: string
+  try {
+    raw = await readFile(EXTENSIONS_LOCKFILE, 'utf8')
+  } catch {
+    return []
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  const rows: InstalledExtension[] = []
+  for (const candidate of parsed) {
+    const result = installedExtensionSchema.safeParse(candidate)
+    if (result.success) {
+      // The ABI gate, applied at LOAD and not only at install. The schema accepts
+      // any positive apiVersion (it is shared with the install path, which wants
+      // to report a mismatch with a better message than a field error), so a row
+      // written under a host that implemented v1 would otherwise keep loading
+      // against a host that implements v2. Version skew arrives by UPGRADING
+      // AGENT CODE, which involves no install — so an install-time-only check can
+      // never see it.
+      const mismatch = apiVersionMismatch(result.data.manifest.apiVersion)
+      if (mismatch) {
+        console.warn(`[extensions] skipping ${result.data.manifest.id}: ${mismatch}`)
+        continue
+      }
+      // Migrate a pre-`origin` row by the one field that actually distinguishes the
+      // two installers: `ref`. The local installer writes the literal 'local' there
+      // (it has no git ref to record), and the GitHub installer writes a tag or a
+      // branch name. A repository whose branch is literally named `local` would be
+      // misread — and would then simply take the Update path it already took before
+      // this field existed, so the migration is never worse than not having it.
+      rows.push({
+        ...result.data,
+        origin: result.data.origin ?? (result.data.ref === 'local' ? 'local' : 'github'),
+      })
+    } else {
+      // Surfaced, not silent: a dropped row means a corrupt/hand-edited ledger,
+      // and the message names the field so it is diagnosable rather than an
+      // extension mysteriously vanishing from the list.
+      console.warn(
+        `[extensions] dropping invalid ledger row: ${result.error.issues[0]?.message ?? 'unknown'}`,
+      )
+    }
+  }
+  return rows
+}
+
+/**
+ * Serialises every read-modify-write of the ledger.
+ *
+ * ── WHY temp+rename IS NOT ENOUGH ──
+ * `writeLedger` renames a temp file into place, which makes a write ATOMIC — an
+ * interrupted write leaves the previous ledger, never a truncated one. It does
+ * nothing about a LOST UPDATE, and the two were being conflated.
+ *
+ * Both `finalizeInstall` and `removeExtension` do read → mutate → write with no
+ * lock between them, so: two concurrent installs of different extensions both read
+ * `[]`, both write a one-row ledger, and the first extension's row is gone while
+ * its bundle sits on disk with nothing referencing it. An install racing a remove
+ * of the same id resurrects the extension the user just uninstalled — with a stale
+ * grant, because revokeGrant ran before the reinstall wrote a new row.
+ *
+ * A single module-scope chain is the right size for this: ledger writes are rare,
+ * they are all in main, and the contention window is a few milliseconds. A file
+ * lock would additionally guard a second Agent Code process, which the app's
+ * single-instance lock already prevents.
+ */
+let ledgerQueue: Promise<unknown> = Promise.resolve()
+
+export function withLedgerLock<T>(operation: () => Promise<T>): Promise<T> {
+  // `.then(op, op)` rather than `.then(op)`: a previous operation's REJECTION must
+  // not skip this one. The failure still reaches its own caller through the promise
+  // returned here; it just does not poison the queue.
+  const next = ledgerQueue.then(operation, operation)
+  ledgerQueue = next.catch(() => {})
+  return next
+}
+
+export async function writeLedger(rows: InstalledExtension[]): Promise<void> {
+  await mkdir(STATE_DIR, { recursive: true })
+  // temp+rename in the same directory, matching workspace.json: an interrupted
+  // write must leave the previous ledger intact rather than a truncated file that
+  // reads as "nothing installed" and orphans every bundle on disk.
+  const tmp = `${EXTENSIONS_LOCKFILE}.tmp-${process.pid}-${Date.now()}`
+  await writeFile(tmp, `${JSON.stringify(rows, null, 2)}\n`, 'utf8')
+  await rename(tmp, EXTENSIONS_LOCKFILE)
+}
+
+/**
+ * The ledger, annotated with whether each bundle is actually on disk and loadable.
+ *
+ * `present: false` is surfaced rather than filtered because the two states need
+ * different user actions: a missing bundle is reinstallable from the recorded repo,
+ * whereas silently hiding the row would leave the user wondering where their
+ * extension went.
+ */
+export async function listInstalledExtensions(): Promise<ExtensionListEntry[]> {
+  const rows = await readLedger()
+  return Promise.all(
+    rows.map(async row => {
+      let present = false
+      try {
+        await access(join(EXTENSIONS_DIR, row.manifest.id, row.manifest.entry))
+        present = true
+      } catch {
+        present = false
+      }
+      return { ...row, present }
+    }),
+  )
+}
+
+/**
+ * Remove an extension's bundle and ledger row.
+ *
+ * Deliberately does NOT delete the extension's state under EXTENSION_STATE_DIR.
+ * Uninstall-then-reinstall is a normal troubleshooting move, and silently
+ * destroying saved data as a side effect of it would be hostile. Orphaned state is
+ * a few KB of JSON; lost state is the user's data.
+ */
+export async function removeExtension(id: string): Promise<void> {
+  // VALIDATE BEFORE THE RECURSIVE DELETE. `id` arrives from IPC, and this is a
+  // `rm(..., { recursive: true })` — a value like `../../something` would escape
+  // EXTENSIONS_DIR entirely and delete an unrelated tree. Every other path-handling
+  // site in this subsystem validates; this one did not, which is the whole reason the
+  // shared validator now exists rather than a fifth copy of the regex.
+  if (!isValidExtensionId(id)) throw new Error(`invalid extension id: ${id}`)
+
+  // Under the lock as ONE unit, with the ledger row dropped BEFORE the bundle. An
+  // interruption between the two then leaves a bundle with no row — which the
+  // startup sweep reclaims — rather than a row with no bundle, which the user sees
+  // as a broken "files missing" entry they have to fix by hand.
+  await withLedgerLock(async () => {
+    await writeLedger((await readLedger()).filter(row => row.manifest.id !== id))
+    await rm(join(EXTENSIONS_DIR, id), { recursive: true, force: true })
+  })
+}
diff --git a/src/main/extensions/manifest.test.ts b/src/main/extensions/manifest.test.ts
new file mode 100644
index 000000000..15cc52ae7
--- /dev/null
+++ b/src/main/extensions/manifest.test.ts
@@ -0,0 +1,167 @@
+import { describe, expect, it } from 'vitest'
+
+import { EXTENSION_CAPABILITIES } from '@shared/types/extensions.js'
+import {
+  ManifestError,
+  SUPPORTED_API_VERSION,
+  apiVersionMismatch,
+  parseExtensionManifest,
+} from '@main/extensions/manifest.js'
+
+// The manifest is the least-trusted input in the application: JSON from a
+// repository whose name a user pasted, which then decides a directory name, a
+// module URL the renderer executes, a set of global command ids, and a
+// permission prompt. Everything here protects a rule that, if it stopped
+// holding, would be invisible until something hostile or badly-built arrived.
+
+function manifest(overrides: Record<string, unknown> = {}): string {
+  return JSON.stringify({
+    id: 'timer',
+    name: 'Timer',
+    description: 'A focus timer.',
+    version: '0.1.0',
+    apiVersion: SUPPORTED_API_VERSION,
+    entry: 'dist/index.js',
+    ...overrides,
+  })
+}
+
+describe('parseExtensionManifest — path safety of `entry`', () => {
+  // `entry` is joined onto the bundle directory and then loaded AS CODE over a
+  // scheme the renderer is allowed to execute from. Each of these shapes turns
+  // that field into arbitrary-file access if the refinement is lost.
+  it.each([
+    ['absolute', '/etc/passwd.js'],
+    ['parent traversal', '../../../etc/passwd.js'],
+    ['traversal mid-path', 'dist/../../secrets.js'],
+    ['backslash separator', 'dist\\index.js'],
+    ['not a module', 'dist/index.txt'],
+  ])('rejects an %s entry', (_label, entry) => {
+    expect(() => parseExtensionManifest(manifest({ entry }))).toThrow(ManifestError)
+  })
+
+  it('accepts an ordinary nested module path', () => {
+    expect(parseExtensionManifest(manifest({ entry: 'dist/index.js' })).entry).toBe('dist/index.js')
+  })
+})
+
+describe('parseExtensionManifest — id grammar', () => {
+  // The id becomes a directory name under EXTENSIONS_DIR, the storage namespace,
+  // and the HOST of the extension's own origin. A value that escapes any of
+  // those is a path-traversal primitive.
+  it.each([
+    ['traversal', '../evil'],
+    ['slash', 'a/b'],
+    ['leading digit', '1timer'],
+    ['uppercase', 'Timer'],
+    ['empty', ''],
+    ['too long', 'a'.repeat(65)],
+  ])('rejects a %s id', (_label, id) => {
+    expect(() => parseExtensionManifest(manifest({ id }))).toThrow(ManifestError)
+  })
+})
+
+describe('parseExtensionManifest — contribution namespacing', () => {
+  it('rejects a command id outside the extension namespace', () => {
+    // Contributed ids land in one registry beside ~95 first-party commands.
+    // `session.kill` from a third party would collide with a real command and
+    // resolve arbitrarily; install is the last moment a user can act on it.
+    expect(() =>
+      parseExtensionManifest(
+        manifest({ contributes: { commands: [{ id: 'session.kill', title: 'Kill' }] } }),
+      ),
+    ).toThrow(/must start with "timer\."/)
+  })
+
+  it('rejects a keybinding pointing at a command it does not contribute', () => {
+    expect(() =>
+      parseExtensionManifest(
+        manifest({
+          contributes: {
+            commands: [{ id: 'timer.start', title: 'Start' }],
+            keybindings: [{ command: 'timer.nope', key: 'cmd+t' }],
+          },
+        }),
+      ),
+    ).toThrow(/does not contribute/)
+  })
+
+  it('rejects an activation event naming a contribution that does not exist', () => {
+    // A dead activation event is the hardest authoring mistake to diagnose: the
+    // extension simply never activates, with no error anywhere.
+    expect(() =>
+      parseExtensionManifest(
+        manifest({
+          activationEvents: ['onCommand:timer.ghost'],
+          contributes: { commands: [{ id: 'timer.start', title: 'Start' }] },
+        }),
+      ),
+    ).toThrow(/does not contribute/)
+  })
+
+  it('rejects duplicate ids within one manifest', () => {
+    expect(() =>
+      parseExtensionManifest(
+        manifest({
+          contributes: {
+            commands: [
+              { id: 'timer.start', title: 'Start' },
+              { id: 'timer.start', title: 'Start again' },
+            ],
+          },
+        }),
+      ),
+    ).toThrow(/duplicate command id/)
+  })
+})
+
+describe('parseExtensionManifest — capabilities', () => {
+  it('accepts every capability the host actually implements', () => {
+    const parsed = parseExtensionManifest(manifest({ permissions: [...EXTENSION_CAPABILITIES] }))
+    expect(parsed.permissions).toEqual([...EXTENSION_CAPABILITIES])
+  })
+
+  // ── THE REGRESSION THIS BLOCK EXISTS FOR ──
+  // The schema used to accept seven Tier 2/3 names that nothing implemented:
+  // there was no frameProtocol request member, no frameHost arm, no API surface.
+  // A manifest could ask for filesystem write and git commit, the user got a
+  // blocking OS warning dialog naming those powers, approved it, and a permanent
+  // grant was written for capabilities that did nothing. Refusing the install is
+  // the honest outcome — it tells the author their extension needs a newer host
+  // instead of silently granting them nothing.
+  it.each(['fs.read', 'fs.write', 'git.read', 'git.commit', 'transcript.read', 'sessions.prompt', 'network.fetch'])(
+    'refuses to install a manifest requesting the unimplemented capability %s',
+    capability => {
+      expect(() => parseExtensionManifest(manifest({ permissions: [capability] }))).toThrow(
+        ManifestError,
+      )
+    },
+  )
+
+  it('names the accepted set in the failure message rather than reading as a typo report', () => {
+    expect(() => parseExtensionManifest(manifest({ permissions: ['fs.write'] }))).toThrow(
+      /not available yet/,
+    )
+  })
+})
+
+describe('apiVersionMismatch', () => {
+  // Extracted from parseExtensionManifest precisely so the ledger can apply it on
+  // every read. Version skew arrives by UPGRADING AGENT CODE, which involves no
+  // install, so an install-time-only check can never observe it.
+  it('passes the supported version', () => {
+    expect(apiVersionMismatch(SUPPORTED_API_VERSION)).toBeNull()
+  })
+
+  it('reports both versions so the message says who is out of date', () => {
+    const message = apiVersionMismatch(SUPPORTED_API_VERSION + 1)
+    expect(message).toContain(`v${SUPPORTED_API_VERSION + 1}`)
+    expect(message).toContain(`v${SUPPORTED_API_VERSION}`)
+  })
+
+  it('rejects an older major too, not only a newer one', () => {
+    // A downgrade is just as much a contract mismatch: the host would hand a v1
+    // object to code written against v0's shape.
+    expect(apiVersionMismatch(SUPPORTED_API_VERSION - 1)).not.toBeNull()
+  })
+})
diff --git a/src/main/extensions/manifest.ts b/src/main/extensions/manifest.ts
new file mode 100644
index 000000000..234864945
--- /dev/null
+++ b/src/main/extensions/manifest.ts
@@ -0,0 +1,307 @@
+import { z } from 'zod'
+
+import { EXTENSION_CAPABILITIES } from '@shared/types/extensions.js'
+import type {
+  ExtensionActivationEvent,
+  ExtensionManifest,
+} from '@shared/types/extensions.js'
+
+// Manifest validation.
+//
+// WHY zod and not hand-written checks: this JSON comes from a repository the user
+// pasted a name for. It is the least trusted input in the app. The remote protocol
+// (main/remote/protocol/messages.ts) already established the principle here — the
+// schema IS the allow-list, and anything not expressible in it is unrepresentable
+// rather than denied later. Same reasoning, same library, already a dependency.
+
+/** The one AgentCodeApi major this host implements. */
+export const SUPPORTED_API_VERSION = 1
+
+// Duplicated from main/extensions/storage.ts on purpose, with the duplication
+// called out in both places: storage owns the rule because there the id becomes a
+// filesystem path, and this schema owns it because here is where a hostile manifest
+// first arrives. A single shared const would be tidier but would let a future edit
+// to one call site silently relax the other's guarantee.
+const EXTENSION_ID = z
+  .string()
+  .regex(/^[a-z][a-z0-9-]{0,63}$/, 'id must match /^[a-z][a-z0-9-]{0,63}$/')
+
+// WHY `entry` is this restrictive: it is joined onto the bundle directory and then
+// loaded as code. `../../../etc/passwd`, an absolute path, or a URL would each turn
+// a manifest field into arbitrary-file access. Rejecting the shape here means the
+// containment check in install.ts is a second line of defence rather than the only
+// one. Backslashes are rejected too — a Windows-style separator that survives to a
+// POSIX join is a normalization bug waiting to happen.
+const ENTRY_PATH = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine(value => !value.startsWith('/'), 'entry must be a relative path')
+  .refine(value => !value.includes('\\'), 'entry must use forward slashes')
+  .refine(
+    value => !value.split('/').some(segment => segment === '..'),
+    'entry must not contain ".." segments',
+  )
+  .refine(value => /\.m?js$/.test(value), 'entry must be a .js or .mjs module')
+
+// Contribution ids are `<extensionId>.<name>`, optionally with further dotted
+// segments (`timer.ui.accent`). The namespace half is checked against the
+// manifest's own id after parsing, where the id is available.
+//
+// WHY camelCase is allowed after the first dot while the extension id itself is
+// kebab-only: the extension id becomes a DIRECTORY NAME, so it is constrained by
+// the filesystem and by case-insensitive volumes. A contribution id is just a
+// registry key, and `timer.inheritTheme` is the idiomatic spelling everywhere
+// this convention exists. An earlier version of this regex demanded kebab-case
+// throughout and rejected the first real manifest written against it.
+const CONTRIBUTION_ID = z
+  .string()
+  .min(3)
+  .max(96)
+  .regex(
+    /^[a-z][a-zA-Z0-9-]*(\.[a-zA-Z][a-zA-Z0-9-]*)+$/,
+    'must look like "<extensionId>.<name>"',
+  )
+
+const commandContribution = z.object({
+  id: CONTRIBUTION_ID,
+  title: z.string().min(1).max(80),
+  description: z.string().max(400).optional(),
+  keywords: z.array(z.string().min(1).max(40)).max(24).optional(),
+})
+
+const viewContribution = z.object({
+  id: CONTRIBUTION_ID,
+  title: z.string().min(1).max(80),
+  // Closed union rather than a free string: the host owns the chrome, and an
+  // unknown mount kind must fail at install with a message rather than resolve
+  // to nothing at render time. 'panel'/'tab' get added here when their host
+  // shells exist.
+  mount: z.enum(['modal', 'panel']),
+})
+
+const settingContribution = z.discriminatedUnion('type', [
+  z.object({
+    id: CONTRIBUTION_ID,
+    title: z.string().min(1).max(80),
+    description: z.string().max(400).optional(),
+    type: z.literal('boolean'),
+    default: z.boolean(),
+  }),
+  z.object({
+    id: CONTRIBUTION_ID,
+    title: z.string().min(1).max(80),
+    description: z.string().max(400).optional(),
+    type: z.literal('number'),
+    // Finite only — a NaN default would be written straight into extension
+    // storage, where JSON.stringify turns it into null.
+    default: z.number().finite(),
+  }),
+  z.object({
+    id: CONTRIBUTION_ID,
+    title: z.string().min(1).max(80),
+    description: z.string().max(400).optional(),
+    type: z.literal('string'),
+    default: z.string().max(400),
+  }),
+])
+
+const keybindingContribution = z.object({
+  command: CONTRIBUTION_ID,
+  key: z.string().min(1).max(64),
+})
+
+// A closed capability set — like activationEvent, an unknown capability must fail
+// install with a message, not resolve to nothing. Kept in lockstep with
+// EXTENSION_CAPABILITIES in @shared/types/extensions (the schema wins on drift).
+//
+// ONLY IMPLEMENTED CAPABILITIES BELONG HERE. The Tier 2/3 names this enum used to
+// accept (fs.read, transcript.read, git.read, sessions.prompt, fs.write,
+// git.commit, network.fetch) had no request method, no broker arm and no API
+// surface — approving them granted nothing while showing the user a warning
+// dialog that said otherwise. See the ExtensionCapability doc comment for the
+// rule that replaced them.
+const capabilityName = z.enum(EXTENSION_CAPABILITIES, {
+  // zod's default enum message lists the accepted values, which reads as a typo
+  // report. An author who wrote `fs.write` did not make a typo — they wrote
+  // against a capability this build does not have — so the message says that,
+  // in the same shape as the apiVersion mismatch below.
+  message:
+    `unknown capability — this build implements only ${EXTENSION_CAPABILITIES.join(', ')}. ` +
+    `Filesystem, transcript, git, prompt and network capabilities are not available yet.`,
+})
+
+// `.refine` validates but does not narrow, so the parsed type would be `string`
+// and would not satisfy ExtensionActivationEvent. The transform is the narrowing
+// step, and it is safe precisely because the refine above already rejected
+// everything outside the union — if that predicate and this cast ever disagree,
+// the predicate is the bug.
+const activationEvent = z
+  .string()
+  .max(96)
+  .refine(
+    value =>
+      value === 'onStartupFinished' ||
+      value === '*' ||
+      value.startsWith('onCommand:') ||
+      value.startsWith('onView:'),
+    'unknown activation event',
+  )
+  .transform(value => value as ExtensionActivationEvent)
+
+export const extensionManifestSchema = z.object({
+  id: EXTENSION_ID,
+  name: z.string().min(1).max(80),
+  description: z.string().min(1).max(400),
+  version: z.string().min(1).max(40),
+  apiVersion: z.number().int().positive(),
+  entry: ENTRY_PATH,
+  keywords: z.array(z.string().min(1).max(40)).max(24).optional(),
+  activationEvents: z.array(activationEvent).max(32).optional(),
+  contributes: z
+    .object({
+      commands: z.array(commandContribution).max(64).optional(),
+      views: z.array(viewContribution).max(16).optional(),
+      settings: z.array(settingContribution).max(64).optional(),
+      keybindings: z.array(keybindingContribution).max(32).optional(),
+    })
+    .optional(),
+  permissions: z.array(capabilityName).max(16).optional(),
+})
+
+export class ManifestError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'ManifestError'
+  }
+}
+
+/**
+ * Parse and validate a manifest's raw text.
+ *
+ * Throws ManifestError with a message intended to be shown to the user — they are
+ * the one who chose the repository, so "this repo's manifest is missing `entry`" is
+ * actionable to them in a way a stack trace is not.
+ */
+export function parseExtensionManifest(raw: string): ExtensionManifest {
+  let json: unknown
+  try {
+    json = JSON.parse(raw)
+  } catch {
+    throw new ManifestError('agent-code.extension.json is not valid JSON')
+  }
+
+  const result = extensionManifestSchema.safeParse(json)
+  if (!result.success) {
+    const detail = result.error.issues
+      .map(issue => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+      .join('; ')
+    throw new ManifestError(`agent-code.extension.json is invalid — ${detail}`)
+  }
+
+  // Checked after shape validation rather than inside the schema so the user gets
+  // "needs API v2, this build has v1" instead of a generic field error. This is the
+  // only failure here that is not the author's mistake — it means Agent Code is out
+  // of date relative to the extension, and the message should say so.
+  const versionError = apiVersionMismatch(result.data.apiVersion)
+  if (versionError) throw new ManifestError(versionError)
+
+  assertContributionsAreCoherent(result.data)
+  return result.data
+}
+
+/**
+ * The API-version gate, as a REUSABLE check rather than a step inside install.
+ *
+ * ── WHY THIS IS NOT ONLY AN INSTALL-TIME CONCERN ──
+ * It used to live solely in parseExtensionManifest, so it ran when a bundle was
+ * installed and never again. The ledger is re-read on every launch and validates
+ * rows with `extensionManifestSchema` directly, which accepts any positive
+ * integer — so a row recorded under one host version kept loading forever under
+ * the next one. The whole point of versioning the ABI is to refuse to hand a
+ * newer host object to an extension written against an older contract, and a
+ * check that only fires at install cannot do that: the host is what changes,
+ * and it changes without any install happening.
+ *
+ * Returns the user-facing message, or null when the version is supported.
+ */
+export function apiVersionMismatch(apiVersion: number): string | null {
+  if (apiVersion === SUPPORTED_API_VERSION) return null
+  return `extension targets Agent Code API v${apiVersion}, this build implements v${SUPPORTED_API_VERSION}`
+}
+
+/**
+ * Cross-field checks the schema cannot express, because each needs the
+ * manifest's own `id` or a view of the whole `contributes` block.
+ */
+function assertContributionsAreCoherent(manifest: ExtensionManifest): void {
+  const prefix = `${manifest.id}.`
+  const commands = manifest.contributes?.commands ?? []
+  const views = manifest.contributes?.views ?? []
+  const settings = manifest.contributes?.settings ?? []
+  const keybindings = manifest.contributes?.keybindings ?? []
+
+  // WHY namespacing is ENFORCED and not merely conventional: contributed command
+  // ids land in one global registry beside ~95 first-party commands. An
+  // extension declaring `session.kill` would collide with a real one, and the
+  // resolution would be arbitrary. Install is the only moment where the user can
+  // still act on it, so it fails here rather than resolving oddly forever.
+  const namespaced = [...commands, ...views, ...settings]
+  for (const contribution of namespaced) {
+    if (!contribution.id.startsWith(prefix)) {
+      throw new ManifestError(
+        `contribution id "${contribution.id}" must start with "${prefix}" — ` +
+          `extensions may only contribute inside their own namespace`,
+      )
+    }
+  }
+
+  // Duplicates WITHIN one manifest are always an authoring mistake and are
+  // rejected. Duplicates ACROSS extensions are a different problem — they are
+  // resolved at load time (first wins, second reported) because neither author
+  // can see the other's manifest and failing the install would punish whoever
+  // happened to install second.
+  assertUnique(commands.map(c => c.id), 'command')
+  assertUnique(views.map(v => v.id), 'view')
+  assertUnique(settings.map(s => s.id), 'setting')
+
+  const commandIds = new Set(commands.map(command => command.id))
+  for (const binding of keybindings) {
+    if (!commandIds.has(binding.command)) {
+      throw new ManifestError(
+        `keybinding "${binding.key}" targets command "${binding.command}", ` +
+          `which this extension does not contribute`,
+      )
+    }
+  }
+
+  // An activation event naming a contribution that does not exist is silently
+  // dead — the extension would simply never activate, with no error anywhere.
+  // That is the single hardest authoring mistake to diagnose, so it is rejected.
+  const viewIds = new Set(views.map(view => view.id))
+  for (const event of manifest.activationEvents ?? []) {
+    if (event.startsWith('onCommand:')) {
+      const target = event.slice('onCommand:'.length)
+      if (!commandIds.has(target)) {
+        throw new ManifestError(
+          `activation event "${event}" names a command this extension does not contribute`,
+        )
+      }
+    } else if (event.startsWith('onView:')) {
+      const target = event.slice('onView:'.length)
+      if (!viewIds.has(target)) {
+        throw new ManifestError(
+          `activation event "${event}" names a view this extension does not contribute`,
+        )
+      }
+    }
+  }
+}
+
+function assertUnique(ids: string[], kind: string): void {
+  const seen = new Set<string>()
+  for (const id of ids) {
+    if (seen.has(id)) throw new ManifestError(`duplicate ${kind} id "${id}"`)
+    seen.add(id)
+  }
+}
diff --git a/src/main/extensions/scheme.ts b/src/main/extensions/scheme.ts
new file mode 100644
index 000000000..1b82ab248
--- /dev/null
+++ b/src/main/extensions/scheme.ts
@@ -0,0 +1,277 @@
+import { randomBytes } from 'crypto'
+import { net, protocol } from 'electron'
+import { realpath } from 'fs/promises'
+import { extname, join, resolve as resolvePath, sep } from 'path'
+import { pathToFileURL } from 'url'
+
+import { isValidExtensionId } from '@shared/types/extensionId.js'
+import { EXTENSIONS_DIR } from '@main/storage/paths.js'
+import { buildFrameDocument, childFrameCsp } from '@main/extensions/frameDocument.js'
+import { readLedger } from '@main/extensions/ledger.js'
+
+export const EXTENSION_SCHEME = 'agent-code-ext'
+
+// The reserved path that serves the sandbox frame HTML document rather than a
+// bundle asset. An extension cannot ship a file at this path — it collides with
+// nothing real because the `.` in a normal entry can never produce this exact
+// name, and even if it did, this branch is checked first and serves the host's
+// document, not the extension's file.
+const RESERVED_FRAME_PATH = '__agent-code-frame__.html'
+
+// Serving installed extension bundles to the renderer.
+//
+// WHY a custom scheme at all, rather than importing the file path directly:
+// the renderer's CSP is `script-src 'self'` and its document origin differs
+// between dev (http://localhost via ELECTRON_RENDERER_URL) and production
+// (file:// via loadFile). A raw filesystem path is blocked in dev by the
+// localhost origin and is a cross-origin file:// fetch in production — it
+// cannot be made to work identically in both, which is exactly the trap this
+// design exists to avoid. A registered scheme has ONE spelling that resolves
+// the same way in both modes, and adding it to script-src is a single, narrow,
+// auditable concession rather than relaxing the policy for everything.
+
+/**
+ * MUST be called at module scope, before `app.whenReady()`.
+ *
+ * Electron silently treats a scheme registered after ready as opaque — no
+ * origin semantics, no secure context, no CORS handling. The resulting failure
+ * surfaces in the renderer as a CSP or CORS error, which sends you looking at
+ * index.html instead of at call ordering. There is no runtime warning for it,
+ * so the ordering constraint lives here in a comment and in the call site.
+ *
+ * The privileges are each load-bearing:
+ *
+ *   standard        Gives the scheme real origin semantics, so a relative
+ *                   specifier inside a bundle (`./util.js` beside `index.js`)
+ *                   resolves. Without it every intra-extension import would
+ *                   have to be an absolute agent-code-ext:// URL, which no
+ *                   normal bundler emits.
+ *   secure          Module scripts and most web APIs require a secure context.
+ *                   Omitting this makes `import()` fail with an error that
+ *                   does not mention security.
+ *   supportFetchAPI Lets an extension fetch its own assets — JSON config, CSS,
+ *                   an SVG sprite — through the same origin it was loaded from.
+ *   corsEnabled     Module scripts are ALWAYS fetched in CORS mode, and
+ *                   `standard: true` makes this a distinct origin from the
+ *                   document. Without CORS handling every import fails.
+ *   stream          Lets the handler return a streaming body instead of
+ *                   buffering each asset in main.
+ */
+export function registerExtensionScheme(): void {
+  protocol.registerSchemesAsPrivileged([
+    {
+      scheme: EXTENSION_SCHEME,
+      privileges: {
+        standard: true,
+        secure: true,
+        supportFetchAPI: true,
+        corsEnabled: true,
+        stream: true,
+      },
+    },
+  ])
+}
+
+// Deliberately small and explicit rather than a mime lookup dependency. An
+// extension bundle is JS plus a handful of asset kinds; anything unrecognised
+// is served as a byte stream rather than guessed at, because a wrong
+// `text/javascript` on a non-module would be worse than an honest download.
+const CONTENT_TYPES: Record<string, string> = {
+  '.js': 'text/javascript',
+  '.mjs': 'text/javascript',
+  '.json': 'application/json',
+  '.css': 'text/css',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.map': 'application/json',
+}
+
+function contentTypeFor(path: string): string {
+  return CONTENT_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream'
+}
+
+/**
+ * Call after `app.whenReady()`, before the first window is created.
+ *
+ * URL shape: `agent-code-ext://<extensionId>/<path-inside-bundle>`
+ */
+/**
+ * CORS for a bundle asset: the extension's own origin, or nothing.
+ *
+ * Returning an empty object (rather than a wildcard) is deliberate — absence of the
+ * header is a closed door, and it keeps cross-extension reads from being a one-word
+ * regression away.
+ */
+function corsHeadersFor(origin: string | null, extensionId: string): Record<string, string> {
+  return origin && origin === `${EXTENSION_SCHEME}://${extensionId}`
+    ? { 'access-control-allow-origin': origin }
+    : {}
+}
+
+export function handleExtensionScheme(): void {
+  protocol.handle(EXTENSION_SCHEME, async request => {
+    let url: URL
+    try {
+      url = new URL(request.url)
+    } catch {
+      return new Response('bad request', { status: 400 })
+    }
+
+    // ── VALIDATE THE ID BEFORE IT IS USED AS A PATH SEGMENT ──
+    // `url.hostname` is attacker-chosen. It is joined onto EXTENSIONS_DIR below, and
+    // the containment check further down resolves against a root DERIVED FROM THIS
+    // VALUE — so if the id escapes, the check certifies the wrong root and approves
+    // everything beneath it. A request for `agent-code-ext://../extension-grants.json`
+    // yielded hostname `..`, rooting the handler at the whole state directory: grants,
+    // the ledger, workspace.json, and the proxy dumps that contain provider
+    // Authorization headers. Reachable from a Tier-0 extension that triggered no
+    // consent dialog, since `connect-src agent-code-ext:` permits the request.
+    //
+    // This must be the FIRST thing the handler does. The shared validator is imported
+    // rather than re-written: this file having no copy of the pattern, while four other
+    // files had one, is precisely how the gap happened.
+    const extensionId = url.hostname
+    if (!isValidExtensionId(extensionId)) return new Response('not found', { status: 404 })
+
+    // decodeURIComponent BEFORE the containment check, never after. A check
+    // performed on the encoded form would pass `..%2f..%2f.ssh` — the segments
+    // only look like traversal once decoded, and decoding afterwards would
+    // reintroduce exactly what the check was meant to stop.
+    let relative: string
+    try {
+      relative = decodeURIComponent(url.pathname).replace(/^\/+/, '')
+    } catch {
+      return new Response('bad request', { status: 400 })
+    }
+
+    // The sandbox frame document. Served BEFORE any file resolution, because it
+    // is not a bundle file — it is the host's own locked-down HTML shell that
+    // frames the extension. It embeds the extension's validated `entry` and a
+    // per-load nonce, and carries a far stricter CSP than the host document.
+    if (relative === RESERVED_FRAME_PATH) {
+      const viewId = url.searchParams.get('view')
+      if (!viewId) return new Response('bad request', { status: 400 })
+
+      const record = (await readLedger()).find(row => row.manifest.id === extensionId)
+      // A frame for an extension not in the ledger is a stale/removed reference;
+      // 404 like a missing bundle rather than serving an empty shell.
+      if (!record) return new Response('not found', { status: 404 })
+
+      // The view id must be one this extension actually declares. It was previously
+      // taken from the query string verbatim and interpolated into the frame document,
+      // where it is an injection sink — and a persisted SessionMeta.extensionViewId is
+      // attacker-influenced on the rehydrate path. Checking it against the manifest we
+      // already hold costs one `.some()` and removes the sink's most reachable source.
+      const declaresView = (record.manifest.contributes?.views ?? []).some(v => v.id === viewId)
+      if (!declaresView) return new Response('bad request', { status: 400 })
+
+      const nonce = randomBytes(16).toString('base64')
+      const html = buildFrameDocument({
+        extensionId,
+        viewId,
+        entry: record.manifest.entry,
+        // From the manifest this handler already validated, so the frame can
+        // enforce the declared-contributions contract without asking anyone.
+        declaredCommands: (record.manifest.contributes?.commands ?? []).map(c => c.id),
+        declaredViews: (record.manifest.contributes?.views ?? []).map(v => v.id),
+        nonce,
+      })
+      return new Response(html, {
+        status: 200,
+        headers: {
+          'content-type': 'text/html; charset=utf-8',
+          // Both the meta tag inside the document AND this header carry the CSP,
+          // with the same nonce. The header cannot be undone by a document.write,
+          // so it is the authoritative copy.
+          'content-security-policy': childFrameCsp(nonce, extensionId),
+          'cache-control': 'no-cache',
+        },
+      })
+    }
+
+    // The id in the URL is a NAME, not authority — the same invariant
+    // EditorFsRootRegistry enforces for filesystem roots. It names a candidate
+    // directory; whether that directory is legitimate is decided by resolving
+    // it against the install root and proving the result stayed inside.
+    const root = join(EXTENSIONS_DIR, extensionId)
+
+    let rootReal: string
+    try {
+      rootReal = await realpath(root)
+    } catch {
+      // Not installed, or the bundle directory was removed by hand. 404 rather
+      // than 403: nothing was forbidden, there is simply nothing there.
+      return new Response('not found', { status: 404 })
+    }
+
+    let targetReal: string
+    try {
+      targetReal = await realpath(resolvePath(rootReal, relative))
+    } catch {
+      return new Response('not found', { status: 404 })
+    }
+
+    // The containment check. This is the single most important line in the file.
+    //
+    // Install-time validation already proves the MANIFEST's entry stays inside
+    // the bundle, but this handler serves arbitrary paths on demand, so it needs
+    // its own check — and it must be realpath-based, because a symlink committed
+    // to the repository survives extraction and points wherever it likes.
+    // Without this, `agent-code-ext://x/../../../.ssh/id_rsa` reads an arbitrary
+    // file through an origin the renderer is permitted to load SCRIPTS from,
+    // which is the worst available combination in this app.
+    //
+    // The `+ sep` matters: a bare startsWith(rootReal) would accept a sibling
+    // directory whose name merely shares the prefix (`extensions/timer-evil`
+    // passes a startsWith check against `extensions/timer`).
+    if (targetReal !== rootReal && !targetReal.startsWith(rootReal + sep)) {
+      return new Response('forbidden', { status: 403 })
+    }
+
+    let fileResponse: Response
+    try {
+      fileResponse = await net.fetch(pathToFileURL(targetReal).toString())
+    } catch {
+      return new Response('not found', { status: 404 })
+    }
+    if (!fileResponse.ok || !fileResponse.body) {
+      return new Response('not found', { status: 404 })
+    }
+
+    return new Response(fileResponse.body, {
+      status: 200,
+      headers: {
+        'content-type': contentTypeFor(targetReal),
+        // Required, and the single most likely thing to cost a day if omitted.
+        // Module scripts are fetched in CORS mode, and `standard: true` makes
+        // this a distinct origin from the document — so without an explicit
+        // allow-origin header every `import()` fails with an opaque CORS error
+        // that says nothing about the actual cause.
+        //
+        // ── NOT `*` ──
+        // The old value was justified as "there is no ambient authority to leak: this
+        // origin serves extension bundle files and nothing else". That is true of the
+        // HOST, and false of a sibling EXTENSION: with `*`, extension A could
+        // `fetch('agent-code-ext://b/index.js')` and read extension B's entire bundle.
+        // Combined with the scheme-wide CSP source it also let A execute B's code.
+        //
+        // Echo the request Origin only when it is this extension's own origin. Any other
+        // origin gets no CORS header at all, so the read fails closed. The host document
+        // itself never fetches bundle assets — it only frames them — so it needs nothing
+        // here.
+        ...corsHeadersFor(request.headers.get('origin'), extensionId),
+        // Bundles are replaced wholesale on update, and a stale cached module
+        // after an update is a confusing, hard-to-diagnose bug class. Extensions
+        // are local files; there is nothing to gain by caching them.
+        'cache-control': 'no-cache',
+      },
+    })
+  })
+}
diff --git a/src/main/extensions/storage.ts b/src/main/extensions/storage.ts
new file mode 100644
index 000000000..e210f427b
--- /dev/null
+++ b/src/main/extensions/storage.ts
@@ -0,0 +1,177 @@
+import { mkdir, readFile, rename, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { EXTENSION_STATE_DIR } from '@main/storage/paths.js'
+
+// Per-app JSON state, main-owned.
+//
+// One file per app (`extensions/<id>/state.json`) rather than one shared file
+// keyed by app id: uninstalling an app becomes `rm -rf` of one directory, a
+// corrupt write can only lose one app's data, and two apps writing concurrently
+// never contend for the same file.
+
+// WHY ids are validated and rejected rather than sanitized: an app id becomes a
+// directory name, so a permissive id is a path-traversal primitive. Sanitizing —
+// stripping or replacing bad characters — silently collapses distinct ids onto the
+// same directory: `../timer` and `timer` would share state, and `a/b` and `a-b`
+// would too. Rejecting is the only handling where the failure is visible to whoever
+// caused it. The pattern is duplicated in the renderer's AppDefinition doc comment;
+// if it changes, change both.
+const APP_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/
+
+export class InvalidAppIdError extends Error {
+  constructor(appId: unknown) {
+    super(
+      `invalid extension app id ${JSON.stringify(appId)} — must match ${String(APP_ID_PATTERN)}`,
+    )
+    this.name = 'InvalidAppIdError'
+  }
+}
+
+function appDirFor(appId: string): string {
+  if (typeof appId !== 'string' || !APP_ID_PATTERN.test(appId)) throw new InvalidAppIdError(appId)
+  return join(EXTENSION_STATE_DIR, appId)
+}
+
+function stateFileFor(appId: string): string {
+  return join(appDirFor(appId), 'state.json')
+}
+
+async function readAll(appId: string): Promise<Record<string, unknown>> {
+  const file = stateFileFor(appId)
+  let raw: string
+  try {
+    raw = await readFile(file, 'utf8')
+  } catch {
+    // Missing file is the normal first-run case, not an error.
+    return {}
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    // A corrupt or non-object file degrades to empty rather than throwing. An app
+    // losing saved state is recoverable and visible; an app that throws on every
+    // read can never start again, and the user has no way to clear it from the UI.
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return {}
+    return parsed as Record<string, unknown>
+  } catch {
+    return {}
+  }
+}
+
+async function writeAll(appId: string, data: Record<string, unknown>): Promise<void> {
+  const dir = appDirFor(appId)
+  await mkdir(dir, { recursive: true })
+  const file = join(dir, 'state.json')
+  // temp+rename, matching workspace.json's discipline: rename is atomic within a
+  // filesystem, so a crash mid-write leaves either the old file or the new one —
+  // never a half-written one that then fails to parse forever. The temp file lives
+  // in the same directory precisely so the rename cannot cross a device boundary.
+  //
+  // The temp name is UNIQUE per write. An earlier version used a fixed
+  // `${file}.tmp`, which review reproduced as a hard failure 3/3: two concurrent
+  // writers both create the same temp path, the first rename consumes it, and the
+  // second rename fails ENOENT — losing one write AND rejecting. Uniqueness alone
+  // still permits a lost update (both read the old state), which is why every write
+  // for an app also goes through the serialization queue below.
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}-${writeCounter++}`
+  await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, 'utf8')
+  await rename(tmp, file)
+}
+
+let writeCounter = 0
+
+// One promise chain per app id, so read-modify-write cycles for the same app never
+// interleave.
+//
+// WHY this is necessary and not paranoia: the ABI makes every storage method
+// async, which invites exactly the fire-and-forget shape that breaks a naive
+// implementation — `void api.storage.set('a', 1); void api.storage.set('b', 2)` from
+// one click handler. Without serialization both calls read the same original state
+// and the second write erases the first key. Chaining makes that sequence correct
+// without the extension author having to know it needed awaiting.
+//
+// WHY a Map keyed by app rather than one global chain: two different extensions
+// write to different files and have no reason to block each other. The map grows by
+// one small entry per app that ever writes, bounded by the number of installed
+// extensions.
+const writeQueues = new Map<string, Promise<void>>()
+
+function enqueueWrite(appId: string, mutate: () => Promise<void>): Promise<void> {
+  // Validate BEFORE joining the queue so a bad id rejects immediately instead of
+  // waiting behind unrelated work — and so an invalid id never creates a queue entry.
+  appDirFor(appId)
+
+  const previous = writeQueues.get(appId) ?? Promise.resolve()
+  // `.catch(() => {})` on the tail: one failed write must not poison every
+  // subsequent write for that app. The failure still propagates to ITS caller
+  // through the returned promise; this only stops it propagating to the next one.
+  const next = previous.catch(() => {}).then(mutate)
+  writeQueues.set(
+    appId,
+    next.catch(() => {}),
+  )
+  return next
+}
+
+export async function extensionStorageGet(appId: string, key: string): Promise<unknown> {
+  return (await readAll(appId))[key]
+}
+
+export class NonSerializableValueError extends Error {
+  constructor(detail: string) {
+    super(`extension storage value is not JSON-serializable: ${detail}`)
+    this.name = 'NonSerializableValueError'
+  }
+}
+
+// WHY non-finite numbers are rejected rather than stored: the ABI types values
+// as JsonValue, whose `number` member is unrestricted, so TypeScript happily
+// accepts NaN and ±Infinity — but JSON.stringify turns all three into `null`.
+// An extension writing NaN and reading back null is a silent data corruption
+// with no error anywhere, and the author has no way to discover it except by
+// noticing wrong behaviour much later. Rejecting at the boundary converts a
+// silent corruption into an immediate, attributable failure.
+//
+// Checked here rather than in the renderer because this is the last point where
+// the value is still structured; after JSON.stringify the information is gone.
+function assertSerializable(value: unknown, path = 'value'): void {
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new NonSerializableValueError(`${path} is ${String(value)}`)
+    }
+    return
+  }
+  if (value === null || typeof value !== 'object') return
+  if (Array.isArray(value)) {
+    value.forEach((entry, index) => assertSerializable(entry, `${path}[${index}]`))
+    return
+  }
+  for (const [key, entry] of Object.entries(value)) {
+    assertSerializable(entry, `${path}.${key}`)
+  }
+}
+
+export async function extensionStorageSet(
+  appId: string,
+  key: string,
+  value: unknown,
+): Promise<void> {
+  assertSerializable(value)
+  return enqueueWrite(appId, async () => {
+    const data = await readAll(appId)
+    data[key] = value
+    await writeAll(appId, data)
+  })
+}
+
+export async function extensionStorageDelete(appId: string, key: string): Promise<void> {
+  return enqueueWrite(appId, async () => {
+    const data = await readAll(appId)
+    delete data[key]
+    await writeAll(appId, data)
+  })
+}
+
+export async function extensionStorageKeys(appId: string): Promise<string[]> {
+  return Object.keys(await readAll(appId))
+}
diff --git a/src/main/index.ts b/src/main/index.ts
index eb56d9f10..1eaebaf2a 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -26,6 +26,11 @@ import { TmuxRegistry } from '@main/tmux/TmuxRegistry.js'
 import { reconcile } from '@main/tmux/tmuxRecovery.js'
 import type { PersistedTerminalRef } from '@main/tmux/tmuxRecovery.js'
 
+import {
+  handleExtensionScheme,
+  registerExtensionScheme,
+} from '@main/extensions/scheme.js'
+import { sweepAbandonedInstallDirectories } from '@main/extensions/install.js'
 import { STATE_DIR, STATE_FILE } from '@main/storage/paths.js'
 import {
   scheduleDebugStoragePrune,
@@ -217,6 +222,15 @@ async function runPackagingSmoke(): Promise<void> {
 // shared. If that lock ever feels too strict, the storage model must be changed
 // first; deleting the guard alone would make last-writer-wins corruption
 // possible again.
+// MUST run at module scope, before any app.whenReady() handler. Electron silently
+// treats a scheme registered after ready as opaque — no origin semantics, no secure
+// context, no CORS — and the failure then surfaces in the renderer as a CSP or CORS
+// error, which sends you looking at index.html instead of at call ordering. There is
+// no runtime warning for getting this wrong. Verified working from a file:// document
+// (the production origin) by the B1 spike: dynamic import, relative specifiers, and
+// path-traversal rejection all behave.
+registerExtensionScheme()
+
 const hasSingleInstanceLock = packagingSmoke || app.requestSingleInstanceLock()
 
 if (packagingSmoke) {
@@ -447,6 +461,20 @@ async function startApp(): Promise<void> {
     appRunJournal.recordError('prior_run.classify.error', err)
   }
 
+  // Install the agent-code-ext:// handler before any window exists. The renderer
+  // imports extension modules over this scheme during startup, so a window that
+  // opened first could race a request against an unregistered handler and see a
+  // spurious load failure that never reproduces on a warm run.
+  handleExtensionScheme()
+
+  // Reclaim staging and replaced-bundle directories abandoned by an install that
+  // was interrupted by a crash or a force-quit. Startup is the only moment at which
+  // no install can be in flight, so anything matching those shapes is definitionally
+  // dead. Fire-and-forget: housekeeping must never delay or block launch.
+  void sweepAbandonedInstallDirectories().catch(err => {
+    console.warn('[extensions] staging sweep failed:', err)
+  })
+
   void performanceService.start().catch(err => {
     console.warn('[performance] failed to start:', err)
     appRunJournal?.recordError('performance.start.error', err)
diff --git a/src/main/ipc/extensions.ts b/src/main/ipc/extensions.ts
new file mode 100644
index 000000000..8ba569be9
--- /dev/null
+++ b/src/main/ipc/extensions.ts
@@ -0,0 +1,267 @@
+import { join } from 'path'
+
+import { BrowserWindow, dialog, ipcMain } from 'electron'
+import type { IpcMainInvokeEvent } from 'electron'
+
+import {
+  extensionStorageDelete,
+  extensionStorageGet,
+  extensionStorageKeys,
+  extensionStorageSet,
+} from '@main/extensions/storage.js'
+import { installExtension, installExtensionFromPath } from '@main/extensions/install.js'
+import type { ConsentPrompt } from '@main/extensions/install.js'
+import { listInstalledExtensions, removeExtension } from '@main/extensions/ledger.js'
+import { grantedCapabilities, revokeGrant } from '@main/extensions/grants.js'
+import { computeBundleHash } from '@main/extensions/bundleHash.js'
+import { EXTENSIONS_DIR } from '@main/storage/paths.js'
+import { isValidExtensionId } from '@shared/types/extensionId.js'
+import type {
+  ExtensionCapability,
+  ExtensionInstallResult,
+  ExtensionListEntry,
+} from '@shared/types/extensions.js'
+
+// The capability-consent dialog, shared by both install paths (GitHub + local
+// folder). A blocking, OS-native dialog on purpose: granting an extension
+// filesystem or session access is exactly the moment that must not be a quiet
+// in-page toggle. Tier-0-only extensions never reach it (installers only call it
+// when permissions is non-empty).
+/**
+ * What each capability actually discloses, in the user's terms.
+ *
+ * ── WHY THE RAW ENUM NAME IS NOT ENOUGH ──
+ * The dialog used to render `  • sessions.observe` and nothing else. That gives a
+ * user no way to know it discloses the ABSOLUTE WORKING DIRECTORY of every open
+ * session — which for a working developer enumerates client names, private
+ * repository names, and employer directory layout. A consent prompt that names a
+ * permission without describing it is a prompt that can only be answered by
+ * trusting the author, which is the decision it is supposed to inform.
+ *
+ * Keyed by the capability union, so a new capability does not compile until its
+ * disclosure is written. That is deliberate: the description is part of shipping
+ * the capability, not a follow-up.
+ */
+const CAPABILITY_DISCLOSURE: Record<ExtensionCapability, string> = {
+  'workspace.observe': 'Which tabs are open, and how many sessions exist.',
+  'sessions.observe':
+    'Every open session: its title, its provider, and the full folder path it is running in.',
+  'panes.observe': 'How your panes are arranged, and which session is in each one.',
+}
+
+function consentPromptFor(evt: IpcMainInvokeEvent, source: string): ConsentPrompt {
+  return async manifest => {
+    const win = BrowserWindow.fromWebContents(evt.sender)
+    const permissions = manifest.permissions ?? []
+    const detail = permissions.map(cap => `  • ${CAPABILITY_DISCLOSURE[cap]}`).join('\n')
+
+    const options = {
+      // 'question', not 'warning'. Every remaining capability is a read-only
+      // metadata snapshot; the ones that ACTED were removed because nothing
+      // implemented them. A warning triangle over three read permissions trains
+      // click-through exactly as reliably as saying too little does, and the next
+      // capability that genuinely deserves alarm would inherit a numb user.
+      type: 'question' as const,
+      buttons: ['Cancel', 'Grant & install'],
+      // Both point at Cancel: Return, Escape and closing the window all decline.
+      defaultId: 0,
+      cancelId: 0,
+      title: 'Extension permissions',
+      // `source` is what the USER typed — the repo name or the folder they picked —
+      // and AppsSettingsRow's own header calls it "the trust decision". It was the
+      // one thing the dialog did not show. `manifest.name` is attacker-chosen and
+      // only length-bounded, so it is presented as a claim about an identity
+      // (`id`), never as the identity itself.
+      message: `Install ${manifest.id} from ${source}?`,
+      detail:
+        `"${manifest.name}" wants to read:\n\n${detail}\n\n` +
+        `It cannot change anything, and it has no network access. ` +
+        `Install it only if you trust ${source}.`,
+    }
+    const result = win
+      ? await dialog.showMessageBox(win, options)
+      : await dialog.showMessageBox(options)
+    return result.response === 1
+  }
+}
+
+// IPC for extension-app state.
+//
+// WHY appId is a caller-supplied parameter rather than derived from the sender:
+// NOT because identity is unavailable, but because the sender is never the
+// extension. An extension frame is cross-origin with no preload and therefore no
+// `ipcRenderer` at all — it cannot call this or any other handler. Every caller
+// here is the trusted host renderer's main frame, brokering on the extension's
+// behalf, so `event.senderFrame` would identify the BROKER, not the extension, and
+// binding to it would achieve nothing.
+//
+// (An earlier version of this comment said the opposite: that every app shared one
+// WebContents and that a future "Stage 2" giving each extension its own frame would
+// make sender binding possible. That stage shipped — the frames exist — and the
+// conclusion inverted rather than resolved. A maintainer acting on the old text
+// would implement senderFrame binding, find it identifies the host, and either
+// break every extension's storage or conclude that Tier 1-3 handlers are now safe
+// here. They are not; see below.)
+//
+// The authority boundary is real, and it lives in two places that actually enforce
+// it: `createAppHostApi` closes over one extensionId and is the sole call site of
+// `window.api.extensionStorage*`, and `frameHost` refuses any message whose
+// `event.source` is not that iframe's contentWindow and whose browser-stamped
+// `event.origin` is not `agent-code-ext://<id>`.
+//
+// The prohibition stands unchanged: do NOT add workspace, session, transcript,
+// git, filesystem or network capabilities to this module. Those must route through
+// frameHost, where the origin check is — adding one here would be a real privilege
+// escalation wearing a namespace's clothes.
+export function registerExtensionsIpc(): void {
+  ipcMain.handle('extensions:storage-get', async (_evt, appId: string, key: string) =>
+    extensionStorageGet(appId, key),
+  )
+
+  ipcMain.handle(
+    'extensions:storage-set',
+    async (_evt, appId: string, key: string, value: unknown) =>
+      extensionStorageSet(appId, key, value),
+  )
+
+  ipcMain.handle('extensions:storage-delete', async (_evt, appId: string, key: string) =>
+    extensionStorageDelete(appId, key),
+  )
+
+  ipcMain.handle('extensions:storage-keys', async (_evt, appId: string) =>
+    extensionStorageKeys(appId),
+  )
+
+  ipcMain.handle('extensions:list', async (): Promise<ExtensionListEntry[]> =>
+    listInstalledExtensions(),
+  )
+
+  // WHY install returns a result object instead of rejecting: every failure here is
+  // something the user can act on — wrong repo name, private repo, missing
+  // manifest, unsupported API version, archive too large. An IPC rejection reaches
+  // the renderer as `Error invoking remote method 'extensions:install': …` with the
+  // real message buried in a prefix, and the error class is lost across the bridge.
+  // Returning `{ ok: false, error }` keeps the actionable sentence intact and makes
+  // the Settings UI's job a render, not a parse.
+  ipcMain.handle(
+    'extensions:install',
+    async (evt, repo: string): Promise<ExtensionInstallResult> => {
+      try {
+        const record = await installExtension(repo, consentPromptFor(evt, repo.trim()))
+        return { ok: true, entry: { ...record, present: true } }
+      } catch (error) {
+        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+    },
+  )
+
+  // "Load unpacked" — install from a local folder chosen in a native picker, so an
+  // author iterating on an unpublished extension never has to cut a GitHub release.
+  // The picker runs in main (a directory chooser cannot be a renderer input), and
+  // the same consent + validation pipeline as GitHub install applies.
+  ipcMain.handle('extensions:install-path', async (evt): Promise<ExtensionInstallResult> => {
+    const win = BrowserWindow.fromWebContents(evt.sender)
+    const options = {
+      properties: ['openDirectory' as const],
+      title: 'Load extension from folder',
+      message: "Choose the extension's built folder (containing agent-code.extension.json)",
+    }
+    const picked = win
+      ? await dialog.showOpenDialog(win, options)
+      : await dialog.showOpenDialog(options)
+    const dir = picked.filePaths[0]
+    if (picked.canceled || !dir) return { ok: false, error: 'No folder selected.' }
+    try {
+      const record = await installExtensionFromPath(dir, consentPromptFor(evt, dir))
+      return { ok: true, entry: { ...record, present: true } }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  })
+
+  // Reinstall a LOCAL extension from the folder already recorded in its ledger row,
+  // with no directory picker.
+  //
+  // WHY this is not a security regression: the path is not caller-supplied. It is
+  // read from the ledger, where it was written by a native picker the user drove
+  // themselves — so this re-runs a choice already made, exactly as the GitHub
+  // Update button re-runs `owner/repo`. Making the renderer pass a path instead
+  // WOULD be a regression: it would turn "reinstall what you chose" into "install
+  // any directory on this machine, on the renderer's say-so".
+  //
+  // The full validation pipeline still runs: manifest parse, tree containment,
+  // entry containment, and — for any manifest requesting permissions — a consent
+  // prompt. That prompt is UNCONDITIONAL, not "only if the bytes changed":
+  // finalizeInstall gates on `permissions.length`, never on a hash comparison, so
+  // an author reloading an unchanged build is asked again. Deliberate, given the
+  // alternative is comparing against a grant the reload is about to replace.
+  ipcMain.handle('extensions:update-local', async (evt, id: string): Promise<ExtensionInstallResult> => {
+    if (!isValidExtensionId(id)) return { ok: false, error: 'Unknown extension.' }
+    const installed = await listInstalledExtensions()
+    const entry = installed.find(candidate => candidate.manifest.id === id)
+    if (!entry) return { ok: false, error: 'Extension is no longer installed.' }
+    if (entry.origin !== 'local') {
+      return { ok: false, error: 'This extension was installed from GitHub; use Update.' }
+    }
+    try {
+      const record = await installExtensionFromPath(entry.repo, consentPromptFor(evt, entry.repo))
+      return { ok: true, entry: { ...record, present: true } }
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) }
+    }
+  })
+
+  ipcMain.handle('extensions:remove', async (_evt, id: string): Promise<void> => {
+    // The grant is revoked in a `finally`, not after a successful remove.
+    //
+    // Sequenced the other way, a removeExtension that threw partway — a locked
+    // file, a permissions error, an interrupted write — left the bundle in an
+    // unknown state AND the grant fully intact. Revoking is the safe direction in
+    // every one of those outcomes: the worst case is that a still-installed
+    // extension has to be re-consented, and the alternative worst case is a
+    // half-removed extension retaining capabilities the user just tried to revoke.
+    try {
+      await removeExtension(id)
+    } finally {
+      await revokeGrant(id).catch(() => {})
+    }
+  })
+
+  // Reads WHICH capabilities the user consented to for an extension. This is NOT
+  // the Tier 1-3 escalation the module header forbids: it does not PERFORM any
+  // capability (each capability still executes through its own per-feature IPC) —
+  // it reports the grant so the frame broker (frameHost.perform) can GATE a
+  // capability call before allowing it.
+  //
+  // ── THE HASH IS RECOMPUTED FROM DISK, NOT READ FROM THE LEDGER ──
+  // This previously passed `entry.sha256`, the value the ledger recorded at
+  // install. The grant's hash was written by the same finalizeInstall() call, so
+  // the comparison inside grantedCapabilities compared two copies of one value
+  // and could never fail. The documented invariant — different bytes, no grant —
+  // did not exist, and editing a file under EXTENSIONS_DIR silently kept every
+  // capability the user had approved for the original code.
+  //
+  // Hashing the bundle here is what makes the check real. It costs one read of the
+  // bundle per frame creation — not one per capability call, because frameHost
+  // resolves this once and every consumer (including viewBridge's observe
+  // subscription) shares that one promise. The installer bounds the work on the
+  // other side: 32 MB compressed, 256 MB extracted, 10,000 files.
+  //
+  // Every failure path returns [] rather than throwing: an unreadable or missing
+  // bundle must mean "no capabilities", never "unchanged". Fail closed.
+  ipcMain.handle(
+    'extensions:granted-capabilities',
+    async (_evt, id: string): Promise<ExtensionCapability[]> => {
+      if (!isValidExtensionId(id)) return []
+      const installed = await listInstalledExtensions()
+      const entry = installed.find(candidate => candidate.manifest.id === id)
+      if (!entry) return []
+      try {
+        const actual = await computeBundleHash(join(EXTENSIONS_DIR, id))
+        return [...(await grantedCapabilities(id, actual))]
+      } catch {
+        return []
+      }
+    },
+  )
+}
diff --git a/src/main/ipc/index.ts b/src/main/ipc/index.ts
index cff094883..f7ab7f9db 100644
--- a/src/main/ipc/index.ts
+++ b/src/main/ipc/index.ts
@@ -47,6 +47,7 @@ import { registerWorkflowIpc } from '@main/ipc/workflows.js'
 import { registerAgentCodeConventionsIpc } from '@main/ipc/agentCodeConventions.js'
 import { registerAgentCodeCustomSkillsIpc } from '@main/ipc/agentCodeCustomSkills.js'
 import type { WorkflowBridge } from '@main/workflows/WorkflowBridge.js'
+import { registerExtensionsIpc } from '@main/ipc/extensions.js'
 
 // IPC registration aggregator.
 //
@@ -113,6 +114,10 @@ export function registerAllIpc(deps: IpcDeps): void {
   registerUsageIpc()
   registerCliUpdatesIpc(deps.cliUpdateOrchestrator)
   registerWorkflowIpc(deps.workflowBridge)
+  // Takes no deps on purpose: extension storage is a pure filesystem namespace
+  // under STATE_DIR with no app service behind it. The moment this needs a dep,
+  // it has stopped being storage and the Stage-2 sender-identity question applies.
+  registerExtensionsIpc()
   registerAgentCodeConventionsIpc(deps.agentCodeConventionsService)
   registerAgentCodeCustomSkillsIpc(deps.agentCodeConventionsService)
 }
diff --git a/src/main/remote/RemoteServer.ts b/src/main/remote/RemoteServer.ts
index 5a2f9c6f9..5f8873b98 100644
--- a/src/main/remote/RemoteServer.ts
+++ b/src/main/remote/RemoteServer.ts
@@ -12,6 +12,7 @@ import type { AppRunJournal } from '@main/incident/AppRunJournal.js'
 import type { ResolveConditionResult } from '@shared/sessionFeed/types.js'
 import type { ConditionCustomAction } from '@shared/conditions-core/contract.js'
 import type { SessionKind } from '@shared/types/providerKind.js'
+import { isAgentProviderKind } from '@shared/types/providerKind.js'
 import type { PromptDeliveryResult } from '@shared/types/providerConfig.js'
 import type { SessionBackendSnapshot } from '@shared/types/session.js'
 
@@ -662,7 +663,7 @@ export class RemoteServer extends EventEmitter {
           return { ok: false, error: 'no transcript on disk yet for this session' }
         }
         const kind = this.deps.manager.getSessionKind(msg.sessionId)
-        if (!kind || kind === 'terminal') {
+        if (!isAgentProviderKind(kind)) {
           return { ok: false, error: 'not an agent session' }
         }
         const chunk = msg.beforeMarker
diff --git a/src/main/sessionManager.ts b/src/main/sessionManager.ts
index 8ee976728..5a84d496b 100644
--- a/src/main/sessionManager.ts
+++ b/src/main/sessionManager.ts
@@ -45,6 +45,7 @@ import type {
 import {
   DEFAULT_PROVIDER,
   isAgentProviderKind,
+  isAgentSessionKind,
   isSessionKind,
 } from '@shared/types/providerKind.js'
 import type { AgentProviderKind, SessionKind } from '@shared/types/providerKind.js'
@@ -649,7 +650,7 @@ export class SessionManager extends EventEmitter {
     sessionId: string,
     kind: SessionKind,
     expectedEntry?: RegistryEntry,
-    revokeAgentMcp = kind !== 'terminal',
+    revokeAgentMcp = isAgentSessionKind(kind),
     expectedGeneration = expectedEntry?.lifecycle.generation,
   ): boolean {
     // WHY this helper exists even before the larger SessionState consolidation:
@@ -1253,6 +1254,18 @@ export class SessionManager extends EventEmitter {
         message: 'This Agent Code version does not support the requested provider.',
       })
     }
+    // Same fence as spawnWithId: an extension-view leaf is process-less and is
+    // excluded from the rehydrate live-process set (collectLiveProcessIds), so a
+    // recover for one should never be issued. If a stale renderer does, refuse
+    // rather than fall through and spawn a terminal shell for it.
+    if (requestedKind === 'extension-view') {
+      return Promise.resolve({
+        ok: false,
+        code: 'start-failed',
+        retryable: false,
+        message: 'extension-view panes have no process to recover.',
+      })
+    }
     const kind = options.kind ?? DEFAULT_PROVIDER
     const cwd = path.resolve(options.cwd)
     if (this.shuttingDown) {
@@ -2179,6 +2192,14 @@ export class SessionManager extends EventEmitter {
     if (requestedKind !== undefined && !isSessionKind(requestedKind)) {
       throw new Error('Unsupported session provider')
     }
+    // Extension-view "sessions" are renderer-only tile leaves with NO process; they
+    // are created directly in the workspace store (openExtensionViewInPane) and must
+    // never reach main. isSessionKind now accepts 'extension-view', so without this
+    // it would fall through to the terminal-spawn branch below and start a stray
+    // shell. A spawn request for one is a stale or hostile caller — refuse it.
+    if (requestedKind === 'extension-view') {
+      throw new Error('extension-view panes have no process and cannot be spawned')
+    }
     const kind: SessionKind = options.kind ?? DEFAULT_PROVIDER
     if (
       this.sessions.has(sessionId) ||
@@ -3384,7 +3405,7 @@ export class SessionManager extends EventEmitter {
         sessionId,
         recovery.kind,
         undefined,
-        recovery.kind !== 'terminal',
+        isAgentSessionKind(recovery.kind),
         generation,
       )
     }
@@ -3442,6 +3463,13 @@ export class SessionManager extends EventEmitter {
   ): Promise<boolean> {
     const requestedKind: unknown = options.kind
     if (requestedKind !== undefined && !isSessionKind(requestedKind)) return false
+    // The THIRD renderer→main path that can carry an extension-view kind, after
+    // spawnWithId and recover. Every close path in the renderer sends the pane's
+    // kind here, and this returned false for an extension pane already — but by
+    // accident of the ownership tables being empty for it, not by a decision.
+    // Stating it makes the boundary three-for-three and stops a future ownership
+    // change from turning "nothing to kill" into "kill something".
+    if (requestedKind === 'extension-view') return false
     const kind = options.kind ?? DEFAULT_PROVIDER
     const cwd = path.resolve(options.cwd)
     const entry = this.sessions.get(options.sessionId)
@@ -3547,7 +3575,7 @@ export class SessionManager extends EventEmitter {
         sessionId,
         claim.kind,
         undefined,
-        claim.kind !== 'terminal',
+        isAgentSessionKind(claim.kind),
         claim.spawnGeneration,
       )
     }
@@ -3724,7 +3752,7 @@ export class SessionManager extends EventEmitter {
     if (observed) return observed
     const info = this.spawnInfo.get(sessionId)
     const kind = this.getSessionKind(sessionId)
-    if (!info?.resumeSessionId || !kind || kind === 'terminal') return null
+    if (!info?.resumeSessionId || !isAgentProviderKind(kind)) return null
     try {
       return await resolveProviderTranscriptPath({
         kind,
diff --git a/src/main/storage/paths.ts b/src/main/storage/paths.ts
index ac64ecb17..654abc204 100644
--- a/src/main/storage/paths.ts
+++ b/src/main/storage/paths.ts
@@ -21,6 +21,38 @@ export const STATE_DIR = join(homedir(), '.config', APP_SLUG)
 // The renderer owns the JSON shape; main is a byte mover.
 export const STATE_FILE = join(STATE_DIR, 'workspace.json')
 
+// Installed extension bundles — one directory per extension id, each holding the
+// unpacked repository contents (manifest + built entry + assets).
+//
+// This is CODE, fetched from a remote repository. It is disposable in the sense
+// that reinstalling restores it, and it is the directory a future privileged
+// scheme serves from.
+export const EXTENSIONS_DIR = join(STATE_DIR, 'extensions')
+
+// The install ledger: which extensions are installed, from which repo and ref, at
+// which content hash. Separate from the bundles so a corrupt or half-extracted
+// bundle directory can never make the app forget what is supposed to be installed.
+export const EXTENSIONS_LOCKFILE = join(STATE_DIR, 'extensions.json')
+
+// Per-extension state, one JSON file per extension id.
+//
+// WHY this is a SIBLING of EXTENSIONS_DIR rather than living inside each bundle:
+// the bundle directory is replaced wholesale on install and update — extracting a
+// new version over it, or removing it first, would take the user's saved state with
+// it. Keeping state outside means an update never touches it and an uninstall can
+// choose whether to. It also means the scheme that serves extension code can be
+// pointed at EXTENSIONS_DIR without ever exposing state files over that origin.
+//
+// WHY main-owned rather than the renderer's zustand-persist blob: app-state/store.ts
+// records that adding a field without bumping the persist version black-screened
+// launch twice (#249). Extension state is authored outside the app's release cycle —
+// by definition nobody bumps a version for it — so it must not be able to reach that
+// failure mode at all.
+//
+// WHY deliberately NOT registered with debugRetention, unlike every debug root
+// below: those are disposable forensic caches with a disk budget, and this is *user
+// data*. A retention sweep would silently delete an extension's saved state.
+export const EXTENSION_STATE_DIR = join(STATE_DIR, 'extension-state')
 // Main-owned desired state and ownership journal for the optional personal
 // conventions skill. Provider copies are integration surfaces, never the source
 // of truth; keeping this beside workspace state gives recovery one stable path.
diff --git a/src/preload/api/extensions.ts b/src/preload/api/extensions.ts
new file mode 100644
index 000000000..1faa86515
--- /dev/null
+++ b/src/preload/api/extensions.ts
@@ -0,0 +1,70 @@
+import { ipcRenderer } from 'electron'
+
+import type {
+  ExtensionCapability,
+  ExtensionInstallResult,
+  ExtensionListEntry,
+} from '@shared/types/extensions.js'
+
+// Extension-app storage and management bridge.
+//
+// ── WHO IS ALLOWED TO CALL WHAT, AND WHY IT IS TWO GROUPS ──
+// An earlier version of this header claimed these methods had a single call site,
+// `apps/api/useAppHostApi.ts`, and that a second one would mean "the ABI has been
+// bypassed". That module does not exist, and five files call these methods
+// directly — so the comment asserted a security-shaped invariant that was simply
+// false, which is worse than no comment at all.
+//
+// The real rule has two halves:
+//
+//   The STORAGE methods are extension-facing, and `createAppHostApi` is their only
+//   legitimate call site. It closes over one extension id, so an extension can
+//   never name another's namespace. A second call site for THOSE would be a real
+//   bypass. (ExtensionSettingRow also calls them, deliberately: a contributed
+//   settings row reads and writes the extension's own storage on its behalf, with
+//   the id coming from the validated manifest.)
+//
+//   The MANAGEMENT methods — list, install, install-path, update-local, remove,
+//   granted-capabilities — are host-facing by design. The Settings UI and the frame
+//   broker call them directly and must. An extension must never reach them, and it
+//   cannot: its frame is cross-origin with no preload, so it has no `window.api`
+//   and no ipcRenderer at all.
+export const extensionsApi = {
+  extensionStorageGet: (appId: string, key: string): Promise<unknown> =>
+    ipcRenderer.invoke('extensions:storage-get', appId, key),
+
+  extensionStorageSet: (appId: string, key: string, value: unknown): Promise<void> =>
+    ipcRenderer.invoke('extensions:storage-set', appId, key, value),
+
+  extensionStorageDelete: (appId: string, key: string): Promise<void> =>
+    ipcRenderer.invoke('extensions:storage-delete', appId, key),
+
+  extensionStorageKeys: (appId: string): Promise<string[]> =>
+    ipcRenderer.invoke('extensions:storage-keys', appId),
+
+  // Install management. These are HOST methods, not part of AgentCodeApiV1 — an
+  // extension must never be able to install or remove another extension. They are
+  // called only by the Settings UI.
+  extensionsList: (): Promise<ExtensionListEntry[]> => ipcRenderer.invoke('extensions:list'),
+
+  extensionsInstall: (repo: string): Promise<ExtensionInstallResult> =>
+    ipcRenderer.invoke('extensions:install', repo),
+
+  // "Load unpacked" from a local folder (main opens the native directory picker).
+  extensionsInstallPath: (): Promise<ExtensionInstallResult> =>
+    ipcRenderer.invoke('extensions:install-path'),
+
+  // Reinstall a locally-loaded extension from the folder recorded at install time.
+  // Takes only the id — main reads the path from its own ledger, so the renderer
+  // never names a directory.
+  extensionsUpdateLocal: (id: string): Promise<ExtensionInstallResult> =>
+    ipcRenderer.invoke('extensions:update-local', id),
+
+  extensionsRemove: (id: string): Promise<void> => ipcRenderer.invoke('extensions:remove', id),
+
+  // Reads the set of capabilities a user granted an extension, for the frame broker
+  // to gate Tier 1-3 calls. A HOST method, not part of AgentCodeApiV1 — an extension
+  // must never read (or change) its own or another's grants; only the broker calls it.
+  extensionGrantedCapabilities: (id: string): Promise<ExtensionCapability[]> =>
+    ipcRenderer.invoke('extensions:granted-capabilities', id),
+}
diff --git a/src/preload/api/index.ts b/src/preload/api/index.ts
index f4aecad63..7a97e0c08 100644
--- a/src/preload/api/index.ts
+++ b/src/preload/api/index.ts
@@ -27,6 +27,7 @@ import { remoteApi } from '@preload/api/remote.js'
 import { usageApi } from '@preload/api/usage.js'
 import { cliUpdatesApi } from '@preload/api/cliUpdates.js'
 import { workflowsApi } from '@preload/api/workflows.js'
+import { extensionsApi } from '@preload/api/extensions.js'
 import { agentCodeConventionsApi } from '@preload/api/agentCodeConventions.js'
 import { agentCodeCustomSkillsApi } from '@preload/api/agentCodeCustomSkills.js'
 
@@ -75,6 +76,7 @@ export const api = {
   ...usageApi,
   ...cliUpdatesApi,
   ...workflowsApi,
+  ...extensionsApi,
   ...agentCodeConventionsApi,
   ...agentCodeCustomSkillsApi,
 }
diff --git a/src/renderer/index.html b/src/renderer/index.html
index 247923fb1..cdb1f67a4 100644
--- a/src/renderer/index.html
+++ b/src/renderer/index.html
@@ -11,10 +11,26 @@
       directive, workers fall back to script-src 'self', which blocks
       blob: — the TS/JSON/CSS/HTML workers die silently and tokenization
       goes blank intermittently (#513).
+      ── agent-code-ext: APPEARS IN frame-src AND NOWHERE ELSE ──
+      That single directive is what contains extension frames, and it is the
+      one doing the real work here — everything above describes the other
+      directives, so someone tidying this line has no way to know that.
+
+      It was previously also in script-src, connect-src, img-src, style-src and
+      font-src, to serve ExtensionHost.activate() — a host-realm
+      import('agent-code-ext://…') that evaluates third-party extension code in
+      THIS realm, where window.api exposes every IPC handler including
+      extensions:install and extensions:remove. That path has no callers: command
+      execution moved into the sandboxed frame. So the concession bought nothing
+      and left the renderer permitted to run extension code directly.
+
+      The child loads its own assets under its own far stricter policy (see
+      childFrameCsp), so the host needs none of these. If background activation
+      is added later it must be a hidden FRAME, not a host-realm import.
     -->
     <meta
       http-equiv="Content-Security-Policy"
-      content="default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' data: https://fonts.gstatic.com; script-src 'self'; worker-src 'self' blob:"
+      content="default-src 'self'; img-src 'self' data: blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' data: https://fonts.gstatic.com; script-src 'self'; connect-src 'self'; frame-src agent-code-ext:; worker-src 'self' blob:"
     />
     <title>Agent Code</title>
   </head>
diff --git a/src/renderer/src/app-state/types.ts b/src/renderer/src/app-state/types.ts
index 63dbd1f71..e981027ef 100644
--- a/src/renderer/src/app-state/types.ts
+++ b/src/renderer/src/app-state/types.ts
@@ -8,6 +8,8 @@ import type {
 import type { SessionId, TabId } from '@renderer/workspace/types'
 import type { WorkspaceState } from '@renderer/workspace/types'
 import type { SessionRuntime } from '@renderer/session-runtime/state'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+import type { ExtensionFailure } from '@renderer/apps/types'
 import type {
   ReaderModeState,
   SpotlightState,
@@ -118,6 +120,10 @@ export type UiShellSlice = UiShellState & {
   closeUsageModal: () => void
   openRewindPrompt: (sessionId: SessionId) => void
   closeRewindPrompt: () => void
+  openApp: (appId: string) => void
+  closeApp: () => void
+  setInstalledExtensions: (entries: ExtensionListEntry[]) => void
+  setExtensionFailures: (failures: ExtensionFailure[]) => void
   openAgentViewModePicker: (sessionId: SessionId) => void
   closeAgentViewModePicker: () => void
   openColorFlagPicker: (sessionId: SessionId) => void
diff --git a/src/renderer/src/app-state/uiShell/slice.ts b/src/renderer/src/app-state/uiShell/slice.ts
index 06b4eb512..68392ad61 100644
--- a/src/renderer/src/app-state/uiShell/slice.ts
+++ b/src/renderer/src/app-state/uiShell/slice.ts
@@ -51,6 +51,13 @@ export const createUiShellSlice: StateCreator<
   usageModalOpen: false,
   rewindPromptSessionId: null,
   agentViewModePickerSessionId: null,
+  openAppId: null,
+  installedExtensions: [],
+  // False until the first SUCCESSFUL extensionsList(). Distinguishes "no extensions"
+  // from "not asked yet", which the pane leaf needs to avoid claiming an installed
+  // extension is missing during the async gap on every reload.
+  installedExtensionsLoaded: false,
+  extensionFailures: [],
   colorFlagPickerSessionId: null,
   // Default keeps the dispatch list at 25% (matching the
   // previous-hardcoded `basis-1/4`) so the migration is visually a
@@ -316,6 +323,18 @@ export const createUiShellSlice: StateCreator<
   closeRewindPrompt: () =>
     set({ rewindPromptSessionId: null }, false, 'uiShell/closeRewindPrompt'),
 
+  openApp: appId => set({ openAppId: appId }, false, 'uiShell/openApp'),
+  closeApp: () => set({ openAppId: null }, false, 'uiShell/closeApp'),
+
+  setInstalledExtensions: entries =>
+    set(
+      { installedExtensions: entries, installedExtensionsLoaded: true },
+      false,
+      'uiShell/setInstalledExtensions',
+    ),
+  setExtensionFailures: failures =>
+    set({ extensionFailures: failures }, false, 'uiShell/setExtensionFailures'),
+
   openAgentViewModePicker: sessionId =>
     set(
       { agentViewModePickerSessionId: sessionId },
diff --git a/src/renderer/src/app-state/uiShell/types.ts b/src/renderer/src/app-state/uiShell/types.ts
index 9e1199dae..489533e9b 100644
--- a/src/renderer/src/app-state/uiShell/types.ts
+++ b/src/renderer/src/app-state/uiShell/types.ts
@@ -1,5 +1,7 @@
 import type { PaletteMode } from '@renderer/features/command-palette/paletteMode'
 import type { TabId, SessionId } from '@renderer/workspace/types'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+import type { ExtensionFailure } from '@renderer/apps/types'
 
 export type DispatchAttachIntent = {
   sessionId: SessionId
@@ -312,6 +314,48 @@ export type UiShellState = {
    * session.
    */
   agentViewModePickerSessionId: SessionId | null
+  /**
+   * Non-null when a built-in app is open; the value is its `AppDefinition` id.
+   *
+   * WHY one nullable id rather than one boolean per app: apps are mutually
+   * exclusive by construction — a single host surface renders one at a time — and
+   * N booleans would permit two to be true, a state the host physically cannot
+   * express. Same shape and same reasoning as `rewindPromptSessionId` above.
+   *
+   * WHY this is a plain string and not a branded id like SessionId: the value comes
+   * from a compile-time registry today but from a manifest on disk in Stage 2, and
+   * a brand would have to be cast away at exactly the boundary where validation
+   * actually matters. `AppHostSurface` resolves it through `APP_BY_ID` and treats a
+   * miss as closed, which is the real check.
+   *
+   * WHY uiShell (in-memory) and never persisted Settings: an app left open across a
+   * restart is not desirable, and more importantly extension-adjacent data must not
+   * enter the zustand-persist blob — app-state/store.ts records that a forgotten
+   * version bump there black-screened launch twice (#249).
+   */
+  openAppId: string | null
+  /**
+   * Installed extensions, as reported by main's ledger.
+   *
+   * WHY the store and not a module-scope array: the palette, Settings and the
+   * view host must all re-render when an extension is installed or removed, and
+   * a module variable cannot notify them. The previous static `APPS` array was
+   * exactly that mistake — an adversarial audit found it, along with the stale
+   * `APP_BY_ID` map built beside it.
+   *
+   * Holds the MANIFESTS, not loaded modules. Contributions are declared, so this
+   * is enough to populate the palette and Settings without importing a single
+   * extension bundle.
+   */
+  installedExtensions: ExtensionListEntry[]
+  /** True once extensionsList() has succeeded at least once. */
+  installedExtensionsLoaded: boolean
+  /** Extensions whose frame failed to boot, or whose module threw during import
+   *  or activate(). Reported BY THE FRAME over postMessage and collected by
+   *  viewBridge — the extension does not run in this realm, so the host cannot
+   *  observe the throw directly. Surfaced in Settings rather than hidden, because
+   *  a silently-missing extension is undiagnosable for whoever installed it. */
+  extensionFailures: ExtensionFailure[]
   /** Session whose Dispatch color-flag picker modal is open, or null. */
   colorFlagPickerSessionId: SessionId | null
   /** Splitter ratio between the dispatch agent list and the active
diff --git a/src/renderer/src/app/main.tsx b/src/renderer/src/app/main.tsx
index b14b17f96..90701820e 100644
--- a/src/renderer/src/app/main.tsx
+++ b/src/renderer/src/app/main.tsx
@@ -16,6 +16,7 @@ import { AppErrorBoundary } from '@renderer/app/AppErrorBoundary'
 import { WorkflowClientProvider } from '@renderer/features/workflows/client/WorkflowClientContext'
 import { ipcWorkflowClient } from '@renderer/features/workflows/client/IpcWorkflowClient'
 import { startRendererFreezeHeartbeat } from '@renderer/performance/freezeHeartbeat'
+import { InstalledExtensionsLoader } from '@renderer/apps/host/InstalledExtensionsLoader'
 
 void initializePerformance().then(() => {
   mark('app.renderer.reactRenderCalled')
@@ -85,8 +86,16 @@ createRoot(document.getElementById('root')!).render(
     <WorkflowClientProvider value={ipcWorkflowClient}>
       <SessionFeedProvider value={ipcSessionFeed}>
         <GlobalToastProvider>
+          {/* INSIDE AppErrorBoundary, not wrapped around it. The previous
+              placement put the loader OUTSIDE the boundary while its comment
+              claimed the opposite, so a throw during its render would have
+              blanked the whole app instead of being caught. It reads the store
+              and runs one IPC effect, so there is nothing it needs from being
+              higher in the tree. */}
           <AppErrorBoundary>
-            <App />
+            <InstalledExtensionsLoader>
+              <App />
+            </InstalledExtensionsLoader>
           </AppErrorBoundary>
         </GlobalToastProvider>
       </SessionFeedProvider>
diff --git a/src/renderer/src/app/surfaces/GlobalModals.tsx b/src/renderer/src/app/surfaces/GlobalModals.tsx
index eb2816bd2..858d09dd0 100644
--- a/src/renderer/src/app/surfaces/GlobalModals.tsx
+++ b/src/renderer/src/app/surfaces/GlobalModals.tsx
@@ -1,9 +1,14 @@
 import { modalSurfaces } from './registry'
+import { sortSurfacesByLayer } from './types'
 
 export function GlobalModals() {
+  // Sorted by layer before render. First-party entries omit `layer`, so the stable
+  // sort leaves their documented order untouched; an extension-contributed surface
+  // (EXTENSION_SURFACE_LAYER) is lifted into its own band above the first-party
+  // stack instead of tie-breaking into it. See SurfaceEntry.layer.
   return (
     <>
-      {modalSurfaces.map(entry => (
+      {sortSurfacesByLayer(modalSurfaces).map(entry => (
         <entry.Component key={entry.id} />
       ))}
     </>
diff --git a/src/renderer/src/app/surfaces/registry.tsx b/src/renderer/src/app/surfaces/registry.tsx
index 73b778dc3..2bf040ecf 100644
--- a/src/renderer/src/app/surfaces/registry.tsx
+++ b/src/renderer/src/app/surfaces/registry.tsx
@@ -27,6 +27,7 @@ import { ColorFlagPickerSurface } from '@renderer/features/workspace/surfaces/Co
 import { KeyboardShortcutsSurface } from '@renderer/features/settings/surfaces/KeyboardShortcutsSurface'
 import { RewindToPromptSurface } from '@renderer/features/workspace/surfaces/RewindToPromptSurface'
 import { AgentTitlePromptSurface } from '@renderer/features/workspace/surfaces/AgentTitlePromptSurface'
+import { AppHostSurface } from '@renderer/apps/surfaces/AppHostSurface'
 
 // The surface registry (issue #494). Adding a surface = write a wrapper
 // in the owning feature's surfaces/ folder + add ONE import + ONE array
@@ -81,6 +82,13 @@ export const modalSurfaces: SurfaceEntry[] = [
   { id: 'rewind-to-prompt', Component: RewindToPromptSurface },
   { id: 'agent-title-prompt', Component: AgentTitlePromptSurface },
   { id: 'usage', Component: UsageModalSurface },
+  // Built-in apps host. Last in the array, which per the paint-order contract
+  // above means it paints above every modal already mounted. That placement is
+  // reasoned, not defaulted: an app is always user-initiated from the palette and
+  // is the thing awaiting input for as long as it is open, so nothing already on
+  // screen has a claim to cover it. No app has a reason to sit *under* another
+  // modal — if one ever does, that is a signal it should not be an app.
+  { id: 'app-host', Component: AppHostSurface },
 ]
 
 /**
diff --git a/src/renderer/src/app/surfaces/types.ts b/src/renderer/src/app/surfaces/types.ts
index d89b2dcd2..3e21530fa 100644
--- a/src/renderer/src/app/surfaces/types.ts
+++ b/src/renderer/src/app/surfaces/types.ts
@@ -24,4 +24,30 @@ export type SurfaceEntry = {
    * props by design — props would put App back in the wiring business.
    */
   Component: ComponentType
+  /**
+   * Paint band. Entries are stably sorted by `layer` (default 0) before render,
+   * so within a band the array order still decides sibling/paint order exactly as
+   * before — every first-party entry omits `layer` and keeps its documented
+   * position. The field exists so a NON-first-party surface (an extension one,
+   * WS7) can be given a distinct band it cannot escape: it can never tie-break
+   * into the first-party z-50 stack and silently reorder it, which is the exact
+   * class of bug PR #505 hit. First-party entries should not set it.
+   */
+  layer?: number
+}
+
+/**
+ * The band all extension-contributed surfaces sit in — above the first-party stack,
+ * so an extension surface always paints over app chrome (it is user-initiated and
+ * awaiting input) but cannot reorder first-party surfaces among themselves.
+ */
+export const EXTENSION_SURFACE_LAYER = 100
+
+/** Stable sort by layer. First-party entries (layer undefined → 0) keep their exact
+ *  authored order; only cross-band ordering is imposed. */
+export function sortSurfacesByLayer(entries: readonly SurfaceEntry[]): SurfaceEntry[] {
+  return entries
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => (a.entry.layer ?? 0) - (b.entry.layer ?? 0) || a.index - b.index)
+    .map(({ entry }) => entry)
 }
diff --git a/src/renderer/src/apps/api/createAppHostApi.ts b/src/renderer/src/apps/api/createAppHostApi.ts
new file mode 100644
index 000000000..94def366d
--- /dev/null
+++ b/src/renderer/src/apps/api/createAppHostApi.ts
@@ -0,0 +1,153 @@
+import { useAppStore } from '@renderer/app-state/hooks'
+import { collectLeaves } from '@renderer/workspace/workspaceStore'
+
+import type { AgentCodeApiV1, JsonValue } from '@renderer/apps/api/types'
+
+// Discovering which `--theme-*` custom properties exist requires walking every
+// stylesheet rule, which is O(all CSS in the app). The NAMES are fixed at build
+// time — a theme change rewrites values on :root, it never invents a new token —
+// so the expensive half runs once per renderer lifetime and only the cheap
+// getPropertyValue lookups repeat.
+let cachedTokenNames: string[] | null = null
+
+// Tokens the host assigns at RUNTIME via root.style.setProperty, which therefore
+// appear in NO stylesheet — walking document.styleSheets cannot find them however
+// thorough the walk. Source of truth: app-state/settings/theme.ts (applyTheme).
+// There is no automated link between the two; this comment is the link.
+const RUNTIME_ONLY_TOKENS = [
+  '--theme-accent',
+  '--theme-accent-fg',
+  '--theme-app-font',
+  '--theme-font-code',
+] as const
+
+function themeTokenNames(): string[] {
+  if (cachedTokenNames) return cachedTokenNames
+
+  const names = new Set<string>(RUNTIME_ONLY_TOKENS)
+  for (const sheet of Array.from(document.styleSheets)) {
+    let rules: CSSRuleList
+    try {
+      rules = sheet.cssRules
+    } catch {
+      // Cross-origin stylesheet — the Google Fonts @import in styles.css is one.
+      // Reading .cssRules throws SecurityError. Nothing we need is in there.
+      continue
+    }
+    for (const rule of Array.from(rules)) {
+      if (!(rule instanceof CSSStyleRule)) continue
+      for (const prop of Array.from(rule.style)) {
+        if (prop.startsWith('--theme-')) names.add(prop)
+      }
+    }
+  }
+
+  cachedTokenNames = Array.from(names).sort()
+  return cachedTokenNames
+}
+
+export type AppHostApiDeps = {
+  extensionId: string
+  showToast: (message: string) => void
+  /** Closes whatever surface is currently hosting this extension. */
+  closeSurface: () => void
+}
+
+/**
+ * Builds the `AgentCodeApiV1` instance handed to one extension.
+ *
+ * WHY a plain factory rather than the hook it started as: `ExtensionHost` needs
+ * to construct an API for an extension at ACTIVATION time, which can happen from
+ * a palette command with no component mounted — and a hook cannot be called
+ * there. The React-context dependencies (toast, close) are injected instead, so
+ * the same factory serves both the host and any component that needs one.
+ *
+ * WHY extensionId is closed over rather than passed per call: an extension must
+ * not be able to name a different extension's storage namespace. In this stage
+ * that is enforced by this closure being the only call site of
+ * window.api.extensionStorage*. It becomes properly enforceable when each
+ * extension gets its own frame and main derives the id from the sender.
+ */
+export function createAppHostApi(deps: AppHostApiDeps): AgentCodeApiV1 {
+  const { extensionId, showToast, closeSurface } = deps
+
+  return {
+    extension: { id: extensionId, apiVersion: 1 },
+
+    storage: {
+      get: async <T extends JsonValue>(key: string): Promise<T | undefined> =>
+        (await window.api.extensionStorageGet(extensionId, key)) as T | undefined,
+      set: (key: string, value: JsonValue) =>
+        window.api.extensionStorageSet(extensionId, key, value),
+      delete: (key: string) => window.api.extensionStorageDelete(extensionId, key),
+      keys: () => window.api.extensionStorageKeys(extensionId),
+    },
+
+    ui: {
+      // Async despite being synchronous internally — see the ABI's note on why
+      // no method here may be declared sync, however obviously sync it is.
+      close: async () => {
+        closeSurface()
+      },
+      showToast: async (message: string) => {
+        showToast(message)
+      },
+    },
+
+    theme: {
+      tokens: async () => {
+        const style = getComputedStyle(document.documentElement)
+        const out: Record<string, string> = {}
+        for (const name of themeTokenNames()) {
+          const value = style.getPropertyValue(name).trim()
+          // Skip empties rather than emitting `'--theme-x': ''`. A caller pushing
+          // these into a frame would otherwise set variables to the empty string,
+          // which resolves as invalid and defeats the consumer's own fallback.
+          if (value) out[name] = value
+        }
+        return out
+      },
+    },
+
+    // Tier-1 observe reads. These implementations are UNGATED here on purpose —
+    // the grant check lives in the frame broker (frameHost.perform), the single
+    // trusted chokepoint every frame request passes through. Curated, serializable
+    // snapshots only: never the live store objects, which hold renderer handles.
+    workspace: {
+      observe: async () => {
+        const ws = useAppStore.getState().workspaceState
+        return {
+          activeTabId: ws.activeTabId ?? null,
+          tabIds: ws.tabs.map(tab => tab.id),
+          sessionCount: Object.keys(ws.sessions).length,
+        }
+      },
+      // Real subscription for a same-realm caller. In the FRAME model the extension
+      // calls the child's own subscribe (frameDocument), driven by the host's change
+      // nudge — this impl is what satisfies the contract and would serve a same-realm
+      // consumer; it is never reached through the broker (subscribe is not a request).
+      subscribe: listener => useAppStore.subscribe(s => s.workspaceState, () => listener()),
+    },
+
+    sessions: {
+      observe: async () =>
+        Object.entries(useAppStore.getState().workspaceState.sessions).map(([id, meta]) => ({
+          id,
+          kind: meta.kind ?? null,
+          cwd: meta.cwd,
+          title: meta.title ?? null,
+        })),
+      subscribe: listener =>
+        useAppStore.subscribe(s => s.workspaceState.sessions, () => listener()),
+    },
+
+    panes: {
+      observe: async () =>
+        useAppStore.getState().workspaceState.tabs.map(tab => ({
+          tabId: tab.id,
+          leafSessionIds: [...collectLeaves(tab.root)],
+        })),
+      subscribe: listener => useAppStore.subscribe(s => s.workspaceState.tabs, () => listener()),
+    },
+  }
+}
diff --git a/src/renderer/src/apps/api/types.ts b/src/renderer/src/apps/api/types.ts
new file mode 100644
index 000000000..2b0f1d63e
--- /dev/null
+++ b/src/renderer/src/apps/api/types.ts
@@ -0,0 +1,145 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+
+// --- Tier-1 observe snapshots ------------------------------------------------
+// Curated, fully-serializable projections of host state — NOT the live store
+// objects, which carry renderer-only handles and would not survive the frame
+// boundary. These are point-in-time reads; live updates arrive over the push
+// channel (Group D). Kept deliberately minimal: an extension gets identity and
+// shape, not the host's internal runtime.
+
+export type ExtensionWorkspaceSnapshot = {
+  activeTabId: string | null
+  tabIds: string[]
+  sessionCount: number
+}
+
+export type ExtensionSessionSnapshot = {
+  id: string
+  /** Provider/terminal/extension-view kind, or null if unset. */
+  kind: string | null
+  cwd: string
+  title: string | null
+}
+
+export type ExtensionPaneSnapshot = {
+  tabId: string
+  /** Session ids of the leaves in this tab's tile tree, in tree order. */
+  leafSessionIds: string[]
+}
+
+/**
+ * The Agent Code app host API, version 1.
+ *
+ * WHY this exists in a stage where apps are compiled into the renderer and could
+ * simply `import { useAppStore }`: this object IS the migration boundary. An app
+ * that talks only through it can be lifted into its own repository and loaded at
+ * runtime — through a custom scheme or an iframe — with no edits inside it. An app
+ * that reaches into `@renderer/*` cannot, and the cost of discovering that is a
+ * simultaneous rewrite of every app that exists. The rule is binary and checkable
+ * with one grep, which is the only kind of architectural rule that survives contact
+ * with a codebase this size.
+ *
+ * WHY every method returns a Promise, including ones that could be synchronous
+ * today: under a future postMessage transport nothing can be synchronous, and a
+ * signature cannot be widened from `void` to `Promise<void>` later without touching
+ * every call site in every app. It costs nothing now. Of everything in this design
+ * this is the single highest-value forward-compatibility decision, and it is also
+ * the easiest one to lose by accident — if you are tempted to make something here
+ * synchronous "because it obviously is," that is the temptation this comment exists
+ * to stop.
+ *
+ * WHY the surface is this small: it is Tier 0 — everything an app may have without
+ * asking anyone's permission. Workspace, session, transcript, git, filesystem and
+ * network access are Tiers 1-3, each gated behind a manifest capability and a
+ * consent flow that do not exist yet. Adding one before a real app needs it means
+ * guessing a contract with no consumer to validate it against, and a wrong guess in
+ * a versioned ABI is far more expensive than a late one.
+ *
+ * Versioning: this interface is frozen once an app outside this repo depends on it.
+ * A v2 is a new `AgentCodeApiV2` built from the same internals with `createHostV1`
+ * kept alongside it, dispatched on a manifest `apiVersion` — not an edit to this
+ * file. That is roughly thirty lines and is the whole reason the surface is one
+ * object rather than 153 flat methods.
+ */
+export interface AgentCodeApiV1 {
+  readonly extension: {
+    /** This app's id. Matches its AppDefinition id and its storage namespace. */
+    readonly id: string
+    readonly apiVersion: 1
+  }
+
+  readonly storage: {
+    get<T extends JsonValue>(key: string): Promise<T | undefined>
+    set(key: string, value: JsonValue): Promise<void>
+    delete(key: string): Promise<void>
+    keys(): Promise<string[]>
+  }
+
+  readonly ui: {
+    /** Close this app's view. */
+    close(): Promise<void>
+    /**
+     * Transient app-wide toast. Deliberately not an OS notification — a background
+     * app that can raise system notifications is a Tier 3 capability, because it
+     * can interrupt the user while they are working in another application.
+     */
+    showToast(message: string): Promise<void>
+  }
+
+  readonly theme: {
+    /**
+     * Resolved `--theme-*` custom properties, e.g. `{ '--theme-surface': '#111113' }`.
+     *
+     * Apps should prefer plain CSS — `background: var(--theme-surface)` — which
+     * cascades for free today and keeps working unchanged across a frame boundary
+     * once the host pushes the same variables into the child document. This
+     * accessor exists only for imperative consumers that cannot use CSS: canvas
+     * drawing, inline SVG fill computation, chart libraries.
+     *
+     * Only the `--theme-*` layer is exposed, never the `--color-*` Tailwind binding
+     * layer. The former is a stable contract; the latter is an implementation
+     * detail of how the app's utilities are wired, and depending on it would couple
+     * an app to the host's build system — exactly what portability forbids.
+     */
+    tokens(): Promise<Record<string, string>>
+  }
+
+  // --- Tier 1 — read-only metadata (capability-gated) ------------------------
+  // These require a granted manifest permission (workspace.observe /
+  // sessions.observe / panes.observe). The frame broker denies the call with an
+  // error if the grant is absent, so an extension that did not request the
+  // capability never reaches these. Snapshots today; a live subscription is a
+  // Group-D addition, not a signature change here.
+
+  readonly workspace: {
+    /** Point-in-time workspace shape. Requires `workspace.observe`. */
+    observe(): Promise<ExtensionWorkspaceSnapshot>
+    /**
+     * Fire `listener` whenever the workspace changes; returns an unsubscribe.
+     * The listener receives no argument — call observe() to read fresh state. This
+     * is the live half of observe: the host pushes a change nudge, the extension
+     * re-reads. Requires `workspace.observe` (the re-read is what's gated).
+     */
+    subscribe(listener: () => void): () => void
+  }
+
+  readonly sessions: {
+    /** All sessions' identity/shape. Requires `sessions.observe`. */
+    observe(): Promise<ExtensionSessionSnapshot[]>
+    /** Fire on any session change; returns an unsubscribe. Re-read via observe(). */
+    subscribe(listener: () => void): () => void
+  }
+
+  readonly panes: {
+    /** The tile layout as leaf ids per tab. Requires `panes.observe`. */
+    observe(): Promise<ExtensionPaneSnapshot[]>
+    /** Fire on any pane-layout change; returns an unsubscribe. Re-read via observe(). */
+    subscribe(listener: () => void): () => void
+  }
+}
diff --git a/src/renderer/src/apps/host/InstalledExtensionsLoader.tsx b/src/renderer/src/apps/host/InstalledExtensionsLoader.tsx
new file mode 100644
index 000000000..0e289ea25
--- /dev/null
+++ b/src/renderer/src/apps/host/InstalledExtensionsLoader.tsx
@@ -0,0 +1,67 @@
+import { useEffect } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+
+/**
+ * Loads the install ledger into the store, once, at startup.
+ *
+ * ── WHY THIS IS NO LONGER A PROVIDER ──
+ * It was `ExtensionHostProvider`, and it constructed an `ExtensionHost` that
+ * imported and activated extension modules in the RENDERER'S OWN REALM — where
+ * `window.api` exposes every IPC handler, including `extensions:install` and
+ * `extensions:remove`. Once activation moved into the sandboxed frame, that host
+ * had no callers left: `activate()`, `executeCommand()` and the whole
+ * registration store were dead, and `index.html` had already dropped
+ * `agent-code-ext:` from `script-src`, so the import it existed to perform could
+ * not have run anyway.
+ *
+ * Six files still called `useExtensionHost()` and threaded the object into
+ * `derive*`, which ignored it. Deleting the host removed the context, and what
+ * was left is this: one effect that fills `installedExtensions`. A component
+ * whose only job is a startup effect does not need to wrap the tree, but it
+ * stays a component (rather than a hook called from App) so the ordering
+ * constraint below is expressed by where it sits in main.tsx rather than by a
+ * comment somewhere else.
+ *
+ * ── WHAT REPLACED THE HOST'S FAILURE TRACKING ──
+ * `ExtensionHost` collected failures from its own try/catch around import and
+ * activate. Those now happen inside the frame, so the frame reports them over
+ * postMessage and `viewBridge` publishes them to the same store slice. The
+ * Settings row is unchanged; only the producer moved to the far side of the
+ * sandbox, which is where the code actually runs.
+ */
+export function InstalledExtensionsLoader({ children }: { children: React.ReactNode }) {
+  const setInstalledExtensions = useAppStore(state => state.setInstalledExtensions)
+
+  useEffect(() => {
+    let cancelled = false
+
+    void (async () => {
+      let installed: Awaited<ReturnType<typeof window.api.extensionsList>>
+      try {
+        installed = await window.api.extensionsList()
+      } catch {
+        // A failed list is not an empty list. Leaving the store untouched keeps
+        // `installedExtensionsLoaded` false, which is what stops ExtensionViewLeaf
+        // from telling the user an installed extension is missing.
+        return
+      }
+      if (cancelled) return
+      setInstalledExtensions(installed)
+    })()
+
+    return () => {
+      cancelled = true
+    }
+  }, [setInstalledExtensions])
+
+  // ── NO EAGER ACTIVATION HAPPENS HERE, DELIBERATELY ──
+  // `onStartupFinished` and `'*'` activation events are declared in manifests,
+  // validated at install, and currently fire NOWHERE. That is a real gap, and it
+  // is named as one in docs/extensions/authoring.md rather than papered over: the
+  // honest fix is a hidden background frame per extension, because reintroducing
+  // host-realm activation is what the sandbox exists to prevent. Until then an
+  // extension activates on its first view open or command invocation, which means
+  // background work does not run while every view is closed.
+  return <>{children}</>
+}
diff --git a/src/renderer/src/apps/host/derive.ts b/src/renderer/src/apps/host/derive.ts
new file mode 100644
index 000000000..0fe7dc55e
--- /dev/null
+++ b/src/renderer/src/apps/host/derive.ts
@@ -0,0 +1,200 @@
+import type { CommandDef } from '@renderer/features/command-palette/types'
+import type { AppDefinition } from '@renderer/apps/types'
+import { viewComponentFor } from '@renderer/apps/host/viewBridge'
+import { dispatchToFrame, queuePendingCommand } from '@renderer/apps/host/frameRegistry'
+import type { CommandBindingDefault } from '@renderer/features/command-keybindings/defaults'
+import { tryNormalizeKeybinding } from '@renderer/features/command-keybindings/normalize'
+import type { Keybinding } from '@renderer/features/command-keybindings/normalize'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+
+// Turning DECLARATIONS into app surfaces.
+//
+// The load-bearing property of everything here is that it reads the MANIFEST,
+// never a loaded module. That is what makes lazy activation real: the palette
+// lists an extension's commands and the app registry knows about its views while
+// not a single extension bundle has been imported. Importing happens on first
+// use, inside its own frame.
+//
+// Cross-extension id collisions are resolved here rather than at install: neither
+// author can see the other's manifest, so failing the install would punish
+// whoever happened to install second. First wins, and the loser is dropped
+// rather than silently shadowing.
+
+/** `AppDefinition`s for every contributed view. */
+export function deriveAppDefinitions(installed: ExtensionListEntry[]): AppDefinition[] {
+  const seen = new Set<string>()
+  const definitions: AppDefinition[] = []
+
+  for (const entry of installed) {
+    if (!entry.present) continue
+    for (const view of entry.manifest.contributes?.views ?? []) {
+      if (seen.has(view.id)) continue
+      seen.add(view.id)
+      definitions.push({
+        id: view.id,
+        title: view.title,
+        // A view has no description of its own; the extension's is the honest
+        // fallback and is what the palette shows under the command.
+        description: entry.manifest.description,
+        keywords: entry.manifest.keywords,
+        Component: viewComponentFor(entry, view.id),
+      })
+    }
+  }
+
+  return definitions
+}
+
+/**
+ * `CommandDef`s for every contributed command.
+ *
+ * A command whose id matches a contributed VIEW id opens that view; anything
+ * else dispatches to the extension's registered handler. That mapping is why the
+ * timer can declare `timer.open` with no handler — opening a declared view is
+ * the host's job, and a handler whose only body is "show my own view" would be a
+ * worse version of the host's own routing.
+ */
+export function deriveExtensionCommands(
+  installed: ExtensionListEntry[],
+  openApp: (appId: string) => void,
+  // Opens a contributed view as a PANE (a tile leaf) instead of a modal. A view
+  // whose manifest `mount` is 'panel' routes here; 'modal' routes to openApp. Made
+  // optional with a no-op default so the Settings call sites that only LIST commands
+  // stay a 3-arg call — the routing still resolves there, it just never fires.
+  openInPane: (viewId: string) => void = () => {},
+): CommandDef[] {
+  const seen = new Set<string>()
+  const commands: CommandDef[] = []
+
+  for (const entry of installed) {
+    if (!entry.present) continue
+    const views = entry.manifest.contributes?.views ?? []
+    const viewIds = new Set(views.map(view => view.id))
+    // Where each view wants to render, so an "open" command targets the right host
+    // shell — a modal or a pane — from the same declaration.
+    const viewMountById = new Map(views.map(view => [view.id, view.mount]))
+
+    for (const command of entry.manifest.contributes?.commands ?? []) {
+      if (seen.has(command.id)) continue
+      seen.add(command.id)
+
+      // `timer.open` -> view `timer.main`: an extension's "open" command with no
+      // matching view id still needs a target, so a single-view extension gets
+      // its only view. More than one view means the author has to be explicit,
+      // and the command simply dispatches to a handler instead.
+      const onlyView = viewIds.size === 1 ? [...viewIds][0] : undefined
+      const targetView = viewIds.has(command.id)
+        ? command.id
+        : command.id.endsWith('.open') && onlyView
+          ? onlyView
+          : undefined
+
+      commands.push({
+        id: command.id,
+        title: command.title,
+        // buildCommandRegistry throws on a blank description, so the manifest's
+        // extension-level description is the fallback rather than an empty
+        // string — a missing description would be a launch crash.
+        description: command.description ?? entry.manifest.description,
+        // 'app': extensions are mode-independent. They have no relationship to
+        // the tile tree or to Dispatch, so hiding them in either mode would be
+        // wrong.
+        surface: 'app',
+        // Assigned HERE, not by each consumer. Two Settings surfaces used to
+        // re-tag these with `.map(c => ({...c, category: 'extensions'}))` after
+        // calling this function, and the command palette did not — so the same
+        // command grouped under "Extensions" in the keybinding editor and under
+        // "Other" in the palette, and sortCommands carried a comment asserting
+        // extension commands "have no way to declare one at all". The manifest
+        // still cannot set a category, which is the point: a third party must not
+        // be able to file itself under a first-party heading. The HOST assigns it,
+        // and one assignment site is what makes every consumer agree.
+        category: 'extensions',
+        keywords: command.keywords ?? [],
+        run: ({ ui }) => {
+          // A command that maps to a view is an "open" command — opening a declared
+          // view is the host's job, not a handler's (an extension declaring a command
+          // whose only body is "show my own view" would be a worse version of this).
+          // The view's declared mount decides WHICH host shell opens it.
+          if (targetView) {
+            if (viewMountById.get(targetView) === 'panel') openInPane(targetView)
+            else openApp(targetView)
+            ui.closePalette()
+            return
+          }
+          // Action command. It runs inside the extension's live frame — the ONLY
+          // place the extension executes now that host-realm activation is gone. If a
+          // frame is open, dispatch straight in. If not, open the extension's single
+          // view to bring a frame up and QUEUE the command to fire the instant that
+          // frame signals ready — so a cold "timer.start" opens the timer and starts
+          // it in one action. With no view to open, the action cannot run yet; the
+          // background-frame follow-up (Group A, A4) removes that last limitation.
+          const extensionId = entry.manifest.id
+          if (!dispatchToFrame(extensionId, command.id)) {
+            if (onlyView) {
+              queuePendingCommand(extensionId, command.id)
+              // Honour the view's DECLARED mount, exactly as the targetView branch
+              // above does. This called openApp() unconditionally, so a panel-only
+              // extension's action command opened it as a floating modal — directly
+              // contradicting its own manifest — because deriveAppDefinitions builds
+              // an AppDefinition for every view regardless of declared mount.
+              if (viewMountById.get(onlyView) === 'panel') openInPane(onlyView)
+              else openApp(onlyView)
+            }
+          }
+          ui.closePalette()
+        },
+      })
+    }
+  }
+
+  return commands
+}
+
+/**
+ * `CommandBindingDefault`s for every contributed keybinding.
+ *
+ * These are DEFAULTS, concatenated onto `buildDefaultKeybindings()` at every
+ * `resolveEffectiveKeybindings` call site — a user override in
+ * `commandKeybindingOverrides` still wins, exactly like a first-party default.
+ * Reads manifests only (no bundle import), the sibling of `deriveExtensionCommands`.
+ *
+ * Three deliberate choices:
+ * - The manifest `key` is freeform text; the resolver needs the canonical
+ *   `Keybinding` form. `tryNormalizeKeybinding` returns null on garbage so one
+ *   malformed manifest key is dropped rather than throwing the whole default table.
+ * - Several `{command, key}` entries for one command collapse into that command's
+ *   `bindings` array — the multi-chord case the resolver already models.
+ * - Context is always 'global'. The manifest declares none, and 'global' is the
+ *   strictest for collision-checking (it overlaps every context), so an extension
+ *   binding errs toward being reported as a conflict rather than silently
+ *   shadowing a contextual first-party chord. The reservation check that consumes
+ *   these is what actually lets first-party win; see the WS2 wiring.
+ */
+export function deriveExtensionKeybindings(
+  installed: ExtensionListEntry[],
+): CommandBindingDefault[] {
+  const byCommand = new Map<string, Keybinding[]>()
+  const order: string[] = []
+
+  for (const entry of installed) {
+    if (!entry.present) continue
+    for (const binding of entry.manifest.contributes?.keybindings ?? []) {
+      const chord = tryNormalizeKeybinding(binding.key)
+      if (!chord) continue
+      let chords = byCommand.get(binding.command)
+      if (chords === undefined) {
+        chords = []
+        byCommand.set(binding.command, chords)
+        order.push(binding.command)
+      }
+      if (!chords.includes(chord)) chords.push(chord)
+    }
+  }
+
+  return order.map(commandId => ({
+    commandId,
+    bindings: byCommand.get(commandId)!,
+    context: 'global' as const,
+  }))
+}
diff --git a/src/renderer/src/apps/host/frameHost.ts b/src/renderer/src/apps/host/frameHost.ts
new file mode 100644
index 000000000..a0930c1e7
--- /dev/null
+++ b/src/renderer/src/apps/host/frameHost.ts
@@ -0,0 +1,199 @@
+import type { AgentCodeApiV1, JsonValue } from '@renderer/apps/api/types'
+import {
+  extensionIdFromOrigin,
+  frameRequestEnvelopeSchema,
+  type FramePush,
+  type FrameReply,
+  type FrameRequest,
+} from '@renderer/apps/host/frameProtocol'
+import type { ExtensionCapability } from '@shared/types/extensions'
+
+// The trusted host-side broker for one extension frame (WS4, Decision A).
+//
+// It is the ONLY thing that both (a) can perform a capability and (b) can hear the
+// frame. The extension iframe holds no capability; it posts a request, this broker
+// verifies the request came from that exact frame at the expected origin, performs
+// it against the real AgentCodeApiV1, and posts back a reply. Every trust decision
+// lives here, in the parent realm, never in the child.
+//
+// The `api` passed in is the same `createAppHostApi(...)` instance the same-realm
+// path uses, so storage/ui/theme behave identically across the boundary and there
+// is exactly one implementation of each capability to audit.
+
+export type FrameHostHandle = {
+  /** Push theme tokens (or a mount command) into the child. */
+  push: (message: FramePush) => void
+  /**
+   * The capabilities granted to this frame's extension, resolved once.
+   *
+   * Exposed so the view bridge can gate its observe subscription on the SAME
+   * promise the broker gates requests on. It previously made its own
+   * `extensionGrantedCapabilities` call, which meant every frame open recomputed
+   * the bundle hash TWICE in the main process — and the IPC handler's comment
+   * claimed it happened once, citing this cache.
+   */
+  granted: Promise<readonly ExtensionCapability[]>
+  /** Detach the listener. Idempotent. */
+  dispose: () => void
+}
+
+/** Compile-time proof that every FrameRequest method is handled. */
+function assertNeverMethod(request: never): never {
+  throw new Error(`unhandled frame request method: ${JSON.stringify(request)}`)
+}
+
+export function createFrameHost(options: {
+  iframe: HTMLIFrameElement
+  extensionId: string
+  api: AgentCodeApiV1
+}): FrameHostHandle {
+  const { iframe, extensionId, api } = options
+  // The origin this frame's messages MUST carry. The scheme gives every extension
+  // its own origin (`agent-code-ext://<id>`), so this is both the target for our
+  // pushes and the identity we check on every inbound message.
+  const expectedOrigin = `agent-code-ext://${extensionId}`
+
+  // The capability grant, fetched ONCE and cached for this frame's lifetime. This is
+  // the "teeth" of the tiered permission model: every Tier 1+ request is gated on it
+  // below. The grant is keyed on a hash of the installed bundle recomputed from disk
+  // (grantedCapabilities), so bytes that were never consented to authorize nothing.
+  // Read here rather than in main's per-feature IPC because that surface is
+  // deliberately NOT sender-bound — the frame broker is the one renderer chokepoint
+  // every capability call already passes through.
+  //
+  // ── WHAT "FOR THIS FRAME'S LIFETIME" COSTS, AND WHY IT IS ACCEPTABLE ──
+  // Revocation reaches a frame by DESTROYING it, not by re-reading the grant: an
+  // uninstall drops the extension from the store, which unmounts the view, which
+  // navigates the iframe to about:blank. So a permission downgrade shipped in an
+  // UPDATE does not take effect until the open view is closed — the frame keeps
+  // running the old code with the grant the user approved for exactly that code,
+  // which is internally consistent rather than a hole.
+  //
+  // Re-reading per request would not close the remaining gap either: it is a full
+  // bundle hash in main per capability call, and the frame it would police is one
+  // the user already consented to. The teardown path is the enforcement mechanism,
+  // and AppsSettingsRow.remove is careful to make it fire even when the refresh IPC
+  // that normally triggers it fails.
+  const grantPromise: Promise<readonly ExtensionCapability[]> = window.api
+    .extensionGrantedCapabilities(extensionId)
+    .catch(() => [])
+
+  const requireGrant = async (capability: ExtensionCapability): Promise<void> => {
+    const granted = await grantPromise
+    if (!granted.includes(capability)) {
+      // Becomes an `ok:false` reply automatically (perform's rejection is caught
+      // below), which the child surfaces as a rejected api call. A denied capability
+      // must fail loudly at the call, never silently return empty.
+      throw new Error(`capability "${capability}" is not granted to ${extensionId}`)
+    }
+  }
+
+  const post = (message: FrameReply | FramePush): void => {
+    // targetOrigin is pinned to the extension's origin, never '*': a reply carrying
+    // storage contents must not be deliverable to a frame that was navigated away
+    // or replaced between request and reply.
+    iframe.contentWindow?.postMessage(message, expectedOrigin)
+  }
+
+  /**
+   * Which capability each method requires — DATA, not a convention inside a switch.
+   *
+   * The tier gate used to exist only as `await requireGrant(...)` lines sprinkled
+   * through the switch below. Adding a Tier-2/3 member to frameRequestSchema and
+   * forgetting its requireGrant line was a one-line, review-invisible privilege
+   * escalation; there was nothing to notice the omission. As a Record keyed by the
+   * method union, a new schema member does not COMPILE until its tier is declared.
+   *
+   * `null` means Tier 0 — no grant needed, available to every extension.
+   */
+  const REQUIRED_CAPABILITY: Record<FrameRequest['method'], ExtensionCapability | null> = {
+    'storage.get': null,
+    'storage.set': null,
+    'storage.delete': null,
+    'storage.keys': null,
+    'ui.close': null,
+    'ui.showToast': null,
+    'theme.tokens': null,
+    'workspace.observe': 'workspace.observe',
+    'sessions.observe': 'sessions.observe',
+    'panes.observe': 'panes.observe',
+  }
+
+  const perform = async (request: FrameRequest): Promise<unknown> => {
+    // One gate, before the dispatch, so no arm can accidentally skip it.
+    const needed = REQUIRED_CAPABILITY[request.method]
+    if (needed) await requireGrant(needed)
+
+    switch (request.method) {
+      case 'storage.get':
+        return api.storage.get(request.key)
+      case 'storage.set':
+        await api.storage.set(request.key, request.value as JsonValue)
+        return undefined
+      case 'storage.delete':
+        await api.storage.delete(request.key)
+        return undefined
+      case 'storage.keys':
+        return api.storage.keys()
+      case 'ui.close':
+        await api.ui.close()
+        return undefined
+      case 'ui.showToast':
+        await api.ui.showToast(request.message)
+        return undefined
+      case 'theme.tokens':
+        return api.theme.tokens()
+      // Tier 1 — the grant was already enforced above by REQUIRED_CAPABILITY.
+      case 'workspace.observe':
+        return api.workspace.observe()
+      case 'sessions.observe':
+        return api.sessions.observe()
+      case 'panes.observe':
+        return api.panes.observe()
+      default:
+        // Exhaustiveness. Without it an unhandled method fell off the end returning
+        // undefined, which the caller reported as `ok: true, result: undefined` — a
+        // silent false success for a capability that was never performed.
+        return assertNeverMethod(request)
+    }
+  }
+
+  const onMessage = (event: MessageEvent): void => {
+    // Three gates, all before the payload is trusted:
+    // 1. It came from THIS frame's window (not another frame, not the top window).
+    if (event.source !== iframe.contentWindow) return
+    // 2. It carries this extension's origin. The browser stamps event.origin; the
+    //    child cannot forge it. A message whose origin resolves to a different
+    //    extension id — or to no valid id — is dropped, never mis-attributed.
+    if (event.origin !== expectedOrigin) return
+    if (extensionIdFromOrigin(event.origin) !== extensionId) return
+    // 3. It matches the request schema. Anything else (an unrelated library's
+    //    postMessage, a malformed frame) fails the parse and is ignored.
+    const parsed = frameRequestEnvelopeSchema.safeParse(event.data)
+    if (!parsed.success) return
+
+    const { id, request } = parsed.data
+    void perform(request).then(
+      result => post({ kind: 'agent-code-ext:reply', id, ok: true, result }),
+      error =>
+        post({
+          kind: 'agent-code-ext:reply',
+          id,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        }),
+    )
+  }
+
+  window.addEventListener('message', onMessage)
+  let disposed = false
+  return {
+    push: post,
+    granted: grantPromise,
+    dispose: () => {
+      if (disposed) return
+      disposed = true
+      window.removeEventListener('message', onMessage)
+    },
+  }
+}
diff --git a/src/renderer/src/apps/host/frameProtocol.ts b/src/renderer/src/apps/host/frameProtocol.ts
new file mode 100644
index 000000000..b69211b61
--- /dev/null
+++ b/src/renderer/src/apps/host/frameProtocol.ts
@@ -0,0 +1,153 @@
+import { z } from 'zod'
+
+// The host <-> extension-frame message contract (WS4, sandbox substrate).
+//
+// THE INVARIANT, borrowed verbatim from the remote mobile protocol
+// (main/remote/protocol/messages.ts): the request union below is the COMPLETE
+// set of things a sandboxed extension can ask the host to do. Anything not in it
+// is unrepresentable, not "checked and denied". Widening it is a deliberate
+// capability decision.
+//
+// WHY this exists at all — the isolation model (Decision A). An extension view is
+// a plain <iframe src="agent-code-ext://<id>/..."> in the app's renderer. Because
+// the scheme is a real, distinct origin (scheme.ts registers it `standard: true`),
+// the child document is same-process but cross-ORIGIN: it cannot reach `window.api`,
+// the parent DOM, or another extension. Its ONLY channel to the host is
+// `window.postMessage`. So the frame never holds a capability; it posts a request,
+// and the parent host — the trusted broker — performs it with the real API and
+// posts back a reply.
+//
+// WHY identity is NOT a field in the message. The remote protocol carries a device
+// `token` because a socket cannot otherwise be attributed. A frame can: the browser
+// stamps `event.origin` on every postMessage, and it is unforgeable by the child.
+// The host derives WHICH extension sent a request from that origin
+// (`extensionIdFromOrigin`), never from anything the child claims. This is the
+// whole reason the sandbox turns the storage namespace into a real authority
+// boundary (see ipc/extensions.ts's "namespace, not authority" comment — this is
+// the "Stage 2" it defers to).
+
+// --- Requests (frame -> host) ------------------------------------------------
+// One per Tier-0 AgentCodeApiV1 method. Kept flat + discriminated so a malformed
+// or out-of-scope request fails the same parse as an unknown one.
+
+const jsonValueSchema: z.ZodType<unknown> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.number(),
+    z.boolean(),
+    z.null(),
+    z.array(jsonValueSchema),
+    z.record(z.string(), jsonValueSchema),
+  ]),
+)
+
+/**
+ * A storage key that cannot collide with Object.prototype machinery.
+ *
+ * `storage.ts` does `data[key] = value` on a JSON.parse result. With key `__proto__`
+ * that hits Object.prototype's setter instead of creating an own property: on a fresh
+ * store the write silently vanishes and keys() never lists it, while on a store whose
+ * JSON literally contained "__proto__" it behaves completely differently. Not
+ * exploitable — Object.prototype is never mutated — but it is silent, state-dependent
+ * data loss, and an extension author would have no way to diagnose it. Reject loudly.
+ */
+const SAFE_STORAGE_KEY = z
+  .string()
+  .min(1)
+  .max(256)
+  .refine(k => k !== '__proto__' && k !== 'constructor' && k !== 'prototype', {
+    message: 'key may not be __proto__, constructor, or prototype',
+  })
+
+export const frameRequestSchema = z.discriminatedUnion('method', [
+  z.object({ method: z.literal('storage.get'), key: SAFE_STORAGE_KEY }),
+  z.object({
+    method: z.literal('storage.set'),
+    key: SAFE_STORAGE_KEY,
+    value: jsonValueSchema,
+  }),
+  z.object({ method: z.literal('storage.delete'), key: SAFE_STORAGE_KEY }),
+  z.object({ method: z.literal('storage.keys') }),
+  z.object({ method: z.literal('ui.close') }),
+  z.object({ method: z.literal('ui.showToast'), message: z.string().min(1).max(2000) }),
+  z.object({ method: z.literal('theme.tokens') }),
+  // Tier-1 observe reads. No arguments — each returns a snapshot. The broker gates
+  // these on the extension's grant before performing (Tier-0 above is ungated).
+  z.object({ method: z.literal('workspace.observe') }),
+  z.object({ method: z.literal('sessions.observe') }),
+  z.object({ method: z.literal('panes.observe') }),
+])
+
+/**
+ * Every request carries a child-minted `id` the host echoes on the reply, so the
+ * extension can correlate responses over the single postMessage channel. A `kind`
+ * tag namespaces our frames away from any other postMessage traffic sharing
+ * `window` — an unrelated message (a library's, a devtools bridge's) fails this
+ * parse and is ignored rather than misread as a request.
+ */
+export const frameRequestEnvelopeSchema = z.object({
+  kind: z.literal('agent-code-ext:request'),
+  id: z.string().min(1).max(200),
+  request: frameRequestSchema,
+})
+
+export type FrameRequest = z.infer<typeof frameRequestSchema>
+export type FrameRequestEnvelope = z.infer<typeof frameRequestEnvelopeSchema>
+
+// --- Replies + pushes (host -> frame) ----------------------------------------
+// These are produced by the trusted host, so they are TYPES, not runtime-parsed
+// schemas — the child validates them only as much as its own SDK chooses to. The
+// host is not a boundary the host must defend against.
+
+export type FrameReply =
+  | { kind: 'agent-code-ext:reply'; id: string; ok: true; result: unknown }
+  | { kind: 'agent-code-ext:reply'; id: string; ok: false; error: string }
+
+/**
+ * Host-initiated messages that are not replies to a request.
+ * - `mount`: the host tells the child which view to render into its document, the
+ *   frame equivalent of calling `ViewMount(element)` in the same-realm model.
+ * - `theme`: theme tokens pushed on change, because the CSS cascade does not cross
+ *   the frame boundary — the same values `api.theme.tokens()` returns.
+ * - `command`: invoke a contributed command's handler INSIDE the frame. After the
+ *   activation model was unified onto the iframe (Group A), the extension's command
+ *   handlers live only in the frame, so the palette/keybind router delivers an
+ *   invocation here rather than running a host-side handler. Unlike a request there
+ *   is no reply — a command is fire-and-forget from the host's side; the frame owns
+ *   the outcome (and reports failures to its own console).
+ */
+export type FramePush =
+  | { kind: 'agent-code-ext:mount'; viewId: string }
+  | { kind: 'agent-code-ext:theme'; tokens: Record<string, string> }
+  | { kind: 'agent-code-ext:command'; commandId: string }
+  // A change NUDGE for a Tier-1 observe topic (workspace/sessions/panes). Carries no
+  // data on purpose: the child re-reads via the grant-gated observe() call, so a
+  // nudge can never leak host state to an extension that lacks the capability — the
+  // re-read would be denied. This makes observe live without duplicating the
+  // snapshot projection or widening what crosses the boundary.
+  | { kind: 'agent-code-ext:event'; topic: string }
+
+// --- Identity ----------------------------------------------------------------
+
+/**
+ * The extension id that owns a frame, derived from its unforgeable origin.
+ *
+ * A frame served from `agent-code-ext://timer/view.html` has origin
+ * `agent-code-ext://timer`; the host part is the extension id. Returns null for
+ * any origin that is not this scheme or whose id does not match the install-time
+ * id grammar — a request from an unexpected origin is dropped, never attributed to
+ * a guessed extension. The grammar is duplicated from manifest.ts/storage.ts on
+ * purpose (each owns the check at its own boundary); a mismatch here would let a
+ * malformed origin address a storage namespace, so the same regex guards it.
+ */
+export function extensionIdFromOrigin(origin: string): string | null {
+  let url: URL
+  try {
+    url = new URL(origin)
+  } catch {
+    return null
+  }
+  if (url.protocol !== 'agent-code-ext:') return null
+  const id = url.hostname
+  return /^[a-z][a-z0-9-]{0,63}$/.test(id) ? id : null
+}
diff --git a/src/renderer/src/apps/host/frameRegistry.ts b/src/renderer/src/apps/host/frameRegistry.ts
new file mode 100644
index 000000000..f2444f824
--- /dev/null
+++ b/src/renderer/src/apps/host/frameRegistry.ts
@@ -0,0 +1,98 @@
+// The bridge from a host command to the extension's LIVE frame (Group A).
+//
+// WHY this exists: after the activation model was unified onto the iframe, an
+// extension runs in exactly one place — its frame — and NOT in the host realm. So
+// "invoke contributed command timer.start" can no longer call a host-side handler
+// (there is none); it must be delivered INTO the frame that is currently showing
+// the extension. The frame is created deep inside a viewBridge component instance,
+// while the command's `run` closure lives in derive.ts with no handle to it. This
+// module is the small, explicit rendezvous between the two: a viewBridge registers
+// its frame's dispatcher here on ready, and derive.ts looks it up when a command
+// fires.
+//
+// WHY a module singleton and not React context: the command `run` closures are
+// built by deriveExtensionCommands (a plain function, not a hook) and invoked from
+// the palette/keybind router, neither of which sits inside the provider tree at the
+// call site. A singleton keyed by extension id is the honest shape; identity is the
+// extension id the frame was minted for.
+
+/** Sends one contributed command id into an extension's frame. */
+type FrameDispatch = (commandId: string) => void
+
+// ── A STACK PER EXTENSION, NOT A SINGLE ENTRY ──
+// This was a `Map<extensionId, dispatch>` whose comment asserted "there is at most
+// one visible frame per extension". The pane path broke that assumption the moment
+// it landed: openExtensionViewInPane always splits a NEW leaf, and a pane and a
+// modal of the same extension are explicitly designed to coexist. So a second frame
+// silently overwrote the first's dispatcher — and because clearFrameDispatch only
+// removes an entry still pointing at the disposing frame, closing the NEWER frame
+// deleted the entry outright while an older live frame was still on screen. The
+// extension then looked dead: dispatchToFrame returned false, and the command
+// handler responded by opening yet another pane.
+//
+// A stack fixes both directions. The most recently readied frame receives commands,
+// which is the one the user just interacted with; when it goes away, the next live
+// frame down inherits, instead of the extension going deaf.
+const dispatchers = new Map<string, FrameDispatch[]>()
+
+// Commands fired while no frame is open. The command opens the extension's view to
+// bring a frame up, and these flush the instant that frame signals ready — so
+// "timer.start" from a cold palette opens the timer AND starts it, rather than
+// silently dropping because the frame did not exist yet. A short-lived buffer, not
+// durable state: if the frame never comes up, the intent is discarded, which is the
+// correct outcome for a UI action nobody is watching.
+const pending = new Map<string, string[]>()
+
+/**
+ * A frame announces it is ready to receive commands. Flushes anything queued for
+ * this extension immediately, in order.
+ */
+export function setFrameDispatch(extensionId: string, dispatch: FrameDispatch): void {
+  const stack = dispatchers.get(extensionId) ?? []
+  // Pushed last = receives commands. Filtered first so a frame that somehow
+  // re-announces readiness moves to the top rather than appearing twice.
+  dispatchers.set(extensionId, [...stack.filter(entry => entry !== dispatch), dispatch])
+
+  const queued = pending.get(extensionId)
+  if (queued && queued.length > 0) {
+    pending.delete(extensionId)
+    for (const commandId of queued) dispatch(commandId)
+  }
+}
+
+/**
+ * A frame is tearing down. Removes only ITS OWN dispatcher, leaving any other live
+ * frame of the same extension registered — so closing one of two open views does
+ * not deafen the survivor, and a slow unmount cannot unregister the frame that
+ * replaced it.
+ */
+export function clearFrameDispatch(extensionId: string, dispatch: FrameDispatch): void {
+  const stack = dispatchers.get(extensionId)
+  if (!stack) return
+  const next = stack.filter(entry => entry !== dispatch)
+  if (next.length === 0) dispatchers.delete(extensionId)
+  else dispatchers.set(extensionId, next)
+}
+
+/**
+ * Send a command into the extension's live frame. Returns false when no frame is
+ * open, so the caller can decide whether to bring one up and queue the command.
+ */
+export function dispatchToFrame(extensionId: string, commandId: string): boolean {
+  const stack = dispatchers.get(extensionId)
+  const dispatch = stack?.[stack.length - 1]
+  if (!dispatch) return false
+  dispatch(commandId)
+  return true
+}
+
+/**
+ * Buffer a command to run as soon as a frame for this extension registers. Caller
+ * is expected to also open the extension's view so a frame actually comes up;
+ * without that the buffer is simply never flushed.
+ */
+export function queuePendingCommand(extensionId: string, commandId: string): void {
+  const queued = pending.get(extensionId)
+  if (queued) queued.push(commandId)
+  else pending.set(extensionId, [commandId])
+}
diff --git a/src/renderer/src/apps/host/viewBridge.tsx b/src/renderer/src/apps/host/viewBridge.tsx
new file mode 100644
index 000000000..c9f1a369d
--- /dev/null
+++ b/src/renderer/src/apps/host/viewBridge.tsx
@@ -0,0 +1,483 @@
+import { useEffect, useRef, useState } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+import { createFrameHost } from '@renderer/apps/host/frameHost'
+import { clearFrameDispatch, setFrameDispatch } from '@renderer/apps/host/frameRegistry'
+import { THEME_CHANGED_EVENT } from '@renderer/app-state/settings/theme'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+
+// How long the host waits for the frame's own boot signal before calling the load
+// failed. Generous: the only thing it races is a frame that will never start, and a
+// premature "failed" on a slow machine is a worse lie than a late one.
+const BOOT_TIMEOUT_MS = 10_000
+
+/**
+ * Record (or clear) an extension's failure on its Settings row.
+ *
+ * WHY these write through the store rather than local component state: the failure
+ * belongs to the EXTENSION, not to this view instance. Settings lists it next to the
+ * extension long after the frame that produced it was closed, and a second frame for
+ * the same extension must not show a stale failure from the first.
+ */
+function reportFailure(extensionId: string, message: string): void {
+  const state = useAppStore.getState()
+  const name =
+    state.installedExtensions.find(candidate => candidate.manifest.id === extensionId)?.manifest
+      .name ?? extensionId
+  state.setExtensionFailures([
+    ...state.extensionFailures.filter(failure => failure.id !== extensionId),
+    { id: extensionId, name, error: message },
+  ])
+}
+
+function clearFailure(extensionId: string): void {
+  const state = useAppStore.getState()
+  if (!state.extensionFailures.some(failure => failure.id === extensionId)) return
+  state.setExtensionFailures(state.extensionFailures.filter(failure => failure.id !== extensionId))
+}
+
+/**
+ * Adapts a contributed view into the `AppDefinition.Component` shape — the iframe
+ * model (WS4, Decision A).
+ *
+ * This is the ENTIRE bridge between the host's React world and the extension. It
+ * was the same-realm `mount(element)` call the DOM-level ViewMount contract was
+ * designed around; that contract is exactly what let this become an iframe without
+ * touching the extension: the extension still exports `activate(context)` and calls
+ * `registerView(id, mount)`, but now that runs in the CHILD document (see
+ * frameDocument.ts's bootstrap), and the parent only frames it, brokers its Tier-0
+ * API over postMessage (frameHost.ts), and signals which view to mount.
+ *
+ * WHY the parent never imports or activates the extension: an iframe at the
+ * extension's own origin cannot reach `window.api`, the parent DOM, or another
+ * extension, so the module MUST run on the far side of that boundary. Commands run
+ * there too — the frame is the ONE place an extension executes, which is what ended
+ * the split-brain where a palette command drove a different instance than the
+ * visible view.
+ *
+ * RUNTIME NOTE: this is the WS4 flip that can only be validated in a live frame —
+ * the iframe load, the postMessage handshake, and the child CSP are not
+ * typecheckable. A real extension view rendering is its acceptance test.
+ */
+function buildViewComponent(
+  extensionId: string,
+  viewId: string,
+  // The installed bundle's identity. Not read for behaviour — it is part of the
+  // CACHE KEY and of the frame URL, which is what makes an update replace the
+  // running frame. See viewComponentFor.
+  bundleRevision: string,
+  // When true (a PANE host), the iframe FILLS its container rather than sizing to
+  // the extension's reported content height. A modal floats and should hug its view
+  // (content-height); a pane is a fixed tile and the view should fill it edge to
+  // edge. The child still reports its size — we simply ignore it for height in fill
+  // mode. Defaults false so the modal path is unchanged.
+  fill = false,
+): (props: { api: AgentCodeApiV1 }) => JSX.Element {
+  return function ExtensionView({ api }: { api: AgentCodeApiV1 }) {
+    // Read the display name from the store rather than closing over a manifest.
+    // The component is cached by identity (see viewComponentFor), so a captured
+    // manifest would go stale the first time the extension was updated — and the
+    // name is the only manifest field this component ever needed.
+    const displayName = useAppStore(
+      state =>
+        state.installedExtensions.find(candidate => candidate.manifest.id === extensionId)
+          ?.manifest.name ?? extensionId,
+    )
+    const iframeRef = useRef<HTMLIFrameElement | null>(null)
+    const [status, setStatus] = useState<'loading' | 'ready' | 'failed'>('loading')
+    // Content-driven height. The child (frameDocument.ts) measures its own view and
+    // posts its natural height; we size the iframe to it so the auto-height host
+    // modal grows to fit the extension instead of clamping it. Null until the first
+    // report — the iframe falls back to a minimum so it is never a zero-height strip.
+    const [contentHeight, setContentHeight] = useState<number | null>(null)
+    // Content-driven WIDTH, the sibling of the height above: a fixed-width extension
+    // (a game canvas) reports its natural width and the modal grows to fit it, while
+    // a small extension stays snug. Null until the first report → the iframe falls
+    // back to filling its container (the modal's own width).
+    const [contentWidth, setContentWidth] = useState<number | null>(null)
+
+    // Viewport, tracked so an oversized extension can be SCALED to fit (see `scale`).
+    const [viewport, setViewport] = useState(() => ({
+      w: typeof window === 'undefined' ? 1280 : window.innerWidth,
+      h: typeof window === 'undefined' ? 800 : window.innerHeight,
+    }))
+    useEffect(() => {
+      if (fill) return
+      const onResize = () => setViewport({ w: window.innerWidth, h: window.innerHeight })
+      window.addEventListener('resize', onResize)
+      return () => window.removeEventListener('resize', onResize)
+    }, [])
+
+    useEffect(() => {
+      const iframe = iframeRef.current
+      if (!iframe) {
+        setStatus('failed')
+        return
+      }
+
+      // The broker: the ONLY thing that can both hear this frame and perform a
+      // capability. Attached before the src is set so no early message is missed.
+      const frameHost = createFrameHost({ iframe, extensionId, api })
+
+      // This frame's command dispatcher, published to the registry once the child
+      // signals ready. derive.ts looks it up to route a contributed command's
+      // invocation into THIS frame — the one place the extension actually runs.
+      const dispatch = (commandId: string) =>
+        frameHost.push({ kind: 'agent-code-ext:command', commandId })
+
+      // Presentational + lifecycle side-channels, kept OUT of frameHost: neither a
+      // resize nor a ready signal is a capability request (they perform nothing,
+      // carry no authority), so they do not belong in the schema-validated request
+      // path. Authenticated the same way frameHost authenticates requests — by
+      // window reference, which no other frame can forge.
+      const expectedChildOrigin = `agent-code-ext://${extensionId}`
+      const onChildMessage = (event: MessageEvent) => {
+        // TWO gates, matching frameHost — source AND origin. This listener previously
+        // checked only the window reference, and claimed parity with frameHost while
+        // having one fewer check. `iframe.contentWindow` is an identity-stable
+        // WindowProxy across navigations, so source alone survives a frame navigating
+        // itself: a document at any other agent-code-ext:// origin landing in this frame
+        // could still fire `ready` and publish a command dispatcher under THIS
+        // extension's id. Origin is the gate that actually distinguishes them.
+        if (event.source !== iframe.contentWindow) return
+        if (event.origin !== expectedChildOrigin) return
+        const data = event.data as
+          | { kind?: unknown; height?: unknown; width?: unknown; message?: unknown }
+          | null
+        if (!data) return
+        if (data.kind === 'agent-code-ext:resize') {
+          // Clamped so a buggy or hostile child cannot drive the modal past the
+          // viewport or collapse it to nothing.
+          if (typeof data.height !== 'number' || !Number.isFinite(data.height)) return
+          setContentHeight(Math.min(Math.max(Math.round(data.height), 80), 1400))
+          if (typeof data.width === 'number' && Number.isFinite(data.width)) {
+            setContentWidth(Math.min(Math.max(Math.round(data.width), 240), 1200))
+          }
+        } else if (data.kind === 'agent-code-ext:boot') {
+          // The frame document is executing. This — not the iframe's own 'load'
+          // event — is what proves the load succeeded: an iframe fires 'load' for
+          // an HTTP error body exactly as it does for a real page, and never fires
+          // 'error' for one, so onError below can only ever catch a network-layer
+          // failure. Without this signal a 404 from the scheme handler showed as a
+          // blank frame stuck in 'ready' forever.
+          if (bootTimer !== null) {
+            clearTimeout(bootTimer)
+            bootTimer = null
+          }
+          setStatus('ready')
+        } else if (data.kind === 'agent-code-ext:escape') {
+          // The frame saw an unhandled Escape. Close the view, which is what Escape
+          // does everywhere else in the app — a modal's own Escape handler and a
+          // pane's Cmd+W both end at this same call. Routed through `api.ui.close`
+          // rather than a local close so the modal and pane hosts keep their single
+          // shared definition of what closing means.
+          void api.ui.close()
+        } else if (data.kind === 'agent-code-ext:error') {
+          // activate() or the dynamic import threw inside the frame. The frame is
+          // the only place that can observe it — the extension does not run in this
+          // realm — so it reports here and we surface it on the Settings row.
+          setStatus('failed')
+          reportFailure(
+            extensionId,
+            typeof data.message === 'string' ? data.message : 'Extension failed to start.',
+          )
+        } else if (data.kind === 'agent-code-ext:ready') {
+          // activate() has RESOLVED — command handlers now exist, so it is safe to
+          // publish the dispatcher and flush any queued commands. Distinct from
+          // 'boot', which only says the document started.
+          setFrameDispatch(extensionId, dispatch)
+          // Cleared HERE and not on 'boot'. Failures are keyed by extension, and two
+          // frames of one extension can be open at once — so a second frame merely
+          // STARTING would wipe a real activate() failure the first had just
+          // reported. Only a completed activation is evidence the extension is well.
+          clearFailure(extensionId)
+        }
+      }
+      window.addEventListener('message', onChildMessage)
+
+      // Backstop for every failure that produces no message at all: a 404/403 body,
+      // a CSP violation that blocks the bootstrap, a syntax error in it. Generous
+      // on purpose — this races nothing but a broken frame, and a false "failed"
+      // on a slow machine would be worse than a late one.
+      let bootTimer: ReturnType<typeof setTimeout> | null = setTimeout(() => {
+        bootTimer = null
+        setStatus(current => (current === 'loading' ? 'failed' : current))
+        reportFailure(
+          extensionId,
+          'The extension frame did not start. Its bundle may be missing or blocked.',
+        )
+      }, BOOT_TIMEOUT_MS)
+
+      // Live observe: nudge the frame when the workspace changes, for each observe
+      // topic the extension was granted, so its api.*.subscribe listeners re-read.
+      // The nudge carries no data — the child re-reads via the grant-gated observe()
+      // — so this cannot leak state to an ungranted extension; gating the SUBSCRIPTION
+      // here is only to avoid waking a frame that could not read anyway. Coalesced so
+      // a burst of store writes becomes one nudge, not one per write.
+      let storeUnsub: (() => void) | null = null
+      let observeDisposed = false
+      let nudgeTimer: ReturnType<typeof setTimeout> | null = null
+      // Reuses the broker's already-resolved grant instead of issuing a second IPC.
+      // Each call recomputes the bundle hash in main, so the duplicate doubled that
+      // work on every single frame open.
+      void frameHost.granted.then(granted => {
+        if (observeDisposed) return
+        const topics = (
+          [
+            ['workspace.observe', 'workspace'],
+            ['sessions.observe', 'sessions'],
+            ['panes.observe', 'panes'],
+          ] as const
+        )
+          .filter(([cap]) => granted.includes(cap))
+          .map(([, topic]) => topic)
+        if (topics.length === 0) return
+        storeUnsub = useAppStore.subscribe(
+          state => state.workspaceState,
+          () => {
+            if (nudgeTimer) return
+            nudgeTimer = setTimeout(() => {
+              nudgeTimer = null
+              for (const topic of topics) frameHost.push({ kind: 'agent-code-ext:event', topic })
+            }, 120)
+          },
+        )
+      })
+
+      const pushTheme = () => {
+        // The CSS cascade does not cross the frame boundary, so tokens are pushed.
+        void api.theme.tokens().then(tokens =>
+          frameHost.push({ kind: 'agent-code-ext:theme', tokens }),
+        )
+      }
+
+      const onLoad = () => {
+        // Deliberately does NOT set 'ready' — see the boot handler above. This
+        // fires for an error body too, so treating it as success is what made the
+        // failure state unreachable.
+        //
+        // THEME BEFORE MOUNT — the ordering is load-bearing.
+        //
+        // Previously mount was pushed synchronously and the theme followed a microtask
+        // later (tokens() is async), so the view rendered against variables that did not
+        // exist yet and every extension had to carry its own fallback palette to avoid a
+        // flash of unstyled content. That is why extensions ended up re-declaring the
+        // whole token set locally — the platform gave them no moment at which the theme
+        // was guaranteed present.
+        //
+        // Pushing theme first, then mount, closes that window: postMessage preserves
+        // order, so by the time the child mounts, --theme-* is already set on its
+        // documentElement. Extensions can now write var(--theme-canvas) bare.
+        //
+        // A theme failure must never prevent the view from mounting, hence the catch:
+        // an unthemed extension is a bug, an unmounted one is a broken product.
+        void api.theme
+          .tokens()
+          .then(tokens => frameHost.push({ kind: 'agent-code-ext:theme', tokens }))
+          .catch(() => {})
+          .finally(() => frameHost.push({ kind: 'agent-code-ext:mount', viewId }))
+      }
+      // A frame that cannot even load its document (bad scheme response, blocked
+      // by CSP) fails visibly rather than showing an indefinite spinner.
+      const onError = () => setStatus('failed')
+
+      iframe.addEventListener('load', onLoad)
+      iframe.addEventListener('error', onError)
+      window.addEventListener(THEME_CHANGED_EVENT, pushTheme)
+
+      // parentOrigin is passed so the child posts its replies back to THIS origin
+      // only, never '*'. location.origin is http://localhost in dev and file://
+      // in prod; the child cannot know it otherwise across the boundary.
+      // `rev` is not read by the frame document — it exists so the URL CHANGES when
+      // the installed bundle changes. Without it, an update left every open pane
+      // executing the pre-update code indefinitely: the effect is mount-once, the
+      // component is cached by identity, and the URL was constant, so nothing about
+      // a reinstall reached a live frame. Worse, install re-binds the grant to the
+      // new bytes, so the stale frame would start failing capability calls it had
+      // been holding.
+      iframe.src =
+        `agent-code-ext://${extensionId}/__agent-code-frame__.html` +
+        `?view=${encodeURIComponent(viewId)}` +
+        `&rev=${encodeURIComponent(bundleRevision)}`
+
+      return () => {
+        iframe.removeEventListener('load', onLoad)
+        iframe.removeEventListener('error', onError)
+        window.removeEventListener('message', onChildMessage)
+        window.removeEventListener(THEME_CHANGED_EVENT, pushTheme)
+        observeDisposed = true
+        if (bootTimer !== null) clearTimeout(bootTimer)
+        if (nudgeTimer) clearTimeout(nudgeTimer)
+        storeUnsub?.()
+        clearFrameDispatch(extensionId, dispatch)
+        frameHost.dispose()
+        // Navigate the frame away so any timers/listeners inside it are torn down
+        // by the browser — the frame model's equivalent of disposing the mount.
+        iframe.src = 'about:blank'
+      }
+      // Mount-once: entry and viewId are fixed for this component's lifetime.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    // ── FIT AN OVERSIZED EXTENSION TO THE WINDOW ──
+    //
+    // An extension with a FIXED natural size — a game canvas is the motivating case —
+    // reports e.g. 892×652. That fits a normal window, but on a short one the modal
+    // previously CLIPPED it: DialogContent has no maxHeight and is `overflow-hidden`,
+    // so the bottom of the game simply vanished with no scrollbar and no way to reach
+    // the action buttons.
+    //
+    // Scaling rather than scrolling, because the content is a single fixed-aspect
+    // surface: a scrollbar on a game is worse than a slightly smaller game, and
+    // clipping is worse than both.
+    //
+    // This MUST live host-side. The obvious alternative — have the extension size
+    // itself in vw/vh — is a trap: those units resolve against the IFRAME's viewport,
+    // which the host sets from the content's reported size, so the extension's size
+    // would depend on its own size. That is exactly the resize feedback loop
+    // frameDocument.ts's measurement is carefully built to avoid.
+    //
+    // Budgets leave room for the modal's own chrome and the scrim margin.
+    const scale =
+      fill || !contentWidth || !contentHeight
+        ? 1
+        : Math.min(1, (viewport.w * 0.9) / contentWidth, (viewport.h * 0.86) / contentHeight)
+
+    // The wrapper must occupy the SCALED footprint, otherwise the auto-sized modal
+    // reserves room for the unscaled iframe and the game floats in dead space.
+    const scaledBox =
+      !fill && status === 'ready' && contentWidth && contentHeight
+        ? { width: contentWidth * scale, height: contentHeight * scale }
+        : undefined
+
+    return (
+      <div
+        className={fill ? 'relative h-full w-full' : 'relative min-h-[120px]'}
+        style={scaledBox}
+      >
+        {status === 'loading' ? (
+          <div className="px-6 py-8 text-[12px] text-muted">Loading {displayName}…</div>
+        ) : null}
+        {status === 'failed' ? (
+          <div className="px-6 py-8">
+            <div className="text-[13px] text-ink">{displayName} failed to start</div>
+            <div className="mt-1 text-[12px] text-muted">
+              The extension frame could not be loaded.
+            </div>
+          </div>
+        ) : null}
+        {/* Always present so the ref exists before the effect runs.
+            ── THE SANDBOX ATTRIBUTE IS LOAD-BEARING ──
+            An earlier comment here claimed `sandbox` could not be used because it would
+            give the frame an opaque "null" origin and break the origin-derived identity
+            the broker depends on. That is only true WITHOUT `allow-same-origin`.
+            With it, the document keeps its agent-code-ext://<id> origin — so event.origin
+            and every identity check are untouched — while the other flags stay off.
+
+            What staying off buys, none of which CSP can do:
+              - no allow-popups        → window.open() is dead. This was a real egress
+                                         channel: no CSP directive governs window.open
+                                         (navigate-to was never shipped), so a Tier-0
+                                         extension could exfiltrate storage to any URL
+                                         via the OS browser with no consent prompt.
+              - no allow-top-navigation → cannot navigate the whole app away.
+              - no allow-modals         → cannot wedge the renderer with alert()/print().
+              - no allow-forms          → closes the <form target=_blank> egress variant.
+              - no allow-downloads      → closes download-based exfiltration.
+
+            The usual objection — that a frame with both allow-scripts and
+            allow-same-origin can strip its own sandbox — requires the child to be
+            same-origin with the EMBEDDER. Here it is cross-origin to the host, so it
+            cannot reach the <iframe> element at all.
+
+            Enforcing here rather than in setWindowOpenHandler is deliberate: Electron's
+            HandlerDetails carries no `frame` field, and `referrer` is suppressible with
+            window.open(url, '_blank', 'noreferrer'), so main cannot reliably identify
+            the initiating frame. The attribute is the only place this is decidable. */}
+        <iframe
+          ref={iframeRef}
+          sandbox="allow-scripts allow-same-origin"
+          title={displayName}
+          style={{
+            display: status === 'ready' ? 'block' : 'none',
+            border: 'none',
+            // Pane (fill): fill the tile in both axes. Modal: a definite pixel width
+            // once reported (so a content-width modal wraps it), else 100% of the
+            // modal's own width until the first report.
+            width: fill ? '100%' : contentWidth ?? '100%',
+            // Modal: a definite pixel height once the child reports its content size —
+            // that is what lets the auto-size modal grow to fit. Before the first
+            // report we use the floor, never '100%': '100%' of an auto parent is what
+            // collapsed the frame to a strip.
+            height: fill ? '100%' : contentHeight ?? 120,
+            minHeight: fill ? undefined : 120,
+            // The iframe keeps its NATURAL pixel size and is scaled visually, so the
+            // extension's own layout never changes and it never learns it was resized
+            // (which would re-trigger the content-size report). Origin top-left so the
+            // scaled box lines up with the wrapper computed above.
+            transform: scale === 1 ? undefined : `scale(${scale})`,
+            transformOrigin: 'top left',
+          }}
+        />
+      </div>
+    )
+  }
+}
+
+// ── COMPONENT IDENTITY IS CACHED, AND THAT IS A CORRECTNESS REQUIREMENT ──
+//
+// React remounts on component IDENTITY, not on props. `deriveAppDefinitions` and
+// `ExtensionViewLeaf` both call this while deriving from the installed list, and
+// that list is refetched on every install, update and remove — so minting a fresh
+// closure per call meant that installing ANY extension unmounted every open
+// extension view, destroyed its iframe, and re-ran activate() in a new document.
+// A running timer reset because an unrelated extension was installed.
+//
+// Keying on the identity triple is what makes the derivation idempotent. Nothing
+// else varies the component: `fill` picks the layout, and the manifest name is
+// read from the store inside the component precisely so it need not be a key.
+//
+// The map is bounded by (installed extensions x contributed views x 2), which is
+// the same order as the ledger itself, and entries stay valid across an uninstall
+// + reinstall of the same id — the component holds no manifest, only ids.
+const componentCache = new Map<string, (props: { api: AgentCodeApiV1 }) => JSX.Element>()
+
+/**
+ * What makes one installed version of a view distinct from another.
+ *
+ * `sha256` alone would be ideal, but it is provenance and can legitimately repeat
+ * (reinstalling the same tarball); `version` alone is author-controlled and often
+ * unchanged during development. Together they change whenever the installed bytes
+ * or the declared version do, which is exactly when a running frame is stale.
+ */
+function bundleRevisionOf(entry: ExtensionListEntry): string {
+  return `${entry.manifest.version}-${entry.sha256.slice(0, 12)}`
+}
+
+/**
+ * The host-side component for one contributed view: a sandboxed iframe at the
+ * extension's origin plus the postMessage broker for it.
+ *
+ * `fill` true means a PANE host — the iframe fills its tile instead of sizing to
+ * the extension's reported content height, which is what a floating modal does.
+ */
+export function viewComponentFor(
+  entry: ExtensionListEntry,
+  viewId: string,
+  fill = false,
+): (props: { api: AgentCodeApiV1 }) => JSX.Element {
+  const revision = bundleRevisionOf(entry)
+  // The revision is part of the key, so an UPDATE yields a different component
+  // identity and React remounts the frame against the new bundle — while a mere
+  // list refresh (install of some other extension, a failed-then-retried list)
+  // yields the same key and leaves running views untouched. Those two cases were
+  // previously indistinguishable: keying on identity alone made every refresh
+  // harmless but also made updates invisible.
+  const key = `${entry.manifest.id}\u0000${viewId}\u0000${fill}\u0000${revision}`
+  const cached = componentCache.get(key)
+  if (cached) return cached
+  const built = buildViewComponent(entry.manifest.id, viewId, revision, fill)
+  componentCache.set(key, built)
+  return built
+}
diff --git a/src/renderer/src/apps/surfaces/AppHostSurface.tsx b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
new file mode 100644
index 000000000..5e4ebf220
--- /dev/null
+++ b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
@@ -0,0 +1,93 @@
+import { useCallback, useMemo } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import { createAppHostApi } from '@renderer/apps/api/createAppHostApi'
+import { deriveAppDefinitions } from '@renderer/apps/host/derive'
+import { Dialog, DialogContent, DialogTitle } from '@renderer/components/ui/dialog'
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
+
+import type { AppDefinition } from '@renderer/apps/types'
+
+/**
+ * The single surface entry that hosts every extension view.
+ *
+ * WHY DialogContent rather than a hand-rolled shell: it mounts
+ * `data-agent-code-interaction-owner="app"` for exactly the interval Radix traps
+ * focus. Seven separate consumers query that marker synchronously — the keybind
+ * router, the palette's native-menu guard, the global editor's Escape handler,
+ * the composer Enter registry, type-to-focus, paste-to-focus, and the native
+ * dictation hotkey. Without it, typing in an extension's input can leak Enter
+ * and paste into a background agent composer, and a native menu click can mutate
+ * the workspace underneath. `components/ui/README.md` records that exact failure
+ * from the old hand-rolled composer guards. Hosting extensions inside the
+ * primitive means they get all seven protections and cannot forget one.
+ */
+export function AppHostSurface() {
+  const openAppId = useAppStore(state => state.openAppId)
+  const installed = useAppStore(state => state.installedExtensions)
+
+  // Derived per render from the store rather than a module-scope map. The
+  // previous version built `APP_BY_ID` once at import time, which meant a newly
+  // installed extension could not open until a reload.
+  const definitions = useMemo(() => deriveAppDefinitions(installed), [installed])
+
+  const definition = openAppId
+    ? definitions.find(candidate => candidate.id === openAppId)
+    : undefined
+
+  // An unknown id degrades to closed, deliberately unlike
+  // `providers/registry.renderer.ts`, which throws on an unknown pane kind — that
+  // throw is correct there, because a pane with no renderer is a broken
+  // workspace. It is wrong here: `openAppId` routinely holds a stale id after an
+  // extension is uninstalled, and throwing inside a surface App.tsx mounts
+  // unconditionally would take down the whole renderer.
+  if (!definition) return null
+
+  return <OpenExtensionView definition={definition} />
+}
+
+function OpenExtensionView({ definition }: { definition: AppDefinition }) {
+  const closeApp = useAppStore(state => state.closeApp)
+  const { showToast } = useGlobalToast()
+
+  const api = useMemo(
+    () =>
+      createAppHostApi({
+        // The view id is namespaced `<extensionId>.<view>`, and storage is keyed
+        // by EXTENSION, not by view — two views of one extension must share
+        // state, and `timer.main` must not get a different namespace from
+        // `timer`.
+        extensionId: definition.id.split('.')[0] ?? definition.id,
+        showToast,
+        closeSurface: () => closeApp(),
+      }),
+    [definition.id, showToast, closeApp],
+  )
+
+  const onOpenChange = useCallback(
+    (open: boolean) => {
+      if (!open) closeApp()
+    },
+    [closeApp],
+  )
+
+  return (
+    <Dialog open onOpenChange={onOpenChange}>
+      {/* Content-width, not a fixed 560: the frame reports its natural size and the
+          iframe takes a definite width/height, so a small extension stays snug while a
+          large one (a game canvas) grows the modal up to the cap. Inline style beats
+          the primitive's own `w-[…]` utility. */}
+      <DialogContent
+        showCloseButton
+        className="overflow-hidden"
+        style={{ width: 'auto', maxWidth: 'min(1160px, 94vw)' }}
+      >
+        {/* Radix requires an accessible title on every Dialog; visually hidden
+            because an extension owns its own header treatment. Omitting it logs
+            a console error and leaves the dialog unlabelled for screen readers. */}
+        <DialogTitle className="sr-only">{definition.title}</DialogTitle>
+        <definition.Component api={api} />
+      </DialogContent>
+    </Dialog>
+  )
+}
diff --git a/src/renderer/src/apps/types.ts b/src/renderer/src/apps/types.ts
new file mode 100644
index 000000000..5d3cbce89
--- /dev/null
+++ b/src/renderer/src/apps/types.ts
@@ -0,0 +1,80 @@
+import type { ComponentType } from 'react'
+
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+/**
+ * One contributed extension view, resolved into something a host shell can render.
+ *
+ * WHY this type still exists after extensions moved into iframes: it is the seam
+ * between "what a manifest declared" and "what a surface mounts". `derive.ts`
+ * produces one of these per `contributes.views` entry, reading ONLY the manifest —
+ * no bundle is imported to build it. AppHostSurface (modal) and ExtensionViewLeaf
+ * (pane) both consume it, which is what lets the same view render in either shell
+ * with nothing but the surrounding chrome differing.
+ *
+ * WHY every field except `Component` is JSON-expressible: they all come straight
+ * off the manifest. `Component` is the one derived member, and it is a closure over
+ * the iframe bridge rather than extension code — the extension itself never crosses
+ * into this realm.
+ *
+ * The failure to avoid: adding a host-only field here — `getWorkspace: () =>
+ * Workspace`, a store selector, a React context, anything not serializable. If a
+ * view needs a capability it belongs in `AgentCodeApiV1`, brokered over
+ * postMessage, not smuggled in beside the component.
+ */
+export type AppDefinition = {
+  /**
+   * The contributed view id, `<extensionId>.<view>`. Also the value held in
+   * `openAppId` while the view is open as a modal.
+   *
+   * The extension-id half is what storage is namespaced by, so renaming it orphans
+   * saved state — treat as permanent. The grammar is enforced by main, at install
+   * (`main/extensions/manifest.ts`), because that is where a hostile manifest first
+   * arrives and where the id becomes a filesystem path. It is deliberately NOT
+   * re-checked here: a second copy of the rule is a second thing to drift.
+   */
+  id: string
+  title: string
+  /**
+   * REQUIRED and non-empty: this string becomes the palette command's description,
+   * and `buildCommandRegistry` throws on a blank description. A missing one is a
+   * launch crash rather than a lint warning, so the type makes it non-optional.
+   * `derive.ts` falls back to the extension's own description for this reason.
+   */
+  description: string
+  keywords?: string[]
+  /**
+   * The view's host-side component: an iframe at the extension's origin, plus the
+   * postMessage broker for it. Built by `viewComponentFor`.
+   *
+   * WHY exactly one prop, unlike `SurfaceEntry.Component` which deliberately takes
+   * none: for a first-party surface propless is right, because the surface can read
+   * the store directly. Here the prop IS the boundary — `api` is the only thing the
+   * far side of the frame is permitted to depend on.
+   */
+  Component: ComponentType<{ api: AgentCodeApiV1 }>
+}
+
+/**
+ * An extension whose frame could not start, surfaced on its Settings row.
+ *
+ * WHY failures are a VALUE in the store rather than a throw: an extension is
+ * third-party code loaded at runtime. One that fails to import, exports no
+ * `activate`, or throws inside it must leave every other extension running and must
+ * never be able to blank the renderer.
+ *
+ * WHY this type lives here and not beside a host object: it used to be produced by
+ * a host-realm `ExtensionHost` that imported and activated extension modules in the
+ * renderer's own realm. That path is gone — an extension now runs only inside its
+ * frame — so failures are REPORTED BY THE FRAME over postMessage and collected by
+ * viewBridge. The type outlived its producer because the Settings row still needs
+ * it; the producer is now the sandbox, which is the point.
+ */
+export type ExtensionFailure = {
+  /** The extension id, matching `InstalledExtension.manifest.id`. */
+  id: string
+  /** Display name, so a row can be labelled before the manifest is looked up. */
+  name: string
+  /** The message shown under the extension's Settings row. */
+  error: string
+}
diff --git a/src/renderer/src/apps/ui/AppsSettingsRow.tsx b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
new file mode 100644
index 000000000..cc89039f9
--- /dev/null
+++ b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
@@ -0,0 +1,307 @@
+import { useCallback, useEffect, useState } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+
+import type { ExtensionListEntry } from '@shared/types/extensions'
+
+/**
+ * Settings → Extensions. Install from a GitHub repository, list what is installed,
+ * remove.
+ *
+ * WHY this row owns its own state and IPC rather than reading a store: same
+ * self-subscribing marker pattern as CliUpdateBehaviorRow and DictationApiKeyRow —
+ * the truth lives in main (`extensions.json` plus the bundle directories), not in
+ * the renderer's Settings, and mirroring it into zustand-persist would put
+ * third-party-derived data into the blob whose version bumps have black-screened
+ * launch twice (#249).
+ *
+ * WHY installing is deliberately a paste-a-repo box and not a browsable directory:
+ * there is no registry to browse, and inventing one would mean hosting an index
+ * before a single extension exists. The repo name IS the trust decision — the user
+ * typing `owner/repo` is the consent step, which is why there is no second
+ * confirmation dialog for a first install.
+ */
+export function AppsSettingsRow() {
+  const [entries, setEntries] = useState<ExtensionListEntry[] | null>(null)
+  const [repo, setRepo] = useState('')
+  const [busy, setBusy] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+
+  // Push the refreshed list into the store as well as local state: the palette
+  // and the view host read from the store, so an install that only updated this
+  // component would add an extension nobody else could see until a reload.
+  const setInstalledExtensions = useAppStore(state => state.setInstalledExtensions)
+  const failures = useAppStore(state => state.extensionFailures)
+
+  const refresh = useCallback(async () => {
+    try {
+      const listed = await window.api.extensionsList()
+      setEntries(listed)
+      setInstalledExtensions(listed)
+      return true
+    } catch (listError) {
+      // A failed list is not the same as an empty list, and rendering "no
+      // extensions" over an IPC failure would be a lie the user acts on. The STORE
+      // is deliberately left untouched for the same reason — but see `remove`,
+      // where leaving it untouched has a consequence this comment used to miss.
+      setEntries([])
+      setError(listError instanceof Error ? listError.message : String(listError))
+      return false
+    }
+  }, [setInstalledExtensions])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  // `target` is explicit rather than always read from `repo` so the Update button
+  // can install a specific entry's repo. The previous version did
+  // `setRepo(entry.repo); void install()`, but `setRepo` is async and `install`
+  // closed over the OLD `repo`, so Update installed the empty/last-typed value —
+  // the no-op bug. Passing the target directly removes the closure dependency.
+  const install = useCallback(
+    async (target?: string) => {
+      const repoTarget = (target ?? repo).trim()
+      if (!repoTarget || busy) return
+
+      setBusy(true)
+      setError(null)
+      setNotice(null)
+      try {
+        const result = await window.api.extensionsInstall(repoTarget)
+        if (result.ok) {
+          if (target === undefined) setRepo('')
+          setNotice(`Installed ${result.entry.manifest.name} ${result.entry.manifest.version}`)
+        } else {
+          setError(result.error)
+        }
+      } catch (installError) {
+        // installExtension returns {ok:false} for every anticipated failure, so
+        // reaching here means the IPC itself broke — worth showing distinctly rather
+        // than swallowing.
+        setError(installError instanceof Error ? installError.message : String(installError))
+      } finally {
+        setBusy(false)
+        await refresh()
+      }
+    },
+    [repo, busy, refresh],
+  )
+
+  // Update = reinstall over the existing bundle (install.ts does rm+rename).
+  //
+  // There is deliberately no host-side deactivate() call here any more. The old one
+  // read as a safeguard but was a no-op: it drove ExtensionHost's loaded-module map,
+  // which is always empty under the frame model because the extension never runs in
+  // this realm. A live frame keeps running against the replaced bundle until it is
+  // closed; its own pagehide handler runs deactivate() at that point, which is the
+  // only place the module actually exists.
+  const update = useCallback(
+    async (entry: ExtensionListEntry) => {
+      // Dispatch on how it was installed. A local extension's `repo` is an absolute
+      // folder path, so feeding it to the GitHub installer failed normalizeRepo every
+      // single time — and "rebuild, click Update" is the entire dev loop this install
+      // path exists for, so Update was broken for exactly the users who need it most.
+      if (entry.origin === 'local') {
+        setBusy(true)
+        setError(null)
+        setNotice(null)
+        try {
+          const result = await window.api.extensionsUpdateLocal(entry.manifest.id)
+          if (result.ok) {
+            setNotice(`Reloaded ${result.entry.manifest.name} ${result.entry.manifest.version}`)
+          } else {
+            setError(result.error)
+          }
+        } catch (updateError) {
+          setError(updateError instanceof Error ? updateError.message : String(updateError))
+        } finally {
+          setBusy(false)
+          await refresh()
+        }
+        return
+      }
+      await install(entry.repo)
+    },
+    [install, refresh],
+  )
+
+  const remove = useCallback(
+    async (entry: ExtensionListEntry) => {
+      if (busy) return
+      setBusy(true)
+      setError(null)
+      setNotice(null)
+      try {
+        await window.api.extensionsRemove(entry.manifest.id)
+        setNotice(`Removed ${entry.manifest.name}`)
+      } catch (removeError) {
+        setError(removeError instanceof Error ? removeError.message : String(removeError))
+      } finally {
+        setBusy(false)
+        // ── TEARDOWN MUST NOT DEPEND ON THE REFRESH SUCCEEDING ──
+        // Unmounting a removed extension's live frames is a side effect of the
+        // store losing its entry, and `refresh` deliberately leaves the store
+        // untouched when the list IPC fails. So one failed list after a successful
+        // remove left the pane mounted, the iframe running, and frameHost's grant
+        // promise still resolved to the full capability set — against a bundle main
+        // had already deleted and a grant it had already revoked. The frame went on
+        // answering sessions.observe for an uninstalled extension.
+        //
+        // Dropping the row locally is not a guess: `extensionsRemove` resolved, so
+        // the extension IS gone. Refresh is how we learn about everything else.
+        if (!(await refresh())) {
+          setInstalledExtensions(
+            (entries ?? []).filter(candidate => candidate.manifest.id !== entry.manifest.id),
+          )
+        }
+      }
+    },
+    [busy, entries, refresh, setInstalledExtensions],
+  )
+
+  // "Load unpacked" — install from a local folder via the native picker (main
+  // opens it). The dev loop for an unpublished extension: rebuild, click, reload —
+  // instead of cutting a GitHub release for every change.
+  const loadFromFolder = useCallback(async () => {
+    if (busy) return
+    setBusy(true)
+    setError(null)
+    setNotice(null)
+    try {
+      const result = await window.api.extensionsInstallPath()
+      if (result.ok) {
+        setNotice(`Loaded ${result.entry.manifest.name} ${result.entry.manifest.version}`)
+        await refresh()
+      } else {
+        setError(result.error)
+      }
+    } catch (loadError) {
+      setError(loadError instanceof Error ? loadError.message : String(loadError))
+    } finally {
+      setBusy(false)
+    }
+  }, [busy, refresh])
+
+  return (
+    <div className="flex flex-col gap-3">
+      <div className="flex gap-2">
+        <input
+          value={repo}
+          onChange={event => setRepo(event.target.value)}
+          onKeyDown={event => {
+            if (event.key === 'Enter') {
+              // Stop the Enter reaching Settings' own handlers or, worse, a
+              // background composer. The interaction-ownership marker on the
+              // Settings takeover root covers the global routers, but the local
+              // keydown still needs to not bubble into Settings itself.
+              event.preventDefault()
+              event.stopPropagation()
+              void install()
+            }
+          }}
+          placeholder="owner/repo or a github.com URL"
+          spellCheck={false}
+          autoCapitalize="off"
+          autoCorrect="off"
+          disabled={busy}
+          className="min-w-0 flex-1 border border-input-border bg-input-bg px-2 py-1.5 text-[13px] text-ink outline-none placeholder:text-input-placeholder focus:border-input-border-focus disabled:opacity-50"
+        />
+        <button
+          type="button"
+          onClick={() => void install()}
+          disabled={busy || repo.trim().length === 0}
+          className="shrink-0 border border-control-border bg-control-bg px-3 py-1.5 text-[12px] text-control-fg outline-none hover:border-control-border-hover disabled:opacity-40"
+        >
+          {busy ? 'Installing…' : 'Install'}
+        </button>
+        <button
+          type="button"
+          onClick={() => void loadFromFolder()}
+          disabled={busy}
+          title="Install from a local folder — for developing an unpublished extension"
+          className="shrink-0 border border-control-border bg-control-bg px-3 py-1.5 text-[12px] text-control-fg outline-none hover:border-control-border-hover disabled:opacity-40"
+        >
+          Load folder…
+        </button>
+      </div>
+
+      {error ? (
+        <div className="border border-border bg-row-bg px-3 py-2 text-[12px] text-ink">{error}</div>
+      ) : null}
+      {notice ? <div className="text-[12px] text-muted">{notice}</div> : null}
+
+      {entries === null ? (
+        <div className="text-[12px] text-muted">Loading…</div>
+      ) : entries.length === 0 ? (
+        <div className="text-[12px] text-muted">
+          No extensions installed. Paste a repository above to install one.
+        </div>
+      ) : (
+        <div className="flex flex-col gap-1">
+          {entries.map(entry => (
+            <div
+              key={entry.manifest.id}
+              className="flex items-center justify-between gap-4 border border-border bg-row-bg px-3 py-2"
+            >
+              <div className="min-w-0">
+                <div className="flex items-baseline gap-2">
+                  <span className="text-[13px] text-ink">{entry.manifest.name}</span>
+                  <span className="text-[11px] text-muted">{entry.manifest.version}</span>
+                  {/* A ledger row whose bundle is gone. Shown rather than filtered:
+                      the fix is reinstalling from the recorded repo, and hiding it
+                      would leave the user wondering where the extension went. */}
+                  {!entry.present ? (
+                    <span className="text-[11px] text-ink-dim">· files missing</span>
+                  ) : null}
+                  {/* An extension whose module threw during import or activate.
+                      Shown here rather than only in the console: a silently
+                      missing extension is undiagnosable for whoever installed
+                      it, and the message names the actual fault. */}
+                  {failures.some(failure => failure.id === entry.manifest.id) ? (
+                    <span className="text-[11px] text-ink-dim">· failed to start</span>
+                  ) : null}
+                </div>
+                <div className="truncate text-[12px] text-muted">{entry.manifest.description}</div>
+                <div className="truncate text-[11px] text-ink-dim">
+                  {/* A local install's `repo` is a folder path, and "…@ local" read
+                      as a broken ref. Say which kind of install it is instead. */}
+                  {entry.origin === 'local' ? `local folder · ${entry.repo}` : `${entry.repo} @ ${entry.ref}`}
+                </div>
+                {failures.find(failure => failure.id === entry.manifest.id) ? (
+                  <div className="mt-1 text-[11px] text-ink">
+                    {failures.find(failure => failure.id === entry.manifest.id)?.error}
+                  </div>
+                ) : null}
+              </div>
+              <div className="flex shrink-0 gap-2">
+                <button
+                  type="button"
+                  onClick={() => void update(entry)}
+                  disabled={busy}
+                  className="border border-control-border bg-control-bg px-3 py-1 text-[12px] text-control-fg outline-none hover:border-control-border-hover disabled:opacity-40"
+                >
+                  {entry.origin === 'local' ? 'Reload' : 'Update'}
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void remove(entry)}
+                  // Every other action here guards on `busy`; Remove did not, so it
+                  // stayed clickable during an in-flight install. Removing an
+                  // extension while its own reinstall is mid-swap is exactly the
+                  // race the ledger lock now serialises — this stops the UI from
+                  // inviting it in the first place.
+                  disabled={busy}
+                  className="border border-control-border px-3 py-1 text-[12px] text-ink-dim outline-none hover:border-control-border-hover hover:text-ink disabled:opacity-40"
+                >
+                  Remove
+                </button>
+              </div>
+            </div>
+          ))}
+        </div>
+      )}
+    </div>
+  )
+}
diff --git a/src/renderer/src/apps/ui/ExtensionSettingRow.tsx b/src/renderer/src/apps/ui/ExtensionSettingRow.tsx
new file mode 100644
index 000000000..cd04196e3
--- /dev/null
+++ b/src/renderer/src/apps/ui/ExtensionSettingRow.tsx
@@ -0,0 +1,110 @@
+import { useEffect, useRef, useState } from 'react'
+
+/**
+ * One extension-contributed setting row.
+ *
+ * WHY this is a self-subscribing marker row and not a generic `toggle`/`select`
+ * control: the value must NOT live in the zustand-persist Settings blob. That blob
+ * needs a persist-version bump on every field change (a forgotten one black-screened
+ * launch twice, #249), and an extension's fields are authored outside the app's
+ * release cycle, so nobody can ever bump the version for them. So the value lives in
+ * the extension's own main-owned storage (`EXTENSION_STATE_DIR/<id>/state.json`, via
+ * `window.api.extensionStorage*`), and this row reads/writes it over IPC — exactly
+ * the pattern DictationApiKeyRow and CliUpdateBehaviorRow use for their off-blob
+ * state.
+ *
+ * The storage key is the setting's contribution id, and the appId is the extension
+ * id, so two extensions can never collide and uninstalling one leaves the other's
+ * values untouched. A missing stored value falls back to the manifest `default`.
+ */
+type Props = {
+  extensionId: string
+  settingId: string
+  valueType: 'boolean' | 'number' | 'string'
+  defaultValue: boolean | number | string
+}
+
+export function ExtensionSettingRow({ extensionId, settingId, valueType, defaultValue }: Props) {
+  const [value, setValue] = useState<boolean | number | string>(defaultValue)
+  const [error, setError] = useState<string | null>(null)
+  // A late IPC read must not clobber an edit the user made while it was in flight.
+  const editedRef = useRef(false)
+
+  useEffect(() => {
+    let cancelled = false
+    void (async () => {
+      try {
+        const stored = await window.api.extensionStorageGet(extensionId, settingId)
+        // Only adopt the stored value if it is still the right shape AND the user
+        // has not already typed something. A hand-corrupted state.json of the wrong
+        // type falls back to the default rather than rendering a broken control.
+        if (cancelled || editedRef.current) return
+        if (stored !== undefined && typeof stored === valueType) {
+          setValue(stored as boolean | number | string)
+        }
+      } catch (readError) {
+        if (!cancelled) setError(readError instanceof Error ? readError.message : String(readError))
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [extensionId, settingId, valueType])
+
+  const persist = (next: boolean | number | string) => {
+    editedRef.current = true
+    setValue(next)
+    setError(null)
+    // Write-through. The store rejects non-finite numbers, so a NaN can never land.
+    void window.api
+      .extensionStorageSet(extensionId, settingId, next)
+      .catch(writeError => setError(writeError instanceof Error ? writeError.message : String(writeError)))
+  }
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      {valueType === 'boolean' ? (
+        <button
+          type="button"
+          onClick={() => persist(!(value as boolean))}
+          className="flex w-full items-center justify-between border border-control-border bg-control-bg px-3 py-2 text-left text-[12px] text-control-fg hover:border-control-border-hover hover:bg-control-hover-bg hover:text-ink"
+        >
+          <span>{value ? 'Enabled' : 'Disabled'}</span>
+          <span
+            className={`flex h-3.5 w-3.5 border ${
+              value
+                ? 'border-control-active-bg bg-control-active-bg'
+                : 'border-control-border-hover bg-transparent'
+            }`}
+          />
+        </button>
+      ) : null}
+
+      {valueType === 'number' ? (
+        <input
+          type="number"
+          value={String(value)}
+          onChange={event => {
+            const parsed = Number(event.target.value)
+            // Ignore an unparseable/blank field rather than writing NaN — the store
+            // would reject it anyway, and clobbering the value mid-edit is hostile.
+            if (Number.isFinite(parsed)) persist(parsed)
+          }}
+          className="w-full border border-input-border bg-input-bg px-2 py-1.5 text-[13px] text-ink outline-none focus:border-input-border-focus"
+        />
+      ) : null}
+
+      {valueType === 'string' ? (
+        <input
+          type="text"
+          value={String(value)}
+          onChange={event => persist(event.target.value)}
+          spellCheck={false}
+          className="w-full border border-input-border bg-input-bg px-2 py-1.5 text-[13px] text-ink outline-none focus:border-input-border-focus"
+        />
+      ) : null}
+
+      {error ? <div className="text-[11px] text-danger">{error}</div> : null}
+    </div>
+  )
+}
diff --git a/src/renderer/src/components/ui/README.md b/src/renderer/src/components/ui/README.md
index 74ca43756..f61c8653a 100644
--- a/src/renderer/src/components/ui/README.md
+++ b/src/renderer/src/components/ui/README.md
@@ -207,3 +207,27 @@ The success condition is intentionally boring: contributors and agents reach
 for familiar names, compose a small local primitive, and keep feature logic in
 the feature. If this directory starts requiring an architectural diagram to
 add a button, it has violated its purpose.
+
+## Why the built-in apps host is not a "surface factory"
+
+`apps/surfaces/AppHostSurface` renders one of N app components inside a standard
+`DialogContent`. It is worth recording why that does not violate the "no generic
+modal schema, JSON-driven form renderer, or surface factory" rule above, because
+it superficially resembles one.
+
+It generates nothing. It is a single ordinary entry in the surface registry that
+switches on one store field (`openAppId`) and resolves it through a compile-time
+array (`apps/registry.ts`). There is no schema, no synthesized shell, and no
+second modal mechanism — apps get the same `DialogContent` every other surface
+gets, which is the point: that is where the interaction-ownership marker and
+Radix's focus trap live, and an app must not be able to opt out of either.
+
+The guardrail targets first-party component proliferation, where a factory hides
+which surfaces exist. Here the surfaces are a single greppable array sitting
+beside the registry it mirrors.
+
+Worth knowing for whoever revisits this: the two alternative hosting designs —
+loading app bundles at runtime, or rendering them in an iframe — both *would*
+require a genuine factory, since a loader must synthesize mount points from
+manifests. This guardrail is therefore an argument in favour of the compiled-in
+staging, not against it.
diff --git a/src/renderer/src/features/command-palette/executeCommand.test.ts b/src/renderer/src/features/command-palette/executeCommand.test.ts
index a41d98870..3f304bc0a 100644
--- a/src/renderer/src/features/command-palette/executeCommand.test.ts
+++ b/src/renderer/src/features/command-palette/executeCommand.test.ts
@@ -20,7 +20,7 @@ import {
 import { buildCommandRegistry } from '@renderer/features/command-palette/registry'
 import { recordCommandUse } from '@renderer/features/command-palette/lib/recentCommandHistory'
 import { makeTestCommandContext } from '@renderer/features/command-palette/testing/commandContextHarness'
-import type { CommandContext } from '@renderer/features/command-palette/types'
+import type { CommandContext, CommandDef } from '@renderer/features/command-palette/types'
 
 // ---------------------------------------------------------------------------
 // Phase 1: the command execution gateway.
@@ -351,3 +351,60 @@ describe('create commands in Dispatch Mode', () => {
     }
   })
 })
+
+describe('resolving commands that are not in the compile-time catalog', () => {
+  // ── THE REGRESSION THIS PINS ──
+  // Extension commands are derived per render from the installed manifests, so they
+  // cannot live in the frozen `builtInCommandCatalog`. The gateway resolved only
+  // against that catalog, so every contributed id answered `status: 'unknown'` — and
+  // the keybinding path does not inspect the outcome. The effect was that every
+  // manifest-declared shortcut silently did nothing AND swallowed whatever the chord
+  // would otherwise have done, while the same command clicked in the palette worked,
+  // because that path runs an already-resolved row.
+  function contributedCommand(run: () => void): CommandDef {
+    return {
+      id: 'timer.start',
+      title: 'Start Timer',
+      description: 'Starts the timer.',
+      surface: 'app',
+      category: 'extensions',
+      run,
+    }
+  }
+
+  it('does not resolve a contributed id without extraCommands', async () => {
+    const ctx = makeContext()
+    const outcome = await dispatchCommand({ id: 'timer.start', source: 'keybinding', ctx })
+    expect(outcome.status).toBe('unknown')
+  })
+
+  it('resolves and RUNS a contributed id when extraCommands is supplied', async () => {
+    const ctx = makeContext()
+    let ran = false
+    const outcome = await dispatchCommand({
+      id: 'timer.start',
+      source: 'keybinding',
+      ctx,
+      extraCommands: [contributedCommand(() => { ran = true })],
+    })
+    expect(outcome.status).toBe('ran')
+    expect(ran).toBe(true)
+  })
+
+  it('never lets a contributed command shadow a first-party id', async () => {
+    // Contributed ids are namespaced at install, so a collision should be
+    // impossible — but the lookup must not DEPEND on that validator being correct.
+    const ctx = makeContext()
+    let contributedRan = false
+    const outcome = await dispatchCommand({
+      id: 'new-tab',
+      source: 'keybinding',
+      ctx,
+      extraCommands: [
+        { ...contributedCommand(() => { contributedRan = true }), id: 'new-tab' },
+      ],
+    })
+    expect(contributedRan).toBe(false)
+    expect(outcome.status).not.toBe('unknown')
+  })
+})
\ No newline at end of file
diff --git a/src/renderer/src/features/command-palette/executeCommand.ts b/src/renderer/src/features/command-palette/executeCommand.ts
index 28a4c7fa3..938d8da84 100644
--- a/src/renderer/src/features/command-palette/executeCommand.ts
+++ b/src/renderer/src/features/command-palette/executeCommand.ts
@@ -85,6 +85,24 @@ export type DispatchCommandOptions = {
    * test that wants to assert "a keybinding cannot bypass a capability gate".
    */
   reportError?: (message: string, error: unknown) => void
+  /**
+   * Commands that exist but are not in the compile-time catalog — today, the ones
+   * derived from installed extension manifests.
+   *
+   * ── WHY THE GATEWAY CANNOT JUST IMPORT THEM ──
+   * `builtInCommandCatalog` is a frozen module-scope array, and extension commands
+   * are derived per render from the installed set, so they cannot be in it. Without
+   * this parameter `findCommand` returned undefined for every contributed id and
+   * `dispatchCommand` answered `status: 'unknown'` — which the keybinding path does
+   * not inspect. The result was that every manifest-declared shortcut was a silent
+   * no-op that also swallowed whatever the chord would otherwise have done, while
+   * clicking the same command in the palette worked, because that path runs an
+   * already-resolved row and never consults the catalog.
+   *
+   * Injected rather than imported so this module stays React-free and pure: the
+   * palette already holds the derived list and is the only caller that needs it.
+   */
+  extraCommands?: readonly CommandDef[]
 }
 
 /**
@@ -131,12 +149,12 @@ export function __resetInFlightForTests(): void {
 export async function dispatchCommand(
   options: DispatchCommandOptions,
 ): Promise<CommandDispatchOutcome> {
-  const { id, source, ctx, reportError } = options
+  const { id, source, ctx, reportError, extraCommands } = options
 
   // Resolve against the FULL catalog, never the picker-filtered registry.
   // This one line is the fix for the native-menu defect: hiding a command from
   // the palette can no longer make its menu item unresolvable.
-  const command = findCommand(id)
+  const command = findCommand(id, extraCommands)
   if (!command) {
     return { status: 'unknown', id, source }
   }
@@ -274,13 +292,24 @@ function isTransientRowId(id: string): boolean {
  *
  * Deliberately ignores picker visibility, for the same reason dispatch does.
  */
-export function canDispatchCommand(id: string, ctx: CommandContext): boolean {
-  const command = findCommand(id)
+export function canDispatchCommand(
+  id: string,
+  ctx: CommandContext,
+  extraCommands?: readonly CommandDef[],
+): boolean {
+  const command = findCommand(id, extraCommands)
   return command ? resolveCommandAvailability(command, ctx).available : false
 }
 
-function findCommand(id: string): CommandDef | undefined {
-  return builtInCommandCatalog.find(candidate => candidate.id === id)
+function findCommand(id: string, extraCommands?: readonly CommandDef[]): CommandDef | undefined {
+  // Built-ins first. A contributed id is namespaced `<extensionId>.` and cannot
+  // collide with a first-party one, but resolving the app's own commands from the
+  // app's own catalog first makes that a property of this lookup rather than
+  // something inherited from the manifest validator.
+  return (
+    builtInCommandCatalog.find(candidate => candidate.id === id) ??
+    extraCommands?.find(candidate => candidate.id === id)
+  )
 }
 
 /** Human-readable label for an error message. Function titles need the context
diff --git a/src/renderer/src/features/command-palette/lib/sortCommands.ts b/src/renderer/src/features/command-palette/lib/sortCommands.ts
index ab18a37d3..2beddc0ca 100644
--- a/src/renderer/src/features/command-palette/lib/sortCommands.ts
+++ b/src/renderer/src/features/command-palette/lib/sortCommands.ts
@@ -86,6 +86,10 @@ const CATEGORY_ORDER: readonly CommandCategory[] = [
   'workspace-tools',
   'preferences',
   'developer',
+  // Third-party last. Extension commands are the only category whose membership the
+  // app does not control, so they browse after everything first-party rather than
+  // interleaving — the same reasoning that puts them last in the registry concat.
+  'extensions',
 ]
 
 const CATEGORY_LABELS: Record<CommandCategory, string> = {
@@ -97,16 +101,23 @@ const CATEGORY_LABELS: Record<CommandCategory, string> = {
   'workspace-tools': 'Workspace Tools',
   preferences: 'Preferences',
   developer: 'Developer',
+  extensions: 'Extensions',
 }
 
 /**
  * Section for commands that declare no category.
  *
  * `CommandDef.category` is optional until the governance migration makes it
- * required, and extension-contributed commands have no way to declare one at
- * all. Dropping those rows would silently hide working commands from a browse
- * mode — the worst possible failure for a feature whose entire purpose is
- * discovery — so they get a labelled home at the end instead.
+ * required, so first-party commands that predate the migration land here.
+ * Dropping those rows would silently hide working commands from a browse mode —
+ * the worst possible failure for a feature whose entire purpose is discovery —
+ * so they get a labelled home at the end instead.
+ *
+ * Extension commands are NOT among them, despite an earlier version of this
+ * comment saying they "have no way to declare one at all". A manifest indeed
+ * cannot set a category — deliberately, so a third party cannot file itself under
+ * a first-party heading — but deriveExtensionCommands assigns 'extensions' to
+ * every command it builds, so they group under their own section.
  */
 const UNCATEGORIZED_LABEL = 'Other'
 
diff --git a/src/renderer/src/features/command-palette/registry.ts b/src/renderer/src/features/command-palette/registry.ts
index 310adfde8..f80b6b335 100644
--- a/src/renderer/src/features/command-palette/registry.ts
+++ b/src/renderer/src/features/command-palette/registry.ts
@@ -1,6 +1,8 @@
 import { builtInCommandCatalog } from '@renderer/features/command-palette/catalog'
 import { PALETTE_SELF_EXCLUDED_COMMAND_IDS } from '@renderer/features/command-palette/commands/paletteCommands'
 import { isVisibleInPicker } from '@renderer/features/command-palette/pickerVisibility'
+import { buildDefaultKeybindings } from '@renderer/features/command-keybindings/defaults'
+import type { CommandBindingDefault } from '@renderer/features/command-keybindings/defaults'
 import { displayKeybinding } from '@renderer/features/command-keybindings/normalize'
 import { resolveEffectiveKeybindings } from '@renderer/features/command-keybindings/resolve'
 import { commandAllowedByRenderedViewPolicy } from '@renderer/workspace/agentDisplayMode'
@@ -12,9 +14,16 @@ import type {
   ResolvedCommand,
 } from '@renderer/features/command-palette/types'
 
-// The ordered command list now lives in `catalog.ts`, which is context-free by
-// contract. This module keeps only the question that NEEDS a context: what
-// should the picker show right now. See catalog.ts for why the split exists.
+// The ordered first-party command list now lives in `catalog.ts`, which is
+// context-free by contract. This module keeps only the question that NEEDS a
+// context: what should the picker show right now. See catalog.ts for why the split
+// exists.
+//
+// Extension commands are deliberately NOT in the catalog — they are derived from
+// installed manifests and concatenated per call (see allCommandDefs). A frozen
+// module-scope array cannot gain a command when an extension is installed without a
+// reload, which is exactly the module-scope-snapshot mistake an adversarial audit
+// flagged; the per-call concat is the fix.
 const commandDefs: readonly CommandDef[] = builtInCommandCatalog
 
 /**
@@ -148,16 +157,38 @@ function renderedViewAvailable(command: CommandDef, ctx: CommandContext): boolea
   })
 }
 
-export function buildCommandRegistry(ctx: CommandContext): ResolvedCommand[] {
+/**
+ * Every command available right now: the first-party catalog plus whatever the
+ * installed extensions declare.
+ *
+ * Extension commands go LAST so they browse after first-party ones in the
+ * empty-query list — registry order is the palette's browse order, and putting
+ * third-party entries above the app's own would reshuffle a list people navigate
+ * by position.
+ */
+function allCommandDefs(extensionCommands: readonly CommandDef[]): readonly CommandDef[] {
+  return extensionCommands.length === 0
+    ? commandDefs
+    : [...commandDefs, ...extensionCommands]
+}
+
+export function buildCommandRegistry(
+  ctx: CommandContext,
+  extensionCommands: readonly CommandDef[] = [],
+  // Extension keybinding defaults, so an extension command's row shows its shipped
+  // chord — the same combined table the router fires from and the editor displays.
+  extensionKeybindings: readonly CommandBindingDefault[] = [],
+): ResolvedCommand[] {
   // Built once per registry pass rather than per command: resolving the
   // effective set walks every default, so doing it inside the map would be
   // O(commands x defaults) on every palette keystroke.
   const effective = new Map(
-    resolveEffectiveKeybindings(ctx.flags.commandKeybindingOverrides).map(
-      entry => [entry.commandId, entry.bindings],
-    ),
+    resolveEffectiveKeybindings(ctx.flags.commandKeybindingOverrides, [
+      ...buildDefaultKeybindings(),
+      ...extensionKeybindings,
+    ]).map(entry => [entry.commandId, entry.bindings]),
   )
-  return commandDefs
+  return allCommandDefs(extensionCommands)
     .filter(command => !PALETTE_SELF_EXCLUDED_COMMAND_IDS.has(command.id))
     .filter(command => commandApplicable(command, ctx) && commandVisible(command, ctx))
     .map(command => {
diff --git a/src/renderer/src/features/command-palette/types.ts b/src/renderer/src/features/command-palette/types.ts
index 295b69cd1..e8b3c45d7 100644
--- a/src/renderer/src/features/command-palette/types.ts
+++ b/src/renderer/src/features/command-palette/types.ts
@@ -65,6 +65,14 @@ export type CommandCategory =
   | 'preferences'
   /** Diagnostics, recording, raw inspection, or support artifacts. */
   | 'developer'
+  /**
+   * Contributed by an installed extension, not a first-party command. Kept as a
+   * distinct category so the keybind editor and any grouped command UI list
+   * extension commands under their own heading — and so a third party can never
+   * masquerade as a first-party group. Extension commands are assigned this
+   * category at derivation time; the manifest never sets a category itself.
+   */
+  | 'extensions'
 
 /**
  * A closed family of commands controlled as ONE product unit.
@@ -201,6 +209,9 @@ export type CommandContext = {
     openCloseOldAgents: () => void
     openBulkProviderSwitch: () => void
     openRewindPrompt: (sessionId: string) => void
+    /** Open a built-in app by its AppDefinition id. The host surface resolves the
+     *  id and treats a miss as closed, so a stale id here cannot throw. */
+    openApp: (appId: string) => void
     openAgentViewModePicker: (sessionId: string) => void
     /** Open the Dispatch color-flag swatch picker for a session. */
     openColorFlagPicker: (sessionId: string) => void
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 000ef085c..c23c38412 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -77,6 +77,7 @@ import type {
 } from '@renderer/features/prompt-templates/types'
 import { promptTemplateTargetSessionId } from '@renderer/features/prompt-templates/targetSession'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
+import { deriveExtensionCommands, deriveExtensionKeybindings } from '@renderer/apps/host/derive'
 import { resolveAgentPaneLabel } from '@renderer/workspace/tile-tree/paneLabels'
 import { useWorkspaceContext } from '@renderer/workspace/WorkspaceContext'
 import type { PaletteMode } from '@renderer/features/command-palette/paletteMode'
@@ -283,6 +284,7 @@ function OpenCommandPalette({
   const closePinAgents = useAppStore(state => state.closePinAgents)
   const closePathPicker = useAppStore(state => state.closePathPicker)
   const openUsageModal = useAppStore(state => state.openUsageModal)
+  const openApp = useAppStore(state => state.openApp)
   const toggleGitBar = useAppStore(state => state.toggleGitBar)
   const toggleWorktreesBar = useAppStore(state => state.toggleWorktreesBar)
   const toggleDebugPanel = useAppStore(state => state.toggleDebugPanel)
@@ -654,7 +656,13 @@ function OpenCommandPalette({
         enterAiWorkspaceOpenMode,
         enterAiWorkspaceCreateMode,
         enterAiWorkspaceClearMode,
+        openApp,
         closePalette: onClose,
+        // NOTE: openApp is in the dep array below alongside every other store
+        // action. Zustand action identities are stable, so omitting it was
+        // benign — but it would become a stale closure the instant that
+        // assumption changed, and there is no lint rule in this repo to catch
+        // it (no eslint config, no `lint` script).
       },
       flags: {
         statusModeEnabled,
@@ -727,6 +735,7 @@ function OpenCommandPalette({
       closePinAgents,
       closePathPicker,
       openUsageModal,
+      openApp,
       toggleGitBar,
       toggleWorktreesBar,
       toggleDebugPanel,
@@ -809,7 +818,26 @@ function OpenCommandPalette({
     ],
   )
 
-  const commands = useMemo(() => buildCommandRegistry(commandContext), [commandContext])
+  // Extension commands are derived from installed MANIFESTS, not from loaded
+  // modules — that is what lets the palette list an extension's commands before
+  // a single byte of it has been imported. `run` activates on demand.
+  const installedExtensions = useAppStore(state => state.installedExtensions)
+  const extensionCommands = useMemo(
+    () =>
+      deriveExtensionCommands(installedExtensions, openApp, workspace.openExtensionViewInPane),
+    [installedExtensions, openApp, workspace.openExtensionViewInPane],
+  )
+  // Extension keybinding defaults, so a palette row for an extension command shows
+  // its shipped chord. Independent of the host (manifests only), unlike commands.
+  const extensionKeybindings = useMemo(
+    () => deriveExtensionKeybindings(installedExtensions),
+    [installedExtensions],
+  )
+
+  const commands = useMemo(
+    () => buildCommandRegistry(commandContext, extensionCommands, extensionKeybindings),
+    [commandContext, extensionCommands, extensionKeybindings],
+  )
 
   const promptTemplates = useMemo(
     () => allPromptTemplates(customPromptTemplates),
@@ -1205,6 +1233,10 @@ function OpenCommandPalette({
       source: pendingMenuCommand.source,
       ctx: commandContext,
       reportError: message => showToast(message, 6000),
+      // Without these a contributed keybinding resolved to nothing here, and the
+      // outcome — `status: 'unknown'` — is not inspected by the keybinding path, so
+      // every manifest-declared shortcut was a silent no-op.
+      extraCommands: extensionCommands,
     })
     onMenuCommandHandled()
     // A command that OPENED the palette must not be closed by the "return to
diff --git a/src/renderer/src/features/debug/surfaces/DebugSurfacesImpl.tsx b/src/renderer/src/features/debug/surfaces/DebugSurfacesImpl.tsx
index cb03efd4c..bc251b6ad 100644
--- a/src/renderer/src/features/debug/surfaces/DebugSurfacesImpl.tsx
+++ b/src/renderer/src/features/debug/surfaces/DebugSurfacesImpl.tsx
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
 import { DebugPanel } from '@renderer/features/debug/ui/DebugPanel'
 import { FeedDebugPanel } from '@renderer/features/debug/ui/FeedDebugPanel'
 import { ProxyDebugPanel } from '@renderer/features/debug/ui/ProxyDebugPanel'
@@ -111,7 +111,7 @@ export function DebugSurfacesImpl() {
       {renderingDebugMode && (
         <RenderingDebugInspector
           sessionId={targetId}
-          provider={kind === 'terminal' ? 'unknown' : kind}
+          provider={isAgentProviderKind(kind) ? kind : 'unknown'}
           onSave={saveRenderingElement}
           onClose={toggleRenderingDebugMode}
         />
diff --git a/src/renderer/src/features/dispatch-pin/surfaces/PinAgentsSurface.tsx b/src/renderer/src/features/dispatch-pin/surfaces/PinAgentsSurface.tsx
index 90b6ac603..da25ac636 100644
--- a/src/renderer/src/features/dispatch-pin/surfaces/PinAgentsSurface.tsx
+++ b/src/renderer/src/features/dispatch-pin/surfaces/PinAgentsSurface.tsx
@@ -1,3 +1,4 @@
+import { isAgentSessionKind } from '@shared/types/providerKind'
 import { useMemo } from 'react'
 import { PinAgentsModal } from '@renderer/features/dispatch-pin/PinAgentsModal'
 import type { PinAgentsModalRow } from '@renderer/features/dispatch-pin/PinAgentsModal'
@@ -44,7 +45,7 @@ export function PinAgentsSurface() {
     const pushRow = (sessionId: SessionId, tabId: TabId): void => {
       if (seen.has(sessionId)) return
       const meta = state.sessions[sessionId]
-      if (!meta || meta.kind === 'terminal') return
+      if (!meta || !isAgentSessionKind(meta.kind)) return
       const tabIndex = tabIndexFor(tabId)
       const tab = state.tabs[tabIndex]
       if (!tab) return
diff --git a/src/renderer/src/features/prompt-templates/targetSession.ts b/src/renderer/src/features/prompt-templates/targetSession.ts
index 0f006d3c2..40e1f1daa 100644
--- a/src/renderer/src/features/prompt-templates/targetSession.ts
+++ b/src/renderer/src/features/prompt-templates/targetSession.ts
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { isAgentSessionKind } from '@shared/types/providerKind'
 import { commandTargetSessionIdForState } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 import type { WorkspaceState } from '@renderer/workspace/types'
 import type { Workspace } from '@renderer/workspace/workspaceStore'
@@ -6,11 +6,12 @@ import type { Workspace } from '@renderer/workspace/workspaceStore'
 /**
  * Resolves the composer that may receive a prompt template.
  *
- * WHY this is narrower than the shared command target: terminal panes are real
- * sessions and therefore valid targets for lifecycle commands, but they do not
- * own the agent composer that template insertion edits. Keeping this predicate
- * feature-owned and shared by both command visibility and execution prevents a
- * picker from advertising an action that can only return silently.
+ * WHY this is narrower than the shared command target: terminal and
+ * extension-view panes are real sessions and therefore valid targets for
+ * lifecycle commands, but neither owns the agent composer that template
+ * insertion edits. Keeping this predicate feature-owned and shared by both
+ * command visibility and execution prevents a picker from advertising an action
+ * that can only return silently.
  */
 export function promptTemplateTargetSessionId(workspace: Workspace): string | null {
   return promptTemplateTargetSessionIdForState(workspace.state)
@@ -19,6 +20,5 @@ export function promptTemplateTargetSessionId(workspace: Workspace): string | nu
 export function promptTemplateTargetSessionIdForState(state: WorkspaceState): string | null {
   const sessionId = commandTargetSessionIdForState(state)
   if (!sessionId) return null
-  const kind = state.sessions[sessionId]?.kind ?? DEFAULT_PROVIDER
-  return kind === 'terminal' ? null : sessionId
+  return isAgentSessionKind(state.sessions[sessionId]?.kind) ? sessionId : null
 }
diff --git a/src/renderer/src/features/reader/ui/ReaderView.tsx b/src/renderer/src/features/reader/ui/ReaderView.tsx
index ae78698fc..f21d026ba 100644
--- a/src/renderer/src/features/reader/ui/ReaderView.tsx
+++ b/src/renderer/src/features/reader/ui/ReaderView.tsx
@@ -9,7 +9,7 @@ import { SafeInlineCode } from '@renderer/features/rendered-content/SafeInlineCo
 import { SafeMarkdownLink } from '@renderer/features/rendered-content/SafeMarkdownLink'
 import { hasAppInteractionOwner } from '@renderer/lib/interaction-ownership'
 import { extractAssistantInProgress } from '@shared/parsers/extractAssistant'
-import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentProviderKind, isAgentSessionKind } from '@shared/types/providerKind'
 import { assistantUuidsWithText, extractAssistantByUuid } from '@renderer/lib/copyAssistant'
 import { resolveTabSessions } from '@renderer/workspace/queries'
 import { dispatchSessionIdsForTab } from '@renderer/workspace/dispatch/dispatchSelectors'
@@ -108,7 +108,7 @@ export function ReaderView({ workspace }: Props) {
     // scrollback through xterm.js and do not have assistant messages to
     // extract. Keeping the filter here protects restored/stale reader state in
     // addition to the command-palette guard that prevents new terminal entry.
-    .filter(sessionId => workspace.state.sessions[sessionId]?.kind !== 'terminal')
+    .filter(sessionId => isAgentSessionKind(workspace.state.sessions[sessionId]?.kind))
   if (sessionIds.length === 0) return null
 
   const focusedSessionId = sessionIds.includes(reader.focusedSessionId)
diff --git a/src/renderer/src/features/reply-to-selection/commands/replyToSelectionCommands.ts b/src/renderer/src/features/reply-to-selection/commands/replyToSelectionCommands.ts
index 0b578150d..eb88eb03a 100644
--- a/src/renderer/src/features/reply-to-selection/commands/replyToSelectionCommands.ts
+++ b/src/renderer/src/features/reply-to-selection/commands/replyToSelectionCommands.ts
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentSessionKind } from '@shared/types/providerKind'
 import type { CommandDef } from '@renderer/features/command-palette/types'
 import { prefixDraftWithQuote, quoteSnippet } from '@renderer/features/reply-to-selection/lib/formatQuote'
 import { parkComposerCaretAtEnd } from '@renderer/features/reply-to-selection/lib/parkComposerCaret'
@@ -19,15 +19,16 @@ import type { Workspace } from '@renderer/workspace/workspaceStore'
 //
 // Two things still have to be checked, because the stash is module state
 // that outlives any given render: the session must still exist (it could
-// have been closed between the drag and the palette), and it must not be
-// a terminal (no composer draft to insert into, and xterm owns its own
-// selection model rather than the DOM this feature captures from).
+// have been closed between the drag and the palette), and it must still be
+// an agent pane — a terminal has no composer draft to insert into (and xterm
+// owns its own selection model rather than the DOM this feature captures
+// from), and an extension-view pane has no composer at all.
 function validPendingSelection(workspace: Workspace): PendingSelection | null {
   const pending = peekPendingSelection()
   if (!pending) return null
   const meta = workspace.state.sessions[pending.sessionId]
   if (!meta) return null
-  if ((meta.kind ?? DEFAULT_PROVIDER) === 'terminal') return null
+  if (!isAgentSessionKind(meta.kind)) return null
   return pending
 }
 
diff --git a/src/renderer/src/features/settings/lib/settingsCategories.ts b/src/renderer/src/features/settings/lib/settingsCategories.ts
index 2cf64b7da..5754551f3 100644
--- a/src/renderer/src/features/settings/lib/settingsCategories.ts
+++ b/src/renderer/src/features/settings/lib/settingsCategories.ts
@@ -6,6 +6,7 @@ export type SettingCategoryId =
   | 'dictation'
   | 'experimental'
   | 'safety'
+  | 'apps'
 
 export type SettingCategory = {
   id: SettingCategoryId
@@ -49,4 +50,13 @@ export const SETTING_CATEGORIES: SettingCategory[] = [
     label: 'Safety',
     description: 'Defaults that change agent risk posture.',
   },
+  // Last on purpose: apps are additive tooling rather than a setting that changes
+  // how the shell or an agent behaves, so they should not push the behavioural
+  // categories down the list. In Stage 2 this becomes the install/manage surface
+  // and the position can be revisited then, with a reason.
+  {
+    id: 'apps',
+    label: 'Extensions',
+    description: 'Install extensions from a GitHub repository.',
+  },
 ]
diff --git a/src/renderer/src/features/settings/lib/settingsRegistry.ts b/src/renderer/src/features/settings/lib/settingsRegistry.ts
index 062aa7c22..8361e8d4e 100644
--- a/src/renderer/src/features/settings/lib/settingsRegistry.ts
+++ b/src/renderer/src/features/settings/lib/settingsRegistry.ts
@@ -14,6 +14,7 @@ import type {
 import type { Workspace } from '@renderer/workspace/workspaceStore'
 import { SETTING_CATEGORIES } from '@renderer/features/settings/lib/settingsCategories'
 import type { SettingCategoryId } from '@renderer/features/settings/lib/settingsCategories'
+import type { ExtensionListEntry } from '@shared/types/extensions'
 import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
 import type { MouseButtonBinding } from '@renderer/lib/mouseBinding'
 import { coerceMouseChordBinding } from '@renderer/lib/mouseBinding'
@@ -203,6 +204,46 @@ export type SettingDefinition =
         type: 'dictation-api-key'
       }
     }
+  | {
+      id: string
+      category: SettingCategoryId
+      title: string
+      description: string
+      keywords: string[]
+      metadata?: SettingMetadata
+      // Marker for the extension installer. Same escape hatch as
+      // cli-update-behavior: the truth lives in main (extensions.json plus the
+      // bundle directories on disk), not in Settings, so the row owns its own
+      // IPC round-trip. It is also the only row that is a whole interactive
+      // surface — a text input, an install action, and a list with per-row
+      // update/remove — which no generic control type can express.
+      // See apps/ui/AppsSettingsRow.tsx.
+      control: {
+        type: 'apps'
+      }
+    }
+  | {
+      id: string
+      category: SettingCategoryId
+      title: string
+      description: string
+      keywords: string[]
+      metadata?: SettingMetadata
+      // Marker for one extension-contributed setting. Self-subscribing like the
+      // other markers, because the VALUE lives in the extension's main-owned
+      // storage (EXTENSION_STATE_DIR), never the zustand-persist blob (#249). The
+      // payload is everything the row needs to read/write that store; the row owns
+      // its own IPC round-trip. See apps/ui/ExtensionSettingRow.tsx.
+      control: {
+        type: 'extension'
+        /** Storage namespace (appId) — the owning extension's id. */
+        extensionId: string
+        /** Storage key — the setting's `<extensionId>.<name>` contribution id. */
+        settingId: string
+        valueType: 'boolean' | 'number' | 'string'
+        default: boolean | number | string
+      }
+    }
   | {
       id: string
       category: SettingCategoryId
@@ -319,8 +360,64 @@ function updateDefaultBuiltInMcpDomain(
   ctx.onChange({ defaultBuiltInMcpDomains: next })
 }
 
-export function getSettingsRegistry(): SettingDefinition[] {
+/**
+ * `SettingDefinition`s for every contributed extension setting. Reads manifests
+ * only (no bundle import), the settings sibling of deriveExtensionCommands. Rows
+ * are the self-subscribing 'extension' marker; the value lives in per-extension
+ * storage, never the Settings blob. First-wins on a cross-extension id collision,
+ * matching the command/keybinding derivations.
+ */
+function deriveExtensionSettings(
+  installed: readonly ExtensionListEntry[],
+): SettingDefinition[] {
+  const seen = new Set<string>()
+  const rows: SettingDefinition[] = []
+
+  for (const entry of installed) {
+    if (!entry.present) continue
+    for (const setting of entry.manifest.contributes?.settings ?? []) {
+      if (seen.has(setting.id)) continue
+      seen.add(setting.id)
+      rows.push({
+        id: setting.id,
+        category: 'apps',
+        // Prefix with the extension name so a flat Extensions category still reads
+        // as grouped by owner, and two extensions' identically-titled settings stay
+        // distinguishable.
+        title: `${entry.manifest.name}: ${setting.title}`,
+        description: setting.description ?? '',
+        keywords: [entry.manifest.name, setting.title, entry.manifest.id],
+        control: {
+          type: 'extension',
+          extensionId: entry.manifest.id,
+          settingId: setting.id,
+          valueType: setting.type,
+          default: setting.default,
+        },
+      })
+    }
+  }
+
+  return rows
+}
+
+export function getSettingsRegistry(
+  // Installed extensions, so contributed settings render as rows. An empty default keeps
+  // every non-extension caller (the tests, mainly) unchanged. The extension set changes
+  // on install/remove, so this is not a per-lifetime constant and must be recomputed
+  // when the caller's list changes.
+  //
+  // NOTE: this used to also take `extensionCommands` for the Commands settings category.
+  // That category was replaced upstream by the unified command list in
+  // CommandKeybindingsRow, which derives extension commands itself — so the parameter
+  // was removed rather than left dangling.
+  installedExtensions: readonly ExtensionListEntry[] = [],
+): SettingDefinition[] {
   return [
+    // Extension-contributed settings, one row each, under the Extensions category.
+    // Derived from manifests (no bundle import); an uninstall drops the manifest
+    // from installedExtensions and the rows vanish with it, leaving a clean block.
+    ...deriveExtensionSettings(installedExtensions),
     {
       id: 'theme-mode',
       category: 'appearance',
@@ -916,6 +1013,20 @@ export function getSettingsRegistry(): SettingDefinition[] {
       metadata: { scope: 'app', apply: 'immediate', storage: 'setup' },
       control: { type: 'cli-update-behavior' },
     },
+    {
+      // Built-in apps listing. A marker row with no value — the content is
+      // apps/registry.ts, which is compile-time data. Deliberately NOT mirrored
+      // into Settings: extension-adjacent state must stay out of the
+      // zustand-persist blob (a forgotten version bump there black-screened
+      // launch twice, #249), and here there is nothing to persist anyway.
+      // See apps/ui/AppsSettingsRow.tsx.
+      id: 'apps-installed',
+      category: 'apps',
+      title: 'Extensions',
+      description: 'Install, update, and remove extensions from GitHub repositories.',
+      keywords: ['apps', 'extensions', 'plugins', 'install', 'github', 'tools'],
+      control: { type: 'apps' },
+    },
     {
       id: 'reset-settings',
       category: 'workspace',
diff --git a/src/renderer/src/features/settings/ui/CommandKeybindingsRow.tsx b/src/renderer/src/features/settings/ui/CommandKeybindingsRow.tsx
index fd6e1708d..d15affc48 100644
--- a/src/renderer/src/features/settings/ui/CommandKeybindingsRow.tsx
+++ b/src/renderer/src/features/settings/ui/CommandKeybindingsRow.tsx
@@ -2,6 +2,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
 import { useAppStore } from '@renderer/app-state/hooks'
 import { builtInCommandCatalog } from '@renderer/features/command-palette/catalog'
+import { deriveExtensionCommands, deriveExtensionKeybindings } from '@renderer/apps/host/derive'
 import { PALETTE_SELF_EXCLUDED_COMMAND_IDS } from '@renderer/features/command-palette/commands/paletteCommands'
 import { buildDefaultKeybindings } from '@renderer/features/command-keybindings/defaults'
 import type { BindingContext } from '@renderer/features/command-keybindings/defaults'
@@ -55,6 +56,7 @@ const CATEGORY_LABELS: Record<CommandCategory, string> = {
   'workspace-tools': 'Workspace Tools',
   preferences: 'Preferences',
   developer: 'Developer',
+  extensions: 'Extensions',
 }
 
 /**
@@ -75,6 +77,10 @@ const CATEGORY_RANK: Record<CommandCategory, number> = {
   'workspace-tools': 5,
   preferences: 6,
   developer: 7,
+  // Last: extension-contributed commands browse after every first-party group,
+  // the same "third-party entries never above the app's own" ordering the palette
+  // uses for extension commands.
+  extensions: 8,
 }
 
 const CATEGORY_ORDER = (Object.keys(CATEGORY_RANK) as CommandCategory[])
@@ -171,6 +177,19 @@ export function CommandKeybindingsRow() {
   const settings = useAppStore(state => state.settings)
   const setSettings = useAppStore(state => state.setSettings)
 
+  // Extension commands, derived from installed MANIFESTS exactly as the palette
+  // (CommandPalette.tsx) and the visibility list (SettingsPage.tsx) do — no bundle
+  // is imported. Without this the editor iterated only builtInCommandCatalog, so an
+  // extension command could be shown/hidden in the Commands list but never assigned
+  // a key here. openApp is a no-op: the editor reads command metadata and never
+  // invokes `run`. They are stamped with the 'extensions' category so the row
+  // builder's category filter admits them and they group under their own heading.
+  const installedExtensions = useAppStore(state => state.installedExtensions)
+  const extensionCommands = useMemo(
+    () => deriveExtensionCommands(installedExtensions, () => {}),
+    [installedExtensions],
+  )
+
   const [query, setQuery] = useState('')
   const [capturingFor, setCapturingFor] = useState<string | null>(null)
   const [conflict, setConflict] = useState<PendingConflict | null>(null)
@@ -178,7 +197,13 @@ export function CommandKeybindingsRow() {
   const overrides = settings.commandKeybindingOverrides
   const visibilityOverrides = settings.commandVisibilityOverrides
   const navigationCommandsEnabled = settings.navigationCommandsEnabled
-  const defaults = useMemo(() => buildDefaultKeybindings(), [])
+  // Shipped defaults + extension-contributed defaults, so the editor shows an
+  // extension's declared chord as its default and conflict-checks against it —
+  // the same combined table the router fires from (useKeybinds.ts).
+  const defaults = useMemo(
+    () => [...buildDefaultKeybindings(), ...deriveExtensionKeybindings(installedExtensions)],
+    [installedExtensions],
+  )
 
   const effective = useMemo(() => {
     const map = new Map<string, readonly Keybinding[]>()
@@ -198,7 +223,7 @@ export function CommandKeybindingsRow() {
 
   const rows = useMemo(() => {
     const needle = query.trim().toLowerCase()
-    return builtInCommandCatalog
+    return [...builtInCommandCatalog, ...extensionCommands]
       // A command the palette never renders still gets a binding row — it is
       // reachable by chord, menu and programmatic call, so it is bindable.
       .filter(command => command.category)
@@ -241,7 +266,14 @@ export function CommandKeybindingsRow() {
         ].join(' ').toLowerCase()
         return haystack.includes(needle)
       })
-  }, [query, effective, overrides, visibilityOverrides, navigationCommandsEnabled])
+  }, [
+    query,
+    effective,
+    overrides,
+    extensionCommands,
+    visibilityOverrides,
+    navigationCommandsEnabled,
+  ])
 
   const setPaletteVisible = useCallback(
     (command: CommandDef, visible: boolean) => {
diff --git a/src/renderer/src/features/settings/ui/KeyboardShortcutsModal.tsx b/src/renderer/src/features/settings/ui/KeyboardShortcutsModal.tsx
index a94adc3b4..323390589 100644
--- a/src/renderer/src/features/settings/ui/KeyboardShortcutsModal.tsx
+++ b/src/renderer/src/features/settings/ui/KeyboardShortcutsModal.tsx
@@ -2,6 +2,7 @@ import { useEffect, useMemo, useRef, useState } from 'react'
 
 import { useAppStore } from '@renderer/app-state/hooks'
 import { builtInCommandCatalog } from '@renderer/features/command-palette/catalog'
+import { deriveExtensionCommands, deriveExtensionKeybindings } from '@renderer/apps/host/derive'
 import { buildDefaultKeybindings } from '@renderer/features/command-keybindings/defaults'
 import { displayKeybinding } from '@renderer/features/command-keybindings/normalize'
 import { resolveEffectiveKeybindings } from '@renderer/features/command-keybindings/resolve'
@@ -62,6 +63,7 @@ const CATEGORY_LABELS: Record<CommandCategory, string> = {
   'workspace-tools': 'Workspace Tools',
   preferences: 'Preferences',
   developer: 'Developer',
+  extensions: 'Extensions',
 }
 
 /** Display order. Exhaustive by type for the same reason the Settings row is:
@@ -77,6 +79,7 @@ const CATEGORY_RANK: Record<CommandCategory, number> = {
   'workspace-tools': 5,
   preferences: 6,
   developer: 7,
+  extensions: 8,
 }
 
 /**
@@ -97,6 +100,15 @@ const CONTEXT_LABELS: Record<BindingContext, string | null> = {
 
 export function KeyboardShortcutsModal({ open, onClose }: Props) {
   const overrides = useAppStore(state => state.settings.commandKeybindingOverrides)
+
+  // Extension commands, so a chord a user bound to one is not a silent hole in a
+  // reference sheet — the exact failure the CATEGORY_RANK comment above warns
+  // against. Derived from manifests (no bundle import); openApp unused here.
+  const installedExtensions = useAppStore(state => state.installedExtensions)
+  const extensionCommands = useMemo(
+    () => deriveExtensionCommands(installedExtensions, () => {}),
+    [installedExtensions],
+  )
   const [query, setQuery] = useState('')
   const inputRef = useRef<HTMLInputElement>(null)
 
@@ -111,12 +123,14 @@ export function KeyboardShortcutsModal({ open, onClose }: Props) {
   }, [open])
 
   const rows = useMemo<ShortcutRow[]>(() => {
-    const defaults = buildDefaultKeybindings()
+    // Include extension-contributed defaults so a chord an extension SHIPS (not
+    // just one the user rebound) shows in the reference, matching what fires.
+    const defaults = [...buildDefaultKeybindings(), ...deriveExtensionKeybindings(installedExtensions)]
     const contextById = new Map(defaults.map(d => [d.commandId, d.context]))
     const effective = new Map(
       resolveEffectiveKeybindings(overrides, defaults).map(e => [e.commandId, e.bindings]),
     )
-    const byId = new Map(builtInCommandCatalog.map(c => [c.id, c]))
+    const byId = new Map([...builtInCommandCatalog, ...extensionCommands].map(c => [c.id, c]))
 
     const out: ShortcutRow[] = []
     for (const [commandId, bindings] of effective) {
@@ -140,7 +154,7 @@ export function KeyboardShortcutsModal({ open, onClose }: Props) {
       })
     }
     return out
-  }, [overrides])
+  }, [overrides, extensionCommands, installedExtensions])
 
   const filtered = useMemo(() => {
     const needle = query.trim().toLowerCase()
diff --git a/src/renderer/src/features/settings/ui/SettingsList.tsx b/src/renderer/src/features/settings/ui/SettingsList.tsx
index d3ec26ace..4a656aa3c 100644
--- a/src/renderer/src/features/settings/ui/SettingsList.tsx
+++ b/src/renderer/src/features/settings/ui/SettingsList.tsx
@@ -12,6 +12,8 @@ import { CliUpdateBehaviorRow } from '@renderer/features/cli-updates/CliUpdateBe
 import { DictationApiKeyRow } from '@renderer/features/voice-dictation/DictationApiKeyRow'
 import { DictationHistoryRow } from '@renderer/features/voice-dictation/DictationHistoryRow'
 import { ThemePickerRow } from '@renderer/features/settings/ui/ThemePickerRow'
+import { AppsSettingsRow } from '@renderer/apps/ui/AppsSettingsRow'
+import { ExtensionSettingRow } from '@renderer/apps/ui/ExtensionSettingRow'
 import { AgentCodeConventionsRow } from '@renderer/features/settings/ui/AgentCodeConventionsRow'
 import { AgentCodeCustomSkillsRow } from '@renderer/features/settings/ui/AgentCodeCustomSkillsRow'
 import { Button } from '@renderer/components/ui/button'
@@ -206,6 +208,17 @@ function SettingRow({
               features/cli-updates/CliUpdateBehaviorRow.tsx. */}
           {control.type === 'command-keybindings' ? <CommandKeybindingsRow /> : null}
 
+          {/* One extension-contributed setting. Self-subscribing: the value lives
+              in the extension's own storage, not the Settings blob (#249). */}
+          {control.type === 'extension' ? (
+            <ExtensionSettingRow
+              extensionId={control.extensionId}
+              settingId={control.settingId}
+              valueType={control.valueType}
+              defaultValue={control.default}
+            />
+          ) : null}
+
           {control.type === 'cli-update-behavior' ? <CliUpdateBehaviorRow /> : null}
 
           {/* Voice-dictation API key — same self-subscribing marker-row
@@ -214,6 +227,12 @@ function SettingRow({
               round-trip. See features/voice-dictation/DictationApiKeyRow.tsx. */}
           {control.type === 'dictation-api-key' ? <DictationApiKeyRow /> : null}
 
+          {/* Built-in apps — the purest marker row: there is no value at all,
+              just a listing of apps/registry.ts, which is compile-time data the
+              Settings store has no business mirroring.
+              See apps/ui/AppsSettingsRow.tsx. */}
+          {control.type === 'apps' ? <AppsSettingsRow /> : null}
+
           {/* Same marker-row rationale: the transcripts and lifetime totals
               live in a main-owned JSON store, not in Settings. */}
           {control.type === 'dictation-history' ? <DictationHistoryRow /> : null}
diff --git a/src/renderer/src/features/settings/ui/SettingsPage.tsx b/src/renderer/src/features/settings/ui/SettingsPage.tsx
index 8b9465e11..befe4c255 100644
--- a/src/renderer/src/features/settings/ui/SettingsPage.tsx
+++ b/src/renderer/src/features/settings/ui/SettingsPage.tsx
@@ -31,6 +31,7 @@ import { getSettingsRegistry, matchesSettingQuery } from '@renderer/features/set
 import { SettingsList } from '@renderer/features/settings/ui/SettingsList'
 import { SettingsSearch } from '@renderer/features/settings/ui/SettingsSearch'
 import { SettingsSidebar } from '@renderer/features/settings/ui/SettingsSidebar'
+import { useAppStore } from '@renderer/app-state/store'
 
 type Props = {
   onClose: () => void
@@ -53,7 +54,16 @@ export function SettingsPage({ onClose, workspace, settings, onChange, onReset }
   // (null) distinguishable from "creating" (id: null).
   const [editorTarget, setEditorTarget] = useState<{ id: string | null } | null>(null)
 
-  const registry = useMemo(() => getSettingsRegistry(), [])
+  // Contributed settings rows are derived from installed MANIFESTS, so Settings
+  // lists them without importing a single extension bundle.
+  //
+  // There used to be an `extensionCommands` memo here too. It was dead: an earlier
+  // revision passed it to getSettingsRegistry for a "Commands" settings category
+  // that was replaced upstream by CommandKeybindingsRow, which derives its own. The
+  // memo survived as a dependency of the line below and nothing else — computing a
+  // command list on every install just to feed it to an array it was not in.
+  const installedExtensions = useAppStore(state => state.installedExtensions)
+  const registry = useMemo(() => getSettingsRegistry(installedExtensions), [installedExtensions])
   const visibleDefinitions = useMemo(
     () =>
       registry.filter(definition => {
diff --git a/src/renderer/src/features/workspace/commands/paneCommands.ts b/src/renderer/src/features/workspace/commands/paneCommands.ts
index be70bf9e9..a499812fa 100644
--- a/src/renderer/src/features/workspace/commands/paneCommands.ts
+++ b/src/renderer/src/features/workspace/commands/paneCommands.ts
@@ -1,4 +1,9 @@
-import { AGENT_PROVIDER_KINDS, DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
+import {
+  AGENT_PROVIDER_KINDS,
+  DEFAULT_PROVIDER,
+  isAgentProviderKind,
+  isAgentSessionKind,
+} from '@shared/types/providerKind'
 import { getRendererProviderCapabilities } from '@providers/registry.renderer.capabilities'
 import { extractLastAssistantText } from '@renderer/lib/copyAssistant'
 import type { CommandContext, CommandDef } from '@renderer/features/command-palette/types'
@@ -509,10 +514,10 @@ export const paneCommands: CommandDef[] = [
       if (!sessionId) return false
       // WHY tail is agent-only even though terminals are Dispatch rows:
       // tailMode controls the rendered transcript/feed scroll container.
-      // Terminal panes delegate scrollback to xterm.js, so toggling this
-      // runtime flag on a terminal would present a command that appears to
-      // work while changing nothing visible.
-      return workspace.state.sessions[sessionId]?.kind !== 'terminal'
+      // Terminal panes delegate scrollback to xterm.js, and extension-view panes
+      // have no feed at all, so toggling this runtime flag on either would
+      // present a command that appears to work while changing nothing visible.
+      return isAgentSessionKind(workspace.state.sessions[sessionId]?.kind)
     },
     run: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
@@ -555,8 +560,7 @@ export const paneCommands: CommandDef[] = [
     when: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
       if (!sessionId) return false
-      const kind = workspace.state.sessions[sessionId]?.kind ?? DEFAULT_PROVIDER
-      return kind !== 'terminal'
+      return isAgentSessionKind(workspace.state.sessions[sessionId]?.kind)
     },
     run: ({ workspace }) => {
       workspace.scrollFocusedToLatest()
@@ -571,11 +575,13 @@ export const paneCommands: CommandDef[] = [
     when: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
       if (!sessionId) return false
-      // WHY hide this for terminals: terminal output is not an assistant
+      // WHY hide this on non-agent panes: terminal output is not an assistant
       // transcript, and extractLastAssistantText intentionally reads provider
       // entries. Showing the command on a shell row would imply there is an
-      // assistant response to copy when there is only PTY scrollback.
-      return workspace.state.sessions[sessionId]?.kind !== 'terminal'
+      // assistant response to copy when there is only PTY scrollback — and on an
+      // extension-view pane `run` would call getRuntime() for a session that has
+      // no runtime at all.
+      return isAgentSessionKind(workspace.state.sessions[sessionId]?.kind)
     },
     run: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
@@ -606,12 +612,13 @@ export const paneCommands: CommandDef[] = [
       '**What it does:** Empties the composer draft for the focused agent.\n\n**Use when:** You typed or dictated something you want to start over from — with a mouse there is no select-all-and-delete.\n\n**Notes:** Reversible with **Undo Clear Composer**. Attached images are removed but not restored by the undo.',
     keywords: ['clear', 'composer', 'draft', 'erase', 'reset', 'prompt', 'delete'],
     // Terminals have no composer draft — their input goes straight to the PTY —
-    // so offering this on a shell row would imply a draft that cannot exist.
-    // Same reasoning as copy-last-assistant above.
+    // and extension-view panes have no composer at all, so offering this on
+    // either would imply a draft that cannot exist. Same reasoning as
+    // copy-last-assistant above.
     when: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
       if (!sessionId) return false
-      return workspace.state.sessions[sessionId]?.kind !== 'terminal'
+      return isAgentSessionKind(workspace.state.sessions[sessionId]?.kind)
     },
     run: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
@@ -671,7 +678,7 @@ export const paneCommands: CommandDef[] = [
     when: ({ workspace }) => {
       const sessionId = commandTargetSessionId(workspace)
       if (!sessionId) return false
-      return workspace.state.sessions[sessionId]?.kind !== 'terminal'
+      return isAgentSessionKind(workspace.state.sessions[sessionId]?.kind)
     },
     // Routed through the Enter registry rather than reimplemented: `submit` is
     // built from `submitCurrentDraft`, which owns provider capability dispatch,
diff --git a/src/renderer/src/features/workspace/lib/sessionDisplay.ts b/src/renderer/src/features/workspace/lib/sessionDisplay.ts
index 4d9e27392..4f5bd563f 100644
--- a/src/renderer/src/features/workspace/lib/sessionDisplay.ts
+++ b/src/renderer/src/features/workspace/lib/sessionDisplay.ts
@@ -28,8 +28,12 @@ export function cwdBasename(cwd: string): string {
 // agent providers (PromptSearchModal) can still pass the narrower
 // 'claude' | 'codex' subset — TypeScript will accept it.
 export function providerGlyph(kind: SessionKind): string {
-  // Registry-derived for agent kinds (#394 phase 2c-2); terminal is
-  // the only non-registry pane kind and keeps its literal.
+  // Registry-derived for agent kinds (#394 phase 2c-2). The non-registry pane
+  // kinds are listed EXPLICITLY rather than sharing one fallback: 'terminal' was
+  // the only one when this was written, so `return '$'` doubled as "the terminal
+  // glyph" and "the default". Adding 'extension-view' silently gave an extension
+  // pane a shell prompt — the same widening this codebase hit at ~30 other sites.
   if (isAgentProviderKind(kind)) return getRendererProviderCapabilities(kind).glyph
+  if (kind === 'extension-view') return '◈'
   return '$'
 }
diff --git a/src/renderer/src/features/workspace/ui/AgentActivityModal.tsx b/src/renderer/src/features/workspace/ui/AgentActivityModal.tsx
index 46e53c09f..19e41cb21 100644
--- a/src/renderer/src/features/workspace/ui/AgentActivityModal.tsx
+++ b/src/renderer/src/features/workspace/ui/AgentActivityModal.tsx
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentSessionKind } from '@shared/types/providerKind'
 import type { SessionKind } from '@shared/types/providerKind'
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
 
@@ -128,6 +128,14 @@ export function AgentActivityModal({ open, workspace, onClose }: Props) {
       for (const sessionId of leaves) {
         const meta = workspace.state.sessions[sessionId]
         if (!meta) continue
+        // Extension-view panes are tile leaves with no process and no
+        // transcript, so they have no activity to report and every column here
+        // ("last active", "live", status tone, bury) is meaningless for them.
+        // Skipping is right rather than rendering an empty row: this modal is a
+        // triage list, and a permanently-blank entry per open extension pane is
+        // pure noise in the one view meant to answer "what is my fleet doing".
+        // Terminals stay because a PTY genuinely has running/exited state.
+        if (meta.kind === 'extension-view') continue
         const kind = (meta.kind ?? DEFAULT_PROVIDER) as SessionKind
         const runtime = workspace.runtimes[sessionId]
 
@@ -287,9 +295,11 @@ export function AgentActivityModal({ open, workspace, onClose }: Props) {
     (row: Row) => {
       // Agent sessions only — bury keeps the process alive so the
       // user can revive from the Revive Buried Pane command. Codex
-      // and Claude both support this; terminal doesn't (no notion
-      // of a resumable conversation).
-      if (row.kind === 'terminal') return
+      // and Claude both support this; a terminal does not (no notion
+      // of a resumable conversation) and an extension-view pane has
+      // no process to keep alive at all — burying one would park a
+      // leaf that Revive then has to fence.
+      if (!isAgentSessionKind(row.kind)) return
       // Close our modal before the bury-note prompt opens so the
       // two dialogs don't stack visually. buryFocused(note, id)
       // already accepts an explicit target id, so the note prompt
@@ -421,7 +431,7 @@ export function AgentActivityModal({ open, workspace, onClose }: Props) {
               </div>
             </>
           )}
-          {row.lastActiveAt == null && row.kind !== 'terminal' && !row.isLive && (
+          {row.lastActiveAt == null && isAgentSessionKind(row.kind) && !row.isLive && (
             <div className="text-[10px] text-muted">no activity yet</div>
           )}
         </div>
@@ -434,7 +444,7 @@ export function AgentActivityModal({ open, workspace, onClose }: Props) {
           `}
           onClick={e => e.stopPropagation()}
         >
-          {row.kind !== 'terminal' && (
+          {isAgentSessionKind(row.kind) && (
             <button
               type="button"
               onClick={() => buryRow(row)}
diff --git a/src/renderer/src/ui/GlobalToast.tsx b/src/renderer/src/ui/GlobalToast.tsx
index bde4a7ee5..df4c9dcca 100644
--- a/src/renderer/src/ui/GlobalToast.tsx
+++ b/src/renderer/src/ui/GlobalToast.tsx
@@ -12,6 +12,18 @@ import { createContext, useCallback, useContext, useRef, useState } from 'react'
 // dismiss: warning-grade toasts (hotkey failures) use long durations so
 // the user actually sees them, and a 10-second banner you can't get rid
 // of reads as broken UI — one click clears it early.
+//
+// WHY z-[1200] and not z-50: the toast sat below the Radix dialog scrim
+// (z-[1100], 88% opaque) so any toast raised while a modal was open was
+// washed out to invisibility. That went unnoticed for as long as every caller
+// was non-modal chrome — TileLeaf, SafeInlineCode, SafeMarkdownLink. It broke
+// the moment extensions started toasting from inside a hosted view, where the
+// toast can ONLY fire while a dialog is open, making it hidden 100% of the time.
+//
+// Raising the toast rather than lowering the dialog is the correct direction: a
+// toast is by definition the topmost transient layer, and every existing caller
+// is unaffected by it moving up, whereas lowering the dialog would break the
+// modal stacking the entire surface registry depends on.
 
 type GlobalToastContextValue = {
   showToast: (message: string, durationMs?: number) => void
@@ -54,7 +66,7 @@ export function GlobalToastProvider({ children }: { children: React.ReactNode })
           onClick={dismiss}
           title="Dismiss"
           className="
-            fixed top-3 right-3 z-50
+            fixed top-3 right-3 z-[1200]
             toast-enter
             cursor-pointer
             bg-accent/80 border border-accent/40
diff --git a/src/renderer/src/workspace/dispatch/DispatchAgentList.tsx b/src/renderer/src/workspace/dispatch/DispatchAgentList.tsx
index 14ca26b49..d0ed67e63 100644
--- a/src/renderer/src/workspace/dispatch/DispatchAgentList.tsx
+++ b/src/renderer/src/workspace/dispatch/DispatchAgentList.tsx
@@ -2,6 +2,7 @@ import { getRendererProviderCapabilities } from '@providers/registry.renderer.ca
 import {
   DEFAULT_PROVIDER,
   isAgentProviderKind,
+  isAgentSessionKind,
 } from '@shared/types/providerKind'
 import { memo, useCallback, useLayoutEffect, useMemo, useRef } from 'react'
 import { useShallow } from 'zustand/react/shallow'
@@ -402,7 +403,7 @@ export function dispatchRowTitle(
   entries?: Entry[],
 ): string {
   if (row.agentTitle) return row.agentTitle
-  if (row.kind !== 'terminal' && entries) {
+  if (isAgentSessionKind(row.kind) && entries) {
     return cachedLatestPromptTitle(entries, row.kind) ?? row.title
   }
   return row.title
@@ -427,6 +428,12 @@ function dispatchSubtitle(runtime: {
     if (runtime.sessionStatus === 'running') return 'shell running'
     return 'shell idle'
   }
+  // An extension pane has NO process and no runtime of its own, so every branch
+  // below is a lie about it: a freshly created one reported "starting" forever
+  // (sessionStatus undefined), and a rehydrated one reported "idle" because
+  // rehydrate seeds an empty runtime — both claiming an agent lifecycle that does
+  // not exist. It has one honest state.
+  if (kind === 'extension-view') return 'extension view'
   if (runtime.sessionStatus === undefined) return 'starting'
   if (runtime.streamPhase && runtime.streamPhase !== 'idle') return runtime.streamPhase
   if (runtime.sessionStatus === 'running') return 'running'
@@ -452,13 +459,23 @@ function dispatchAttentionLabel(runtime: {
 function DispatchAgentBadge({ kind }: { kind: SessionKind | undefined }) {
   // Registry-derived (#394 phase 4); terminal keeps its literal,
   // undefined kind = pre-kind back-compat (Claude).
+  // Both non-agent kinds are named explicitly. Falling through to DEFAULT_PROVIDER
+  // is only correct for an ABSENT kind (a pre-kind session, which really was
+  // Claude); letting a known non-agent kind reach it badged every extension pane
+  // "Claude". This site was missed by the isAgentSessionKind sweep because it is
+  // spelled `=== 'terminal' ? … : <agent default>`, so it does not contain the
+  // banned `!== 'terminal'` shape while having exactly the same defect.
   const label =
     kind === 'terminal'
       ? 'Terminal'
-      : getRendererProviderCapabilities(isAgentProviderKind(kind) ? kind : DEFAULT_PROVIDER).shortLabel
-  const classes = kind === 'terminal'
-    ? 'border-info-border bg-info-soft text-info'
-    : 'border-border bg-surface-hi text-muted'
+      : kind === 'extension-view'
+        ? 'Extension'
+        : getRendererProviderCapabilities(isAgentProviderKind(kind) ? kind : DEFAULT_PROVIDER)
+            .shortLabel
+  const classes =
+    kind === 'terminal' || kind === 'extension-view'
+      ? 'border-info-border bg-info-soft text-info'
+      : 'border-border bg-surface-hi text-muted'
   return (
     <span className={`flex-shrink-0 px-1.5 py-[1px] text-[9px] font-code leading-none border ${classes}`}>
       {label}
diff --git a/src/renderer/src/workspace/dispatch/dispatchSelectors.ts b/src/renderer/src/workspace/dispatch/dispatchSelectors.ts
index cff4194e7..eb7dc8a6c 100644
--- a/src/renderer/src/workspace/dispatch/dispatchSelectors.ts
+++ b/src/renderer/src/workspace/dispatch/dispatchSelectors.ts
@@ -2,6 +2,7 @@ import type { SessionId, SessionKind, Tab, TabId, WorkspaceState } from '@render
 import { collectLeaves } from '@renderer/workspace/tile-tree/treeOps'
 import { tabIndexLabel } from '@renderer/workspace/tile-tree/paneLabelFormat'
 import { resolveTabSessions } from '@renderer/workspace/queries'
+import { isAgentSessionKind } from '@shared/types/providerKind'
 
 export type DispatchAgentRow = {
   key: string
@@ -43,7 +44,7 @@ export function buildDispatchGroups(
   // ("this is in two places at once"). Same exclusivity invariant as
   // detached-vs-grid: each row belongs to exactly one bucket.
   const pinnedSet = new Set(
-    state.pinnedSessionIds.filter(id => state.sessions[id]?.kind !== 'terminal'),
+    state.pinnedSessionIds.filter(id => isAgentSessionKind(state.sessions[id]?.kind)),
   )
 
   // The tab letter answers "which project group owns this row"; the
@@ -262,7 +263,7 @@ export function buildPinnedDispatchRows(
   let pinnedIndex = 1
   for (const sessionId of state.pinnedSessionIds) {
     const meta = state.sessions[sessionId]
-    if (!meta || meta.kind === 'terminal') continue
+    if (!meta || !isAgentSessionKind(meta.kind)) continue
     // Locate the owning tab. A pinned agent that's detached has its
     // tab id on `detachedSessions[sessionId].projectTabId`; a
     // grid-placed pinned agent is a leaf in some tab's tree. We do
diff --git a/src/renderer/src/workspace/extensionPaneOwnership.test.ts b/src/renderer/src/workspace/extensionPaneOwnership.test.ts
new file mode 100644
index 000000000..265a35ee2
--- /dev/null
+++ b/src/renderer/src/workspace/extensionPaneOwnership.test.ts
@@ -0,0 +1,107 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  collectLiveProcessIds,
+  collectOwnedSessionIds,
+  collectTileLeafIds,
+} from '@renderer/workspace/sessionOwnership'
+import type { SessionId, SessionMeta, Tab } from '@renderer/workspace/types'
+
+// The two ownership sets an `extension-view` pane has to sit BETWEEN.
+//
+// It is a real tile leaf, so its metadata must survive every autosave — but it has
+// no process, so rehydrate must never try to spawn or recover one for it. Those are
+// different questions with different answers, and the module they live in was
+// deliberately split so that "excluded from spawning" cannot silently mean
+// "excluded from persistence".
+//
+// That is not a hypothetical pairing. Built on the pre-split shape, the extension
+// skip removed these panes from the OWNED set too, so pickOwnedSessions deleted
+// their metadata on the very next autosave — turning them into the orphan leaves
+// the same module then repairs by collapsing them out of the user's tree.
+
+const AGENT = 'agent-1' as SessionId
+const EXTENSION = 'ext-1' as SessionId
+const TERMINAL = 'term-1' as SessionId
+
+function meta(overrides: Partial<SessionMeta>): SessionMeta {
+  return { cwd: '/repo', ...overrides } as SessionMeta
+}
+
+function workspaceWithAllThreeKinds(): { tabs: Tab[]; sessions: Record<SessionId, SessionMeta> } {
+  return {
+    tabs: [
+      {
+        id: 'tab-1',
+        title: 'Project',
+        focusedSessionId: AGENT,
+        root: {
+          type: 'split',
+          direction: 'horizontal',
+          ratio: 0.5,
+          a: { type: 'leaf', sessionId: AGENT },
+          b: {
+            type: 'split',
+            direction: 'vertical',
+            ratio: 0.5,
+            a: { type: 'leaf', sessionId: EXTENSION },
+            b: { type: 'leaf', sessionId: TERMINAL },
+          },
+        },
+      } as Tab,
+    ],
+    sessions: {
+      [AGENT]: meta({ kind: 'claude' }),
+      [EXTENSION]: meta({ kind: 'extension-view', extensionViewId: 'timer.main' }),
+      [TERMINAL]: meta({ kind: 'terminal', tmuxName: 'ac-term-1' }),
+    },
+  }
+}
+
+describe('extension-view pane ownership', () => {
+  it('is OWNED, so autosave keeps its metadata', () => {
+    // If this ever fails, an extension pane's SessionMeta is deleted on the next
+    // autosave tick and the pane silently disappears on the following launch.
+    const owned = collectOwnedSessionIds(workspaceWithAllThreeKinds())
+    expect(owned.has(EXTENSION)).toBe(true)
+    expect(owned.has(AGENT)).toBe(true)
+    expect(owned.has(TERMINAL)).toBe(true)
+  })
+
+  it('is a tile leaf, like every other pane', () => {
+    expect(collectTileLeafIds(workspaceWithAllThreeKinds()).has(EXTENSION)).toBe(true)
+  })
+
+  it('is NOT in the live-process set, so rehydrate never spawns for it', () => {
+    // Rehydrate spawns or recovers a process for every id in this set. An
+    // extension-view kind reaching SessionManager falls through the provider switch
+    // into the terminal branch and starts a stray shell.
+    const live = collectLiveProcessIds(workspaceWithAllThreeKinds())
+    expect(live.has(EXTENSION)).toBe(false)
+    // …while its neighbours are, so the exclusion is not just "the set is empty".
+    expect(live.has(AGENT)).toBe(true)
+    expect(live.has(TERMINAL)).toBe(true)
+  })
+
+  it('keeps the two sets genuinely different for this kind', () => {
+    // The property that matters, stated directly: owned ⊃ live, and the extension
+    // pane is exactly what sits in the gap. Collapsing the two sets back into one
+    // would pass every other assertion in this file.
+    const input = workspaceWithAllThreeKinds()
+    const owned = collectOwnedSessionIds(input)
+    const live = collectLiveProcessIds(input)
+    const gap = [...owned].filter(id => !live.has(id))
+    expect(gap).toEqual([EXTENSION])
+  })
+
+  it('does not strand a leaf whose metadata is missing entirely', () => {
+    // The failure mode undo-close produced: a leaf in the tree with no row in
+    // `sessions`. It must not be reported as live (there is nothing to spawn — no
+    // cwd, no kind) or the restore-completion gate becomes unsatisfiable forever,
+    // which locks autosave and freezes the workspace file.
+    const input = workspaceWithAllThreeKinds()
+    delete input.sessions[EXTENSION]
+    expect(collectLiveProcessIds(input).has(EXTENSION)).toBe(false)
+    expect(collectOwnedSessionIds(input).has(EXTENSION)).toBe(false)
+  })
+})
diff --git a/src/renderer/src/workspace/gridRelatedAgents.ts b/src/renderer/src/workspace/gridRelatedAgents.ts
index c0b1d168d..47dc577b0 100644
--- a/src/renderer/src/workspace/gridRelatedAgents.ts
+++ b/src/renderer/src/workspace/gridRelatedAgents.ts
@@ -1,3 +1,4 @@
+import { isAgentSessionKind } from '@shared/types/providerKind'
 import { collectLeaves } from '@renderer/workspace/tile-tree/treeOps'
 import type { SessionId, SessionKind, TabId, WorkspaceState } from '@renderer/workspace/types'
 
@@ -18,7 +19,7 @@ export function buildGridRelatedAgentTabs(
   ownerSessionId: SessionId,
 ): GridRelatedAgentTab[] {
   const ownerMeta = state.sessions[ownerSessionId]
-  if (!ownerMeta || ownerMeta.kind === 'terminal') return []
+  if (!ownerMeta || !isAgentSessionKind(ownerMeta.kind)) return []
 
   const candidateIds = sessionIdsOwnedByTab(state, tabId)
   const tabs: GridRelatedAgentTab[] = [{
@@ -33,7 +34,7 @@ export function buildGridRelatedAgentTabs(
   for (const sessionId of candidateIds) {
     if (sessionId === ownerSessionId) continue
     const meta = state.sessions[sessionId]
-    if (!meta || meta.kind === 'terminal') continue
+    if (!meta || !isAgentSessionKind(meta.kind)) continue
 
     // WHY direct linked parent and orchestration root both count here:
     // linked agents flatten to one parent by construction, while orchestration
diff --git a/src/renderer/src/workspace/hook/actions/dispatch.ts b/src/renderer/src/workspace/hook/actions/dispatch.ts
index 9045897a7..f32b893bf 100644
--- a/src/renderer/src/workspace/hook/actions/dispatch.ts
+++ b/src/renderer/src/workspace/hook/actions/dispatch.ts
@@ -16,6 +16,7 @@ import type {
 } from '@renderer/workspace/hook/context'
 import type { WorkspaceRefs } from '@renderer/workspace/hook/refs'
 import type { SessionActions } from '@renderer/workspace/hook/actions/session'
+import { isAgentSessionKind } from '@shared/types/providerKind'
 
 export function useDispatchActions(
   state: { activeTabId: TabId; dispatchMode: DispatchModeState | null; sessions: Record<SessionId, SessionMeta> },
@@ -306,7 +307,7 @@ export function useDispatchActions(
       setState(prev => {
         if (prev.pinnedSessionIds.includes(sessionId)) return prev
         const meta = prev.sessions[sessionId]
-        if (!meta || meta.kind === 'terminal') return prev
+        if (!meta || !isAgentSessionKind(meta.kind)) return prev
         return {
           ...prev,
           pinnedSessionIds: [...prev.pinnedSessionIds, sessionId],
@@ -339,7 +340,7 @@ export function useDispatchActions(
         // at render time.
         const filtered = ids.filter(id => {
           const meta = prev.sessions[id]
-          return meta !== undefined && meta.kind !== 'terminal'
+          return meta !== undefined && isAgentSessionKind(meta.kind)
         })
         // Deduplicate while preserving caller order (first occurrence wins).
         // The modal already enforces this client-side, but a programmatic
diff --git a/src/renderer/src/workspace/hook/actions/pane.ts b/src/renderer/src/workspace/hook/actions/pane.ts
index 067774585..4c686b3c4 100644
--- a/src/renderer/src/workspace/hook/actions/pane.ts
+++ b/src/renderer/src/workspace/hook/actions/pane.ts
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentSessionKind } from '@shared/types/providerKind'
 import {
   expandSessionCloseTargets,
   expandTabCloseTargets,
@@ -65,6 +65,7 @@ import {
   killSessionBackendIfOwned,
   type SessionActions,
 } from '@renderer/workspace/hook/actions/session'
+import type { AgentProviderKind } from '@shared/types/providerKind'
 
 // -----------------------------------------------------------------------------
 // Pane / focus / navigation actions.
@@ -322,11 +323,11 @@ export function usePaneActions(
   startNewAgentPlacement: () => void
   commitNewAgentPlacement: (kind: SessionKind, target: PlacementTarget) => Promise<void>
   createDetachedDispatchAgent: (
-    kind: Exclude<SessionKind, 'terminal'>,
+    kind: AgentProviderKind,
     projectOverride?: { tabId: TabId; anchorSessionId: SessionId },
   ) => Promise<void>
   createLinkedAgent: (
-    kind: Exclude<SessionKind, 'terminal'>,
+    kind: AgentProviderKind,
     parentId: SessionId,
   ) => Promise<void>
   createOrchestrationAgent: (params: {
@@ -355,6 +356,7 @@ export function usePaneActions(
   focusSession: (sessionId: SessionId) => void
   focusSessionInTab: (tabId: string, sessionId: SessionId) => void
   navigate: (direction: 'left' | 'right' | 'up' | 'down') => void
+  openExtensionViewInPane: (viewId: string, direction?: SplitDirection) => void
 } {
   const closeSessionRef = useRef<
     ((targetId: SessionId, options?: CloseSessionOptions) => Promise<boolean>) | null
@@ -371,7 +373,7 @@ export function usePaneActions(
       const resumeSessionId = continuation?.resumeSessionId
       const builtInMcpDomains = continuation?.builtInMcpDomains
       const dispatchSnapshot = refs.stateRef.current
-      if (dispatchSnapshot.dispatchMode && kind !== 'terminal') {
+      if (dispatchSnapshot.dispatchMode && isAgentSessionKind(kind)) {
         // Same target resolution as createDetachedDispatchAgent: follow the
         // focused lane in Tiled Dispatch so cwd and projectTab agree on the
         // project the user is commanding (issue #266 / #248).
@@ -576,7 +578,7 @@ export function usePaneActions(
 
   const createDetachedDispatchAgent = useCallback(
     async (
-      kind: Exclude<SessionKind, 'terminal'>,
+      kind: AgentProviderKind,
       // Explicit project override, supplied by the Dispatch header "+".
       //
       // WHY it must override BOTH halves rather than just the tab: cwd is
@@ -675,7 +677,7 @@ export function usePaneActions(
   // route through applyDispatchSpawnFocus so Tiled lanes and classic
   // focus cannot drift.
   const createLinkedAgent = useCallback(
-    async (kind: Exclude<SessionKind, 'terminal'>, parentId: SessionId) => {
+    async (kind: AgentProviderKind, parentId: SessionId) => {
       const snapshot = refs.stateRef.current
       const parentMeta = snapshot.sessions[parentId]
       if (!parentMeta) {
@@ -2124,6 +2126,62 @@ export function usePaneActions(
     [focusSession, state.activeTabId, state.tabs],
   )
 
+  // Open a contributed extension view as a PANE (a tile leaf), not a modal.
+  //
+  // Unlike every other pane this creates NO backing process: an extension view is
+  // pure renderer UI reconstructed from SessionMeta.extensionViewId by
+  // ExtensionViewLeaf. So it deliberately does NOT call sessionActions.spawn (which
+  // mints the SessionId in MAIN by starting a PTY/agent). It mints its own id — the
+  // one place the renderer is allowed to, the same as tab ids — writes the meta
+  // directly, and splits beside the focused pane. collectLiveProcessIds excludes
+  // 'extension-view', so rehydrate reconstructs this leaf from metadata and never
+  // tries to recover a process for it.
+  const openExtensionViewInPane = useCallback(
+    (viewId: string, direction: SplitDirection = 'vertical') => {
+      const snapshot = refs.stateRef.current
+      const tab = snapshot.tabs.find(t => t.id === snapshot.activeTabId)
+      if (!tab) return
+      // commandTargetSessionIdForState, NOT tab.focusedSessionId. Grid focus is
+      // grid-only: while Dispatch is active it names the hidden pane behind the
+      // Dispatch surface, so anchoring to it split a pane the user could not see
+      // (the #94 class every other action in this file already routes around).
+      const parentSessionId = commandTargetSessionIdForState(snapshot)
+      if (!parentSessionId) return
+      // Cosmetic for a process-less view, but SessionMeta carries a cwd and the
+      // parent pane's is the honest inheritance (mirrors splitFocused).
+      const cwd = snapshot.sessions[parentSessionId]?.cwd ?? ''
+      const sessionId = crypto.randomUUID() as SessionId
+      setState(prev => ({
+        ...prev,
+        ...(() => {
+          // The metadata is committed ONLY if the tree actually took the leaf.
+          // splitLeaf returns the root UNCHANGED when the anchor is not a leaf, and
+          // writing sessions[sessionId] unconditionally then left a row owned by
+          // nothing — dropped on the next autosave with a "dropping unowned
+          // sessions" warning, i.e. a silent no-op the user reads as a broken
+          // command. attachDetachedToGrid guards the same way.
+          let inserted = false
+          const tabs = prev.tabs.map(t => {
+            if (t.id !== prev.activeTabId) return t
+            const root = splitLeaf(t.root, parentSessionId, direction, sessionId)
+            if (root === t.root) return t
+            inserted = true
+            return { ...t, root, focusedSessionId: sessionId }
+          })
+          if (!inserted) return {}
+          return {
+            tabs,
+            sessions: {
+              ...prev.sessions,
+              [sessionId]: { cwd, kind: 'extension-view' as const, extensionViewId: viewId },
+            },
+          }
+        })(),
+      }))
+    },
+    [refs.stateRef, setState],
+  )
+
   return {
     splitFocused,
     startNewAgentPlacement,
@@ -2143,6 +2201,7 @@ export function usePaneActions(
     focusSession,
     focusSessionInTab,
     navigate,
+    openExtensionViewInPane,
   }
 }
 
diff --git a/src/renderer/src/workspace/hook/actions/session.ts b/src/renderer/src/workspace/hook/actions/session.ts
index 994fdb5c6..503ce4170 100644
--- a/src/renderer/src/workspace/hook/actions/session.ts
+++ b/src/renderer/src/workspace/hook/actions/session.ts
@@ -1,6 +1,7 @@
 import {
   DEFAULT_PROVIDER,
   isAgentProviderKind,
+  isAgentSessionKind,
   isSessionKind,
 } from '@shared/types/providerKind'
 import type { SessionRecoverFailureCode } from '@shared/types/session'
@@ -262,12 +263,12 @@ export function useSessionActions(
       const kind: SessionKind = opts?.kind ?? DEFAULT_PROVIDER
       const dangerousMode =
         opts?.dangerousMode ??
-        (kind !== 'terminal' ? refs.dangerousAgentsRef.current : undefined)
+        (isAgentSessionKind(kind) ? refs.dangerousAgentsRef.current : undefined)
       // Agent providers both accept `useProxy`; terminals ignore it.
       // Claude uses MITM proxy streaming, Codex uses a local Responses
       // proxy via `openai_base_url`.
       const useProxy =
-        kind !== 'terminal' ? refs.useProxyStreamingRef.current : undefined
+        isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined
       const builtInMcpDomains =
         isAgentProviderKind(kind)
           ? resolveSessionBuiltInMcpDomains({
@@ -310,7 +311,7 @@ export function useSessionActions(
         cwd,
         kind,
         ...(tmuxName ? { tmuxName } : {}),
-        ...(kind !== 'terminal' && opts?.resumeSessionId
+        ...(isAgentSessionKind(kind) && opts?.resumeSessionId
           ? {
               providerSessionId: opts.resumeSessionId,
               providerSessionIdSource: 'resume-request' as const,
@@ -337,7 +338,7 @@ export function useSessionActions(
           ...prev,
           [sessionId]: {
             ...base,
-            ...(kind !== 'terminal'
+            ...(isAgentSessionKind(kind)
               ? seedResumedRuntimeFields(current, meta)
               : {
                   hasOlderHistory: false,
@@ -352,7 +353,7 @@ export function useSessionActions(
           },
         }
       })
-      if (kind !== 'terminal' && meta.providerSessionId) {
+      if (isAgentSessionKind(kind) && meta.providerSessionId) {
         void loadInitialHistoryForSession({
           sessionId,
           meta,
@@ -454,6 +455,21 @@ export function useSessionActions(
         if (!meta) {
           throw new Error(`Cannot wake ${sessionId}; no persisted session metadata exists.`)
         }
+        // ── A PROCESS-LESS LEAF IS ALREADY LIVE ──
+        // isSessionKind now accepts 'extension-view', so this function used to sail
+        // past the unsupported-kind guard below, call recoverSession, and get main's
+        // "extension-view panes have no process to recover" rejection — which it
+        // throws. That stranded a pane permanently in three separate flows, all of
+        // which funnel through here: Revive Buried, Attach Detached, and Attach All.
+        // Bury and Detach-to-Dispatch are both ungated commands, so this was a
+        // one-way trip with Kill Buried as the only exit.
+        //
+        // Fencing at this single choke point covers all three callers and mirrors the
+        // two fences main already has. There is nothing to wake: a leaf with no
+        // process is live by definition.
+        if (meta.kind === 'extension-view') {
+          return { sessionId, builtInMcpDomains: undefined }
+        }
         if (meta.kind !== undefined && !isSessionKind(meta.kind)) {
           const message = 'This pane uses an unsupported provider. Update Agent Code or close it.'
           setRuntimes(prev => {
@@ -484,7 +500,7 @@ export function useSessionActions(
                 defaultDomains: refs.defaultBuiltInMcpDomainsRef.current,
               })
             : undefined
-        const resumeSessionId = kind !== 'terminal' ? resumableProviderSessionId(meta) : undefined
+        const resumeSessionId = isAgentSessionKind(kind) ? resumableProviderSessionId(meta) : undefined
         const restoredMeta = withoutProvisionalProviderSession(meta)
         const priorRecoveryFailureCode =
           refs.latestRuntimesRef.current[sessionId]?.recoveryFailureCode ?? null
@@ -546,8 +562,8 @@ export function useSessionActions(
             resumeSessionId,
             builtInMcpDomains,
             recoverTmuxName: kind === 'terminal' ? meta.tmuxName : undefined,
-            dangerousMode: kind !== 'terminal' ? refs.dangerousAgentsRef.current : undefined,
-            useProxy: kind !== 'terminal' ? refs.useProxyStreamingRef.current : undefined,
+            dangerousMode: isAgentSessionKind(kind) ? refs.dangerousAgentsRef.current : undefined,
+            useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
           })
           if (!recovery.ok) {
             readyError = new Error(recovery.message)
@@ -785,7 +801,7 @@ export function useSessionActions(
         })
 
         if (
-          kind !== 'terminal' &&
+          isAgentSessionKind(kind) &&
           resumeSessionId &&
           refs.stateRef.current.sessions[sessionId] &&
           refs.latestRuntimesRef.current[sessionId]
@@ -1142,7 +1158,7 @@ export function useSessionActions(
             cwd: meta.cwd,
             resumeSessionId,
             dangerousMode,
-            useProxy: kind !== 'terminal' ? refs.useProxyStreamingRef.current : undefined,
+            useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
             builtInMcpDomains,
           })
           idMap.set(oldId, newId)
diff --git a/src/renderer/src/workspace/hook/actions/undoClose.ts b/src/renderer/src/workspace/hook/actions/undoClose.ts
index 88fc8ecd8..71434cd59 100644
--- a/src/renderer/src/workspace/hook/actions/undoClose.ts
+++ b/src/renderer/src/workspace/hook/actions/undoClose.ts
@@ -1,4 +1,4 @@
-import { DEFAULT_PROVIDER } from '@shared/types/providerKind'
+import { DEFAULT_PROVIDER, isAgentSessionKind } from '@shared/types/providerKind'
 import { useCallback, useState } from 'react'
 
 import type {
@@ -79,18 +79,34 @@ export function useUndoCloseAction(
       //     point of having a tmux backing.
       const meta = entry.sessionMeta
       let newSessionId: SessionId
-      try {
-        newSessionId = await sessionActions.spawn(meta.cwd, {
+      if (meta.kind === 'extension-view') {
+        // ── A PROCESS-LESS LEAF IS RESTORED, NOT SPAWNED ──
+        // Undo previously called spawn() for every kind. Main rejects an
+        // extension-view spawn outright, the catch below turned that into
+        // 'retryable-failure', and undoClose PUSHES A FAILED ENTRY BACK — so the
+        // stack head became permanently poisoned. Every later Cmd+Shift+T popped the
+        // same entry, failed, re-pushed, and returned: all older undo history became
+        // unreachable for the rest of the session.
+        //
+        // Minting the id mirrors openExtensionViewInPane; there is nothing to
+        // recover because there was never a process. The METADATA is written in the
+        // setState below — see the note there, because getting that half wrong is
+        // worse than the bug this branch was added to fix.
+        newSessionId = crypto.randomUUID() as SessionId
+      } else {
+        try {
+          newSessionId = await sessionActions.spawn(meta.cwd, {
           kind: meta.kind ?? DEFAULT_PROVIDER,
           resumeSessionId: resumableProviderSessionId(meta),
           recoverTmuxName: meta.kind === 'terminal' ? meta.tmuxName : undefined,
           // WHY capability intent is restored but credentials are not: closing a pane revokes its
           // session token. Undo must ask main to mint a fresh token from these durable domain names;
           // dropping them makes an undo-restored transcript silently lose tools after restart.
-          builtInMcpDomains: meta.builtInMcpDomains,
-        })
-      } catch {
-        return 'retryable-failure'
+            builtInMcpDomains: meta.builtInMcpDomains,
+          })
+        } catch {
+          return 'retryable-failure'
+        }
       }
 
       let inserted = false
@@ -113,7 +129,29 @@ export function useUndoCloseAction(
             focusedSessionId: newSessionId,
           }
         })
-        return { ...prev, tabs }
+        // ── THE LEAF MUST ARRIVE WITH ITS SessionMeta, IN THE SAME UPDATE ──
+        // For every other kind, `sessionActions.spawn` wrote `sessions[newId]`
+        // before we got here. The extension branch skips spawn, so it has to write
+        // it itself — and the first version did not, which put a leaf into the tile
+        // tree with no row in `sessions`.
+        //
+        // That is not a cosmetic gap. renderWorkspaceLeaf has no missing-meta guard:
+        // `kind = meta?.kind ?? DEFAULT_PROVIDER` resolved to 'claude', so the
+        // extension-view short-circuit was skipped and the restored pane came back as
+        // a dead Claude pane with a live composer sending into nothing. Then, on the
+        // next 400 ms autosave, repairPersistedTabs classified the leaf as an orphan
+        // and closed it out of the serialized tree — and if it was the tab's only
+        // leaf, dropped the whole tab. On-screen and on-disk diverged until relaunch,
+        // after which the pane was simply gone.
+        //
+        // In the SAME updater as the tree edit, deliberately: two setState calls
+        // would leave a window in which a render sees the leaf without its metadata,
+        // which is the same orphan state one tick wide.
+        const sessions =
+          meta.kind === 'extension-view'
+            ? { ...prev.sessions, [newSessionId]: meta }
+            : prev.sessions
+        return { ...prev, tabs, sessions }
       })
 
       if (!inserted) {
@@ -151,6 +189,20 @@ export function useUndoCloseAction(
         if (!meta) {
           return 'stale'
         }
+        // Same process-less restore as the pane branch, and it matters MORE here:
+        // this loop spawns leaves in order, so hitting an extension-view leaf used to
+        // throw partway through, and the catch below then killed every sibling it had
+        // just spawned. Undoing a tab that contained one extension pane started N real
+        // claude/codex processes and their proxies, killed them all, restored nothing,
+        // and poisoned the undo stack.
+        if (meta.kind === 'extension-view') {
+          const newId = crypto.randomUUID() as SessionId
+          idMap.set(oldId, newId)
+          freshSessions[newId] = meta
+          // Deliberately NOT pushed to spawnedIds: there is no process to kill on
+          // rollback, and adding it would make the failure path try to terminate one.
+          continue
+        }
         try {
           const kind: SessionKind = meta.kind ?? DEFAULT_PROVIDER
           // Same per-kind recover hint as the pane-undo branch
@@ -158,7 +210,7 @@ export function useUndoCloseAction(
           // agents.
           const newId = await sessionActions.spawn(meta.cwd, {
             kind,
-            resumeSessionId: kind !== 'terminal' ? resumableProviderSessionId(meta) : undefined,
+            resumeSessionId: isAgentSessionKind(kind) ? resumableProviderSessionId(meta) : undefined,
             recoverTmuxName: kind === 'terminal' ? meta.tmuxName : undefined,
             builtInMcpDomains: meta.builtInMcpDomains,
           })
@@ -218,7 +270,7 @@ export function useUndoCloseAction(
           // detached terminals doesn't silently drop tmuxName.
           const newId = await sessionActions.spawn(detached.meta.cwd, {
             kind,
-            resumeSessionId: kind !== 'terminal'
+            resumeSessionId: isAgentSessionKind(kind)
               ? resumableProviderSessionId(detached.meta)
               : undefined,
             recoverTmuxName: kind === 'terminal' ? detached.meta.tmuxName : undefined,
@@ -253,6 +305,14 @@ export function useUndoCloseAction(
           ...prev,
           tabs,
           activeTabId: restoredTab.id,
+          // `freshSessions` holds metadata for every leaf this restore minted an id
+          // for WITHOUT going through spawn — today that is exactly the
+          // extension-view leaves. It was being populated and then dropped on the
+          // floor: the comment further up explains the merge is unnecessary because
+          // "spawn registers SessionMeta itself", which is true for every branch
+          // except the one that skips spawn. The result was an orphan leaf that
+          // autosave then deleted from the restored tab.
+          sessions: { ...prev.sessions, ...freshSessions },
           detachedSessions: { ...prev.detachedSessions, ...restoredDetached },
           // Restored sessions get fresh ids (idMap); remap any tiled lane that
           // pointed at the closed tab's sessions so the lane follows the
diff --git a/src/renderer/src/workspace/hook/index.ts b/src/renderer/src/workspace/hook/index.ts
index fdd3d0a07..803e670c4 100644
--- a/src/renderer/src/workspace/hook/index.ts
+++ b/src/renderer/src/workspace/hook/index.ts
@@ -905,6 +905,7 @@ export function useWorkspace(
     ensureSessionLive,
     killSession,
     splitFocused: paneActions.splitFocused,
+    openExtensionViewInPane: paneActions.openExtensionViewInPane,
     startNewAgentPlacement: paneActions.startNewAgentPlacement,
     commitNewAgentPlacement: paneActions.commitNewAgentPlacement,
     createDetachedDispatchAgent: paneActions.createDetachedDispatchAgent,
diff --git a/src/renderer/src/workspace/hook/invalidation/effects.ts b/src/renderer/src/workspace/hook/invalidation/effects.ts
index 1b39f338a..a20147b12 100644
--- a/src/renderer/src/workspace/hook/invalidation/effects.ts
+++ b/src/renderer/src/workspace/hook/invalidation/effects.ts
@@ -16,6 +16,8 @@ import {
 } from '@renderer/lib/copyAssistant'
 import { ratiosEqual, sanitizeTileTabsState } from '@renderer/workspace/layout/helpers'
 
+import { isAgentSessionKind } from '@shared/types/providerKind'
+
 import type {
   WorkspaceSetReaderMode,
   WorkspaceSetSpotlight,
@@ -114,7 +116,7 @@ function validFocusSessionIdsForMode(
     : resolveTabSessions(state, tabId)
 
   return options.agentOnly
-    ? sessionIds.filter(sessionId => state.sessions[sessionId]?.kind !== 'terminal')
+    ? sessionIds.filter(sessionId => isAgentSessionKind(state.sessions[sessionId]?.kind))
     : sessionIds
 }
 
@@ -176,7 +178,7 @@ export function usePinnedSessionIdsSanity(
       // (legacy workspace.json, manual reducer slip) treat it like a
       // missing session and drop it — the invariant the modal +
       // command paths depend on is "pinned ids point at agents."
-      return meta !== undefined && meta.kind !== 'terminal'
+      return meta !== undefined && isAgentSessionKind(meta.kind)
     })
     if (valid.length === pinnedSessionIds.length) return
     setState(prev => {
@@ -186,7 +188,7 @@ export function usePinnedSessionIdsSanity(
       // in this file.
       const next = prev.pinnedSessionIds.filter(id => {
         const meta = prev.sessions[id]
-        return meta !== undefined && meta.kind !== 'terminal'
+        return meta !== undefined && isAgentSessionKind(meta.kind)
       })
       if (next.length === prev.pinnedSessionIds.length) return prev
       return { ...prev, pinnedSessionIds: next }
diff --git a/src/renderer/src/workspace/hook/persistence/rehydrate.ts b/src/renderer/src/workspace/hook/persistence/rehydrate.ts
index 38857009d..fde81c90f 100644
--- a/src/renderer/src/workspace/hook/persistence/rehydrate.ts
+++ b/src/renderer/src/workspace/hook/persistence/rehydrate.ts
@@ -1,6 +1,7 @@
 import {
   DEFAULT_PROVIDER,
   isAgentProviderKind,
+  isAgentSessionKind,
   isSessionKind,
 } from '@shared/types/providerKind'
 import type {
@@ -683,15 +684,15 @@ export async function rehydrateWorkspace(
           // loopback URLs/tokens for every new provider process. If rehydrate
           // respawns without the saved domains, the pane visually restores but
           // its tool surface silently changes underneath the user.
-          const resumeSessionId = kind !== 'terminal' ? resumableProviderSessionId(meta) : undefined
+          const resumeSessionId = isAgentSessionKind(kind) ? resumableProviderSessionId(meta) : undefined
           const restoredMeta = withoutProvisionalProviderSession(meta)
           const recovery = await recoverSessionBeforeDeadline(recoveryApi, {
             sessionId: oldId,
             kind,
             cwd: meta.cwd,
             resumeSessionId,
-            dangerousMode: kind !== 'terminal' ? refs.dangerousAgentsRef.current : undefined,
-            useProxy: kind !== 'terminal' ? refs.useProxyStreamingRef.current : undefined,
+            dangerousMode: isAgentSessionKind(kind) ? refs.dangerousAgentsRef.current : undefined,
+            useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
             recoverTmuxName: kind === 'terminal' ? meta.tmuxName : undefined,
             builtInMcpDomains,
             // Only bootstrap can prove the predecessor ID still came from the
@@ -765,7 +766,7 @@ export async function rehydrateWorkspace(
           syncRecoveryProjection()
           commitRehydratedState(newId)
           if (
-            kind !== 'terminal' &&
+            isAgentSessionKind(kind) &&
             resumeSessionId &&
             refs.stateRef.current.sessions[newId] &&
             refs.latestRuntimesRef.current[newId]
diff --git a/src/renderer/src/workspace/sessionOwnership.ts b/src/renderer/src/workspace/sessionOwnership.ts
index 685d2abcb..3c864f0a5 100644
--- a/src/renderer/src/workspace/sessionOwnership.ts
+++ b/src/renderer/src/workspace/sessionOwnership.ts
@@ -198,7 +198,22 @@ export function collectOwnedSessionIds(input: SessionOwnershipInput): Set<Sessio
 // nowhere else. Narrowing `collectTileLeafIds` instead would drop its metadata
 // on the next save — see the comment on that function.
 export function collectLiveProcessIds(input: SessionOwnershipInput): Set<SessionId> {
-  return collectTileLeafIds(input)
+  const live = collectTileLeafIds(input)
+  for (const id of live) {
+    // Extension-view leaves have NO backing process (no PTY, no agent). They ARE
+    // tile leaves — owned and persisted like any other — but they must never enter
+    // the live-process set: rehydrate spawns or recovers a process for every id in
+    // here, and an `extension-view` kind would fall through SessionManager's
+    // provider switch into the terminal-spawn branch and start a stray shell.
+    // Their pane is reconstructed purely from SessionMeta.extensionViewId by
+    // ExtensionViewLeaf, so there is nothing to spawn.
+    //
+    // Narrowed HERE and nowhere else, exactly as the comment above instructs:
+    // narrowing collectTileLeafIds instead would drop these panes from the OWNED
+    // set, and pickOwnedSessions would delete their metadata on the next autosave.
+    if (input.sessions[id]?.kind === 'extension-view') live.delete(id)
+  }
+  return live
 }
 
 export function collectUnownedSessionIds(input: SessionOwnershipInput): SessionId[] {
diff --git a/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx b/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
index 855ba3e78..145818fb7 100644
--- a/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
+++ b/src/renderer/src/workspace/tile-tree/AgentTerminalLeaf.tsx
@@ -17,6 +17,7 @@ import { PaneToast } from '@renderer/workspace/tile-tree/TileLeaf/PaneToast'
 import { useComposerDictation } from '@renderer/workspace/tile-tree/TileLeaf/useComposerDictation'
 import { useAgentTerminalDimensionActive } from '@renderer/workspace/terminal/AgentTerminalOwnership'
 import { AgentTitleHeader } from '@renderer/workspace/tile-tree/AgentTitleHeader'
+import type { AgentProviderKind } from '@shared/types/providerKind'
 
 type Props = {
   sessionId: SessionId
@@ -27,7 +28,7 @@ type Props = {
   workspace: Workspace
   runtime: SessionRuntime
   projectDir: string | null
-  provider: Exclude<SessionKind, 'terminal'>
+  provider: AgentProviderKind
 }
 
 // AgentTerminalLeaf — full-pane raw provider terminal for Claude/Codex agents.
diff --git a/src/renderer/src/workspace/tile-tree/ExtensionViewLeaf.tsx b/src/renderer/src/workspace/tile-tree/ExtensionViewLeaf.tsx
new file mode 100644
index 000000000..2f1e7bba7
--- /dev/null
+++ b/src/renderer/src/workspace/tile-tree/ExtensionViewLeaf.tsx
@@ -0,0 +1,122 @@
+import { useMemo } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import { createAppHostApi } from '@renderer/apps/api/createAppHostApi'
+import { viewComponentFor } from '@renderer/apps/host/viewBridge'
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
+import type { Workspace } from '@renderer/workspace/workspaceStore'
+import type { SessionId } from '@renderer/workspace/types'
+
+/**
+ * A contributed extension view mounted as a grid/dispatch PANE (WS6).
+ *
+ * The same frame the modal path uses (viewBridge → iframe sandbox), only the host
+ * container is a tile leaf instead of a dialog. That reuse is the whole payoff of the
+ * DOM-level ViewMount contract: an extension view is location-agnostic, so "in a
+ * modal" and "in a pane" differ by their surrounding chrome and nothing else.
+ *
+ * The pane's `SessionMeta.extensionViewId` names which view to render. storage/close
+ * are keyed by EXTENSION id (the part before the dot), matching AppHostSurface, so a
+ * pane and a modal of the same extension share state; `ui.close()` closes THIS pane.
+ *
+ * RUNTIME NOTE: this only renders once something spawns an extension-view session —
+ * the creation path (main-minted session + the panel command) is the deep,
+ * runtime-gated remainder of WS6. This is the render seam that receives it.
+ */
+// `paneLabel` and `focused` are deliberately NOT props here, unlike every sibling
+// leaf. An extension owns its whole rectangle — the host draws no header strip over
+// it — so there is no chrome to label and no focus ring to paint. They were accepted
+// and then discarded (`focused` reached a `${focused ? '' : ''}` template), which
+// reads as "focus styling exists" to anyone scanning the file.
+type Props = {
+  sessionId: SessionId
+  onFocusRequest: () => void
+  workspace: Workspace
+}
+
+export function ExtensionViewLeaf({ sessionId, workspace, onFocusRequest }: Props) {
+  const installedExtensions = useAppStore(state => state.installedExtensions)
+  const installedExtensionsLoaded = useAppStore(state => state.installedExtensionsLoaded)
+  const { showToast } = useGlobalToast()
+
+  const persistedViewId = workspace.state.sessions[sessionId]?.extensionViewId
+  const extensionId = persistedViewId ? (persistedViewId.split('.')[0] ?? persistedViewId) : undefined
+  const entry = extensionId
+    ? installedExtensions.find(candidate => candidate.manifest.id === extensionId)
+    : undefined
+
+  // ── THE PERSISTED VIEW ID MUST BE ONE THE MANIFEST DECLARES ──
+  // extensionViewId is an unconstrained string on SessionMeta, restored from
+  // workspace.json. Deriving the extension from `split('.')[0]` and then trusting the
+  // rest means any persisted "victim.anything" mounts a live broker for victim. It also
+  // used to flow unchecked into the frame document, where it was an injection sink.
+  // Accept it only if the extension actually contributes that view.
+  const viewId =
+    persistedViewId && (entry?.manifest.contributes?.views ?? []).some(v => v.id === persistedViewId)
+      ? persistedViewId
+      : undefined
+
+  const api = useMemo(
+    () =>
+      extensionId
+        ? createAppHostApi({
+            extensionId,
+            showToast,
+            // Closing the extension's own view closes the pane it lives in.
+            closeSurface: () => workspace.closeSession(sessionId),
+          })
+        : null,
+    [extensionId, showToast, workspace, sessionId],
+  )
+
+  const View = useMemo(
+    // fill=true: a pane is a fixed tile, so the view fills it rather than sizing to
+    // its own content the way the floating modal does.
+    //
+    // Depends on the ids and the installed REVISION, never on the `entry` object.
+    // `entry` is a fresh object on every list refetch, so depending on it remounted
+    // the frame whenever any unrelated extension was installed — destroying this
+    // extension's state for someone else's install. The revision changes only when
+    // THIS extension's installed bytes or version change, which is exactly when the
+    // running frame is stale and must be replaced. viewComponentFor keys its cache
+    // the same way, so the two agree by construction.
+    () => (entry && viewId ? viewComponentFor(entry, viewId, true) : null),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [extensionId, viewId, entry?.manifest.version, entry?.sha256],
+  )
+
+  if (!viewId || !entry || !View || !api) {
+    // ── DO NOT CLAIM "NOT INSTALLED" BEFORE THE LIST HAS LOADED ──
+    // installedExtensions starts [] and is filled by an async IPC whose failure path
+    // deliberately leaves the store untouched. Collapsing "still loading" into "not
+    // installed" flashed a false message on every reload, and one failed
+    // extensionsList() made it permanent — sending the user to uninstall and reinstall
+    // an extension that was fine.
+    const stillLoading = !installedExtensionsLoaded
+    return (
+      <div
+        className="flex h-full w-full items-center justify-center bg-canvas px-6 text-center"
+        onMouseDown={onFocusRequest}
+      >
+        <div className="text-[12px] text-muted">
+          {stillLoading
+            ? 'Loading…'
+            : persistedViewId
+              ? `Extension "${extensionId}" is not installed. Install it to restore this pane.`
+              : 'This pane is not backed by an extension view.'}
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    // onMouseDown wires pane focus, which every sibling leaf does and this one did not:
+    // clicking an extension pane left focus on the previously focused pane, so Cmd+W
+    // then closed the WRONG pane. The cross-origin iframe swallows mousedown over its
+    // own content, so this catches the surrounding gutter — partial, but strictly
+    // better than a pane that can never be focused by pointer at all.
+    <div className="h-full w-full bg-canvas" onMouseDown={onFocusRequest}>
+      <View api={api} />
+    </div>
+  )
+}
diff --git a/src/renderer/src/workspace/tile-tree/TileLeaf/labels.ts b/src/renderer/src/workspace/tile-tree/TileLeaf/labels.ts
index 9f795c46c..9de6e46c7 100644
--- a/src/renderer/src/workspace/tile-tree/TileLeaf/labels.ts
+++ b/src/renderer/src/workspace/tile-tree/TileLeaf/labels.ts
@@ -18,15 +18,23 @@ export function shortenCwd(cwd: string | null): string {
 }
 
 /** Human label for the provider kind, shown next to the scroll
- *  position badge above the composer. Unknown kinds default to
- *  'Claude Code' — historically every session was Claude, so a
- *  missing kind is treated as claude for back-compat. */
+ *  position badge above the composer. A missing kind defaults to
+ *  'Claude Code' — historically every session was Claude, so an
+ *  absent kind is treated as claude for back-compat. */
 export function providerLabel(kind: SessionKind | undefined): string {
-  // Registry-derived long display name for agent kinds (#394 phase
-  // 2c-2). Terminal is the only non-registry pane kind; undefined
-  // kinds fall back to the DEFAULT_PROVIDER's name (historically
-  // every session was Claude, so a missing kind means Claude).
+  // Registry-derived long display name for agent kinds (#394 phase 2c-2).
+  //
+  // The two non-agent kinds carry literals because neither has a provider
+  // registry entry to derive a name from. They are listed EXPLICITLY rather
+  // than left to the fallback: the `undefined` fallback means "pre-kind
+  // back-compat session, therefore Claude", and letting a known non-agent kind
+  // reach it would print "Claude Code" on a pane that has no agent at all.
+  // extension-view cannot reach here today (TileTree routes it to
+  // ExtensionViewLeaf before TileLeaf mounts), but this function is exported
+  // and takes a bare SessionKind, so the first caller outside the tile would
+  // silently get the wrong label.
   if (kind === 'terminal') return 'Terminal'
+  if (kind === 'extension-view') return 'Extension'
   if (kind !== undefined && isAgentProviderKind(kind)) {
     return getRendererProviderCapabilities(kind).name
   }
diff --git a/src/renderer/src/workspace/tile-tree/TileTree.tsx b/src/renderer/src/workspace/tile-tree/TileTree.tsx
index 443604081..1dd4eeb3c 100644
--- a/src/renderer/src/workspace/tile-tree/TileTree.tsx
+++ b/src/renderer/src/workspace/tile-tree/TileTree.tsx
@@ -11,6 +11,7 @@ import {
 import { AgentTerminalLeaf } from '@renderer/workspace/tile-tree/AgentTerminalLeaf'
 import { MountedAgentTerminalOwner } from '@renderer/workspace/terminal/AgentTerminalOwnership'
 import { TerminalLeaf } from '@renderer/workspace/tile-tree/TerminalLeaf'
+import { ExtensionViewLeaf } from '@renderer/workspace/tile-tree/ExtensionViewLeaf'
 import type { Workspace } from '@renderer/workspace/workspaceStore'
 import type { SessionId, TabId, TileNode } from '@renderer/workspace/types'
 import { paneLabelForSession } from '@renderer/workspace/tile-tree/paneLabels'
@@ -133,6 +134,21 @@ export function renderWorkspaceLeaf(
     )
   }
 
+  // Extension-view pane. Short-circuited BEFORE getRendererProvider(kind), which
+  // throws on any non-agent kind — the single edit that lights this up in grid,
+  // both dispatch layouts, spotlight, and tile-tabs at once, because they all funnel
+  // here. Uses `sessionId` (the physical leaf) not `renderedSessionId`: an extension
+  // pane has no related-agent tab selection.
+  if (kind === 'extension-view') {
+    return (
+      <ExtensionViewLeaf
+        sessionId={sessionId}
+        onFocusRequest={onFocusRequest}
+        workspace={workspace}
+      />
+    )
+  }
+
   const provider = getRendererProvider(kind)
   const runtime = workspace.getRuntime(renderedSessionId)
   if (getEffectiveAgentSurfaceForSession({
diff --git a/src/renderer/src/workspace/tile-tree/focusModeKeyboardOwnership.renderer.test.tsx b/src/renderer/src/workspace/tile-tree/focusModeKeyboardOwnership.renderer.test.tsx
index f60d80fc9..6be5df1f3 100644
--- a/src/renderer/src/workspace/tile-tree/focusModeKeyboardOwnership.renderer.test.tsx
+++ b/src/renderer/src/workspace/tile-tree/focusModeKeyboardOwnership.renderer.test.tsx
@@ -10,6 +10,14 @@ const harness = vi.hoisted(() => ({
   appState: {} as Record<string, unknown>,
 }))
 
+// useKeybinds reads the extension slice to fold contributed chords into the
+// binding index. The harness builds `appState` by hand, so every slice the hook
+// touches has to be present here or the mock stops resembling the real store —
+// which is how this file started failing the moment extension keybindings landed.
+// Empty is the honest value: these assertions are about first-party focus-mode
+// ownership, and a contributed chord would be a different test.
+const EXTENSION_SLICE = { installedExtensions: [], installedExtensionsLoaded: true }
+
 vi.mock('@renderer/app-state/hooks', () => {
   const useAppStore = Object.assign(
     (selector: (state: Record<string, unknown>) => unknown) => selector(harness.appState),
@@ -117,6 +125,7 @@ function pressOptionArrow(key: 'ArrowUp' | 'ArrowDown'): void {
 describe('focus-mode keyboard ownership', () => {
   beforeEach(() => {
     harness.appState = {
+      ...EXTENSION_SLICE,
       settingsPageOpen: false,
       requestCommandInvocation: vi.fn(),
       settings: {
diff --git a/src/renderer/src/workspace/tile-tree/useKeybinds.ts b/src/renderer/src/workspace/tile-tree/useKeybinds.ts
index 26ec2cdaf..f800be640 100644
--- a/src/renderer/src/workspace/tile-tree/useKeybinds.ts
+++ b/src/renderer/src/workspace/tile-tree/useKeybinds.ts
@@ -1,8 +1,9 @@
 import { useEffect, useMemo } from 'react'
 
 import { useAppStore } from '@renderer/app-state/hooks'
+import { deriveExtensionKeybindings } from '@renderer/apps/host/derive'
 import { buildDefaultKeybindings } from '@renderer/features/command-keybindings/defaults'
-import type { BindingContext } from '@renderer/features/command-keybindings/defaults'
+import type { BindingContext, CommandBindingDefault } from '@renderer/features/command-keybindings/defaults'
 import { keybindingFromEvent } from '@renderer/features/command-keybindings/normalize'
 import { commandOwnsOpenSurface } from '@renderer/features/command-palette/surfaceOwnership'
 import { resolveEffectiveKeybindings } from '@renderer/features/command-keybindings/resolve'
@@ -263,9 +264,17 @@ const SPOTLIGHT_FOCUS_MODE_COMMAND_IDS: ReadonlySet<string> = new Set([
 /** Chord -> candidate commands, built once per override change. */
 function buildBindingIndex(
   overrides: Record<string, string[]>,
+  // Extension-contributed defaults, concatenated onto the shipped table. A user
+  // override still wins (resolveEffectiveKeybindings applies overrides on top of
+  // whatever defaults it is handed), so this is the ONE site that actually makes
+  // an extension's declared chord fire — the editor/sheet/palette only display it.
+  extensionDefaults: CommandBindingDefault[],
 ): Map<string, { commandId: string; context: BindingContext }[]> {
   const index = new Map<string, { commandId: string; context: BindingContext }[]>()
-  for (const entry of resolveEffectiveKeybindings(overrides, buildDefaultKeybindings())) {
+  for (const entry of resolveEffectiveKeybindings(overrides, [
+    ...buildDefaultKeybindings(),
+    ...extensionDefaults,
+  ])) {
     for (const binding of entry.bindings) {
       const list = index.get(binding) ?? []
       list.push({ commandId: entry.commandId, context: entry.context })
@@ -283,6 +292,7 @@ export function useKeybinds(
   const commandKeybindingOverrides = useAppStore(
     state => state.settings.commandKeybindingOverrides,
   )
+  const installedExtensions = useAppStore(state => state.installedExtensions)
   const agentViewMode = useAppStore(state => state.settings.agentViewMode)
   const closeSettingsPage = useAppStore(state => state.closeSettingsPage)
   const buryPromptSessionId = useAppStore(state => state.buryPromptSessionId)
@@ -315,12 +325,30 @@ export function useKeybinds(
   const pinAgentsOpen = useAppStore(state => state.pinAgentsOpen)
   const closePinAgents = useAppStore(state => state.closePinAgents)
 
+  // Extension keybinding defaults, derived from installed manifests (no bundle
+  // import). Recomputed only when the installed set changes, so an install/remove
+  // makes a contributed chord start/stop firing without a reload.
+  //
+  // ── THE `?? []` IS NOT DEFENSIVE NOISE ──
+  // This hook owns the global keydown router: if it throws during render, the
+  // application has no keyboard at all, and it throws before anything can catch
+  // it usefully. That is the same shape as the persist-version bug that
+  // black-screened launch twice (#249) — a store slice that was expected to exist
+  // and did not. Extension state is the newest slice and the one most likely to be
+  // absent from a partially-restored or partially-mocked store, so the core
+  // keyboard path degrades to "no contributed chords" instead of taking the app
+  // down with it. Nothing else in this hook has an opinion about extensions.
+  const extensionKeybindings = useMemo(
+    () => deriveExtensionKeybindings(installedExtensions ?? []),
+    [installedExtensions],
+  )
+
   // Built once per override change, not per keystroke. Resolving inside the
   // handler meant rebuilding the default table and re-normalizing ~30 strings
   // on every keydown, including ordinary typing.
   const bindingIndex = useMemo(
-    () => buildBindingIndex(commandKeybindingOverrides),
-    [commandKeybindingOverrides],
+    () => buildBindingIndex(commandKeybindingOverrides, extensionKeybindings),
+    [commandKeybindingOverrides, extensionKeybindings],
   )
 
   useEffect(() => {
diff --git a/src/renderer/src/workspace/types.ts b/src/renderer/src/workspace/types.ts
index a608f0fdd..a987c0d9a 100644
--- a/src/renderer/src/workspace/types.ts
+++ b/src/renderer/src/workspace/types.ts
@@ -137,6 +137,14 @@ export type SessionMeta = {
    * and for agent sessions (P3 may extend this; not in P1).
    */
   tmuxName?: string
+  /**
+   * Set on an `extension-view` pane: the contributed view id (`<extensionId>.<view>`)
+   * this leaf hosts. The durable handle that answers "which extension view does this
+   * pane render", the extension analogue of `tmuxName` for a terminal. The render
+   * seam reads it; rehydrate uses it to decide whether the owning extension is still
+   * installed. Absent on every non-extension kind.
+   */
+  extensionViewId?: string
   /**
    * Set on a "Linked Agent" — an agent spawned via the Linked Agent
    * command with another agent as its parent. Two consequences:
diff --git a/src/shared/types/extensionId.test.ts b/src/shared/types/extensionId.test.ts
new file mode 100644
index 000000000..c4e5433ab
--- /dev/null
+++ b/src/shared/types/extensionId.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest'
+
+import { isValidExtensionId } from '@shared/types/extensionId.js'
+
+// The single validator every untrusted-string → extension-identity conversion goes
+// through. The traversal cases below are the ones that actually reached a filesystem
+// path join: `agent-code-ext://../extension-grants.json` parsed to hostname `..`, which
+// rooted the scheme handler at the whole state directory.
+
+describe('isValidExtensionId', () => {
+  it('accepts well-formed ids', () => {
+    for (const id of ['a', 'timer', 'mini-games', 'a1', 'a'.repeat(64)]) {
+      expect(isValidExtensionId(id), id).toBe(true)
+    }
+  })
+
+  it('rejects traversal and separators', () => {
+    for (const id of ['..', '.', '../..', 'a/b', 'a\\b', '../evil', '%2e%2e']) {
+      expect(isValidExtensionId(id), id).toBe(false)
+    }
+  })
+
+  it('rejects shapes that are not lowercase-letter-led', () => {
+    for (const id of ['', '1abc', '-abc', 'Abc', 'aBc', 'a_b', 'a.b', 'a'.repeat(65)]) {
+      expect(isValidExtensionId(id), id).toBe(false)
+    }
+  })
+
+  it('rejects non-strings rather than coercing them', () => {
+    for (const id of [null, undefined, 42, {}, []]) {
+      expect(isValidExtensionId(id)).toBe(false)
+    }
+  })
+})
diff --git a/src/shared/types/extensionId.ts b/src/shared/types/extensionId.ts
new file mode 100644
index 000000000..7bbce944d
--- /dev/null
+++ b/src/shared/types/extensionId.ts
@@ -0,0 +1,28 @@
+/**
+ * The extension-id shape, in ONE place.
+ *
+ * ── WHY THIS MODULE EXISTS ──
+ * This pattern was previously written out in four files (`storage.ts`, `manifest.ts`,
+ * `frameProtocol.ts`, and a doc comment in `apps/types.ts`) — and the one place that
+ * mattered most, the `agent-code-ext://` scheme handler, had no copy at all. It took
+ * `url.hostname` verbatim and used it as a path segment, so a request for
+ * `agent-code-ext://../extension-grants.json` resolved the install root to the whole
+ * state directory and the containment check then certified that wrong root.
+ *
+ * Four hand-copied regexes is exactly how one gets omitted. Everything that turns an
+ * untrusted string into an extension identity imports from here.
+ */
+
+/** Lowercase, starts with a letter, max 64 chars. Safe as a path segment and a hostname. */
+export const EXTENSION_ID_PATTERN = /^[a-z][a-z0-9-]{0,63}$/
+
+/**
+ * True when `id` is a well-formed extension id.
+ *
+ * Call this BEFORE using the value in any path join, URL, or filesystem operation —
+ * not after. A containment check that resolves against an attacker-chosen root
+ * validates the wrong thing.
+ */
+export function isValidExtensionId(id: unknown): id is string {
+  return typeof id === 'string' && EXTENSION_ID_PATTERN.test(id)
+}
diff --git a/src/shared/types/extensions.ts b/src/shared/types/extensions.ts
new file mode 100644
index 000000000..1da85028f
--- /dev/null
+++ b/src/shared/types/extensions.ts
@@ -0,0 +1,186 @@
+// Extension manifest and install-ledger shapes, shared by main and renderer.
+//
+// The manifest is authored by a third party and read off disk, so main validates it
+// with zod (see main/extensions/manifest.ts) and the renderer only ever sees the
+// validated result. These types are the contract between those two halves — the zod
+// schema is the source of truth for VALIDATION, and this file is the source of truth
+// for the SHAPE. If they drift, the schema wins and this file is the bug.
+
+/** Where a contributed view is rendered. The host owns the chrome; an extension
+ *  declares the KIND of surface it wants, not the pixels around it. Only 'modal'
+ *  is implemented in v1 — the others are the same registration with a different
+ *  host shell, and are reserved so a manifest written for them stays valid. */
+export type ExtensionViewMount = 'modal' | 'panel'
+
+export type ExtensionCommandContribution = {
+  /** Must be namespaced `<extensionId>.` — enforced at install. */
+  id: string
+  title: string
+  description?: string
+  keywords?: string[]
+}
+
+export type ExtensionViewContribution = {
+  id: string
+  title: string
+  mount: ExtensionViewMount
+}
+
+export type ExtensionSettingContribution =
+  | { id: string; title: string; description?: string; type: 'boolean'; default: boolean }
+  | { id: string; title: string; description?: string; type: 'number'; default: number }
+  | { id: string; title: string; description?: string; type: 'string'; default: string }
+
+export type ExtensionKeybindingContribution = {
+  /** A command id this manifest also contributes. */
+  command: string
+  /** Accelerator, e.g. `cmd+shift+t`. Consulted AFTER every first-party
+   *  binding, so an extension can never shadow ⌘W. */
+  key: string
+}
+
+export type ExtensionContributions = {
+  commands?: ExtensionCommandContribution[]
+  views?: ExtensionViewContribution[]
+  settings?: ExtensionSettingContribution[]
+  keybindings?: ExtensionKeybindingContribution[]
+}
+
+/**
+ * A power an extension can REQUEST beyond the always-granted Tier-0 API
+ * (storage/ui/theme, which need no permission). A closed set: an unknown
+ * capability fails validation at install, exactly as an unknown activation event
+ * does, rather than being silently ignored.
+ *
+ * ── THIS LIST CONTAINS ONLY CAPABILITIES THAT ARE IMPLEMENTED ──
+ * It previously also declared Tier 2 (`fs.read`, `transcript.read`, `git.read`)
+ * and Tier 3 (`sessions.prompt`, `fs.write`, `git.commit`, `network.fetch`).
+ * None of them existed. There was no request method for any of them in
+ * frameProtocol, no arm in frameHost.perform, and no API surface an extension
+ * could call — `network.fetch` was additionally impossible by construction,
+ * since the child CSP is `connect-src <self>` only.
+ *
+ * What that produced was consent theatre: a manifest could request "filesystem
+ * write and git commit", the user got a blocking OS warning dialog naming those
+ * powers, approved it, and a permanent grant was written for capabilities that
+ * did nothing. The cost is not the dead code — it is that it trains people to
+ * click through the one dialog in the product that must not become routine.
+ *
+ * So the rule for this union is: **a capability is added here in the same change
+ * that implements it**, i.e. together with its member of `frameRequestSchema`,
+ * its entry in frameHost's REQUIRED_CAPABILITY record (which will not compile
+ * without one), and its arm in `perform`. Declaring the vocabulary ahead of the
+ * mechanism is what went wrong; the tier names below are a design note about
+ * blast radius, not a roadmap that manifests may write against.
+ *
+ * Tier 1 is read-only metadata. Tier 2 (reads real user content) and Tier 3
+ * (acts) are deliberately unrepresentable until something implements them — a
+ * manifest asking for one fails install with a message naming it, which is
+ * actionable, rather than being granted nothing in silence.
+ */
+export type ExtensionCapability =
+  // Tier 1 — read-only metadata. Implemented: frameProtocol has a request
+  // member for each, frameHost gates each on this grant, createAppHostApi
+  // returns a curated serializable snapshot.
+  | 'workspace.observe'
+  | 'sessions.observe'
+  | 'panes.observe'
+
+export const EXTENSION_CAPABILITIES: readonly ExtensionCapability[] = [
+  'workspace.observe',
+  'sessions.observe',
+  'panes.observe',
+]
+
+/**
+ * When the host imports and activates an extension's module.
+ *
+ * The whole reason contributions are DECLARED rather than registered by running
+ * the extension: the palette and Settings can list everything an extension
+ * offers while its module has never been loaded, so activation can be deferred
+ * to first use. Without declarations, populating a command list would require
+ * importing every installed extension at startup.
+ */
+export type ExtensionActivationEvent =
+  | 'onStartupFinished'
+  | '*'
+  | `onCommand:${string}`
+  | `onView:${string}`
+
+/** Contents of `agent-code.extension.json` at the root of an extension repository. */
+export type ExtensionManifest = {
+  /** Stable identity. Also the install directory name and the storage namespace,
+   *  so it is constrained to /^[a-z][a-z0-9-]{0,63}$/ — see manifest.ts. */
+  id: string
+  name: string
+  description: string
+  /** Author's own version string. Displayed and recorded; not interpreted. */
+  version: string
+  /** Which AgentCodeApi major this extension was written against. The host refuses
+   *  to load a manifest whose apiVersion it does not implement, which is the whole
+   *  point of versioning the ABI rather than silently passing a newer host object
+   *  to an extension written for an older one. */
+  apiVersion: number
+  /** Path, relative to the repository root, of the built ES module to load.
+   *  Must stay inside the bundle — validated, not trusted. */
+  entry: string
+  keywords?: string[]
+  /** Absent means "never activate" — legal, and how a manifest that only
+   *  contributes settings behaves. */
+  activationEvents?: ExtensionActivationEvent[]
+  contributes?: ExtensionContributions
+  /** Capabilities beyond Tier 0 this extension requests. The user grants (or
+   *  declines) them at install; absent/empty means Tier 0 only. */
+  permissions?: ExtensionCapability[]
+}
+
+/** One row in the install ledger (`extensions.json`). */
+export type InstalledExtension = {
+  manifest: ExtensionManifest
+  /**
+   * Where this extension came from, in a form the installer can re-run.
+   *
+   * WHY `origin` exists rather than sniffing `repo`: a GitHub install stores
+   * `owner/repo` here, and a local-folder install stores an ABSOLUTE PATH. Update
+   * fed this field straight back to `installExtension`, which calls
+   * `normalizeRepo` — so every Update of a locally-loaded extension failed with
+   * `"/Users/…/timer" is not a GitHub repository`, which is the one install path an
+   * author uses on every single rebuild. Making the origin explicit lets Update
+   * dispatch instead of guessing from the string's shape.
+   */
+  origin: 'github' | 'local'
+  /** `owner/repo` for a GitHub install; the absolute source folder for a local one. */
+  repo: string
+  /** The git ref actually installed — a release tag when one exists, else the
+   *  default branch name. Recorded so an update can report what it is moving from. */
+  ref: string
+  /** SHA-256 of the downloaded tarball (or, for a local-folder install, of the
+   *  built entry file — there is no tarball). This is PROVENANCE and nothing
+   *  else: it answers "which bytes did the source hand me", and it is what an
+   *  update reports moving from.
+   *
+   *  ── NO HASH IN THIS LEDGER GATES ANY CAPABILITY ──
+   *  There was briefly a second field here, `bundleSha256`, documented as "the
+   *  integrity record the capability grant binds to". Nothing ever read it: the
+   *  grant check recomputes the bundle hash FROM DISK and compares it against the
+   *  grants file, never against a ledger row. A persisted copy of a security value
+   *  that is deliberately not consulted is a trap — the obvious optimisation ("the
+   *  ledger already has the hash, skip the expensive recompute") reinstates exactly
+   *  the tautology this design removed — so the field is gone rather than
+   *  documented. If you want to know which bytes are installed, hash them. */
+  sha256: string
+  /** Epoch millis. */
+  installedAt: number
+}
+
+/** What the Settings UI renders for each installed extension. */
+export type ExtensionListEntry = InstalledExtension & {
+  /** False when the ledger has a row but the bundle directory is missing or its
+   *  entry file is absent — a half-removed or hand-deleted install. Surfaced rather
+   *  than hidden so the user can see why an extension stopped appearing. */
+  present: boolean
+}
+
+export type ExtensionInstallResult =
+  | { ok: true; entry: ExtensionListEntry }
+  | { ok: false; error: string }
diff --git a/src/shared/types/providerConfig.ts b/src/shared/types/providerConfig.ts
index d4211c7f2..ac2099264 100644
--- a/src/shared/types/providerConfig.ts
+++ b/src/shared/types/providerConfig.ts
@@ -15,7 +15,7 @@
 
 import type { ComponentType, ReactNode } from 'react'
 import type { SessionOptions, SessionInfo, AgentSession } from '@shared/types/session.js'
-import type { AgentProviderKind } from '@shared/types/providerKind.js'
+import type { AgentProviderKind, SessionKind } from '@shared/types/providerKind.js'
 import type { Entry, ToolResultBlock, ToolUseBlock } from '@shared/types/transcript.js'
 
 /**
@@ -109,7 +109,14 @@ export type TileLeafRelatedAgentTab = {
   relation: 'parent' | 'linked' | 'orchestration'
   label: string
   title: string
-  kind: AgentProviderKind | 'terminal' | undefined
+  // Typed SessionKind because the value flows from SessionMeta.kind, which is a
+  // SessionKind. buildGridRelatedAgentTabs guarantees at runtime that only agent
+  // kinds actually arrive here (it drops every non-agent owner and candidate via
+  // isAgentSessionKind), so the wider type is a plumbing artifact, not a claim
+  // that a terminal or extension-view pane can be a related-agent tab. Narrowing
+  // it to AgentProviderKind would need a cast at the one construction site and
+  // would move the guarantee from a readable filter into an assertion.
+  kind: SessionKind | undefined
   placement: 'grid' | 'detached'
 }
 
diff --git a/src/shared/types/providerKind.test.ts b/src/shared/types/providerKind.test.ts
index e10d04a78..9c6e71923 100644
--- a/src/shared/types/providerKind.test.ts
+++ b/src/shared/types/providerKind.test.ts
@@ -4,6 +4,7 @@ import {
   AGENT_PROVIDER_KINDS,
   SESSION_KINDS,
   isAgentProviderKind,
+  isAgentSessionKind,
   isSessionKind,
 } from '@shared/types/providerKind.js'
 
@@ -18,28 +19,68 @@ describe('provider kind source of truth', () => {
     expect([...AGENT_PROVIDER_KINDS]).toEqual(['claude', 'codex', 'opencode'])
   })
 
-  it('SESSION_KINDS is the agent kinds plus terminal, derived (never hand-listed)', () => {
-    expect([...SESSION_KINDS]).toEqual(['claude', 'codex', 'opencode', 'terminal'])
+  it('SESSION_KINDS is the agent kinds plus the non-agent pane kinds, derived', () => {
+    // Asserted as a DERIVATION rather than a literal list, which is what the guard
+    // was always for: hand-listing is exactly how the set silently drifts from
+    // AGENT_PROVIDER_KINDS.
+    expect([...SESSION_KINDS]).toEqual([...AGENT_PROVIDER_KINDS, 'terminal', 'extension-view'])
   })
 
   it('isAgentProviderKind accepts wired providers and rejects everything else', () => {
     expect(isAgentProviderKind('claude')).toBe(true)
     expect(isAgentProviderKind('codex')).toBe(true)
     expect(isAgentProviderKind('opencode')).toBe(true)
-    // terminal is a SessionKind but NOT an agent provider — it must be rejected
-    // here so agent-only code paths can't be handed it.
+    // terminal and extension-view are SessionKinds but NOT agent providers — they
+    // must be rejected here so agent-only code paths can't be handed one.
     expect(isAgentProviderKind('terminal')).toBe(false)
-        expect(isAgentProviderKind('')).toBe(false)
+    expect(isAgentProviderKind('extension-view')).toBe(false)
+    expect(isAgentProviderKind('')).toBe(false)
     expect(isAgentProviderKind(undefined)).toBe(false)
     expect(isAgentProviderKind(null)).toBe(false)
     expect(isAgentProviderKind(42)).toBe(false)
   })
 
-  it('isSessionKind accepts agent kinds plus terminal', () => {
-    expect(isSessionKind('claude')).toBe(true)
-    expect(isSessionKind('codex')).toBe(true)
-    expect(isSessionKind('terminal')).toBe(true)
-    expect(isSessionKind('opencode')).toBe(true)
+  it('isSessionKind accepts every pane kind, agent or not', () => {
+    for (const kind of SESSION_KINDS) expect(isSessionKind(kind)).toBe(true)
     expect(isSessionKind(undefined)).toBe(false)
+    expect(isSessionKind('not-a-kind')).toBe(false)
+  })
+})
+
+// ── The regression this file exists for ──
+//
+// Adding 'extension-view' to SessionKind silently reclassified ~30 renderer call
+// sites that spelled "is an agent" as `kind !== 'terminal'`: pane command `when`
+// guards, the Dispatch pin filter, Reader Mode's list, the activity modal, the
+// related-agent tabs. Every one of those expressions stayed valid TypeScript and
+// changed meaning, so no compiler and no existing test could see it.
+//
+// These assertions are deliberately written as a PARTITION over SESSION_KINDS
+// rather than as a list of literals. A future non-agent pane kind added to
+// SESSION_KINDS but forgotten in AGENT_PROVIDER_KINDS is then covered the moment
+// it is declared — which is the only shape of test that could have caught the
+// original defect, because the original defect WAS "we added a kind and forgot
+// where it flows".
+describe('isAgentSessionKind — the agent/non-agent partition', () => {
+  it('is true for exactly the agent provider kinds', () => {
+    for (const kind of SESSION_KINDS) {
+      expect(isAgentSessionKind(kind)).toBe(isAgentProviderKind(kind))
+    }
+  })
+
+  it('rejects every non-agent pane kind', () => {
+    const nonAgents = SESSION_KINDS.filter(kind => !isAgentProviderKind(kind))
+    // Guards the guard: if this ever empties, the partition assertion above
+    // becomes vacuously true and would pass while testing nothing.
+    expect(nonAgents.length).toBeGreaterThan(0)
+    for (const kind of nonAgents) expect(isAgentSessionKind(kind)).toBe(false)
+  })
+
+  it('treats an absent kind as an agent, matching DEFAULT_PROVIDER back-compat', () => {
+    // SessionMeta.kind postdates the workspace format; sessions persisted before
+    // it existed genuinely were Claude. Every call site this predicate replaced
+    // already read `undefined` as an agent (absent !== 'terminal'), so flipping
+    // this to false would strand every pre-kind pane in a saved workspace.
+    expect(isAgentSessionKind(undefined)).toBe(true)
   })
 })
diff --git a/src/shared/types/providerKind.ts b/src/shared/types/providerKind.ts
index cef696350..d9a03a154 100644
--- a/src/shared/types/providerKind.ts
+++ b/src/shared/types/providerKind.ts
@@ -38,16 +38,28 @@ export const AGENT_PROVIDER_KINDS = ['claude', 'codex', 'opencode'] as const
 export type AgentProviderKind = (typeof AGENT_PROVIDER_KINDS)[number]
 
 /**
- * A kind of pane the shell can host. Superset of AgentProviderKind:
- * `'terminal'` is a plain shell pane with no agent transcript/conditions.
- * Terminal is deliberately NOT an AgentProviderKind so code that only
- * makes sense for agents (resume listing, prompt indexing, condition
- * snapshots) cannot accidentally be handed `'terminal'`.
+ * A kind of pane the shell can host. Strict superset of AgentProviderKind, with
+ * two members that are deliberately NOT agents:
+ *
+ *   'terminal'        a plain shell pane. Has a PTY, no agent transcript.
+ *   'extension-view'  a contributed extension view rendered as a tile leaf.
+ *                     Has NO backing process at all — no PTY, no agent — and is
+ *                     reconstructed purely from SessionMeta.extensionViewId.
+ *
+ * Neither is an AgentProviderKind, so code that only makes sense for agents
+ * (resume listing, prompt indexing, condition snapshots, composer drafts) cannot
+ * be handed one by the type system.
+ *
+ * ── HOW TO TEST FOR "IS THIS AN AGENT" ──
+ * Use `isAgentSessionKind`, never `kind !== 'terminal'`. The negative spelling
+ * was correct only while 'terminal' was the ONLY non-agent kind; adding
+ * 'extension-view' silently reclassified every extension pane as an agent at
+ * ~30 call sites at once. See that function for the full account.
  */
-export type SessionKind = AgentProviderKind | 'terminal'
+export type SessionKind = AgentProviderKind | 'terminal' | 'extension-view'
 
 /** All session kinds, runtime form. Kept derived so it never drifts. */
-export const SESSION_KINDS = [...AGENT_PROVIDER_KINDS, 'terminal'] as const
+export const SESSION_KINDS = [...AGENT_PROVIDER_KINDS, 'terminal', 'extension-view'] as const
 
 /**
  * Narrow an untrusted string (IPC arg, persisted metadata, MCP input)
@@ -61,11 +73,43 @@ export function isAgentProviderKind(value: unknown): value is AgentProviderKind
   return typeof value === 'string' && (AGENT_PROVIDER_KINDS as readonly string[]).includes(value)
 }
 
-/** Narrow an untrusted string to a SessionKind (includes 'terminal'). */
+/** Narrow an untrusted string to a SessionKind (any pane kind, agent or not). */
 export function isSessionKind(value: unknown): value is SessionKind {
   return typeof value === 'string' && (SESSION_KINDS as readonly string[]).includes(value)
 }
 
+/**
+ * Does this pane run an agent — i.e. does it have a transcript, a composer,
+ * conditions, a resumable provider session?
+ *
+ * ── WHY THIS EXISTS, AND WHY `kind !== 'terminal'` IS BANNED ──
+ * For most of this codebase's history 'terminal' was the only non-agent kind, so
+ * "is an agent" was spelled `kind !== 'terminal'` in about thirty places: pane
+ * command `when` guards, the Dispatch pin filter, rehydrate's spawn options,
+ * Reader Mode's session list, the activity modal, invalidation effects.
+ *
+ * Adding 'extension-view' to SessionKind reclassified every one of them at once,
+ * and the compiler could not see it — the expression stayed perfectly valid and
+ * silently changed meaning. Concretely, an extension pane became eligible for
+ * "Copy Last Response" (which then calls getRuntime on a pane that has no
+ * runtime), got pinned into Dispatch as an agent, was offered a composer it does
+ * not have, and rendered a "Claude Code" provider label in its header.
+ *
+ * The positive spelling cannot fail that way: a new non-agent kind is simply not
+ * in AGENT_PROVIDER_KINDS, so it is excluded by construction everywhere at once.
+ *
+ * ── WHY `undefined` COUNTS AS AN AGENT ──
+ * Not a shortcut — it is the same back-compat truth DEFAULT_PROVIDER encodes.
+ * `SessionMeta.kind` is optional because it postdates the workspace format, and
+ * every session persisted before it existed genuinely was Claude. Every call site
+ * this replaced already treated `undefined` as an agent (an absent kind is not
+ * equal to 'terminal'), so preserving that here is what makes the substitution
+ * behaviour-preserving for real sessions while fixing extension panes.
+ */
+export function isAgentSessionKind(value: SessionKind | undefined): boolean {
+  return value === undefined || isAgentProviderKind(value)
+}
+
 /**
  * The provider used when a spawn/restore site has no explicit kind.
  *
diff --git a/testing/unit/testTierRouting.test.ts b/testing/unit/testTierRouting.test.ts
index 9c888cf85..8c5c2f9b3 100644
--- a/testing/unit/testTierRouting.test.ts
+++ b/testing/unit/testTierRouting.test.ts
@@ -15,17 +15,36 @@ describe('root test-tier routing', () => {
     expect(unitTestIncludes).toEqual([
       'testing/unit/**/*.test.ts',
       'src/**/*.test.ts',
+      'src/**/*.test.tsx',
     ])
   })
 
-  it('quarantines every specialized suffix from the core project', () => {
+  it('collects .tsx so a test cannot fall between every project', () => {
+    // The renderer project takes only `*.renderer.test.tsx`, so before `.tsx` was
+    // added above, a file named `Foo.test.tsx` matched NO project: it ran nowhere,
+    // vitest reported success, and the contract script — which greps for `.only`,
+    // not for project membership — agreed. A test that silently never runs is worse
+    // than a missing one, because the coverage it appears to provide is counted.
+    expect(unitTestIncludes).toContain('src/**/*.test.tsx')
+  })
+
+  it('quarantines every specialized suffix from the core project, in BOTH extensions', () => {
+    // The `.tsx` half is load-bearing rather than symmetric-for-neatness: the unit
+    // include now covers `src/**/*.test.tsx`, which `*.renderer.test.tsx` also
+    // matches. Without these excludes every renderer test is ALSO collected into the
+    // node-environment unit project and fails with "document is not defined".
     expect(unitTierExcludes).toEqual(expect.arrayContaining([
       '**/*.system.test.ts',
+      '**/*.system.test.tsx',
       '**/*.live.test.ts',
+      '**/*.live.test.tsx',
       '**/*.soak.test.ts',
+      '**/*.soak.test.tsx',
       '**/*.corpus.test.ts',
+      '**/*.corpus.test.tsx',
       '**/*.integration.test.ts',
       '**/*.renderer.test.ts',
+      '**/*.renderer.test.tsx',
     ]))
   })
 
diff --git a/vitest.config.ts b/vitest.config.ts
index bcfcdb519..25bba2e3d 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -66,18 +66,41 @@ const exclude = [
 // credentials. Keeping the exact patterns inspectable lets a focused contract
 // test prevent a future broad `**/*.test.ts` edit from silently pulling those
 // files back into the parallel core project.
-export const unitTestIncludes = [
+export // ── `.tsx` IS INCLUDED SO A TEST CANNOT FALL BETWEEN PROJECTS ──
+// The renderer project takes only `*.renderer.test.tsx`, and this one used to take
+// only `.ts`. A file named `Foo.test.tsx` therefore matched NO project: vitest ran
+// it nowhere, reported success, and `check-test-contract.mjs` — which greps for
+// `.only`, not for project membership — agreed. A test that silently never runs is
+// worse than a missing one, because the coverage it appears to provide is counted.
+//
+// Every one of the ~300 current test files maps to exactly one project, so this
+// closes a hole rather than fixing a live miss. A `.tsx` test that needs a DOM must
+// still be named `*.renderer.test.tsx`; this catches the ones that do not.
+const unitTestIncludes = [
   'testing/unit/**/*.test.ts',
   'src/**/*.test.ts',
+  'src/**/*.test.tsx',
 ] as const
 
+// Every tier suffix, in BOTH extensions.
+//
+// The `.tsx` half is not decorative: the unit project's include list covers
+// `src/**/*.test.tsx`, and `*.renderer.test.tsx` matches that glob too. Without the
+// `.tsx` excludes here, every renderer test would ALSO be collected into the
+// node-environment unit project and fail with "document is not defined" — which is
+// exactly what happened the first time the include was widened.
 export const unitTierExcludes = [
   '**/*.integration.test.ts',
   '**/*.renderer.test.ts',
+  '**/*.renderer.test.tsx',
   '**/*.system.test.ts',
+  '**/*.system.test.tsx',
   '**/*.live.test.ts',
+  '**/*.live.test.tsx',
   '**/*.soak.test.ts',
+  '**/*.soak.test.tsx',
   '**/*.corpus.test.ts',
+  '**/*.corpus.test.tsx',
 ] as const
 
 export const systemTestIncludes = [