From 4ac7656afaa887991a05b608e6f92db5b9d24c70 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 12:41:22 +0200
Subject: [PATCH 01/18] docs: record extension-platform investigation evidence
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

First artifact on this branch. This is deliberately NOT the plan — the
architecture decision (compiled-in vs runtime-loaded vs iframe) is still
open at §8 and four consultants are being run against it.

Committing the evidence first because the expensive mistake here is
planning against an unverified substrate: three of the four constraints
that decide this design (the CSP, the dev/prod origin split, and the
fact that interaction-ownership and paint-order are DOM-level contracts)
are non-obvious and were each found by reading, not by assumption.

Also records that workflow-mcp is already a complete extension host —
sandbox, approval store, utilityProcess, SHA-256 pinning — which reframes
the whole problem as UI-only.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...-07-20-extension-platform-investigation.md | 305 ++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-20-extension-platform-investigation.md

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 00000000..ebf67c6e
--- /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.

From bf773779e4eacceef434c492701f6faa9630eb2b Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:00:22 +0200
Subject: [PATCH 02/18] docs: Stage 1 implementation plan for the extension
 platform

Six tasks: main-owned per-app storage, the AgentCodeApiV1 ABI, the apps
host surface, the Timer, derived palette commands, and a Settings listing.

The design was settled by four consultants. Both Claude consultants were
assigned opposing briefs (steelman compiled-in / steelman runtime-loaded)
and independently converged on the same staging, which is the main reason
to trust it.

Two findings changed the shape of this plan:

- Monaco already performs a fully runtime-variable dynamic import in the
  shipped bundle, and 92 language chunks load via ESM dynamic import from
  file:// in production. Stage 2's loader is therefore one line, not the
  multi-week problem it was priced at.
- The frame-boundary audit refuted two of the objections to the iframe
  option (paint order and interaction ownership both survive if the host
  wrapper carries the marker) but confirmed the keyboard one: every host
  shortcut dies while focus is inside a frame, and Cmd+W closes the window.

The load-bearing constraint is that an app imports nothing from @renderer/*
and receives one prop, `api: AgentCodeApiV1`. Every host call returns a
Promise even where it could be synchronous, because postMessage cannot be
made sync later. Those two rules are what make Stage 2 a swap rather than a
rewrite, and the plan ends with the grep that proves it.

Stage 2 is deliberately unplanned and conditional: its trigger is extensions
shipping to people running packaged releases, not the owner's own use.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../2026-07-20-extension-platform-stage1.md   | 1368 +++++++++++++++++
 1 file changed, 1368 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-20-extension-platform-stage1.md

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 00000000..8d84d0f7
--- /dev/null
+++ b/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
@@ -0,0 +1,1368 @@
+# Extension Platform — Stage 1 Implementation Plan
+
+> **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.

From bfb9e7d88ed059c72f3690e76710cb8c7a04e3bc Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:08:08 +0200
Subject: [PATCH 03/18] feat(extensions): per-app main-owned storage
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One JSON file per app under STATE_DIR/extensions/<id>/, written temp+rename
so a crash mid-write leaves the old file or the new one, never a half-written
one that fails to parse forever.

App ids are validated and rejected, not sanitized. An id becomes a directory
name, so a permissive id is a traversal primitive — and sanitizing silently
collapses distinct ids onto one directory ("../timer" and "timer" would share
state). Rejecting is the only handling where the failure is visible.

Deliberately NOT the zustand-persist Settings store: app-state/store.ts records
that a forgotten persist version bump black-screened launch twice (#249), and
extension state is authored outside the release cycle so nobody will ever bump
a version for it.

Deliberately NOT registered with debugRetention, unlike every other STATE_DIR
root: those are disposable forensic caches with a disk budget, this is user
data. A retention sweep would silently delete an app's saved state.

appId is a namespace, not authority — Stage 1 apps share one WebContents so the
sender cannot distinguish them. The registration comment records why storage is
the only capability acceptable under that limitation, and that Tier 1-3
capabilities must wait for Stage 2's per-app frame.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/main/extensions/storage.ts | 96 ++++++++++++++++++++++++++++++++++
 src/main/ipc/extensions.ts     | 46 ++++++++++++++++
 src/main/ipc/index.ts          |  5 ++
 src/main/storage/paths.ts      | 15 ++++++
 src/preload/api/extensions.ts  | 23 ++++++++
 src/preload/api/index.ts       |  2 +
 6 files changed, 187 insertions(+)
 create mode 100644 src/main/extensions/storage.ts
 create mode 100644 src/main/ipc/extensions.ts
 create mode 100644 src/preload/api/extensions.ts

diff --git a/src/main/extensions/storage.ts b/src/main/extensions/storage.ts
new file mode 100644
index 00000000..c40e368e
--- /dev/null
+++ b/src/main/extensions/storage.ts
@@ -0,0 +1,96 @@
+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.
+  const tmp = `${file}.tmp`
+  await writeFile(tmp, `${JSON.stringify(data, null, 2)}\n`, '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))
+}
diff --git a/src/main/ipc/extensions.ts b/src/main/ipc/extensions.ts
new file mode 100644
index 00000000..43ef86e9
--- /dev/null
+++ b/src/main/ipc/extensions.ts
@@ -0,0 +1,46 @@
+import { ipcMain } from 'electron'
+
+import {
+  extensionStorageDelete,
+  extensionStorageGet,
+  extensionStorageKeys,
+  extensionStorageSet,
+} from '@main/extensions/storage.js'
+
+// IPC for extension-app state.
+//
+// WHY appId is a caller-supplied parameter rather than derived from the sender:
+// in Stage 1 every app is compiled into the one renderer and shares a single
+// WebContents, so `event.sender` cannot distinguish the timer from any other app.
+// That makes this a NAMESPACE, not an authority boundary — any renderer code can
+// name any app's namespace today, exactly as it can already call the other ~130
+// unvalidated handlers in this directory.
+//
+// The invariant that matters is therefore about what may be added here, not about
+// who is calling: storage is the only capability whose worst case (an app reading
+// another app's saved preferences, in a single-user desktop app where all app code
+// is compiled from this repo) is acceptable without sender binding. Do NOT add
+// workspace, session, transcript, git, filesystem, or network capabilities to this
+// module. Those are Tier 1-3 in the API design and they need the sender-derived
+// identity that only Stage 2 — where each app gets its own frame and preload — can
+// provide. 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),
+  )
+}
diff --git a/src/main/ipc/index.ts b/src/main/ipc/index.ts
index 0a09db1b..1bb62c7a 100644
--- a/src/main/ipc/index.ts
+++ b/src/main/ipc/index.ts
@@ -41,6 +41,7 @@ import { registerCliUpdatesIpc } from '@main/ipc/cliUpdates.js'
 import type { CliUpdateOrchestrator } from '@main/setup/cliUpdateOrchestrator.js'
 import { registerWorkflowIpc } from '@main/ipc/workflows.js'
 import type { WorkflowBridge } from '@main/workflows/WorkflowBridge.js'
+import { registerExtensionsIpc } from '@main/ipc/extensions.js'
 
 // IPC registration aggregator.
 //
@@ -103,4 +104,8 @@ 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()
 }
diff --git a/src/main/storage/paths.ts b/src/main/storage/paths.ts
index 321a4287..da9800e0 100644
--- a/src/main/storage/paths.ts
+++ b/src/main/storage/paths.ts
@@ -21,6 +21,21 @@ 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')
 
+// Per-app extension state, one directory per app id holding one state.json.
+//
+// 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. A directory per app also makes uninstall a single `rm -rf`.
+//
+// WHY this root is deliberately NOT registered with debugRetention, unlike every
+// debug root below it: those are disposable forensic caches with a disk budget, and
+// this is *user data*. A retention sweep that pruned it would silently delete an
+// app's saved state. If this ever needs bounding, bound it per-app inside the writer
+// — never by making it a budgeted bucket.
+export const EXTENSION_STATE_DIR = join(STATE_DIR, 'extensions')
+
 // Per-session feed-debug append-only logs, one JSONL file per session.
 // See storage/feedDebugLog.ts for the write-queue discipline.
 export const FEED_DEBUG_DIR = join(STATE_DIR, 'feed-debug')
diff --git a/src/preload/api/extensions.ts b/src/preload/api/extensions.ts
new file mode 100644
index 00000000..1a2773b6
--- /dev/null
+++ b/src/preload/api/extensions.ts
@@ -0,0 +1,23 @@
+import { ipcRenderer } from 'electron'
+
+// Extension-app storage bridge.
+//
+// These are the only `extension*`-prefixed methods on the flat api object, and the
+// prefix is doing real work: it is what lets `apps/api/useAppHostApi.ts` be the sole
+// call site. App code never touches `window.api` — it receives AgentCodeApiV1, which
+// closes over its own app id. If a second call site for these methods ever appears
+// outside useAppHostApi, the ABI has been bypassed and an app has become
+// non-portable, which is the one failure Stage 1 exists to prevent.
+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),
+}
diff --git a/src/preload/api/index.ts b/src/preload/api/index.ts
index b1b9be8f..9b1813ea 100644
--- a/src/preload/api/index.ts
+++ b/src/preload/api/index.ts
@@ -25,6 +25,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'
 
 // Composed preload API surface.
 //
@@ -69,6 +70,7 @@ export const api = {
   ...usageApi,
   ...cliUpdatesApi,
   ...workflowsApi,
+  ...extensionsApi,
 }
 
 export type Api = typeof api

From 2f88783ac11bc92e8ce1a14c7a884ec07c0e6211 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:09:04 +0200
Subject: [PATCH 04/18] feat(extensions): AgentCodeApiV1, the app host ABI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Defined before it has consumers, because it is the migration boundary rather
than a convenience. An app that talks only through this object lifts into its
own repo 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 is synchronous internally. A
postMessage transport cannot be made sync, and widening void -> Promise<void>
later touches every call site in every app. The ABI comment calls this out
explicitly because it is the easiest property to lose by accident.

Surface is Tier 0 only — storage, close, toast, theme tokens. Workspace,
session, git, filesystem and network stay unrepresentable until a real app
needs them and there is a capability model to gate them; a wrong guess in a
versioned ABI costs more than a late addition.

Only the --theme-* layer is exposed, never the --color-* Tailwind bindings:
the former is a stable contract, the latter is build-system detail that would
couple an app to the host's toolchain.

Token NAMES are cached per renderer lifetime — a theme change rewrites values
on :root but never invents a token, so the stylesheet walk runs once instead
of on every poll.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/api/types.ts         | 85 +++++++++++++++++++
 src/renderer/src/apps/api/useAppHostApi.ts | 96 ++++++++++++++++++++++
 2 files changed, 181 insertions(+)
 create mode 100644 src/renderer/src/apps/api/types.ts
 create mode 100644 src/renderer/src/apps/api/useAppHostApi.ts

diff --git a/src/renderer/src/apps/api/types.ts b/src/renderer/src/apps/api/types.ts
new file mode 100644
index 00000000..e392091e
--- /dev/null
+++ b/src/renderer/src/apps/api/types.ts
@@ -0,0 +1,85 @@
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+
+/**
+ * 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>>
+  }
+}
diff --git a/src/renderer/src/apps/api/useAppHostApi.ts b/src/renderer/src/apps/api/useAppHostApi.ts
new file mode 100644
index 00000000..1a85f21e
--- /dev/null
+++ b/src/renderer/src/apps/api/useAppHostApi.ts
@@ -0,0 +1,96 @@
+import { useMemo } from 'react'
+
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
+
+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 is done once per renderer lifetime and only the cheap
+// getPropertyValue() lookups repeat. Without this cache an app polling tokens on a
+// timer would walk the entire stylesheet set on every tick.
+let cachedTokenNames: string[] | null = null
+
+function themeTokenNames(): string[] {
+  if (cachedTokenNames) return cachedTokenNames
+
+  const names = new Set<string>()
+  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 on it throws a SecurityError. Nothing we need is in
+      // there (it is font-face only), so skipping is correct, not a fallback.
+      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
+}
+
+/**
+ * Builds the AgentCodeApiV1 instance handed to one app.
+ *
+ * WHY a hook rather than a module-level factory: `showToast` comes from React
+ * context (ui/GlobalToast.tsx) and `close` is the host's own state action. Both are
+ * per-mount concerns. The app never learns either origin — it receives the ABI and
+ * nothing else, which is precisely what makes it portable.
+ *
+ * WHY appId is closed over rather than passed on every call: an app must not be
+ * able to name a different app's storage namespace. In Stage 1 that is a
+ * convention enforced by this closure and by the rule that `useAppHostApi` is the
+ * only call site of `window.api.extensionStorage*`. In Stage 2 it becomes properly
+ * enforceable, because each app gets its own frame and main derives the id from the
+ * sender instead of trusting the argument.
+ */
+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: {
+        // 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 () => {
+          onClose()
+        },
+        showToast: async (message: string) => {
+          showToast(message)
+        },
+      },
+
+      theme: {
+        tokens: async () => {
+          const style = getComputedStyle(document.documentElement)
+          const out: Record<string, string> = {}
+          for (const name of themeTokenNames()) {
+            out[name] = style.getPropertyValue(name).trim()
+          }
+          return out
+        },
+      },
+    }),
+    [appId, onClose, showToast],
+  )
+}

From 902d0783fc531c545e960d1a2d9767c1fcf7277d Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:11:15 +0200
Subject: [PATCH 05/18] feat(extensions): apps host surface, registry and store
 field
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One surface entry hosts every app. AppDefinition stays serializable-plus-one so
it is the shape a Stage 2 manifest resolves into — a loader would read
id/title/description/keywords from disk and produce Component, leaving
everything else under apps/ untouched.

Apps mount inside DialogContent so they inherit the interaction-ownership
marker for exactly the focus-trap interval. Seven consumers query that marker
synchronously — keybind router, palette native-menu guard, global editor
Escape, composer Enter registry, type-to-focus, paste-to-focus, native
dictation. Without it an app's input can leak Enter/paste into a background
agent composer, the failure components/ui/README.md records from the old
hand-rolled composer guards.

Unknown openAppId degrades to closed rather than throwing, deliberately unlike
the provider pane registry which is right to throw. A stale id here — after an
app is removed, or uninstalled in Stage 2 — would otherwise take down the whole
renderer from an unconditionally mounted surface.

Registry is empty; no user-visible change. Timer lands after the host is
complete so the infrastructure is never shaped around its one consumer.

Also records in components/ui/README.md why this is not the "surface factory"
the guardrails forbid, and notes that the runtime-load and iframe designs both
WOULD require one.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/app-state/types.ts           |  2 +
 src/renderer/src/app-state/uiShell/slice.ts   |  4 ++
 src/renderer/src/app-state/uiShell/types.ts   | 20 ++++++
 src/renderer/src/app/surfaces/registry.tsx    |  8 +++
 src/renderer/src/apps/registry.ts             | 22 ++++++
 .../src/apps/surfaces/AppHostSurface.tsx      | 68 +++++++++++++++++++
 src/renderer/src/apps/types.ts                | 55 +++++++++++++++
 src/renderer/src/components/ui/README.md      | 24 +++++++
 8 files changed, 203 insertions(+)
 create mode 100644 src/renderer/src/apps/registry.ts
 create mode 100644 src/renderer/src/apps/surfaces/AppHostSurface.tsx
 create mode 100644 src/renderer/src/apps/types.ts

diff --git a/src/renderer/src/app-state/types.ts b/src/renderer/src/app-state/types.ts
index eae4b629..034281e6 100644
--- a/src/renderer/src/app-state/types.ts
+++ b/src/renderer/src/app-state/types.ts
@@ -88,6 +88,8 @@ export type UiShellSlice = UiShellState & {
   closeUsageModal: () => void
   openRewindPrompt: (sessionId: SessionId) => void
   closeRewindPrompt: () => void
+  openApp: (appId: string) => void
+  closeApp: () => void
   openAgentViewModePicker: (sessionId: SessionId) => void
   closeAgentViewModePicker: () => void
 }
diff --git a/src/renderer/src/app-state/uiShell/slice.ts b/src/renderer/src/app-state/uiShell/slice.ts
index e3e4a2f1..4516982f 100644
--- a/src/renderer/src/app-state/uiShell/slice.ts
+++ b/src/renderer/src/app-state/uiShell/slice.ts
@@ -43,6 +43,7 @@ export const createUiShellSlice: StateCreator<
   usageModalOpen: false,
   rewindPromptSessionId: null,
   agentViewModePickerSessionId: null,
+  openAppId: null,
   // Default keeps the dispatch list at 25% (matching the
   // previous-hardcoded `basis-1/4`) so the migration is visually a
   // no-op. The clamp range in setDispatchListRatio is what enforces
@@ -252,6 +253,9 @@ 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'),
+
   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 fe997877..33c45810 100644
--- a/src/renderer/src/app-state/uiShell/types.ts
+++ b/src/renderer/src/app-state/uiShell/types.ts
@@ -189,6 +189,26 @@ 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
   /** Splitter ratio between the dispatch agent list and the active
    *  agent pane in `DispatchLayout`. 0..1, where 0.25 means the list
    *  is 25% of the available width. Clamped to [0.15, 0.5] when the
diff --git a/src/renderer/src/app/surfaces/registry.tsx b/src/renderer/src/app/surfaces/registry.tsx
index 1b274b4d..30a492e2 100644
--- a/src/renderer/src/app/surfaces/registry.tsx
+++ b/src/renderer/src/app/surfaces/registry.tsx
@@ -23,6 +23,7 @@ import { CloseOldAgentsSurface } from '@renderer/features/workspace/surfaces/Clo
 import { BulkProviderSwitchSurface } from '@renderer/features/workspace/surfaces/BulkProviderSwitchSurface'
 import { AgentViewModePickerSurface } from '@renderer/features/workspace/surfaces/AgentViewModePickerSurface'
 import { RewindToPromptSurface } from '@renderer/features/workspace/surfaces/RewindToPromptSurface'
+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
@@ -73,6 +74,13 @@ export const modalSurfaces: SurfaceEntry[] = [
   { id: 'agent-view-mode-picker', Component: AgentViewModePickerSurface },
   { id: 'rewind-to-prompt', Component: RewindToPromptSurface },
   { 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/apps/registry.ts b/src/renderer/src/apps/registry.ts
new file mode 100644
index 00000000..459f5728
--- /dev/null
+++ b/src/renderer/src/apps/registry.ts
@@ -0,0 +1,22 @@
+import type { AppDefinition } from '@renderer/apps/types'
+
+// The built-in app registry.
+//
+// Adding an app = ONE import + ONE array entry, matching the contract
+// `app/surfaces/registry.tsx` and `features/command-palette/registry.ts` already
+// use. An explicit import list is greppable and compiler-checked; side-effect
+// self-registration is neither, and makes module load order load-bearing — which is
+// exactly the class of bug the surface registry's #505 comment records.
+//
+// Stage 2 note: this becomes `[...BUILTIN_APPS, ...loadedApps]` where the second
+// half comes from a manifest loader. Nothing else under `apps/` needs to change for
+// that — `APP_BY_ID`, the host surface, and the derived commands all consume this
+// array and do not care where its entries came from. That is the whole point of
+// keeping `AppDefinition` serializable-plus-one.
+export const APPS: AppDefinition[] = []
+
+// Lookup for the host surface. Built once at module scope rather than per render:
+// the array is static in Stage 1, and in Stage 2 the loader will rebuild both
+// together. If this ever needs to be dynamic, change both in the same commit —
+// a stale map against a live array is a silently-missing app.
+export const APP_BY_ID = new Map<string, AppDefinition>(APPS.map(app => [app.id, app]))
diff --git a/src/renderer/src/apps/surfaces/AppHostSurface.tsx b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
new file mode 100644
index 00000000..6883e477
--- /dev/null
+++ b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
@@ -0,0 +1,68 @@
+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. 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 app's input can leak Enter and paste into a
+ * background agent composer, and a native menu click can mutate the workspace
+ * underneath the app. `components/ui/README.md` records that exact failure from the
+ * old hand-rolled composer guards. Hosting apps inside the primitive means an app
+ * gets all seven protections for free and physically cannot forget one.
+ *
+ * WHY the inner component: `useAppHostApi` is a hook, so it cannot be called after
+ * the `if (!app) return null` guard. Splitting keeps the guard first and the hook
+ * unconditional, which is the only arrangement React permits.
+ */
+export function AppHostSurface() {
+  const openAppId = useAppStore(state => state.openAppId)
+  const app = openAppId ? APP_BY_ID.get(openAppId) : undefined
+
+  // An unknown id degrades to closed. This is a deliberate contrast with
+  // `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
+  // and must be loud. It would be wrong here for two reasons: `openAppId` can hold
+  // a stale id after an app is removed from the registry (and in Stage 2, after an
+  // app is uninstalled), and this surface is mounted unconditionally by App.tsx, so
+  // throwing inside it takes down the entire renderer — the #249 black-screen
+  // failure mode, reached from data rather than from a persist-version mistake.
+  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 className="w-[min(560px,92vw)]">
+        {/* Radix requires an accessible title on every Dialog; visually hidden
+            because an app owns its own header treatment. Omitting it logs a
+            console error and leaves the dialog unlabelled for screen readers. */}
+        <DialogTitle className="sr-only">{app.title}</DialogTitle>
+        <app.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 00000000..e223ee52
--- /dev/null
+++ b/src/renderer/src/apps/types.ts
@@ -0,0 +1,55 @@
+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 that a future out-of-tree manifest resolves INTO. In
+ * Stage 2 a loader reads `id`/`title`/`description`/`keywords` from
+ * `agent-code.app.json` on disk and produces `Component` by importing the app's
+ * bundle — everything else in `apps/` stays exactly as it is. Keeping this type a
+ * strict superset-by-one of a manifest is what makes that a swap.
+ *
+ * The failure to avoid: adding a host-only field here — `getWorkspace: () =>
+ * Workspace`, a store selector, a React context, anything not serializable. That
+ * silently converts this from a manifest target into a host-only interface, and at
+ * that moment Stage 1 becomes a substrate Stage 2 has to tear out rather than one
+ * it keeps. If an app needs a capability, it belongs in `AgentCodeApiV1`, not here.
+ */
+export type AppDefinition = {
+  /**
+   * Stable id. Becomes the palette command id (`app.open.<id>`), the value held in
+   * `openAppId`, and the on-disk state directory name under
+   * `~/.config/agent-code/extensions/`. Renaming it orphans saved state and breaks
+   * muscle memory — treat as permanent.
+   *
+   * Must satisfy the same pattern the main process enforces in
+   * `main/extensions/storage.ts`: /^[a-z][a-z0-9-]{0,63}$/. A violation is not
+   * caught here — it surfaces as an `InvalidAppIdError` on the first storage call,
+   * which is deliberate: main owns that rule because main is where the id becomes
+   * a filesystem path, and duplicating the check here would let the two 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.
+   */
+  description: string
+  keywords?: string[]
+  /**
+   * The app's UI.
+   *
+   * 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 and props would put the host back in the wiring business.
+   * For an app the opposite holds — the prop IS the boundary that makes the app
+   * portable, and `api` is the only thing an app is permitted to depend on. An app
+   * that imports anything from `@renderer/*` other than these two type modules has
+   * broken the contract; the check is `grep -rn "@renderer/" src/renderer/src/apps/<id>/`.
+   */
+  Component: ComponentType<{ api: AgentCodeApiV1 }>
+}
diff --git a/src/renderer/src/components/ui/README.md b/src/renderer/src/components/ui/README.md
index 74ca4375..f61c8653 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.

From a14ea192e225f475e2a86f7e91fdf3531825a62d Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:12:17 +0200
Subject: [PATCH 06/18] feat(extensions): derive palette commands from the app
 registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One .map over APPS. An app physically cannot ship without an opener, which a
hand-written command per app would make a silent failure mode. Keeps the cost
of adding an app at one import plus one array entry.

Adding openApp to CommandContext.ui makes the compiler name every object
literal implementing the context — the intended safety net, and it confirmed
CommandPalette.tsx is the only construction site.

Deliberately not pre-abstracting commandDefs into a getter for Stage 2's
dynamic app list: that is anticipatory indirection the repo guardrails argue
against, and it is a five-line change at one call site when it is actually
needed. Noted in the module comment instead.

APPS is still empty, so this adds zero commands today.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/commands/appCommands.ts | 35 +++++++++++++++++++
 .../src/features/command-palette/registry.ts  |  7 ++++
 .../src/features/command-palette/types.ts     |  3 ++
 .../command-palette/ui/CommandPalette.tsx     |  2 ++
 4 files changed, 47 insertions(+)
 create mode 100644 src/renderer/src/apps/commands/appCommands.ts

diff --git a/src/renderer/src/apps/commands/appCommands.ts b/src/renderer/src/apps/commands/appCommands.ts
new file mode 100644
index 00000000..6b972085
--- /dev/null
+++ b/src/renderer/src/apps/commands/appCommands.ts
@@ -0,0 +1,35 @@
+import type { CommandDef } from '@renderer/features/command-palette/types'
+
+import { APPS } from '@renderer/apps/registry'
+
+// Palette commands, derived rather than hand-written.
+//
+// N apps produce N commands with zero per-app boilerplate, and — more importantly —
+// an app physically cannot ship without a way to open it. A hand-written command
+// per app would make "forgot to register the opener" a real and silent failure
+// mode; deriving makes it unrepresentable.
+//
+// This mapping is also what keeps the cost of adding an app at one import plus one
+// array entry in `apps/registry.ts`. `buildCommandRegistry` already recomputes on
+// every context change, so nothing here needs to be reactive.
+//
+// Stage 2 note: when `APPS` becomes `[...BUILTIN, ...loaded]`, this module needs no
+// edit — but `commandDefs` in the palette registry is a module-scope const, so it
+// will have to become a function that concatenates a live list. That is a five-line
+// change at one call site, deliberately NOT pre-abstracted here: building a getter
+// today to serve a hypothetical loader is the anticipatory indirection this repo's
+// guardrails argue against, and doing it later is cheap.
+export const appCommands: CommandDef[] = APPS.map(app => ({
+  id: `app.open.${app.id}`,
+  title: `Open ${app.title}`,
+  description: app.description,
+  // 'app' rather than 'grid'/'dispatch': an app is mode-independent. It has no
+  // relationship to the tile tree or to Dispatch, so hiding it in either mode would
+  // be wrong — see the CommandSurface doc comment in command-palette/types.ts.
+  surface: 'app',
+  keywords: app.keywords ?? [],
+  run: ({ ui }) => {
+    ui.openApp(app.id)
+    ui.closePalette()
+  },
+}))
diff --git a/src/renderer/src/features/command-palette/registry.ts b/src/renderer/src/features/command-palette/registry.ts
index c3289581..ca4f54a0 100644
--- a/src/renderer/src/features/command-palette/registry.ts
+++ b/src/renderer/src/features/command-palette/registry.ts
@@ -13,6 +13,7 @@ import { promptTemplateCommands } from '@renderer/features/prompt-templates/comm
 import { agentStatusCommands } from '@renderer/features/agent-status/commands/agentStatusCommands'
 import { remoteCommands } from '@renderer/features/remote/commands/remoteCommands'
 import { usageCommands } from '@renderer/features/usage/commands/usageCommands'
+import { appCommands } from '@renderer/apps/commands/appCommands'
 import { commandAllowedByRenderedViewPolicy } from '@renderer/workspace/agentDisplayMode'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 import type {
@@ -43,6 +44,12 @@ const commandDefs: CommandDef[] = [
   ...agentStatusCommands,
   ...remoteCommands,
   ...usageCommands,
+  // Derived from the built-in app registry — one command per app, so an app
+  // cannot ship without an opener. Last so apps browse after first-party
+  // commands in the empty-query list; registry order is the palette's browse
+  // order and reshuffling it reads as a regression to anyone who navigates by
+  // position.
+  ...appCommands,
 ]
 
 /**
diff --git a/src/renderer/src/features/command-palette/types.ts b/src/renderer/src/features/command-palette/types.ts
index c44f81af..418ee309 100644
--- a/src/renderer/src/features/command-palette/types.ts
+++ b/src/renderer/src/features/command-palette/types.ts
@@ -97,6 +97,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
     openUsageModal: () => void
     toggleGitBar: () => void
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 6af2e044..84d6ae6f 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -193,6 +193,7 @@ function OpenCommandPalette({
   const openRewindPrompt = useAppStore(state => state.openRewindPrompt)
   const openAgentViewModePicker = useAppStore(state => state.openAgentViewModePicker)
   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)
@@ -522,6 +523,7 @@ function OpenCommandPalette({
         enterAiWorkspaceOpenMode,
         enterAiWorkspaceCreateMode,
         enterAiWorkspaceClearMode,
+        openApp,
         closePalette: onClose,
       },
       flags: {

From f971cac7fc3e17aa5f7d581be1cdfd1b86799ede Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:13:33 +0200
Subject: [PATCH 07/18] feat(extensions): Settings > Apps listing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fourth instance of the existing self-subscribing marker pattern
(cli-update-behavior, theme-picker, dictation-api-key), and the purest case of
it: there is no value at all. The row lists apps/registry.ts, compile-time data
the Settings store has no business mirroring — and extension-adjacent state
must stay out of the zustand-persist blob regardless (#249).

A listing, not a manager. Apps are compiled in, so install/enable/remove
toggles would be UI for state that cannot vary, and a control that always
reads "enabled" looks broken. Stage 2 replaces the component body and keeps
the slot.

Category is last in SETTING_CATEGORIES: apps are additive tooling, not a
setting that changes shell or agent behaviour, so they should not push the
behavioural categories down.

Open closes Settings first — Settings is a full-takeover surface that also
carries the interaction-ownership marker, and leaving it mounted under an app
would stack two owners of the same input.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/ui/AppsSettingsRow.tsx  | 59 +++++++++++++++++++
 .../settings/lib/settingsCategories.ts        | 10 ++++
 .../features/settings/lib/settingsRegistry.ts | 30 ++++++++++
 .../src/features/settings/ui/SettingsList.tsx |  7 +++
 4 files changed, 106 insertions(+)
 create mode 100644 src/renderer/src/apps/ui/AppsSettingsRow.tsx

diff --git a/src/renderer/src/apps/ui/AppsSettingsRow.tsx b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
new file mode 100644
index 00000000..7df0c508
--- /dev/null
+++ b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
@@ -0,0 +1,59 @@
+import { useAppStore } from '@renderer/app-state/hooks'
+
+import { APPS } from '@renderer/apps/registry'
+
+/**
+ * Settings row listing the built-in apps.
+ *
+ * WHY a listing and not a manager: in Stage 1 apps are compiled into the renderer,
+ * so there is nothing to install, enable, disable, or remove — every app in `APPS`
+ * is present by construction. Shipping toggles now would be UI for state that
+ * cannot vary, and a disabled-looking control that always says "enabled" reads as
+ * broken. Stage 2 replaces this component's body with install/update/remove and
+ * keeps its registry slot, which is why the marker exists at all today.
+ *
+ * WHY this file lives under `apps/ui/` rather than `features/settings/ui/`: it is
+ * host UI *about* apps, owned by the apps subsystem, the same way
+ * `CliUpdateBehaviorRow` lives under `features/cli-updates/`. Note it therefore
+ * uses the app's Tailwind utilities normally — the "import nothing from
+ * @renderer/*" portability rule applies to `apps/<id>/` app code, not to the host
+ * chrome around it.
+ */
+export function AppsSettingsRow() {
+  const openApp = useAppStore(state => state.openApp)
+  const closeSettingsPage = useAppStore(state => state.closeSettingsPage)
+
+  if (APPS.length === 0) {
+    return <div className="text-[12px] text-muted">No apps installed.</div>
+  }
+
+  return (
+    <div className="flex flex-col gap-1">
+      {APPS.map(app => (
+        <div
+          key={app.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="text-[13px] text-ink">{app.title}</div>
+            <div className="truncate text-[12px] text-muted">{app.description}</div>
+          </div>
+          <button
+            type="button"
+            onClick={() => {
+              // Settings is a full-takeover surface that also carries the
+              // interaction-ownership marker. Leaving it mounted under the app
+              // would stack two owners of the same input, so close it first —
+              // the user asked to use the app, not to keep configuring.
+              closeSettingsPage()
+              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 focus-visible:border-focus-ring focus-visible:ring-1 focus-visible:ring-focus-ring"
+          >
+            Open
+          </button>
+        </div>
+      ))}
+    </div>
+  )
+}
diff --git a/src/renderer/src/features/settings/lib/settingsCategories.ts b/src/renderer/src/features/settings/lib/settingsCategories.ts
index 42050d8b..f7fe4366 100644
--- a/src/renderer/src/features/settings/lib/settingsCategories.ts
+++ b/src/renderer/src/features/settings/lib/settingsCategories.ts
@@ -5,6 +5,7 @@ export type SettingCategoryId =
   | 'dictation'
   | 'experimental'
   | 'safety'
+  | 'apps'
 
 export type SettingCategory = {
   id: SettingCategoryId
@@ -43,4 +44,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: 'Apps',
+    description: 'Built-in apps available from the command palette.',
+  },
 ]
diff --git a/src/renderer/src/features/settings/lib/settingsRegistry.ts b/src/renderer/src/features/settings/lib/settingsRegistry.ts
index bf450b3b..3955b5ab 100644
--- a/src/renderer/src/features/settings/lib/settingsRegistry.ts
+++ b/src/renderer/src/features/settings/lib/settingsRegistry.ts
@@ -135,6 +135,22 @@ export type SettingDefinition =
         type: 'dictation-api-key'
       }
     }
+  | {
+      id: string
+      category: SettingCategoryId
+      title: string
+      description: string
+      keywords: string[]
+      // Marker for the built-in apps list. Same escape hatch as
+      // cli-update-behavior — and the purest case of it, because there is no
+      // value at all: the row lists `apps/registry.ts`, which is compile-time
+      // data the Settings store has no business mirroring. A `select` or
+      // `action` control could not express a list with a per-row button.
+      // See apps/ui/AppsSettingsRow.tsx.
+      control: {
+        type: 'apps'
+      }
+    }
   | {
       id: string
       category: SettingCategoryId
@@ -593,6 +609,20 @@ export function getSettingsRegistry(): SettingDefinition[] {
       ],
       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: 'Apps',
+      description: 'Built-in apps available from the command palette.',
+      keywords: ['apps', 'extensions', 'plugins', 'timer', 'tools'],
+      control: { type: 'apps' },
+    },
     {
       id: 'reset-settings',
       category: 'workspace',
diff --git a/src/renderer/src/features/settings/ui/SettingsList.tsx b/src/renderer/src/features/settings/ui/SettingsList.tsx
index 1990d5f3..80e65889 100644
--- a/src/renderer/src/features/settings/ui/SettingsList.tsx
+++ b/src/renderer/src/features/settings/ui/SettingsList.tsx
@@ -8,6 +8,7 @@ import { HotkeyInput } from '@renderer/features/settings/ui/HotkeyInput'
 import { CliUpdateBehaviorRow } from '@renderer/features/cli-updates/CliUpdateBehaviorRow'
 import { DictationApiKeyRow } from '@renderer/features/voice-dictation/DictationApiKeyRow'
 import { ThemePickerRow } from '@renderer/features/settings/ui/ThemePickerRow'
+import { AppsSettingsRow } from '@renderer/apps/ui/AppsSettingsRow'
 
 type Props = {
   definitions: SettingDefinition[]
@@ -225,6 +226,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}
+
           {/* Theme grid — built-ins and saved themes in one list, with the
               create/edit/delete affordances the generic select can't carry.
               See features/settings/ui/ThemePickerRow.tsx. */}

From 04cddea0b34d90f09dfd6b55ab5ce4cb69f8cd83 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 13:14:45 +0200
Subject: [PATCH 08/18] feat(extensions): Timer app, the first AgentCodeApiV1
 consumer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Built last, deliberately: the host was finished before its first consumer
existed so the infrastructure could not be quietly shaped around one app's
needs.

Imports react and the ABI types. Nothing else — verified by
`grep -rn "@renderer/" src/renderer/src/apps/timer/`, which is the migration
test: this directory should lift into its own repository in Stage 2 with no
edits inside it.

Styling is inline var(--theme-*) rather than Tailwind utilities. 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 unchanged. The SVG ring also
demonstrates the arbitrary-pixels case the declarative-vocabulary alternative
could not have served.

Countdown is deadline-based, not decrement-based. A per-tick subtraction drifts
by however long each tick was delayed, and Chromium throttles background
renderers hard enough that a 25-minute pomodoro in an unfocused window would
finish minutes late. Recomputing from a wall-clock deadline makes every late
tick self-correct, and handles sleep/wake by the same property.

Presets are validated on read rather than trusted: state.json is user-editable
on disk and a hand-edit should degrade to defaults, not render NaN buttons.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/registry.ts           |   4 +-
 src/renderer/src/apps/timer/index.ts        |  14 ++
 src/renderer/src/apps/timer/ui/TimerApp.tsx | 255 ++++++++++++++++++++
 3 files changed, 272 insertions(+), 1 deletion(-)
 create mode 100644 src/renderer/src/apps/timer/index.ts
 create mode 100644 src/renderer/src/apps/timer/ui/TimerApp.tsx

diff --git a/src/renderer/src/apps/registry.ts b/src/renderer/src/apps/registry.ts
index 459f5728..dc0059ff 100644
--- a/src/renderer/src/apps/registry.ts
+++ b/src/renderer/src/apps/registry.ts
@@ -1,5 +1,7 @@
 import type { AppDefinition } from '@renderer/apps/types'
 
+import { timerApp } from '@renderer/apps/timer'
+
 // The built-in app registry.
 //
 // Adding an app = ONE import + ONE array entry, matching the contract
@@ -13,7 +15,7 @@ import type { AppDefinition } from '@renderer/apps/types'
 // that — `APP_BY_ID`, the host surface, and the derived commands all consume this
 // array and do not care where its entries came from. That is the whole point of
 // keeping `AppDefinition` serializable-plus-one.
-export const APPS: AppDefinition[] = []
+export const APPS: AppDefinition[] = [timerApp]
 
 // Lookup for the host surface. Built once at module scope rather than per render:
 // the array is static in Stage 1, and in Stage 2 the loader will rebuild both
diff --git a/src/renderer/src/apps/timer/index.ts b/src/renderer/src/apps/timer/index.ts
new file mode 100644
index 00000000..40840ffb
--- /dev/null
+++ b/src/renderer/src/apps/timer/index.ts
@@ -0,0 +1,14 @@
+import type { AppDefinition } from '@renderer/apps/types'
+
+import { TimerApp } from '@renderer/apps/timer/ui/TimerApp'
+
+// The Timer's definition. Everything here except `Component` is exactly what a
+// Stage 2 `agent-code.app.json` would carry — that correspondence is the point,
+// not a coincidence.
+export const timerApp: AppDefinition = {
+  id: 'timer',
+  title: 'Timer',
+  description: 'Countdown timer with presets. Toasts when it finishes.',
+  keywords: ['timer', 'countdown', 'pomodoro', 'clock', 'focus', 'stopwatch'],
+  Component: TimerApp,
+}
diff --git a/src/renderer/src/apps/timer/ui/TimerApp.tsx b/src/renderer/src/apps/timer/ui/TimerApp.tsx
new file mode 100644
index 00000000..53a78f84
--- /dev/null
+++ b/src/renderer/src/apps/timer/ui/TimerApp.tsx
@@ -0,0 +1,255 @@
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+// The Timer app.
+//
+// PORTABILITY CONTRACT: this file may import `react` and the ABI type, and nothing
+// else. No store, no components/ui, no lib/utils, no Tailwind utility classes. That
+// is not stylistic — it is the test of whether the host was built honestly, and it
+// is checked by:
+//
+//   grep -rn "@renderer/" src/renderer/src/apps/timer/
+//
+// If that returns anything but the two type imports, this directory can no longer
+// be lifted into its own repository, and Stage 1 has quietly become a substrate
+// Stage 2 must tear out.
+//
+// Colours come from `var(--theme-*)` rather than `bg-surface`/`text-ink`. The
+// utilities are a build-time Tailwind binding that will not exist out-of-tree; the
+// token names will, and the host can push them across a frame boundary unchanged.
+
+const DEFAULT_PRESETS = [5, 15, 25]
+const PRESETS_KEY = 'presets'
+
+// Ring geometry. 2πr for the dash math, computed once rather than per render.
+const RING_SIZE = 176
+const RING_STROKE = 6
+const RING_RADIUS = (RING_SIZE - RING_STROKE) / 2
+const RING_CIRCUMFERENCE = 2 * Math.PI * RING_RADIUS
+
+function formatRemaining(totalSeconds: number): string {
+  const safe = Math.max(0, Math.ceil(totalSeconds))
+  const minutes = Math.floor(safe / 60)
+  const seconds = safe % 60
+  return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`
+}
+
+type Phase = 'idle' | 'running' | 'paused' | 'done'
+
+export function TimerApp({ api }: { api: AgentCodeApiV1 }) {
+  const [presets, setPresets] = useState<number[]>(DEFAULT_PRESETS)
+  const [phase, setPhase] = useState<Phase>('idle')
+  const [totalMs, setTotalMs] = useState(0)
+  const [remainingMs, setRemainingMs] = useState(0)
+
+  // WHY a deadline rather than decrementing a counter each tick: a setInterval that
+  // subtracts a fixed amount drifts by however long the interval was actually
+  // delayed, and Chromium throttles background renderers aggressively — a
+  // 25-minute pomodoro in an unfocused window would finish minutes late. Storing
+  // the wall-clock deadline means every tick recomputes from truth, so a late tick
+  // self-corrects instead of accumulating error. Sleep/wake is handled by the same
+  // property. `pausedRemainingRef` holds the leftover while paused, since there is
+  // no meaningful deadline during a pause.
+  const deadlineRef = useRef<number | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    void api.storage.get<number[]>(PRESETS_KEY).then(saved => {
+      if (cancelled) return
+      // Validate rather than trust: this is user-editable JSON on disk, and a
+      // hand-edited state.json should degrade to defaults, not render NaN buttons.
+      if (
+        Array.isArray(saved) &&
+        saved.length > 0 &&
+        saved.every(n => typeof n === 'number' && Number.isFinite(n) && n > 0)
+      ) {
+        setPresets(saved)
+      }
+    })
+    return () => {
+      cancelled = true
+    }
+  }, [api])
+
+  useEffect(() => {
+    if (phase !== 'running') return
+
+    // 100ms rather than 1000ms so the ring animates smoothly and the digits never
+    // appear to skip a second when a tick lands just after a boundary. The work per
+    // tick is one subtraction and one setState of a number.
+    const id = setInterval(() => {
+      const deadline = deadlineRef.current
+      if (deadline == null) return
+      const left = deadline - Date.now()
+      if (left <= 0) {
+        deadlineRef.current = null
+        setRemainingMs(0)
+        setPhase('done')
+        void api.ui.showToast('Timer finished')
+        return
+      }
+      setRemainingMs(left)
+    }, 100)
+
+    return () => clearInterval(id)
+  }, [phase, api])
+
+  const start = useCallback((minutes: number) => {
+    const ms = minutes * 60_000
+    deadlineRef.current = Date.now() + ms
+    setTotalMs(ms)
+    setRemainingMs(ms)
+    setPhase('running')
+  }, [])
+
+  const pause = useCallback(() => {
+    const deadline = deadlineRef.current
+    if (deadline == null) return
+    setRemainingMs(Math.max(0, deadline - Date.now()))
+    deadlineRef.current = null
+    setPhase('paused')
+  }, [])
+
+  const resume = useCallback(() => {
+    deadlineRef.current = Date.now() + remainingMs
+    setPhase('running')
+  }, [remainingMs])
+
+  const reset = useCallback(() => {
+    deadlineRef.current = null
+    setPhase('idle')
+    setRemainingMs(0)
+    setTotalMs(0)
+  }, [])
+
+  // Empty ring when idle, full ring at the moment of starting, draining to empty.
+  const progress = totalMs > 0 ? Math.max(0, Math.min(1, remainingMs / totalMs)) : 0
+  const dashOffset = RING_CIRCUMFERENCE * (1 - progress)
+
+  const digitsColor =
+    phase === 'done'
+      ? 'var(--theme-accent)'
+      : phase === 'idle'
+        ? 'var(--theme-muted)'
+        : 'var(--theme-ink)'
+
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        alignItems: 'center',
+        gap: 24,
+        padding: '36px 32px 32px',
+      }}
+    >
+      <div style={{ position: 'relative', width: RING_SIZE, height: RING_SIZE }}>
+        <svg width={RING_SIZE} height={RING_SIZE} style={{ display: 'block' }}>
+          <circle
+            cx={RING_SIZE / 2}
+            cy={RING_SIZE / 2}
+            r={RING_RADIUS}
+            fill="none"
+            stroke="var(--theme-border)"
+            strokeWidth={RING_STROKE}
+          />
+          <circle
+            cx={RING_SIZE / 2}
+            cy={RING_SIZE / 2}
+            r={RING_RADIUS}
+            fill="none"
+            stroke="var(--theme-accent)"
+            strokeWidth={RING_STROKE}
+            strokeLinecap="round"
+            strokeDasharray={RING_CIRCUMFERENCE}
+            strokeDashoffset={dashOffset}
+            // -90deg so the ring starts at 12 o'clock instead of 3 o'clock.
+            transform={`rotate(-90 ${RING_SIZE / 2} ${RING_SIZE / 2})`}
+            style={{ transition: 'stroke-dashoffset 120ms linear' }}
+          />
+        </svg>
+        <div
+          style={{
+            position: 'absolute',
+            inset: 0,
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            fontFamily: 'var(--theme-font-code, ui-monospace, monospace)',
+            fontSize: 40,
+            fontVariantNumeric: 'tabular-nums',
+            letterSpacing: '0.02em',
+            color: digitsColor,
+            transition: 'color 160ms ease',
+          }}
+        >
+          {formatRemaining(remainingMs / 1000)}
+        </div>
+      </div>
+
+      <div style={{ display: 'flex', gap: 8 }}>
+        {presets.map(minutes => (
+          <button
+            key={minutes}
+            type="button"
+            onClick={() => start(minutes)}
+            style={{
+              padding: '6px 14px',
+              fontSize: 13,
+              cursor: 'pointer',
+              background: 'var(--theme-control-bg)',
+              color: 'var(--theme-control-fg)',
+              border: '1px solid var(--theme-control-border)',
+              borderRadius: 6,
+            }}
+          >
+            {minutes}m
+          </button>
+        ))}
+      </div>
+
+      <div style={{ display: 'flex', gap: 8 }}>
+        {phase === 'running' ? (
+          <TimerButton label="Pause" tone="accent" onClick={pause} />
+        ) : phase === 'paused' ? (
+          <TimerButton label="Resume" tone="accent" onClick={resume} />
+        ) : null}
+
+        {phase !== 'idle' ? <TimerButton label="Reset" tone="quiet" onClick={reset} /> : null}
+
+        <TimerButton label="Close" tone="quiet" onClick={() => void api.ui.close()} />
+      </div>
+    </div>
+  )
+}
+
+function TimerButton({
+  label,
+  tone,
+  onClick,
+}: {
+  label: string
+  tone: 'accent' | 'quiet'
+  onClick: () => void
+}) {
+  const accent = tone === 'accent'
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      style={{
+        minWidth: 88,
+        padding: '7px 16px',
+        fontSize: 13,
+        cursor: 'pointer',
+        borderRadius: 6,
+        background: accent ? 'var(--theme-accent)' : 'transparent',
+        color: accent ? 'var(--theme-accent-fg)' : 'var(--theme-ink-dim)',
+        border: `1px solid ${accent ? 'var(--theme-accent)' : 'var(--theme-border)'}`,
+      }}
+    >
+      {label}
+    </button>
+  )
+}

From 2fb388d3d265ada0e991e14f674b782ec7b83305 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:10:07 +0200
Subject: [PATCH 09/18] revert: remove the compiled-in Timer app
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Timer was built as a compiled-in app in src/renderer/src/apps/timer/. That
made it app source code behind an API boundary, not an extension — it could not
be installed, could not come from a repo, and shipped inside the bundle.

That is not what this PR is for. Extensions are installed from a repository at
runtime; nothing in the product ships an app in-tree. Keeping the Timer would
have made the compiled-in path look like a supported way to add functionality,
and the first person to copy it (including future me) would have built the wrong
thing again.

The host stays: AgentCodeApiV1, AppHostSurface, the derived commands, the
Settings slot, and per-app storage are all the resolution target the loader
fills at runtime. APPS is now empty by design.

A timer comes back later as a real installed extension from its own repository,
which is also the honest test of the loader.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/registry.ts           |   7 +-
 src/renderer/src/apps/timer/index.ts        |  14 --
 src/renderer/src/apps/timer/ui/TimerApp.tsx | 255 --------------------
 3 files changed, 4 insertions(+), 272 deletions(-)
 delete mode 100644 src/renderer/src/apps/timer/index.ts
 delete mode 100644 src/renderer/src/apps/timer/ui/TimerApp.tsx

diff --git a/src/renderer/src/apps/registry.ts b/src/renderer/src/apps/registry.ts
index dc0059ff..c5e24699 100644
--- a/src/renderer/src/apps/registry.ts
+++ b/src/renderer/src/apps/registry.ts
@@ -1,7 +1,5 @@
 import type { AppDefinition } from '@renderer/apps/types'
 
-import { timerApp } from '@renderer/apps/timer'
-
 // The built-in app registry.
 //
 // Adding an app = ONE import + ONE array entry, matching the contract
@@ -15,7 +13,10 @@ import { timerApp } from '@renderer/apps/timer'
 // that — `APP_BY_ID`, the host surface, and the derived commands all consume this
 // array and do not care where its entries came from. That is the whole point of
 // keeping `AppDefinition` serializable-plus-one.
-export const APPS: AppDefinition[] = [timerApp]
+// Empty on purpose. Extensions are INSTALLED, not compiled in — nothing ships in
+// this array. It exists as the resolution target the loader fills at runtime, and
+// as the seam a first-party built-in could use if one is ever justified.
+export const APPS: AppDefinition[] = []
 
 // Lookup for the host surface. Built once at module scope rather than per render:
 // the array is static in Stage 1, and in Stage 2 the loader will rebuild both
diff --git a/src/renderer/src/apps/timer/index.ts b/src/renderer/src/apps/timer/index.ts
deleted file mode 100644
index 40840ffb..00000000
--- a/src/renderer/src/apps/timer/index.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-import type { AppDefinition } from '@renderer/apps/types'
-
-import { TimerApp } from '@renderer/apps/timer/ui/TimerApp'
-
-// The Timer's definition. Everything here except `Component` is exactly what a
-// Stage 2 `agent-code.app.json` would carry — that correspondence is the point,
-// not a coincidence.
-export const timerApp: AppDefinition = {
-  id: 'timer',
-  title: 'Timer',
-  description: 'Countdown timer with presets. Toasts when it finishes.',
-  keywords: ['timer', 'countdown', 'pomodoro', 'clock', 'focus', 'stopwatch'],
-  Component: TimerApp,
-}
diff --git a/src/renderer/src/apps/timer/ui/TimerApp.tsx b/src/renderer/src/apps/timer/ui/TimerApp.tsx
deleted file mode 100644
index 53a78f84..00000000
--- a/src/renderer/src/apps/timer/ui/TimerApp.tsx
+++ /dev/null
@@ -1,255 +0,0 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
-
-import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
-
-// The Timer app.
-//
-// PORTABILITY CONTRACT: this file may import `react` and the ABI type, and nothing
-// else. No store, no components/ui, no lib/utils, no Tailwind utility classes. That
-// is not stylistic — it is the test of whether the host was built honestly, and it
-// is checked by:
-//
-//   grep -rn "@renderer/" src/renderer/src/apps/timer/
-//
-// If that returns anything but the two type imports, this directory can no longer
-// be lifted into its own repository, and Stage 1 has quietly become a substrate
-// Stage 2 must tear out.
-//
-// Colours come from `var(--theme-*)` rather than `bg-surface`/`text-ink`. The
-// utilities are a build-time Tailwind binding that will not exist out-of-tree; the
-// token names will, and the host can push them across a frame boundary unchanged.
-
-const DEFAULT_PRESETS = [5, 15, 25]
-const PRESETS_KEY = 'presets'
-
-// Ring geometry. 2πr for the dash math, computed once rather than per render.
-const RING_SIZE = 176
-const RING_STROKE = 6
-const RING_RADIUS = (RING_SIZE - RING_STROKE) / 2
-const RING_CIRCUMFERENCE = 2 * Math.PI * RING_RADIUS
-
-function formatRemaining(totalSeconds: number): string {
-  const safe = Math.max(0, Math.ceil(totalSeconds))
-  const minutes = Math.floor(safe / 60)
-  const seconds = safe % 60
-  return `${String(minutes).padStart(2, '0')}:${String(seconds).padStart(2, '0')}`
-}
-
-type Phase = 'idle' | 'running' | 'paused' | 'done'
-
-export function TimerApp({ api }: { api: AgentCodeApiV1 }) {
-  const [presets, setPresets] = useState<number[]>(DEFAULT_PRESETS)
-  const [phase, setPhase] = useState<Phase>('idle')
-  const [totalMs, setTotalMs] = useState(0)
-  const [remainingMs, setRemainingMs] = useState(0)
-
-  // WHY a deadline rather than decrementing a counter each tick: a setInterval that
-  // subtracts a fixed amount drifts by however long the interval was actually
-  // delayed, and Chromium throttles background renderers aggressively — a
-  // 25-minute pomodoro in an unfocused window would finish minutes late. Storing
-  // the wall-clock deadline means every tick recomputes from truth, so a late tick
-  // self-corrects instead of accumulating error. Sleep/wake is handled by the same
-  // property. `pausedRemainingRef` holds the leftover while paused, since there is
-  // no meaningful deadline during a pause.
-  const deadlineRef = useRef<number | null>(null)
-
-  useEffect(() => {
-    let cancelled = false
-    void api.storage.get<number[]>(PRESETS_KEY).then(saved => {
-      if (cancelled) return
-      // Validate rather than trust: this is user-editable JSON on disk, and a
-      // hand-edited state.json should degrade to defaults, not render NaN buttons.
-      if (
-        Array.isArray(saved) &&
-        saved.length > 0 &&
-        saved.every(n => typeof n === 'number' && Number.isFinite(n) && n > 0)
-      ) {
-        setPresets(saved)
-      }
-    })
-    return () => {
-      cancelled = true
-    }
-  }, [api])
-
-  useEffect(() => {
-    if (phase !== 'running') return
-
-    // 100ms rather than 1000ms so the ring animates smoothly and the digits never
-    // appear to skip a second when a tick lands just after a boundary. The work per
-    // tick is one subtraction and one setState of a number.
-    const id = setInterval(() => {
-      const deadline = deadlineRef.current
-      if (deadline == null) return
-      const left = deadline - Date.now()
-      if (left <= 0) {
-        deadlineRef.current = null
-        setRemainingMs(0)
-        setPhase('done')
-        void api.ui.showToast('Timer finished')
-        return
-      }
-      setRemainingMs(left)
-    }, 100)
-
-    return () => clearInterval(id)
-  }, [phase, api])
-
-  const start = useCallback((minutes: number) => {
-    const ms = minutes * 60_000
-    deadlineRef.current = Date.now() + ms
-    setTotalMs(ms)
-    setRemainingMs(ms)
-    setPhase('running')
-  }, [])
-
-  const pause = useCallback(() => {
-    const deadline = deadlineRef.current
-    if (deadline == null) return
-    setRemainingMs(Math.max(0, deadline - Date.now()))
-    deadlineRef.current = null
-    setPhase('paused')
-  }, [])
-
-  const resume = useCallback(() => {
-    deadlineRef.current = Date.now() + remainingMs
-    setPhase('running')
-  }, [remainingMs])
-
-  const reset = useCallback(() => {
-    deadlineRef.current = null
-    setPhase('idle')
-    setRemainingMs(0)
-    setTotalMs(0)
-  }, [])
-
-  // Empty ring when idle, full ring at the moment of starting, draining to empty.
-  const progress = totalMs > 0 ? Math.max(0, Math.min(1, remainingMs / totalMs)) : 0
-  const dashOffset = RING_CIRCUMFERENCE * (1 - progress)
-
-  const digitsColor =
-    phase === 'done'
-      ? 'var(--theme-accent)'
-      : phase === 'idle'
-        ? 'var(--theme-muted)'
-        : 'var(--theme-ink)'
-
-  return (
-    <div
-      style={{
-        display: 'flex',
-        flexDirection: 'column',
-        alignItems: 'center',
-        gap: 24,
-        padding: '36px 32px 32px',
-      }}
-    >
-      <div style={{ position: 'relative', width: RING_SIZE, height: RING_SIZE }}>
-        <svg width={RING_SIZE} height={RING_SIZE} style={{ display: 'block' }}>
-          <circle
-            cx={RING_SIZE / 2}
-            cy={RING_SIZE / 2}
-            r={RING_RADIUS}
-            fill="none"
-            stroke="var(--theme-border)"
-            strokeWidth={RING_STROKE}
-          />
-          <circle
-            cx={RING_SIZE / 2}
-            cy={RING_SIZE / 2}
-            r={RING_RADIUS}
-            fill="none"
-            stroke="var(--theme-accent)"
-            strokeWidth={RING_STROKE}
-            strokeLinecap="round"
-            strokeDasharray={RING_CIRCUMFERENCE}
-            strokeDashoffset={dashOffset}
-            // -90deg so the ring starts at 12 o'clock instead of 3 o'clock.
-            transform={`rotate(-90 ${RING_SIZE / 2} ${RING_SIZE / 2})`}
-            style={{ transition: 'stroke-dashoffset 120ms linear' }}
-          />
-        </svg>
-        <div
-          style={{
-            position: 'absolute',
-            inset: 0,
-            display: 'flex',
-            alignItems: 'center',
-            justifyContent: 'center',
-            fontFamily: 'var(--theme-font-code, ui-monospace, monospace)',
-            fontSize: 40,
-            fontVariantNumeric: 'tabular-nums',
-            letterSpacing: '0.02em',
-            color: digitsColor,
-            transition: 'color 160ms ease',
-          }}
-        >
-          {formatRemaining(remainingMs / 1000)}
-        </div>
-      </div>
-
-      <div style={{ display: 'flex', gap: 8 }}>
-        {presets.map(minutes => (
-          <button
-            key={minutes}
-            type="button"
-            onClick={() => start(minutes)}
-            style={{
-              padding: '6px 14px',
-              fontSize: 13,
-              cursor: 'pointer',
-              background: 'var(--theme-control-bg)',
-              color: 'var(--theme-control-fg)',
-              border: '1px solid var(--theme-control-border)',
-              borderRadius: 6,
-            }}
-          >
-            {minutes}m
-          </button>
-        ))}
-      </div>
-
-      <div style={{ display: 'flex', gap: 8 }}>
-        {phase === 'running' ? (
-          <TimerButton label="Pause" tone="accent" onClick={pause} />
-        ) : phase === 'paused' ? (
-          <TimerButton label="Resume" tone="accent" onClick={resume} />
-        ) : null}
-
-        {phase !== 'idle' ? <TimerButton label="Reset" tone="quiet" onClick={reset} /> : null}
-
-        <TimerButton label="Close" tone="quiet" onClick={() => void api.ui.close()} />
-      </div>
-    </div>
-  )
-}
-
-function TimerButton({
-  label,
-  tone,
-  onClick,
-}: {
-  label: string
-  tone: 'accent' | 'quiet'
-  onClick: () => void
-}) {
-  const accent = tone === 'accent'
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      style={{
-        minWidth: 88,
-        padding: '7px 16px',
-        fontSize: 13,
-        cursor: 'pointer',
-        borderRadius: 6,
-        background: accent ? 'var(--theme-accent)' : 'transparent',
-        color: accent ? 'var(--theme-accent-fg)' : 'var(--theme-ink-dim)',
-        border: `1px solid ${accent ? 'var(--theme-accent)' : 'var(--theme-border)'}`,
-      }}
-    >
-      {label}
-    </button>
-  )
-}

From 771a8bebf423160e980e184e099b80c39f691aa6 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:15:35 +0200
Subject: [PATCH 10/18] feat(extensions): install from a GitHub repository in
 Settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Settings > Extensions: paste owner/repo, install, update, remove. This is the
thing the PR was actually for; the compiled-in path it replaces was never an
extension system.

Install sequence — everything that can fail happens in a temp directory, and
the bundle only moves into place after the manifest validates and the entry is
proven to resolve inside it. A failed install therefore leaves no partial
directory for a loader to find.

  normalize repo -> resolve ref -> download -> sha256 -> extract to tmp
  -> validate manifest -> verify entry containment -> atomic rename -> ledger

Ref resolution prefers the latest release over the default branch, because a
release is the author saying "this is ready" while a branch is whatever was
pushed thirty seconds ago. Falls back to the default branch so an extension
without releases still installs — which matters early, when author and user are
the same person. Probed against real GitHub: no-releases correctly 404s to the
fallback, and codeload returns no content-length, so the size cap has to be
enforced post-download as well as pre.

Manifest is zod-validated; the schema IS the allow-list, following the remote
protocol's precedent. `entry` rejects absolute paths, backslashes and ".."
segments, and install additionally realpath-checks that it stays inside the
bundle — the schema cannot catch a symlink committed to the repository, and tar
will happily recreate one pointing at ~/.ssh.

Install returns {ok:false,error} rather than rejecting: every failure here is
user-actionable (wrong repo, private, no manifest, wrong API version, too
large), and an IPC rejection mangles the message into "Error invoking remote
method ..." and loses the error class across the bridge.

PATH SPLIT — installed bundles now live at extensions/<id>/ and per-extension
state moved to extension-state/<id>/. Review flagged the collision: the bundle
directory is replaced wholesale on update, which would have taken the user's
saved state with it. Uninstall deliberately keeps state, because
uninstall-then-reinstall is a normal troubleshooting move.

STORAGE RACE FIX (reproduced 3/3 in review) — writes used a fixed
"${file}.tmp", so two concurrent writers raced: the first rename consumed the
temp file and the second failed ENOENT, losing one write AND rejecting. Temp
names are now unique per write, and every write for an app goes through a
per-app promise chain so read-modify-write cycles cannot interleave. The
all-Promise ABI invites exactly the fire-and-forget shape that triggered it.

The install ledger is separate from the bundles on purpose: scanning
directories would make the filesystem the source of truth and a hand-copied
folder would look installed. The ledger records what the app decided to
install, with repo, ref and hash — questions a directory cannot answer.

Extensions still cannot LOAD; that is the next commit. This one makes the
install half real and independently verifiable.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/main/extensions/install.ts                | 246 ++++++++++++++++++
 src/main/extensions/ledger.ts                 |  82 ++++++
 src/main/extensions/manifest.ts               |  94 +++++++
 src/main/extensions/storage.ts                |  60 ++++-
 src/main/ipc/extensions.ts                    |  30 +++
 src/main/storage/paths.ts                     |  34 ++-
 src/preload/api/extensions.ts                 |  12 +
 src/renderer/src/apps/ui/AppsSettingsRow.tsx  | 209 +++++++++++----
 .../settings/lib/settingsCategories.ts        |   4 +-
 .../features/settings/lib/settingsRegistry.ts |  17 +-
 src/shared/types/extensions.ts                |  55 ++++
 11 files changed, 774 insertions(+), 69 deletions(-)
 create mode 100644 src/main/extensions/install.ts
 create mode 100644 src/main/extensions/ledger.ts
 create mode 100644 src/main/extensions/manifest.ts
 create mode 100644 src/shared/types/extensions.ts

diff --git a/src/main/extensions/install.ts b/src/main/extensions/install.ts
new file mode 100644
index 00000000..a2484645
--- /dev/null
+++ b/src/main/extensions/install.ts
@@ -0,0 +1,246 @@
+import { spawn } from 'child_process'
+import { createHash } from 'node:crypto'
+import { access, constants as fsConstants, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from 'fs/promises'
+import { tmpdir } from 'os'
+import { join, resolve as resolvePath, sep } from 'path'
+
+import { EXTENSIONS_DIR } from '@main/storage/paths.js'
+import { ManifestError, parseExtensionManifest } from '@main/extensions/manifest.js'
+import { readLedger, writeLedger } from '@main/extensions/ledger.js'
+import type { ExtensionManifest, InstalledExtension } from '@shared/types/extensions.js'
+
+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
+
+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.`,
+    )
+  }
+  return `${match[1]}/${match[2]}`
+}
+
+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 fetch(`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 fetch(`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}`,
+  }
+}
+
+async function downloadTarball(url: string): Promise<{ bytes: Buffer; sha256: string }> {
+  const res = await fetch(url, { headers: { 'user-agent': 'agent-code' } })
+  if (!res.ok) throw new InstallError(`Download failed with HTTP ${res.status}.`)
+
+  // Buffered rather than streamed to disk because we need the hash of the exact
+  // bytes we are about to extract, and because MAX_TARBALL_BYTES keeps the ceiling
+  // small. A streaming hash would avoid the buffer but complicates the cap: a
+  // stream that exceeds the limit has already written part of a file we then have
+  // to clean up. If extensions ever get large enough for this to matter, switch to
+  // streaming with an abort-on-cap, not to a bigger buffer.
+  const declared = Number(res.headers.get('content-length') ?? '0')
+  if (declared > MAX_TARBALL_BYTES) {
+    throw new InstallError(`Archive is ${Math.round(declared / 1e6)} MB; the limit is 32 MB.`)
+  }
+
+  const bytes = Buffer.from(await res.arrayBuffer())
+  if (bytes.byteLength > MAX_TARBALL_BYTES) {
+    throw new InstallError(`Archive is ${Math.round(bytes.byteLength / 1e6)} MB; the limit is 32 MB.`)
+  }
+
+  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.
+    const child = spawn(tar, ['-xzf', archivePath, '-C', destDir, '--strip-components=1'], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    })
+    let stderr = ''
+    child.stderr.on('data', chunk => {
+      stderr += String(chunk)
+    })
+    child.once('error', reject)
+    child.once('exit', code => {
+      if (code === 0) resolveExtract()
+      else reject(new InstallError(`Could not unpack the archive (tar exit ${code}): ${stderr.trim()}`))
+    })
+  })
+}
+
+/**
+ * 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))
+  }
+}
+
+/**
+ * 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): Promise<InstalledExtension> {
+  const repo = normalizeRepo(repoInput)
+  const source = await resolveSource(repo)
+  const { bytes, sha256 } = await downloadTarball(source.tarballUrl)
+
+  const work = await mkdtemp(join(tmpdir(), 'agent-code-ext-'))
+  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)
+
+    const manifest = await readManifestFrom(staging)
+    await verifyEntryInsideBundle(staging, manifest.entry)
+
+    await mkdir(EXTENSIONS_DIR, { recursive: true })
+    const finalDir = join(EXTENSIONS_DIR, manifest.id)
+
+    // Remove any previous install of this id before renaming the new one in. This
+    // makes install idempotent and doubles as the update path. Extension STATE is
+    // untouched — it lives under EXTENSION_STATE_DIR precisely so an update cannot
+    // take a user's saved data with it.
+    await rm(finalDir, { recursive: true, force: true })
+    await rename(staging, finalDir)
+
+    const record: InstalledExtension = {
+      manifest,
+      repo,
+      ref: source.ref,
+      sha256,
+      installedAt: Date.now(),
+    }
+
+    const ledger = await readLedger()
+    await writeLedger([...ledger.filter(row => row.manifest.id !== manifest.id), record])
+
+    return record
+  } finally {
+    await rm(work, { recursive: true, force: true })
+  }
+}
diff --git a/src/main/extensions/ledger.ts b/src/main/extensions/ledger.ts
new file mode 100644
index 00000000..704bf67a
--- /dev/null
+++ b/src/main/extensions/ledger.ts
@@ -0,0 +1,82 @@
+import { access, mkdir, readFile, rename, rm, writeFile } from 'fs/promises'
+import { join } from 'path'
+
+import { EXTENSIONS_DIR, EXTENSIONS_LOCKFILE, STATE_DIR } from '@main/storage/paths.js'
+import type { ExtensionListEntry, InstalledExtension } from '@shared/types/extensions.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.
+
+export async function readLedger(): Promise<InstalledExtension[]> {
+  let raw: string
+  try {
+    raw = await readFile(EXTENSIONS_LOCKFILE, 'utf8')
+  } catch {
+    return []
+  }
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (!Array.isArray(parsed)) return []
+    // Rows are shape-checked lazily by their consumers rather than re-validated
+    // here: this file is written only by writeLedger, so a malformed row means the
+    // file was hand-edited, and dropping the whole ledger for one bad row would be
+    // worse than passing it through to a consumer that ignores it.
+    return parsed as InstalledExtension[]
+  } catch {
+    return []
+  }
+}
+
+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> {
+  await rm(join(EXTENSIONS_DIR, id), { recursive: true, force: true })
+  const ledger = await readLedger()
+  await writeLedger(ledger.filter(row => row.manifest.id !== id))
+}
diff --git a/src/main/extensions/manifest.ts b/src/main/extensions/manifest.ts
new file mode 100644
index 00000000..a874081e
--- /dev/null
+++ b/src/main/extensions/manifest.ts
@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+import type { 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')
+
+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(),
+})
+
+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.
+  if (result.data.apiVersion !== SUPPORTED_API_VERSION) {
+    throw new ManifestError(
+      `extension targets Agent Code API v${result.data.apiVersion}, this build implements v${SUPPORTED_API_VERSION}`,
+    )
+  }
+
+  return result.data
+}
diff --git a/src/main/extensions/storage.ts b/src/main/extensions/storage.ts
index c40e368e..a7e8e490 100644
--- a/src/main/extensions/storage.ts
+++ b/src/main/extensions/storage.ts
@@ -66,11 +66,53 @@ async function writeAll(appId: string, data: Record<string, unknown>): Promise<v
   // 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.
-  const tmp = `${file}.tmp`
+  //
+  // 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]
 }
@@ -80,15 +122,19 @@ export async function extensionStorageSet(
   key: string,
   value: unknown,
 ): Promise<void> {
-  const data = await readAll(appId)
-  data[key] = value
-  await writeAll(appId, data)
+  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> {
-  const data = await readAll(appId)
-  delete data[key]
-  await writeAll(appId, data)
+  return enqueueWrite(appId, async () => {
+    const data = await readAll(appId)
+    delete data[key]
+    await writeAll(appId, data)
+  })
 }
 
 export async function extensionStorageKeys(appId: string): Promise<string[]> {
diff --git a/src/main/ipc/extensions.ts b/src/main/ipc/extensions.ts
index 43ef86e9..08b9e440 100644
--- a/src/main/ipc/extensions.ts
+++ b/src/main/ipc/extensions.ts
@@ -6,6 +6,9 @@ import {
   extensionStorageKeys,
   extensionStorageSet,
 } from '@main/extensions/storage.js'
+import { installExtension } from '@main/extensions/install.js'
+import { listInstalledExtensions, removeExtension } from '@main/extensions/ledger.js'
+import type { ExtensionInstallResult, ExtensionListEntry } from '@shared/types/extensions.js'
 
 // IPC for extension-app state.
 //
@@ -43,4 +46,31 @@ export function registerExtensionsIpc(): void {
   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)
+        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> =>
+    removeExtension(id),
+  )
 }
diff --git a/src/main/storage/paths.ts b/src/main/storage/paths.ts
index da9800e0..30820346 100644
--- a/src/main/storage/paths.ts
+++ b/src/main/storage/paths.ts
@@ -21,20 +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')
 
-// Per-app extension state, one directory per app id holding one state.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. A directory per app also makes uninstall a single `rm -rf`.
+// failure mode at all.
 //
-// WHY this root is deliberately NOT registered with debugRetention, unlike every
-// debug root below it: those are disposable forensic caches with a disk budget, and
-// this is *user data*. A retention sweep that pruned it would silently delete an
-// app's saved state. If this ever needs bounding, bound it per-app inside the writer
-// — never by making it a budgeted bucket.
-export const EXTENSION_STATE_DIR = join(STATE_DIR, 'extensions')
+// 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')
 
 // Per-session feed-debug append-only logs, one JSONL file per session.
 // See storage/feedDebugLog.ts for the write-queue discipline.
diff --git a/src/preload/api/extensions.ts b/src/preload/api/extensions.ts
index 1a2773b6..4aaf5425 100644
--- a/src/preload/api/extensions.ts
+++ b/src/preload/api/extensions.ts
@@ -1,5 +1,7 @@
 import { ipcRenderer } from 'electron'
 
+import type { ExtensionInstallResult, ExtensionListEntry } from '@shared/types/extensions.js'
+
 // Extension-app storage bridge.
 //
 // These are the only `extension*`-prefixed methods on the flat api object, and the
@@ -20,4 +22,14 @@ export const extensionsApi = {
 
   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),
+
+  extensionsRemove: (id: string): Promise<void> => ipcRenderer.invoke('extensions:remove', id),
 }
diff --git a/src/renderer/src/apps/ui/AppsSettingsRow.tsx b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
index 7df0c508..bbd37ca5 100644
--- a/src/renderer/src/apps/ui/AppsSettingsRow.tsx
+++ b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
@@ -1,59 +1,180 @@
-import { useAppStore } from '@renderer/app-state/hooks'
+import { useCallback, useEffect, useState } from 'react'
 
-import { APPS } from '@renderer/apps/registry'
+import type { ExtensionListEntry } from '@shared/types/extensions'
 
 /**
- * Settings row listing the built-in apps.
+ * Settings → Extensions. Install from a GitHub repository, list what is installed,
+ * remove.
  *
- * WHY a listing and not a manager: in Stage 1 apps are compiled into the renderer,
- * so there is nothing to install, enable, disable, or remove — every app in `APPS`
- * is present by construction. Shipping toggles now would be UI for state that
- * cannot vary, and a disabled-looking control that always says "enabled" reads as
- * broken. Stage 2 replaces this component's body with install/update/remove and
- * keeps its registry slot, which is why the marker exists at all today.
+ * 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 this file lives under `apps/ui/` rather than `features/settings/ui/`: it is
- * host UI *about* apps, owned by the apps subsystem, the same way
- * `CliUpdateBehaviorRow` lives under `features/cli-updates/`. Note it therefore
- * uses the app's Tailwind utilities normally — the "import nothing from
- * @renderer/*" portability rule applies to `apps/<id>/` app code, not to the host
- * chrome around it.
+ * 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 openApp = useAppStore(state => state.openApp)
-  const closeSettingsPage = useAppStore(state => state.closeSettingsPage)
+  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)
 
-  if (APPS.length === 0) {
-    return <div className="text-[12px] text-muted">No apps installed.</div>
-  }
+  const refresh = useCallback(async () => {
+    try {
+      setEntries(await window.api.extensionsList())
+    } 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.
+      setEntries([])
+      setError(listError instanceof Error ? listError.message : String(listError))
+    }
+  }, [])
+
+  useEffect(() => {
+    void refresh()
+  }, [refresh])
+
+  const install = useCallback(async () => {
+    const target = repo.trim()
+    if (!target || busy) return
+
+    setBusy(true)
+    setError(null)
+    setNotice(null)
+    try {
+      const result = await window.api.extensionsInstall(target)
+      if (result.ok) {
+        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])
+
+  const remove = useCallback(
+    async (entry: ExtensionListEntry) => {
+      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 {
+        await refresh()
+      }
+    },
+    [refresh],
+  )
 
   return (
-    <div className="flex flex-col gap-1">
-      {APPS.map(app => (
-        <div
-          key={app.id}
-          className="flex items-center justify-between gap-4 border border-border bg-row-bg px-3 py-2"
+    <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"
         >
-          <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={() => {
-              // Settings is a full-takeover surface that also carries the
-              // interaction-ownership marker. Leaving it mounted under the app
-              // would stack two owners of the same input, so close it first —
-              // the user asked to use the app, not to keep configuring.
-              closeSettingsPage()
-              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 focus-visible:border-focus-ring focus-visible:ring-1 focus-visible:ring-focus-ring"
-          >
-            Open
-          </button>
+          {busy ? 'Installing…' : 'Install'}
+        </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}
+                </div>
+                <div className="truncate text-[12px] text-muted">{entry.manifest.description}</div>
+                <div className="truncate text-[11px] text-ink-dim">
+                  {entry.repo} @ {entry.ref}
+                </div>
+              </div>
+              <div className="flex shrink-0 gap-2">
+                <button
+                  type="button"
+                  onClick={() => {
+                    setRepo(entry.repo)
+                    void install()
+                  }}
+                  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"
+                >
+                  Update
+                </button>
+                <button
+                  type="button"
+                  onClick={() => void remove(entry)}
+                  className="border border-control-border px-3 py-1 text-[12px] text-ink-dim outline-none hover:border-control-border-hover hover:text-ink"
+                >
+                  Remove
+                </button>
+              </div>
+            </div>
+          ))}
         </div>
-      ))}
+      )}
     </div>
   )
 }
diff --git a/src/renderer/src/features/settings/lib/settingsCategories.ts b/src/renderer/src/features/settings/lib/settingsCategories.ts
index f7fe4366..c8f05e68 100644
--- a/src/renderer/src/features/settings/lib/settingsCategories.ts
+++ b/src/renderer/src/features/settings/lib/settingsCategories.ts
@@ -50,7 +50,7 @@ export const SETTING_CATEGORIES: SettingCategory[] = [
   // and the position can be revisited then, with a reason.
   {
     id: 'apps',
-    label: 'Apps',
-    description: 'Built-in apps available from the command palette.',
+    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 3955b5ab..5a3eea01 100644
--- a/src/renderer/src/features/settings/lib/settingsRegistry.ts
+++ b/src/renderer/src/features/settings/lib/settingsRegistry.ts
@@ -141,11 +141,12 @@ export type SettingDefinition =
       title: string
       description: string
       keywords: string[]
-      // Marker for the built-in apps list. Same escape hatch as
-      // cli-update-behavior — and the purest case of it, because there is no
-      // value at all: the row lists `apps/registry.ts`, which is compile-time
-      // data the Settings store has no business mirroring. A `select` or
-      // `action` control could not express a list with a per-row button.
+      // 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'
@@ -618,9 +619,9 @@ export function getSettingsRegistry(): SettingDefinition[] {
       // See apps/ui/AppsSettingsRow.tsx.
       id: 'apps-installed',
       category: 'apps',
-      title: 'Apps',
-      description: 'Built-in apps available from the command palette.',
-      keywords: ['apps', 'extensions', 'plugins', 'timer', 'tools'],
+      title: 'Extensions',
+      description: 'Install, update, and remove extensions from GitHub repositories.',
+      keywords: ['apps', 'extensions', 'plugins', 'install', 'github', 'tools'],
       control: { type: 'apps' },
     },
     {
diff --git a/src/shared/types/extensions.ts b/src/shared/types/extensions.ts
new file mode 100644
index 00000000..499b4f36
--- /dev/null
+++ b/src/shared/types/extensions.ts
@@ -0,0 +1,55 @@
+// 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.
+
+/** 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[]
+}
+
+/** One row in the install ledger (`extensions.json`). */
+export type InstalledExtension = {
+  manifest: ExtensionManifest
+  /** `owner/repo` as the user typed it, normalized. */
+  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. This is the integrity record: it is what a
+   *  reinstall compares against, and what makes "which bytes am I running" an
+   *  answerable question rather than a guess. */
+  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 }

From 9b82a0886ee8dd6145bcfb2d0d747fbba43f1a18 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:21:56 +0200
Subject: [PATCH 11/18] docs: plan the full VS Code style extension system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Supersedes the Stage 1 plan, which was executed and whose product (a compiled-in
app) was deleted. The successor plans what was actually asked for: extensions
installed from a repository and loaded at runtime.

Adopts the VS Code model rather than the narrower one an earlier draft proposed.
A manifest declares contribution points — commands, views, settings, keybindings
— which reach the palette and Settings WITHOUT the module being loaded, and the
module exports activate(context)/deactivate() imported lazily on a declared
activation event.

Why the narrower "one module exports mount(element, api), host generates one
Open X command" design was rejected, recorded because it is the tempting one:
an extension is not always a window (a watcher reacting to an agent going idle
has no UI), one extension has many contributions, and without declarations every
extension must be imported at startup just to populate a command list, which
makes lazy activation impossible.

Resolves the React gap the audit found. React is NOT added to AgentCodeApiV1 —
that would version the host's React major into the extension API, making a React
19 upgrade an ABI break for extensions that never used React. Instead it is
published on a frozen namespaced global before any extension loads, and views
mount at the DOM level so React stays optional entirely.

Records the eight host changes the superseded plan missed (module-scope registry
and command snapshots, synchronous bootstrap, listPickerCommandMeta, and the
rest), and the four defects inherited from Stage 1 that Task B7 fixes: the toast
that renders behind its own dialog scrim, theme.tokens() missing runtime-only
font tokens, JsonValue admitting NaN, and a missing useMemo dep.

Marks the superseded plan with a Status header naming both of its false claims
so neither is reused.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../2026-07-20-extension-platform-stage1.md   |  14 +
 .../plans/2026-07-20-extension-platform.md    | 814 ++++++++++++++++++
 2 files changed, 828 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-07-20-extension-platform.md

diff --git a/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md b/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
index 8d84d0f7..364cb17d 100644
--- a/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
+++ b/docs/superpowers/plans/2026-07-20-extension-platform-stage1.md
@@ -1,5 +1,19 @@
 # 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.
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 00000000..c845e98f
--- /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.

From dec7e90df2505bb4c4af3957061e4eb1d1201b9e Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:36:55 +0200
Subject: [PATCH 12/18] feat(extensions): privileged agent-code-ext:// scheme
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Serves installed extension bundles to the renderer. This is what makes runtime
loading possible at all, and it is verified rather than assumed — a spike ran
the real built renderer at the real file:// origin under the real CSP:

  document origin                      file:
  fetch missing extension              404
  fetch fixture entry                  200 text/javascript
  traversal ../../../.ssh              404  blocked
  ENCODED traversal ..%2f..%2f         404  blocked
  dynamic import of extension module   activate() imported OK
  relative import inside bundle        ./sibling.js resolved

WHY a custom scheme rather than importing the file path directly: the renderer's
document origin differs between dev (http://localhost) and production (file://),
so a raw filesystem path cannot be made to work identically in both — it is
blocked by the localhost origin in dev and is a cross-origin file:// fetch in
prod. A registered scheme has one spelling that resolves the same way in both,
and adding it to script-src is a single auditable concession rather than
relaxing the policy for all code.

Every privilege is load-bearing and the file says why: `standard` is what makes
relative specifiers inside a bundle resolve (proven above — without it every
intra-extension import would need an absolute URL, which no bundler emits);
`secure` is required for module scripts; `corsEnabled` plus an explicit
access-control-allow-origin is required because module scripts are always
fetched in CORS mode and `standard` makes this a distinct origin from the
document. Omitting that header is the single most likely thing to cost a day —
it fails as an opaque CORS error that says nothing about the cause.

Containment is realpath-based and runs on the DECODED path. Install-time
validation already proves the manifest's entry stays inside the bundle, but this
handler serves arbitrary paths on demand, and a symlink committed to a
repository survives extraction and points wherever it likes. The `+ sep` in the
prefix check matters: a bare startsWith would accept extensions/timer-evil
against extensions/timer.

CSP gains agent-code-ext: on script-src and connect-src (default-src backstops
connect-src, so an extension fetching its own JSON would otherwise fail), plus
the asset directives so extensions can ship CSS, icons and fonts without
inlining everything as data: URIs. Deliberately NOT unsafe-eval, NOT blob:, NOT
file:. worker-src is untouched — the #513 comment above it is unrelated and
load-bearing.

Registration is at module scope with a comment explaining why: Electron silently
treats a post-ready registration as opaque, with no runtime warning, and the
resulting error looks like a CSP problem rather than an ordering one.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/main/extensions/scheme.ts | 188 ++++++++++++++++++++++++++++++++++
 src/main/index.ts             |  19 ++++
 src/renderer/index.html       |  13 ++-
 3 files changed, 219 insertions(+), 1 deletion(-)
 create mode 100644 src/main/extensions/scheme.ts

diff --git a/src/main/extensions/scheme.ts b/src/main/extensions/scheme.ts
new file mode 100644
index 00000000..abd3fbb6
--- /dev/null
+++ b/src/main/extensions/scheme.ts
@@ -0,0 +1,188 @@
+import { net, protocol } from 'electron'
+import { realpath } from 'fs/promises'
+import { extname, 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'
+
+// 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>`
+ */
+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 })
+    }
+
+    const extensionId = url.hostname
+    if (!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 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.
+        //
+        // `*` is safe here because the scheme is only reachable from inside this
+        // app's renderer, and the handler above has already proven the path is
+        // contained. There is no ambient authority to leak: this origin serves
+        // extension bundle files and nothing else.
+        'access-control-allow-origin': '*',
+        // 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/index.ts b/src/main/index.ts
index d7094c9e..5160c673 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -25,6 +25,10 @@ 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 { STATE_DIR, STATE_FILE } from '@main/storage/paths.js'
 import {
   scheduleDebugStoragePrune,
@@ -213,6 +217,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) {
@@ -443,6 +456,12 @@ 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()
+
   void performanceService.start().catch(err => {
     console.warn('[performance] failed to start:', err)
     appRunJournal?.recordError('performance.start.error', err)
diff --git a/src/renderer/index.html b/src/renderer/index.html
index 247923fb..61b6a77a 100644
--- a/src/renderer/index.html
+++ b/src/renderer/index.html
@@ -4,6 +4,17 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <!--
+      WHY agent-code-ext: appears in script-src, connect-src, and the asset
+      directives: installed extensions are served over that privileged scheme
+      (see main/extensions/scheme.ts). It is the narrowest concession that makes
+      runtime-loaded extensions possible — deliberately NOT 'unsafe-eval', NOT
+      blob:, and NOT file:, each of which would relax the policy for all code
+      rather than for one auditable origin whose handler enforces path
+      containment. connect-src is required separately because default-src 'self'
+      backstops it, so an extension fetching its own JSON would otherwise fail.
+      script-src is the load-bearing one; the rest let an extension ship CSS,
+      icons and fonts without inlining everything as data: URIs.
+
       WHY worker-src 'self' blob:
       Monaco language services run in Web Workers (Vite ?worker imports
       are same-origin files in prod, but Vite's dev server and some
@@ -14,7 +25,7 @@
     -->
     <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: agent-code-ext:; style-src 'self' 'unsafe-inline' agent-code-ext: https://fonts.googleapis.com; font-src 'self' data: agent-code-ext: https://fonts.gstatic.com; script-src 'self' agent-code-ext:; connect-src 'self' agent-code-ext:; worker-src 'self' blob:"
     />
     <title>Agent Code</title>
   </head>

From 0fa58576d161d6184cb7c5f927b706791107556d Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:54:45 +0200
Subject: [PATCH 13/18] feat(extensions): host runtime global, and fix four
 review defects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B2 — globalThis.__agentCodeHost publishes React, ReactDOM and the JSX runtime
before any extension module can be imported. An extension cannot bundle its own
React (two reconcilers, "invalid hook call" on every hook) and cannot import the
host's by specifier (chunks are content-hashed and rotate every build), so the
runtime has to be handed over.

Deliberately NOT a field on AgentCodeApiV1: that would version the host's React
major into the extension ABI, making a React 19 upgrade a breaking change for
extensions that never used React. Deliberately not an import map either — a map
must be declared before the document's first module and would resolve `react` to
a shim that reads a global anyway.

Frozen and non-configurable against accidents, not attacks. A same-realm
extension can still reach window.api; only moving extensions into a frame
changes that, and the comment says so rather than implying isolation we do not
have.

B7/1 — GlobalToast z-50 -> z-[1200]. It sat UNDER the Radix dialog scrim
(z-[1100], 88% opaque), so any toast raised while a modal was open was washed
out to invisibility. Harmless while every caller was non-modal chrome; broken
the moment an extension toasts from a hosted view, where the toast can only fire
while a dialog is open — hidden 100% of the time. This is load-bearing for the
timer extension, whose reminders fire as toasts when its window is closed.

B7/2 — theme.tokens() missed --theme-accent, --theme-accent-fg, --theme-app-font
and --theme-font-code. Those are assigned at runtime via setProperty and appear
in no stylesheet, so walking document.styleSheets could never find them. It went
unnoticed because var() does not care where a variable was set — it would break
the moment an extension had to push tokens across a frame boundary, which is the
case the accessor exists for. Empty values are now skipped too: pushing
'--theme-x': '' sets an invalid value that defeats the consumer's fallback.

B7/3 — extensionStorageSet rejects non-finite numbers. JsonValue's `number` is
unrestricted so TypeScript accepts NaN and Infinity, but JSON.stringify turns
all three into null — a silent corruption an author could only find by noticing
wrong behaviour much later. Validated in main because that is the last point
where the value is still structured.

B7/4 — openApp added to CommandPalette's useMemo deps. Benign today (zustand
action identities are stable) but a stale closure the moment that changes, and
there is no lint config in this repo to catch it.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/main/extensions/storage.ts                | 35 ++++++++++
 src/renderer/src/app/main.tsx                 |  8 +++
 src/renderer/src/apps/api/hostGlobal.ts       | 65 +++++++++++++++++++
 src/renderer/src/apps/api/useAppHostApi.ts    | 30 ++++++++-
 .../command-palette/ui/CommandPalette.tsx     |  6 ++
 src/renderer/src/ui/GlobalToast.tsx           | 14 +++-
 6 files changed, 155 insertions(+), 3 deletions(-)
 create mode 100644 src/renderer/src/apps/api/hostGlobal.ts

diff --git a/src/main/extensions/storage.ts b/src/main/extensions/storage.ts
index a7e8e490..e210f427 100644
--- a/src/main/extensions/storage.ts
+++ b/src/main/extensions/storage.ts
@@ -117,11 +117,46 @@ export async function extensionStorageGet(appId: string, key: string): Promise<u
   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
diff --git a/src/renderer/src/app/main.tsx b/src/renderer/src/app/main.tsx
index b14b17f9..c4a112b6 100644
--- a/src/renderer/src/app/main.tsx
+++ b/src/renderer/src/app/main.tsx
@@ -16,6 +16,14 @@ 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 { installHostGlobal } from '@renderer/apps/api/hostGlobal'
+
+// Publish globalThis.__agentCodeHost before ANY extension module can be
+// imported. Extension bundles alias `react` to a shim that reads this object at
+// module-evaluation time, so an extension imported before this ran would throw
+// on its very first import rather than on first render — a failure that would
+// look like a broken extension rather than a host ordering bug.
+installHostGlobal()
 
 void initializePerformance().then(() => {
   mark('app.renderer.reactRenderCalled')
diff --git a/src/renderer/src/apps/api/hostGlobal.ts b/src/renderer/src/apps/api/hostGlobal.ts
new file mode 100644
index 00000000..38a472f5
--- /dev/null
+++ b/src/renderer/src/apps/api/hostGlobal.ts
@@ -0,0 +1,65 @@
+import * as React from 'react'
+import * as ReactDOM from 'react-dom/client'
+import * as ReactJsxRuntime from 'react/jsx-runtime'
+
+/** The shape an extension bundle's shims read. Changing it is an ABI break. */
+export type AgentCodeHostGlobal = {
+  react: typeof React
+  reactDom: typeof ReactDOM
+  jsxRuntime: typeof ReactJsxRuntime
+  apiVersion: 1
+}
+
+const GLOBAL_KEY = '__agentCodeHost'
+
+/**
+ * Publish the host runtime for extension bundles to bind against.
+ *
+ * WHY this exists at all: an extension that renders React cannot bundle its own
+ * copy — two React instances in one document means two reconcilers, and every
+ * hook throws "invalid hook call". It also cannot import the host's copy by
+ * specifier, because the app's chunks are content-hashed (`index-BV5jdlWA.js`)
+ * and rotate on every build, so there is no stable URL to import from.
+ *
+ * WHY a global rather than a field on AgentCodeApiV1: putting React on the
+ * extension API would version the host's React major INTO the extension ABI — a
+ * React 19 upgrade would become a breaking change for every extension, including
+ * the ones that never used React. The API stays framework-free; the runtime is a
+ * separate, lower-level handshake.
+ *
+ * WHY a global rather than an import map: an import map must be declared before
+ * the document's first module loads and must resolve `react` to a URL — which
+ * would have to be a shim that reads a global anyway. Same mechanism, extra
+ * indirection, plus a load-order constraint. The extension's own build aliases
+ * `react` to a shim that reads this object, so no bare specifier ever reaches the
+ * browser.
+ *
+ * WHY frozen and non-configurable: this object is reachable from all renderer
+ * code, so locking it 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
+ * moving extensions into a frame changes that. The freeze is about accidents,
+ * not attacks, and the distinction is worth keeping honest.
+ */
+export function installHostGlobal(): void {
+  const globals = globalThis as Record<string, unknown>
+  // Idempotent: React StrictMode and HMR can both re-run module init, and
+  // defineProperty on an existing non-configurable key throws.
+  if (Object.prototype.hasOwnProperty.call(globals, GLOBAL_KEY)) return
+
+  const host: AgentCodeHostGlobal = Object.freeze({
+    react: React,
+    reactDom: ReactDOM,
+    jsxRuntime: ReactJsxRuntime,
+    apiVersion: 1,
+  })
+
+  Object.defineProperty(globals, GLOBAL_KEY, {
+    value: host,
+    writable: false,
+    configurable: false,
+    // Non-enumerable so it does not show up in devtools' global listing or in
+    // anything that walks globalThis. Extensions know the key by name.
+    enumerable: false,
+  })
+}
diff --git a/src/renderer/src/apps/api/useAppHostApi.ts b/src/renderer/src/apps/api/useAppHostApi.ts
index 1a85f21e..176d775d 100644
--- a/src/renderer/src/apps/api/useAppHostApi.ts
+++ b/src/renderer/src/apps/api/useAppHostApi.ts
@@ -12,10 +12,31 @@ import type { AgentCodeApiV1, JsonValue } from '@renderer/apps/api/types'
 // timer would walk the entire stylesheet set on every tick.
 let cachedTokenNames: string[] | null = null
 
+// Tokens the host assigns at RUNTIME via root.style.setProperty and which
+// therefore appear in NO stylesheet — walking document.styleSheets cannot find
+// them however thorough the walk is.
+//
+// This gap was a real defect: an extension reading theme.tokens() got the whole
+// colour palette but silently no font, and the timer extension consumes
+// --theme-font-code for its digits. It works today only because CSS var()
+// resolution does not care where the variable was set — it would break the
+// moment an extension had to push these across a frame boundary, which is
+// exactly the case theme.tokens() exists for.
+//
+// Source of truth: app-state/settings/theme.ts (applyTheme). If a new runtime
+// token is added there, add it here — there is no automated link between them,
+// and 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>()
+  const names = new Set<string>(RUNTIME_ONLY_TOKENS)
   for (const sheet of Array.from(document.styleSheets)) {
     let rules: CSSRuleList
     try {
@@ -85,7 +106,12 @@ export function useAppHostApi(appId: string, onClose: () => void): AgentCodeApiV
           const style = getComputedStyle(document.documentElement)
           const out: Record<string, string> = {}
           for (const name of themeTokenNames()) {
-            out[name] = style.getPropertyValue(name).trim()
+            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 silently defeats the
+            // consumer's own fallback.
+            if (value) out[name] = value
           }
           return out
         },
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 84d6ae6f..9e825a5b 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -525,6 +525,11 @@ function OpenCommandPalette({
         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,
@@ -573,6 +578,7 @@ function OpenCommandPalette({
       openRewindPrompt,
       openAgentViewModePicker,
       openUsageModal,
+      openApp,
       toggleGitBar,
       toggleWorktreesBar,
       toggleDebugPanel,
diff --git a/src/renderer/src/ui/GlobalToast.tsx b/src/renderer/src/ui/GlobalToast.tsx
index bde4a7ee..df4c9dcc 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

From 4a11af2e37457847de02c306c6bfb28ac7529d70 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 14:58:04 +0200
Subject: [PATCH 14/18] feat(extensions): manifest contributions and activation
 events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extensions now DECLARE what they add — commands, views, settings, keybindings —
plus when the host should import them. Declarations are what make lazy
activation possible: the palette can list a command whose module has never been
loaded. Without them, populating a command list would require importing every
installed extension at startup, and one slow extension would degrade launch for
everything.

Cross-field rules the schema cannot express, each rejecting a failure that is
otherwise silent:

- Contribution ids must sit in the extension's own namespace. Ids land in one
  registry beside ~95 first-party commands, so `session.kill` from an extension
  would collide with a real one and resolve arbitrarily. Install is the last
  point where the user can act on it.
- Duplicate ids within a manifest are an authoring mistake and fail. Duplicates
  ACROSS extensions are deliberately not handled here — neither author can see
  the other's manifest, so failing the install would punish whoever installed
  second. Resolved at load instead.
- A keybinding targeting a command the extension does not contribute fails.
- An activation event naming a missing command or view fails. This is the
  hardest authoring mistake to diagnose otherwise: the extension simply never
  activates, with no error anywhere.

Verified against the REAL timer manifest plus nine rejection cases, and that
caught a genuine bug: the contribution-id regex demanded kebab-case throughout
and rejected `timer.inheritTheme`. camelCase after the first dot is idiomatic
and now allowed; the extension id itself stays kebab-only because it becomes a
directory name and is constrained by the filesystem, not by taste.

View mount is a closed enum rather than a free string — the host owns the
chrome, and an unknown kind must fail at install rather than resolve to nothing
at render time. Only 'modal' exists; 'panel'/'tab' are the same registration
with a different shell.

Number setting defaults are `.finite()`: a NaN default would be written straight
into extension storage, where JSON.stringify turns it into null.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/main/extensions/manifest.ts | 176 +++++++++++++++++++++++++++++++-
 src/shared/types/extensions.ts  |  59 +++++++++++
 2 files changed, 234 insertions(+), 1 deletion(-)

diff --git a/src/main/extensions/manifest.ts b/src/main/extensions/manifest.ts
index a874081e..7229f8ef 100644
--- a/src/main/extensions/manifest.ts
+++ b/src/main/extensions/manifest.ts
@@ -1,6 +1,9 @@
 import { z } from 'zod'
 
-import type { ExtensionManifest } from '@shared/types/extensions.js'
+import type {
+  ExtensionActivationEvent,
+  ExtensionManifest,
+} from '@shared/types/extensions.js'
 
 // Manifest validation.
 //
@@ -40,6 +43,91 @@ const ENTRY_PATH = z
   )
   .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']),
+})
+
+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),
+})
+
+// `.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),
@@ -48,6 +136,15 @@ export const extensionManifestSchema = z.object({
   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(),
 })
 
 export class ManifestError extends Error {
@@ -90,5 +187,82 @@ export function parseExtensionManifest(raw: string): ExtensionManifest {
     )
   }
 
+  assertContributionsAreCoherent(result.data)
   return result.data
 }
+
+/**
+ * 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/shared/types/extensions.ts b/src/shared/types/extensions.ts
index 499b4f36..a4be3b29 100644
--- a/src/shared/types/extensions.ts
+++ b/src/shared/types/extensions.ts
@@ -6,6 +6,61 @@
 // 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'
+
+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[]
+}
+
+/**
+ * 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,
@@ -24,6 +79,10 @@ export type ExtensionManifest = {
    *  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
 }
 
 /** One row in the install ledger (`extensions.json`). */

From 2fd224cd41c3a8b77943a021646689bbcb1f976a Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 15:06:49 +0200
Subject: [PATCH 15/18] feat(extensions): extension host, view bridge, and a
 live registry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

B4/B5/B6. Installed extensions now load, activate and render.

EXTENSION HOST. One dynamic import over agent-code-ext://, then activate(context).
Every failure is a VALUE, never a throw: third-party code that fails to import,
exports no activate, or throws inside it must leave every other extension running
and must not be able to blank the renderer. Failures land in Settings with the
message that names the fault.

Activation is memoized on the IN-FLIGHT PROMISE rather than a boolean. A palette
command and a view open can race in the same frame, and a boolean set after the
await would let both call activate() on one module.

Disposal runs deactivate() first, then subscriptions in REVERSE order — later
subscriptions were created against earlier ones, so disposing forwards can tear
down a dependency while a dependant still holds it. A throwing deactivate does
not skip disposal; the subscriptions are the host's cleanup contract, and
skipping them would leak intervals and AudioContexts for the session.

registerCommand/registerView REJECT an id the manifest did not declare. A handler
the palette has no entry for can never be invoked, so accepting it silently would
leave the author with a dead command and no clue why.

VIEW BRIDGE. Adapts a DOM-level ViewMount into AppDefinition.Component, and is
the entire adapter between the host's React world and the extension's DOM world
— the piece that gets replaced, not rewritten, if extensions later move into an
iframe. It activates on render, which is what onView: activation means: the
palette can open a view whose module has never been imported. A throw during
mount is contained rather than allowed to unwind into the host tree, where React
would unmount to the root.

LIVE REGISTRY — the part the superseded plan under-priced as "a five-line
change". Removed three module-scope snapshots: APPS/APP_BY_ID (deleted),
appCommands (deleted), and commandDefs (now builtInCommandDefs plus a
per-call concat). listPickerCommandMeta takes extension commands too, so
Settings' command-visibility row covers them. Installed extensions live in the
store, because the palette, Settings and the view host all have to re-render
when one is installed — a module array cannot notify them.

Commands and views are derived from MANIFESTS, never from loaded modules. That
is the whole point of declaring contributions: ten installed extensions must not
mean ten third-party module evaluations before the app is usable. Only
onStartupFinished/* activate eagerly.

Cross-extension id collisions resolve at load (first wins, loser dropped) rather
than at install — neither author can see the other's manifest, so failing the
install would punish whoever installed second.

useAppHostApi became createAppHostApi, a plain factory: the host must build an
API at activation time, which can happen from a palette command with no
component mounted, and a hook cannot be called there.

Moved the module contract out of src/shared into renderer/apps/host/: it
references AgentCodeApiV1, and src/shared is compiled by the node project which
cannot see @renderer/*. That boundary is real — main validates manifests and
never touches an extension module.

typecheck / 1187 tests / build all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/app-state/types.ts           |   4 +
 src/renderer/src/app-state/uiShell/slice.ts   |   7 +
 src/renderer/src/app-state/uiShell/types.ts   |  19 ++
 src/renderer/src/app/main.tsx                 |  15 +-
 src/renderer/src/apps/api/createAppHostApi.ts | 109 +++++++++
 src/renderer/src/apps/api/useAppHostApi.ts    | 122 -----------
 src/renderer/src/apps/commands/appCommands.ts |  35 ---
 src/renderer/src/apps/host/ExtensionHost.ts   | 206 ++++++++++++++++++
 .../src/apps/host/ExtensionHostProvider.tsx   |  98 +++++++++
 src/renderer/src/apps/host/derive.ts          | 113 ++++++++++
 src/renderer/src/apps/host/moduleContract.ts  |  47 ++++
 src/renderer/src/apps/host/registrations.ts   |  59 +++++
 src/renderer/src/apps/host/viewBridge.tsx     | 106 +++++++++
 src/renderer/src/apps/registry.ts             |  25 ---
 .../src/apps/surfaces/AppHostSurface.tsx      | 104 +++++----
 src/renderer/src/apps/ui/AppsSettingsRow.tsx  |  26 ++-
 .../src/features/command-palette/registry.ts  |  45 +++-
 .../command-palette/ui/CommandPalette.tsx     |  18 +-
 18 files changed, 917 insertions(+), 241 deletions(-)
 create mode 100644 src/renderer/src/apps/api/createAppHostApi.ts
 delete mode 100644 src/renderer/src/apps/api/useAppHostApi.ts
 delete mode 100644 src/renderer/src/apps/commands/appCommands.ts
 create mode 100644 src/renderer/src/apps/host/ExtensionHost.ts
 create mode 100644 src/renderer/src/apps/host/ExtensionHostProvider.tsx
 create mode 100644 src/renderer/src/apps/host/derive.ts
 create mode 100644 src/renderer/src/apps/host/moduleContract.ts
 create mode 100644 src/renderer/src/apps/host/registrations.ts
 create mode 100644 src/renderer/src/apps/host/viewBridge.tsx
 delete mode 100644 src/renderer/src/apps/registry.ts

diff --git a/src/renderer/src/app-state/types.ts b/src/renderer/src/app-state/types.ts
index 034281e6..b8bb0bea 100644
--- a/src/renderer/src/app-state/types.ts
+++ b/src/renderer/src/app-state/types.ts
@@ -3,6 +3,8 @@ import type { DispatchAttachIntent, UiShellState } from '@renderer/app-state/uiS
 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/host/ExtensionHost'
 import type {
   ReaderModeState,
   SpotlightState,
@@ -90,6 +92,8 @@ export type UiShellSlice = UiShellState & {
   closeRewindPrompt: () => void
   openApp: (appId: string) => void
   closeApp: () => void
+  setInstalledExtensions: (entries: ExtensionListEntry[]) => void
+  setExtensionFailures: (failures: ExtensionFailure[]) => void
   openAgentViewModePicker: (sessionId: SessionId) => void
   closeAgentViewModePicker: () => void
 }
diff --git a/src/renderer/src/app-state/uiShell/slice.ts b/src/renderer/src/app-state/uiShell/slice.ts
index 4516982f..b992da47 100644
--- a/src/renderer/src/app-state/uiShell/slice.ts
+++ b/src/renderer/src/app-state/uiShell/slice.ts
@@ -44,6 +44,8 @@ export const createUiShellSlice: StateCreator<
   rewindPromptSessionId: null,
   agentViewModePickerSessionId: null,
   openAppId: null,
+  installedExtensions: [],
+  extensionFailures: [],
   // Default keeps the dispatch list at 25% (matching the
   // previous-hardcoded `basis-1/4`) so the migration is visually a
   // no-op. The clamp range in setDispatchListRatio is what enforces
@@ -256,6 +258,11 @@ export const createUiShellSlice: StateCreator<
   openApp: appId => set({ openAppId: appId }, false, 'uiShell/openApp'),
   closeApp: () => set({ openAppId: null }, false, 'uiShell/closeApp'),
 
+  setInstalledExtensions: entries =>
+    set({ installedExtensions: entries }, 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 33c45810..4fe92eaa 100644
--- a/src/renderer/src/app-state/uiShell/types.ts
+++ b/src/renderer/src/app-state/uiShell/types.ts
@@ -1,4 +1,6 @@
 import type { TabId, SessionId } from '@renderer/workspace/types'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+import type { ExtensionFailure } from '@renderer/apps/host/ExtensionHost'
 
 export type DispatchAttachIntent = {
   sessionId: SessionId
@@ -209,6 +211,23 @@ export type UiShellState = {
    * 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[]
+  /** Extensions whose import or activate() threw. Surfaced in Settings rather
+   *  than hidden, because a silently-missing extension is undiagnosable. */
+  extensionFailures: ExtensionFailure[]
   /** Splitter ratio between the dispatch agent list and the active
    *  agent pane in `DispatchLayout`. 0..1, where 0.25 means the list
    *  is 25% of the available width. Clamped to [0.15, 0.5] when the
diff --git a/src/renderer/src/app/main.tsx b/src/renderer/src/app/main.tsx
index c4a112b6..a138c300 100644
--- a/src/renderer/src/app/main.tsx
+++ b/src/renderer/src/app/main.tsx
@@ -17,6 +17,7 @@ import { WorkflowClientProvider } from '@renderer/features/workflows/client/Work
 import { ipcWorkflowClient } from '@renderer/features/workflows/client/IpcWorkflowClient'
 import { startRendererFreezeHeartbeat } from '@renderer/performance/freezeHeartbeat'
 import { installHostGlobal } from '@renderer/apps/api/hostGlobal'
+import { ExtensionHostProvider } from '@renderer/apps/host/ExtensionHostProvider'
 
 // Publish globalThis.__agentCodeHost before ANY extension module can be
 // imported. Extension bundles alias `react` to a shim that reads this object at
@@ -93,9 +94,17 @@ createRoot(document.getElementById('root')!).render(
     <WorkflowClientProvider value={ipcWorkflowClient}>
       <SessionFeedProvider value={ipcSessionFeed}>
         <GlobalToastProvider>
-          <AppErrorBoundary>
-            <App />
-          </AppErrorBoundary>
+          {/* INSIDE GlobalToastProvider because the extension API's showToast
+              comes from it, and INSIDE AppErrorBoundary's parent so a throw
+              while loading extensions is caught rather than blanking the app.
+              Extensions activate from an effect here, not from bootstrap:
+              blocking the first paint on third-party module evaluation would let
+              one slow extension delay startup for everything. */}
+          <ExtensionHostProvider>
+            <AppErrorBoundary>
+              <App />
+            </AppErrorBoundary>
+          </ExtensionHostProvider>
         </GlobalToastProvider>
       </SessionFeedProvider>
     </WorkflowClientProvider>
diff --git a/src/renderer/src/apps/api/createAppHostApi.ts b/src/renderer/src/apps/api/createAppHostApi.ts
new file mode 100644
index 00000000..eda676f7
--- /dev/null
+++ b/src/renderer/src/apps/api/createAppHostApi.ts
@@ -0,0 +1,109 @@
+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
+      },
+    },
+  }
+}
diff --git a/src/renderer/src/apps/api/useAppHostApi.ts b/src/renderer/src/apps/api/useAppHostApi.ts
deleted file mode 100644
index 176d775d..00000000
--- a/src/renderer/src/apps/api/useAppHostApi.ts
+++ /dev/null
@@ -1,122 +0,0 @@
-import { useMemo } from 'react'
-
-import { useGlobalToast } from '@renderer/ui/GlobalToast'
-
-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 is done once per renderer lifetime and only the cheap
-// getPropertyValue() lookups repeat. Without this cache an app polling tokens on a
-// timer would walk the entire stylesheet set on every tick.
-let cachedTokenNames: string[] | null = null
-
-// Tokens the host assigns at RUNTIME via root.style.setProperty and which
-// therefore appear in NO stylesheet — walking document.styleSheets cannot find
-// them however thorough the walk is.
-//
-// This gap was a real defect: an extension reading theme.tokens() got the whole
-// colour palette but silently no font, and the timer extension consumes
-// --theme-font-code for its digits. It works today only because CSS var()
-// resolution does not care where the variable was set — it would break the
-// moment an extension had to push these across a frame boundary, which is
-// exactly the case theme.tokens() exists for.
-//
-// Source of truth: app-state/settings/theme.ts (applyTheme). If a new runtime
-// token is added there, add it here — there is no automated link between them,
-// and 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 on it throws a SecurityError. Nothing we need is in
-      // there (it is font-face only), so skipping is correct, not a fallback.
-      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
-}
-
-/**
- * Builds the AgentCodeApiV1 instance handed to one app.
- *
- * WHY a hook rather than a module-level factory: `showToast` comes from React
- * context (ui/GlobalToast.tsx) and `close` is the host's own state action. Both are
- * per-mount concerns. The app never learns either origin — it receives the ABI and
- * nothing else, which is precisely what makes it portable.
- *
- * WHY appId is closed over rather than passed on every call: an app must not be
- * able to name a different app's storage namespace. In Stage 1 that is a
- * convention enforced by this closure and by the rule that `useAppHostApi` is the
- * only call site of `window.api.extensionStorage*`. In Stage 2 it becomes properly
- * enforceable, because each app gets its own frame and main derives the id from the
- * sender instead of trusting the argument.
- */
-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: {
-        // 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 () => {
-          onClose()
-        },
-        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 silently defeats the
-            // consumer's own fallback.
-            if (value) out[name] = value
-          }
-          return out
-        },
-      },
-    }),
-    [appId, onClose, showToast],
-  )
-}
diff --git a/src/renderer/src/apps/commands/appCommands.ts b/src/renderer/src/apps/commands/appCommands.ts
deleted file mode 100644
index 6b972085..00000000
--- a/src/renderer/src/apps/commands/appCommands.ts
+++ /dev/null
@@ -1,35 +0,0 @@
-import type { CommandDef } from '@renderer/features/command-palette/types'
-
-import { APPS } from '@renderer/apps/registry'
-
-// Palette commands, derived rather than hand-written.
-//
-// N apps produce N commands with zero per-app boilerplate, and — more importantly —
-// an app physically cannot ship without a way to open it. A hand-written command
-// per app would make "forgot to register the opener" a real and silent failure
-// mode; deriving makes it unrepresentable.
-//
-// This mapping is also what keeps the cost of adding an app at one import plus one
-// array entry in `apps/registry.ts`. `buildCommandRegistry` already recomputes on
-// every context change, so nothing here needs to be reactive.
-//
-// Stage 2 note: when `APPS` becomes `[...BUILTIN, ...loaded]`, this module needs no
-// edit — but `commandDefs` in the palette registry is a module-scope const, so it
-// will have to become a function that concatenates a live list. That is a five-line
-// change at one call site, deliberately NOT pre-abstracted here: building a getter
-// today to serve a hypothetical loader is the anticipatory indirection this repo's
-// guardrails argue against, and doing it later is cheap.
-export const appCommands: CommandDef[] = APPS.map(app => ({
-  id: `app.open.${app.id}`,
-  title: `Open ${app.title}`,
-  description: app.description,
-  // 'app' rather than 'grid'/'dispatch': an app is mode-independent. It has no
-  // relationship to the tile tree or to Dispatch, so hiding it in either mode would
-  // be wrong — see the CommandSurface doc comment in command-palette/types.ts.
-  surface: 'app',
-  keywords: app.keywords ?? [],
-  run: ({ ui }) => {
-    ui.openApp(app.id)
-    ui.closePalette()
-  },
-}))
diff --git a/src/renderer/src/apps/host/ExtensionHost.ts b/src/renderer/src/apps/host/ExtensionHost.ts
new file mode 100644
index 00000000..1304b584
--- /dev/null
+++ b/src/renderer/src/apps/host/ExtensionHost.ts
@@ -0,0 +1,206 @@
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+import type {
+  Disposable,
+  ExtensionContext,
+  ExtensionModule,
+  ViewMount,
+} from '@renderer/apps/host/moduleContract'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+
+import { ExtensionRegistrations } from '@renderer/apps/host/registrations'
+
+export type ExtensionFailure = { id: string; name: string; error: string }
+
+type Loaded = {
+  entry: ExtensionListEntry
+  module: ExtensionModule
+  context: ExtensionContext
+}
+
+/**
+ * Imports, activates and disposes installed extensions.
+ *
+ * WHY every failure is a VALUE and never a throw: an extension is third-party
+ * code loaded at runtime. A module that fails to import, exports no `activate`,
+ * or throws inside it must leave every other extension running and must not be
+ * able to blank the renderer. Failures accumulate in `failures` and are surfaced
+ * in Settings, where the user can act on them.
+ *
+ * WHY activation is memoized on the in-flight promise rather than a boolean:
+ * two triggers can race — a palette command and a view open in the same frame —
+ * and a boolean set after the await would let both run `activate()`. Storing the
+ * promise means the second caller joins the first.
+ */
+export class ExtensionHost {
+  private loaded = new Map<string, Loaded>()
+  private activating = new Map<string, Promise<void>>()
+  private registrations = new ExtensionRegistrations()
+  private failures: ExtensionFailure[] = []
+
+  constructor(
+    /** Builds the per-extension API instance. Injected so the host does not
+     *  reach into React context, and so tests can supply a fake. */
+    private makeApi: (extensionId: string) => AgentCodeApiV1,
+    private onFailuresChanged: (failures: ExtensionFailure[]) => void,
+  ) {}
+
+  getFailures(): ExtensionFailure[] {
+    return this.failures
+  }
+
+  isActivated(extensionId: string): boolean {
+    return this.loaded.has(extensionId)
+  }
+
+  /**
+   * Import and activate, once.
+   *
+   * The single line of actual loading is the dynamic import below. `@vite-ignore`
+   * stops Vite trying to analyze a runtime specifier at build time; 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. The B1 spike then proved it works over
+   * agent-code-ext:// from a file:// document.
+   */
+  async activate(entry: ExtensionListEntry): Promise<void> {
+    const id = entry.manifest.id
+    if (this.loaded.has(id)) return
+    const inFlight = this.activating.get(id)
+    if (inFlight) return inFlight
+
+    const run = (async () => {
+      try {
+        const url = `agent-code-ext://${id}/${entry.manifest.entry}`
+        const module = (await import(/* @vite-ignore */ url)) as ExtensionModule
+
+        if (typeof module.activate !== 'function') {
+          // The most likely authoring mistake by a wide margin, so it gets its
+          // own message rather than surfacing as a TypeError from a call site.
+          throw new Error('entry module does not export an activate(context) function')
+        }
+
+        const context = this.makeContext(entry)
+        await module.activate(context)
+        this.loaded.set(id, { entry, module, context })
+        this.clearFailure(id)
+      } catch (error) {
+        this.recordFailure(id, entry.manifest.name, error)
+      } finally {
+        this.activating.delete(id)
+      }
+    })()
+
+    this.activating.set(id, run)
+    return run
+  }
+
+  async deactivate(extensionId: string): Promise<void> {
+    const loaded = this.loaded.get(extensionId)
+    if (!loaded) return
+    this.loaded.delete(extensionId)
+
+    try {
+      await loaded.module.deactivate?.()
+    } catch (error) {
+      // A throwing deactivate must not prevent disposal — the subscriptions are
+      // the host's cleanup contract, and skipping them would leak intervals and
+      // listeners for the rest of the session.
+      this.recordFailure(extensionId, loaded.entry.manifest.name, error)
+    }
+
+    // Reverse order: later subscriptions were created against earlier ones, so
+    // disposing forwards can tear down a dependency while a dependant still
+    // holds it. This is the same ordering every disposable stack uses, for the
+    // same reason.
+    for (const subscription of [...loaded.context.subscriptions].reverse()) {
+      try {
+        subscription.dispose()
+      } catch {
+        // One bad disposer must not strand the rest.
+      }
+    }
+
+    this.registrations.disposeAll(extensionId)
+  }
+
+  async deactivateAll(): Promise<void> {
+    await Promise.all([...this.loaded.keys()].map(id => this.deactivate(id)))
+  }
+
+  /**
+   * Run a contributed command, activating the extension first if needed.
+   *
+   * This is what makes `onCommand:` activation real: the palette lists the
+   * command from the manifest, and the module is imported only when it is
+   * actually invoked.
+   */
+  async executeCommand(entry: ExtensionListEntry, commandId: string): Promise<void> {
+    await this.activate(entry)
+    const handler = this.registrations.getCommand(entry.manifest.id, commandId)
+    if (!handler) {
+      // Declared but never registered. Not a crash: an extension may reasonably
+      // declare a command whose only meaning is "open my view", which the host
+      // resolves without a handler.
+      return
+    }
+    try {
+      await handler()
+    } catch (error) {
+      this.recordFailure(entry.manifest.id, entry.manifest.name, error)
+    }
+  }
+
+  /** The mount registered for a view, if its extension has activated. */
+  getView(extensionId: string, viewId: string): ViewMount | undefined {
+    return this.registrations.getView(extensionId, viewId)
+  }
+
+  private makeContext(entry: ExtensionListEntry): ExtensionContext {
+    const id = entry.manifest.id
+    const declaredCommands = new Set(
+      (entry.manifest.contributes?.commands ?? []).map(command => command.id),
+    )
+    const declaredViews = new Set((entry.manifest.contributes?.views ?? []).map(view => view.id))
+    const subscriptions: Disposable[] = []
+
+    return {
+      api: this.makeApi(id),
+      subscriptions,
+
+      registerCommand: (commandId, run) => {
+        // Rejecting an undeclared id is deliberate. A handler the palette has no
+        // entry for can never be invoked, so silently accepting it would leave
+        // the author with a command that does nothing and no clue why. The throw
+        // is caught by activate() and shown as an extension failure.
+        if (!declaredCommands.has(commandId)) {
+          throw new Error(
+            `registerCommand("${commandId}") — not declared in contributes.commands`,
+          )
+        }
+        return this.registrations.registerCommand(id, commandId, run)
+      },
+
+      registerView: (viewId, mount) => {
+        if (!declaredViews.has(viewId)) {
+          throw new Error(`registerView("${viewId}") — not declared in contributes.views`)
+        }
+        return this.registrations.registerView(id, viewId, mount)
+      },
+    }
+  }
+
+  private recordFailure(id: string, name: string, error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error)
+    this.failures = [...this.failures.filter(failure => failure.id !== id), { id, name, error: message }]
+    this.onFailuresChanged(this.failures)
+    // Also to the console: Settings shows the message, but a stack is what
+    // actually locates a bug inside third-party code.
+    console.warn(`[extensions] ${id} failed:`, error)
+  }
+
+  private clearFailure(id: string): void {
+    if (!this.failures.some(failure => failure.id === id)) return
+    this.failures = this.failures.filter(failure => failure.id !== id)
+    this.onFailuresChanged(this.failures)
+  }
+}
diff --git a/src/renderer/src/apps/host/ExtensionHostProvider.tsx b/src/renderer/src/apps/host/ExtensionHostProvider.tsx
new file mode 100644
index 00000000..a2d10aab
--- /dev/null
+++ b/src/renderer/src/apps/host/ExtensionHostProvider.tsx
@@ -0,0 +1,98 @@
+import { createContext, useContext, useEffect, useMemo, useRef } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import { createAppHostApi } from '@renderer/apps/api/createAppHostApi'
+import { ExtensionHost } from '@renderer/apps/host/ExtensionHost'
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
+
+const ExtensionHostContext = createContext<ExtensionHost | null>(null)
+
+export function useExtensionHost(): ExtensionHost | null {
+  return useContext(ExtensionHostContext)
+}
+
+/**
+ * Owns the single ExtensionHost and drives the install → load → activate cycle.
+ *
+ * WHY a provider rather than a module singleton: the host needs `showToast`,
+ * which is React context, and it needs to push failures into the store. Both are
+ * app-lifetime concerns, and a module singleton would have to reach for them
+ * through globals.
+ */
+export function ExtensionHostProvider({ children }: { children: React.ReactNode }) {
+  const { showToast } = useGlobalToast()
+  const setInstalledExtensions = useAppStore(state => state.setInstalledExtensions)
+  const setExtensionFailures = useAppStore(state => state.setExtensionFailures)
+  const closeApp = useAppStore(state => state.closeApp)
+
+  // Refs so the host is constructed exactly once and never re-created by a
+  // re-render. Re-creating it would orphan every activated extension: their
+  // modules stay in the module cache but their registrations would be gone, and
+  // a second activate() would run activate() twice on the same module instance.
+  const closeAppRef = useRef(closeApp)
+  closeAppRef.current = closeApp
+  const showToastRef = useRef(showToast)
+  showToastRef.current = showToast
+
+  const host = useMemo(
+    () =>
+      new ExtensionHost(
+        extensionId =>
+          createAppHostApi({
+            extensionId,
+            // Through refs so the API object handed to a long-lived extension
+            // never captures a stale callback from the render that created it.
+            showToast: message => showToastRef.current(message),
+            closeSurface: () => closeAppRef.current(),
+          }),
+        failures => setExtensionFailures(failures),
+      ),
+    [setExtensionFailures],
+  )
+
+  useEffect(() => {
+    let cancelled = false
+
+    const load = 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
+        // whatever was previously loaded rather than making every extension
+        // vanish because one IPC call failed.
+        return
+      }
+      if (cancelled) return
+      setInstalledExtensions(installed)
+
+      // Eager activation ONLY for extensions that asked for it. Everything else
+      // waits for its own onCommand:/onView: trigger, which is the entire point
+      // of declaring contributions: ten installed extensions must not mean ten
+      // third-party module evaluations before the app is usable.
+      for (const entry of installed) {
+        if (!entry.present) continue
+        const events = entry.manifest.activationEvents ?? []
+        if (events.includes('onStartupFinished') || events.includes('*')) {
+          void host.activate(entry)
+        }
+      }
+    }
+
+    void load()
+    return () => {
+      cancelled = true
+    }
+  }, [host, setInstalledExtensions])
+
+  useEffect(() => {
+    return () => {
+      // Best-effort on teardown. In practice the renderer is going away anyway,
+      // but an extension holding an interval or an AudioContext deserves its
+      // deactivate() called rather than being killed mid-flight.
+      void host.deactivateAll()
+    }
+  }, [host])
+
+  return <ExtensionHostContext.Provider value={host}>{children}</ExtensionHostContext.Provider>
+}
diff --git a/src/renderer/src/apps/host/derive.ts b/src/renderer/src/apps/host/derive.ts
new file mode 100644
index 00000000..9f96977d
--- /dev/null
+++ b/src/renderer/src/apps/host/derive.ts
@@ -0,0 +1,113 @@
+import type { CommandDef } from '@renderer/features/command-palette/types'
+import type { AppDefinition } from '@renderer/apps/types'
+import type { ExtensionHost } from '@renderer/apps/host/ExtensionHost'
+import { viewComponentFor } from '@renderer/apps/host/viewBridge'
+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 ExtensionHost.
+//
+// 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(
+  host: ExtensionHost,
+  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(host, 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(
+  host: ExtensionHost,
+  installed: ExtensionListEntry[],
+  openApp: (appId: string) => void,
+): CommandDef[] {
+  const seen = new Set<string>()
+  const commands: CommandDef[] = []
+
+  for (const entry of installed) {
+    if (!entry.present) continue
+    const viewIds = new Set((entry.manifest.contributes?.views ?? []).map(view => view.id))
+
+    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',
+        keywords: command.keywords ?? [],
+        run: ({ ui }) => {
+          if (targetView) {
+            openApp(targetView)
+            ui.closePalette()
+            return
+          }
+          // Fire-and-forget: executeCommand activates the extension first, which
+          // can take a moment, and holding the palette open through a dynamic
+          // import would make every extension command feel broken.
+          void host.executeCommand(entry, command.id)
+          ui.closePalette()
+        },
+      })
+    }
+  }
+
+  return commands
+}
diff --git a/src/renderer/src/apps/host/moduleContract.ts b/src/renderer/src/apps/host/moduleContract.ts
new file mode 100644
index 00000000..9484029d
--- /dev/null
+++ b/src/renderer/src/apps/host/moduleContract.ts
@@ -0,0 +1,47 @@
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+
+// WHY this lives under renderer/apps/host/ and NOT in src/shared/types/:
+// it references AgentCodeApiV1, which is renderer code, and src/shared is
+// compiled by the node tsconfig project which cannot see @renderer/*. That is a
+// real boundary, not a build quirk — main validates MANIFESTS (shared types) and
+// never touches an extension module, because modules are imported into the
+// renderer realm. Putting this in shared compiled fine right up until tsc
+// noticed the cross-project import, and moving it is the correct fix rather than
+// widening the node project's file list.
+
+export type Disposable = { dispose(): void }
+
+/**
+ * A view's renderer: DOM element in, cleanup function out.
+ *
+ * WHY DOM-level rather than a React component: it keeps React optional (plain
+ * DOM, Preact, Svelte and canvas all work with no framework negotiation), and it
+ * is the one shape that survives a future move into an iframe. A React component
+ * reference cannot cross a frame boundary; "call mount with this element" can be
+ * reimplemented on the far side unchanged. A React author writes
+ * `createRoot(element).render(<App/>)` on one line.
+ */
+export type ViewMount = (element: HTMLElement) => void | (() => void)
+
+/**
+ * What `activate()` receives.
+ *
+ * WHY registration is separate from declaration: the manifest declares WHAT
+ * exists so the palette and Settings can list it without loading anything; this
+ * binds the HANDLERS once the module is finally imported. An id that was never
+ * declared is rejected here rather than silently accepted, because a handler the
+ * palette has no entry for can never be invoked and the author would have no
+ * way to notice.
+ */
+export type ExtensionContext = {
+  readonly api: AgentCodeApiV1
+  registerCommand(id: string, run: () => void | Promise<void>): Disposable
+  registerView(id: string, mount: ViewMount): Disposable
+  /** Disposed in reverse order on deactivate. */
+  readonly subscriptions: Disposable[]
+}
+
+export type ExtensionModule = {
+  activate(context: ExtensionContext): void | Promise<void>
+  deactivate?(): void | Promise<void>
+}
diff --git a/src/renderer/src/apps/host/registrations.ts b/src/renderer/src/apps/host/registrations.ts
new file mode 100644
index 00000000..2e29cc10
--- /dev/null
+++ b/src/renderer/src/apps/host/registrations.ts
@@ -0,0 +1,59 @@
+import type { Disposable, ViewMount } from '@renderer/apps/host/moduleContract'
+
+/**
+ * Where an activated extension's handlers live.
+ *
+ * WHY a host-owned store rather than letting each extension keep its own: the
+ * palette invokes a command by id long after activation, and the view host
+ * renders by id on demand. Both need a lookup that outlives the call to
+ * `activate()` and that the host — not the extension — controls the lifetime of.
+ *
+ * Keyed by extension id first so `disposeAll(extensionId)` is a single map
+ * delete. An extension being removed must not leave handlers behind that a stale
+ * palette entry could still reach.
+ */
+export class ExtensionRegistrations {
+  private commands = new Map<string, Map<string, () => void | Promise<void>>>()
+  private views = new Map<string, Map<string, ViewMount>>()
+
+  registerCommand(
+    extensionId: string,
+    commandId: string,
+    run: () => void | Promise<void>,
+  ): Disposable {
+    const forExtension = this.commands.get(extensionId) ?? new Map()
+    forExtension.set(commandId, run)
+    this.commands.set(extensionId, forExtension)
+    return {
+      dispose: () => {
+        // Guarded by identity: a late dispose from a stale closure must not
+        // remove a handler that a subsequent re-activation registered.
+        if (forExtension.get(commandId) === run) forExtension.delete(commandId)
+      },
+    }
+  }
+
+  registerView(extensionId: string, viewId: string, mount: ViewMount): Disposable {
+    const forExtension = this.views.get(extensionId) ?? new Map()
+    forExtension.set(viewId, mount)
+    this.views.set(extensionId, forExtension)
+    return {
+      dispose: () => {
+        if (forExtension.get(viewId) === mount) forExtension.delete(viewId)
+      },
+    }
+  }
+
+  getCommand(extensionId: string, commandId: string): (() => void | Promise<void>) | undefined {
+    return this.commands.get(extensionId)?.get(commandId)
+  }
+
+  getView(extensionId: string, viewId: string): ViewMount | undefined {
+    return this.views.get(extensionId)?.get(viewId)
+  }
+
+  disposeAll(extensionId: string): void {
+    this.commands.delete(extensionId)
+    this.views.delete(extensionId)
+  }
+}
diff --git a/src/renderer/src/apps/host/viewBridge.tsx b/src/renderer/src/apps/host/viewBridge.tsx
new file mode 100644
index 00000000..cd9e1cc5
--- /dev/null
+++ b/src/renderer/src/apps/host/viewBridge.tsx
@@ -0,0 +1,106 @@
+import { useEffect, useRef, useState } from 'react'
+
+import type { AgentCodeApiV1 } from '@renderer/apps/api/types'
+import type { ExtensionHost } from '@renderer/apps/host/ExtensionHost'
+import type { ExtensionListEntry } from '@shared/types/extensions'
+
+/**
+ * Adapts a contributed view into the `AppDefinition.Component` shape.
+ *
+ * This component is the ENTIRE bridge 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 a
+ * child-side bootstrap would call over there.
+ *
+ * WHY it activates on render rather than requiring the extension to be already
+ * loaded: this is `onView:` activation. The palette can open a view whose module
+ * has never been imported, and the import happens here, once, while the dialog
+ * shows a loading state.
+ */
+export function viewComponentFor(
+  host: ExtensionHost,
+  entry: ExtensionListEntry,
+  viewId: string,
+): (props: { api: AgentCodeApiV1 }) => JSX.Element {
+  return function ExtensionView() {
+    const containerRef = useRef<HTMLDivElement | null>(null)
+    const [status, setStatus] = useState<'loading' | 'ready' | 'failed'>(
+      host.isActivated(entry.manifest.id) ? 'ready' : 'loading',
+    )
+    const [error, setError] = useState<string | null>(null)
+
+    useEffect(() => {
+      let cancelled = false
+      let cleanup: void | (() => void)
+
+      const run = async () => {
+        await host.activate(entry)
+        if (cancelled) return
+
+        const mount = host.getView(entry.manifest.id, viewId)
+        if (!mount) {
+          // Activated but the view was never registered — either activate()
+          // failed (its message is already in host.getFailures()) or the author
+          // declared a view and forgot to register it.
+          const failure = host.getFailures().find(f => f.id === entry.manifest.id)
+          setError(failure?.error ?? `view "${viewId}" was declared but never registered`)
+          setStatus('failed')
+          return
+        }
+
+        const element = containerRef.current
+        if (!element) return
+
+        try {
+          cleanup = mount(element)
+          setStatus('ready')
+        } catch (mountError) {
+          // 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.
+          setError(mountError instanceof Error ? mountError.message : String(mountError))
+          setStatus('failed')
+        }
+      }
+
+      void run()
+
+      return () => {
+        cancelled = true
+        try {
+          cleanup?.()
+        } catch {
+          // A throwing cleanup leaks whatever it leaks; the host must still
+          // unmount. Deliberately silent — the extension is already broken and
+          // a second error here would only obscure the first.
+        }
+        // Belt and braces: an extension that rendered into the element without
+        // returning a disposer would otherwise leave its DOM behind for the next
+        // mount to render on top of.
+        containerRef.current?.replaceChildren()
+      }
+      // Intentionally mount-once. `entry` and `viewId` are fixed for the lifetime
+      // of this component (a different view is a different component), and
+      // re-running would tear down and remount a live extension view.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [])
+
+    return (
+      <div className="relative min-h-[120px]">
+        {status === 'loading' ? (
+          <div className="px-6 py-8 text-[12px] text-muted">Loading {entry.manifest.name}…</div>
+        ) : null}
+        {status === 'failed' ? (
+          <div className="px-6 py-8">
+            <div className="text-[13px] text-ink">{entry.manifest.name} failed to start</div>
+            <div className="mt-1 text-[12px] text-muted">{error}</div>
+          </div>
+        ) : null}
+        {/* Always mounted, even while loading: the ref has to exist before the
+            async activation resolves, or mount() would have nothing to render
+            into and the view would silently stay blank. */}
+        <div ref={containerRef} style={{ display: status === 'ready' ? 'block' : 'none' }} />
+      </div>
+    )
+  }
+}
diff --git a/src/renderer/src/apps/registry.ts b/src/renderer/src/apps/registry.ts
deleted file mode 100644
index c5e24699..00000000
--- a/src/renderer/src/apps/registry.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-import type { AppDefinition } from '@renderer/apps/types'
-
-// The built-in app registry.
-//
-// Adding an app = ONE import + ONE array entry, matching the contract
-// `app/surfaces/registry.tsx` and `features/command-palette/registry.ts` already
-// use. An explicit import list is greppable and compiler-checked; side-effect
-// self-registration is neither, and makes module load order load-bearing — which is
-// exactly the class of bug the surface registry's #505 comment records.
-//
-// Stage 2 note: this becomes `[...BUILTIN_APPS, ...loadedApps]` where the second
-// half comes from a manifest loader. Nothing else under `apps/` needs to change for
-// that — `APP_BY_ID`, the host surface, and the derived commands all consume this
-// array and do not care where its entries came from. That is the whole point of
-// keeping `AppDefinition` serializable-plus-one.
-// Empty on purpose. Extensions are INSTALLED, not compiled in — nothing ships in
-// this array. It exists as the resolution target the loader fills at runtime, and
-// as the seam a first-party built-in could use if one is ever justified.
-export const APPS: AppDefinition[] = []
-
-// Lookup for the host surface. Built once at module scope rather than per render:
-// the array is static in Stage 1, and in Stage 2 the loader will rebuild both
-// together. If this ever needs to be dynamic, change both in the same commit —
-// a stale map against a live array is a silently-missing app.
-export const APP_BY_ID = new Map<string, AppDefinition>(APPS.map(app => [app.id, app]))
diff --git a/src/renderer/src/apps/surfaces/AppHostSurface.tsx b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
index 6883e477..6ff29c4e 100644
--- a/src/renderer/src/apps/surfaces/AppHostSurface.tsx
+++ b/src/renderer/src/apps/surfaces/AppHostSurface.tsx
@@ -1,67 +1,89 @@
-import { useCallback } from 'react'
+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 { useExtensionHost } from '@renderer/apps/host/ExtensionHostProvider'
 import { Dialog, DialogContent, DialogTitle } from '@renderer/components/ui/dialog'
+import { useGlobalToast } from '@renderer/ui/GlobalToast'
 
-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.
+ * 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 app's input can leak Enter and paste into a
- * background agent composer, and a native menu click can mutate the workspace
- * underneath the app. `components/ui/README.md` records that exact failure from the
- * old hand-rolled composer guards. Hosting apps inside the primitive means an app
- * gets all seven protections for free and physically cannot forget one.
- *
- * WHY the inner component: `useAppHostApi` is a hook, so it cannot be called after
- * the `if (!app) return null` guard. Splitting keeps the guard first and the hook
- * unconditional, which is the only arrangement React permits.
+ * 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 app = openAppId ? APP_BY_ID.get(openAppId) : undefined
+  const installed = useAppStore(state => state.installedExtensions)
+  const host = useExtensionHost()
+
+  // 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(
+    () => (host ? deriveAppDefinitions(host, installed) : []),
+    [host, installed],
+  )
+
+  const definition = openAppId
+    ? definitions.find(candidate => candidate.id === openAppId)
+    : undefined
 
-  // An unknown id degrades to closed. This is a deliberate contrast with
+  // 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
-  // and must be loud. It would be wrong here for two reasons: `openAppId` can hold
-  // a stale id after an app is removed from the registry (and in Stage 2, after an
-  // app is uninstalled), and this surface is mounted unconditionally by App.tsx, so
-  // throwing inside it takes down the entire renderer — the #249 black-screen
-  // failure mode, reached from data rather than from a persist-version mistake.
-  if (!app) return null
+  // 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 <OpenApp app={app} />
+  return <OpenExtensionView definition={definition} />
 }
 
-function OpenApp({ app }: { app: AppDefinition }) {
+function OpenExtensionView({ definition }: { definition: AppDefinition }) {
   const closeApp = useAppStore(state => state.closeApp)
-  const onClose = useCallback(() => {
-    closeApp()
-  }, [closeApp])
-  const api = useAppHostApi(app.id, onClose)
+  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={open => {
-        if (!open) closeApp()
-      }}
-    >
-      <DialogContent showCloseButton className="w-[min(560px,92vw)]">
+    <Dialog open onOpenChange={onOpenChange}>
+      <DialogContent showCloseButton className="w-[min(560px,92vw)] overflow-hidden">
         {/* Radix requires an accessible title on every Dialog; visually hidden
-            because an app owns its own header treatment. Omitting it logs a
-            console error and leaves the dialog unlabelled for screen readers. */}
-        <DialogTitle className="sr-only">{app.title}</DialogTitle>
-        <app.Component api={api} />
+            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/ui/AppsSettingsRow.tsx b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
index bbd37ca5..93276650 100644
--- a/src/renderer/src/apps/ui/AppsSettingsRow.tsx
+++ b/src/renderer/src/apps/ui/AppsSettingsRow.tsx
@@ -1,5 +1,7 @@
 import { useCallback, useEffect, useState } from 'react'
 
+import { useAppStore } from '@renderer/app-state/hooks'
+
 import type { ExtensionListEntry } from '@shared/types/extensions'
 
 /**
@@ -26,16 +28,24 @@ export function AppsSettingsRow() {
   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 {
-      setEntries(await window.api.extensionsList())
+      const listed = await window.api.extensionsList()
+      setEntries(listed)
+      setInstalledExtensions(listed)
     } 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.
       setEntries([])
       setError(listError instanceof Error ? listError.message : String(listError))
     }
-  }, [])
+  }, [setInstalledExtensions])
 
   useEffect(() => {
     void refresh()
@@ -145,11 +155,23 @@ export function AppsSettingsRow() {
                   {!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">
                   {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
diff --git a/src/renderer/src/features/command-palette/registry.ts b/src/renderer/src/features/command-palette/registry.ts
index ca4f54a0..c133da48 100644
--- a/src/renderer/src/features/command-palette/registry.ts
+++ b/src/renderer/src/features/command-palette/registry.ts
@@ -13,7 +13,6 @@ import { promptTemplateCommands } from '@renderer/features/prompt-templates/comm
 import { agentStatusCommands } from '@renderer/features/agent-status/commands/agentStatusCommands'
 import { remoteCommands } from '@renderer/features/remote/commands/remoteCommands'
 import { usageCommands } from '@renderer/features/usage/commands/usageCommands'
-import { appCommands } from '@renderer/apps/commands/appCommands'
 import { commandAllowedByRenderedViewPolicy } from '@renderer/workspace/agentDisplayMode'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 import type {
@@ -24,7 +23,15 @@ import type {
   ResolvedCommand,
 } from '@renderer/features/command-palette/types'
 
-const commandDefs: CommandDef[] = [
+// First-party commands. Static, because they ship with the app and cannot change
+// at runtime.
+//
+// Extension commands are NOT here — they are derived from installed manifests and
+// concatenated per call (see allCommandDefs below). An earlier version of this
+// file spread a frozen `appCommands` array in at module scope, which meant
+// installing an extension could not add a command without a reload. That was one
+// of eight module-scope snapshots an adversarial audit found.
+const builtInCommandDefs: CommandDef[] = [
   ...tabCommands,
   ...paneCommands,
   ...layoutCommands,
@@ -44,12 +51,6 @@ const commandDefs: CommandDef[] = [
   ...agentStatusCommands,
   ...remoteCommands,
   ...usageCommands,
-  // Derived from the built-in app registry — one command per app, so an app
-  // cannot ship without an opener. Last so apps browse after first-party
-  // commands in the empty-query list; registry order is the palette's browse
-  // order and reshuffling it reads as a regression to anyone who navigates by
-  // position.
-  ...appCommands,
 ]
 
 /**
@@ -121,8 +122,26 @@ function renderedViewAvailable(command: CommandDef, ctx: CommandContext): boolea
   })
 }
 
-export function buildCommandRegistry(ctx: CommandContext): ResolvedCommand[] {
-  return commandDefs
+/**
+ * Every command available right now: first-party 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[]): CommandDef[] {
+  return extensionCommands.length === 0
+    ? builtInCommandDefs
+    : [...builtInCommandDefs, ...extensionCommands]
+}
+
+export function buildCommandRegistry(
+  ctx: CommandContext,
+  extensionCommands: readonly CommandDef[] = [],
+): ResolvedCommand[] {
+  return allCommandDefs(extensionCommands)
     .filter(
       command =>
         surfaceAvailable(command.surface, ctx) &&
@@ -176,8 +195,10 @@ export type PickerCommandMeta = {
  * id is a stable, recognizable stand-in for a settings row and avoids
  * inventing a dummy context purely for a display string.
  */
-export function listPickerCommandMeta(): PickerCommandMeta[] {
-  return commandDefs.map(command => ({
+export function listPickerCommandMeta(
+  extensionCommands: readonly CommandDef[] = [],
+): PickerCommandMeta[] {
+  return allCommandDefs(extensionCommands).map(command => ({
     id: command.id,
     title: typeof command.title === 'function' ? command.id : command.title,
     pickerVisibility: command.pickerVisibility ?? 'default',
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 9e825a5b..16a466f3 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -47,6 +47,8 @@ import type {
   PromptTemplateVariableValueMap,
 } from '@renderer/features/prompt-templates/types'
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
+import { deriveExtensionCommands } from '@renderer/apps/host/derive'
+import { useExtensionHost } from '@renderer/apps/host/ExtensionHostProvider'
 import { resolveAgentPaneLabel } from '@renderer/workspace/tile-tree/paneLabels'
 import { useWorkspaceContext } from '@renderer/workspace/WorkspaceContext'
 import { useAppStore } from '@renderer/app-state/hooks'
@@ -650,7 +652,21 @@ 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 extensionHost = useExtensionHost()
+  const extensionCommands = useMemo(
+    () =>
+      extensionHost ? deriveExtensionCommands(extensionHost, installedExtensions, openApp) : [],
+    [extensionHost, installedExtensions, openApp],
+  )
+
+  const commands = useMemo(
+    () => buildCommandRegistry(commandContext, extensionCommands),
+    [commandContext, extensionCommands],
+  )
 
   const promptTemplates = useMemo(
     () => allPromptTemplates(customPromptTemplates),

From 240f41943bc3a7bcd14730bf297054bb72e2f134 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 15:14:27 +0200
Subject: [PATCH 16/18] docs: extension authoring guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Manifest reference, the activate/deactivate contract, the DOM-level view mount,
the React-from-host requirement, build output rules, the Tier 0 API, theming,
publishing, and a failure-mode table keyed by the exact error strings the host
produces.

Includes a section on what v1 deliberately does NOT have — no agent access, no
process isolation, no marketplace, modal-only views — because each is a decision
with a reason, and an author who hits one should find the reasoning rather than
assume it was forgotten.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/extensions/authoring.md | 305 +++++++++++++++++++++++++++++++++++
 1 file changed, 305 insertions(+)
 create mode 100644 docs/extensions/authoring.md

diff --git a/docs/extensions/authoring.md b/docs/extensions/authoring.md
new file mode 100644
index 00000000..53735ca8
--- /dev/null
+++ b/docs/extensions/authoring.md
@@ -0,0 +1,305 @@
+# Writing an Agent Code extension
+
+> **Status:** live. API version **1**.
+>
+> Reference implementation: [`Juliusolsson05/agent-code-timer`](https://github.com/Juliusolsson05/agent-code-timer).
+> It exercises every part of this document — declarations, lazy activation, a
+> view, persisted state, theming, and background work.
+
+An extension is a **GitHub repository** containing a manifest and a built ES
+module. Agent Code downloads it, validates it, and loads it at runtime. Nothing
+is compiled into the app.
+
+```
+Settings → Extensions → owner/repo → Install
+```
+
+---
+
+## 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",
+
+  "activationEvents": ["onStartupFinished"],
+
+  "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 and your storage namespace. **Permanent** — renaming orphans user data. |
+| `apiVersion` | Must match the host. v1 today; 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. |
+
+### Why contributions are declared
+
+The palette and Settings need to know what your extension offers **before it has
+been loaded**. That is what makes lazy activation possible — a command can be
+listed and invoked while your module has never been imported. Without
+declarations, every installed extension would have to be imported at startup just
+to populate a command list.
+
+It also means a *broken* extension still shows what it contributes, with the
+failure reason next to it, instead of silently vanishing.
+
+### Activation events
+
+| Event | Fires |
+|---|---|
+| `onCommand:<id>` | when one of your declared commands is invoked |
+| `onView:<id>` | when one of your declared views is opened |
+| `onStartupFinished` | once, after the window is interactive |
+| `*` | immediately at startup — **avoid**; it makes every launch pay for you |
+
+Use `onStartupFinished` only if you genuinely need to run without a window — a
+timer that keeps counting, a watcher reacting to events. Otherwise prefer
+`onCommand:`/`onView:` so you cost nothing until used.
+
+---
+
+## 2. The module
+
+Your `entry` must export `activate`, and may export `deactivate`.
+
+```ts
+export function activate(context: ExtensionContext): void | Promise<void> {
+  context.subscriptions.push(
+    context.registerCommand('timer.start', () => { /* … */ }),
+    context.registerView('timer.main', element => {
+      element.textContent = 'hello'
+      return () => { /* cleanup on close */ }
+    }),
+  )
+}
+
+export function deactivate(): void { /* 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.
+- **Everything in `subscriptions` is disposed on deactivate**, in reverse order.
+- **A view mount returns its own cleanup.** It runs when the view closes.
+
+### Views are DOM-level
+
+```ts
+type ViewMount = (element: HTMLElement) => void | (() => void)
+```
+
+You get an empty element. Do whatever you like inside it. React is optional:
+
+```tsx
+import { createRoot } from 'react-dom/client'
+
+context.registerView('timer.main', element => {
+  const root = createRoot(element)
+  root.render(<App />)
+  return () => queueMicrotask(() => root.unmount())
+})
+```
+
+This is DOM-level rather than "export a React component" for two reasons: it keeps
+React optional (plain DOM, Preact, Svelte, canvas all work), and it is the one
+shape that survives extensions later moving into an iframe — a component
+reference cannot cross a frame boundary, but "call mount with this element" can.
+
+---
+
+## 3. React must come from the host
+
+**You cannot bundle your own React.** Two React instances in one document means
+two reconcilers, and every hook throws *invalid hook call*.
+
+Agent Code publishes its runtime on `globalThis.__agentCodeHost`. Alias the
+specifiers to shims that read it:
+
+```ts
+// vite.config.ts
+resolve: {
+  alias: [
+    { find: /^react$/,               replacement: resolve(__dirname, 'src/host/react.ts') },
+    { find: /^react\/jsx-runtime$/,  replacement: resolve(__dirname, 'src/host/jsx-runtime.ts') },
+    { find: /^react-dom\/client$/,   replacement: resolve(__dirname, 'src/host/react-dom-client.ts') },
+  ],
+}
+```
+
+```ts
+// src/host/react.ts
+const react = globalThis.__agentCodeHost.react
+export default react
+export const { useState, useEffect, useRef, useMemo, useCallback /* … */ } = react
+```
+
+Copy these four files from
+[agent-code-timer/src/host/](https://github.com/Juliusolsson05/agent-code-timer/tree/main/src/host).
+
+**Why aliasing and not `external: ['react']`:** marking it external leaves a bare
+`react` specifier in the output, and a browser cannot resolve a bare specifier
+without an import map — which would have to be declared by the host before its own
+first module loads. Aliasing resolves it at *your* build time and needs nothing
+from the host beyond the global. Any dependency that imports react
+(framer-motion does) gets the alias for free.
+
+---
+
+## 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 a file that does not exist"*.
+
+```ts
+build: {
+  lib: { entry: 'src/index.ts', formats: ['es'], fileName: () => 'index.js' },
+  rollupOptions: { output: { inlineDynamicImports: true } },
+  cssCodeSplit: false,
+}
+```
+
+**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 fetches
+exactly one file — a stylesheet nothing requests silently never applies. Import
+it `?inline` and inject a `<style>` tag yourself.
+
+---
+
+## 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.
+
+```ts
+api.extension.id                     // your id
+api.storage.get/set/delete/keys      // your own namespace, persisted
+api.ui.close()                       // close your view
+api.ui.showToast(message)            // app-wide toast
+api.theme.tokens()                   // resolved --theme-* values
+```
+
+That is the whole of API v1 — **Tier 0**, everything an extension may have
+without asking. Workspace, session, transcript, git, filesystem and network
+access are Tiers 1–3: they need a capability model and a consent flow that do not
+exist yet, and guessing their contracts before a real consumer needs them would
+be worse than adding them late.
+
+### 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`.
+- 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.
+
+---
+
+## 6. Theming
+
+Agent Code exposes its palette as `--theme-*` custom properties. 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`.
+
+Prefer CSS over `api.theme.tokens()` — it cascades for free and keeps working
+across a frame boundary. The accessor exists for imperative consumers (canvas,
+computed SVG fills).
+
+**Only the `--theme-*` layer is contract.** The `--color-*` Tailwind bindings are
+an implementation detail of how the app wires its utilities; depending on them
+couples you to the host's build system.
+
+---
+
+## 7. 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.
+
+The installer records the resolved ref and a **SHA-256 of the tarball**, so
+"which bytes am I running" stays answerable.
+
+---
+
+## 8. 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 a file that does not exist"* | `dist/` not committed |
+| *"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 |
+| *invalid hook call* | you bundled React instead of aliasing to the host |
+| renders unstyled | CSS emitted as a sibling file instead of inlined |
+| *"targets Agent Code API v2, this build implements v1"* | Agent Code is older than your extension |
+
+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.
+
+---
+
+## 9. What v1 deliberately does not have
+
+Recorded so you know these are decisions, not oversights:
+
+- **No agent/session access.** Reading transcripts or sending prompts is Tier 1–3
+  and needs enforceable per-extension identity, which same-realm loading cannot
+  provide.
+- **No process isolation.** An extension shares the renderer. An infinite loop in
+  your code hangs the app. The threat model here is *"I made a mistake"*, not
+  *"someone is attacking me"* — extensions come from repositories you chose. That
+  changes if extensions ever come from strangers, and the DOM-level view contract
+  is what keeps the iframe door open.
+- **No marketplace.** The repo name is the trust decision.
+- **`mount: 'modal'` only.** `panel` and `tab` are the same registration with a
+  different host shell.

From 2f65ee96e804622aaf7322b1de897ff0562c9a91 Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 15:29:32 +0200
Subject: [PATCH 17/18] docs(extensions): the process.env.NODE_ENV gotcha
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Vite's library mode does not replace process.env.NODE_ENV, and the output runs
in a renderer with nodeIntegration:false where `process` does not exist. Nearly
every React-ecosystem package guards dev warnings with it, so the first guard to
execute throws — AFTER the extension installs and imports cleanly, which makes
it look like the author's code rather than their build config.

The reference timer hit this on its first real run in the app. Documented with
the fix, the reason not to shim a global `process` instead, and an entry in the
failure-mode table keyed to the exact error string.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 docs/extensions/authoring.md | 25 ++++++++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/docs/extensions/authoring.md b/docs/extensions/authoring.md
index 53735ca8..060f11ff 100644
--- a/docs/extensions/authoring.md
+++ b/docs/extensions/authoring.md
@@ -184,9 +184,31 @@ 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 renderer with
+`nodeIntegration: false`, 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.
+
+The reference timer hit this on its first real run. framer-motion ships eight of
+those guards.
+
 **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 fetches
 exactly one file — a stylesheet nothing requests silently never applies. Import
@@ -278,6 +300,7 @@ The installer records the resolved ref and a **SHA-256 of the tarball**, so
 | *"manifest points at a file that does not exist"* | `dist/` not committed |
 | *"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 |
+| *"process is not defined"* | missing `define: { 'process.env.NODE_ENV': … }` — see §4 |
 | *invalid hook call* | you bundled React instead of aliasing to the host |
 | renders unstyled | CSS emitted as a sibling file instead of inlined |
 | *"targets Agent Code API v2, this build implements v1"* | Agent Code is older than your extension |

From 5e2b20ae6af6a72db7b90dd4776c9fa123c2ab5f Mon Sep 17 00:00:00 2001
From: Julius Olsson <julius.olsson05@gmail.com>
Date: Mon, 20 Jul 2026 15:34:24 +0200
Subject: [PATCH 18/18] fix(extensions): empty view under StrictMode, and
 un-retryable failed imports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three bugs, all found by actually running it. The symptom was an empty modal
with no error anywhere.

1. PER-MOUNT ELEMENT. React.StrictMode runs effects mount -> cleanup -> mount.
An extension whose disposer defers its unmount — queueMicrotask,
requestAnimationFrame, a transition — tears down root #1 AFTER root #2 has
rendered into the same node, and root1.unmount() empties the element root2 lives
in. The view mounts "successfully" and shows nothing. The timer extension defers
exactly this way, which is how it surfaced.

Each mount now gets its own child element, discarded on cleanup, so a late
disposer operates on a detached node it cannot reach anything through. That
makes the host immune to extension cleanup timing rather than requiring every
extension to get it right.

2. NO SILENT EARLY RETURN. `if (!element) return` left status at whatever it
started as — and when the extension already activated at startup that is
'ready', producing a visible empty view with nothing logged. Any exit from the
mount path now sets a status.

3. CACHE-BUSTED IMPORT URL. The ES module registry caches by URL and caches
FAILURES: once import(url) rejects, every later import of that URL returns the
same rejection for the life of the realm, even after the file on disk is
replaced. So an extension that failed once could never be fixed by reinstalling
— the user updates it, sees the identical error, and has no signal that their
fix landed. Reloading the window was the only escape and nothing said so.

The key is version + the installer's sha256, which changes exactly when the
bytes change. The query never reaches the filesystem: the scheme handler builds
its path from url.pathname, which excludes the search string.

typecheck / 1187 tests / build green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/renderer/src/apps/host/ExtensionHost.ts | 16 ++++++-
 src/renderer/src/apps/host/viewBridge.tsx   | 47 ++++++++++++++++++---
 2 files changed, 56 insertions(+), 7 deletions(-)

diff --git a/src/renderer/src/apps/host/ExtensionHost.ts b/src/renderer/src/apps/host/ExtensionHost.ts
index 1304b584..145a86ec 100644
--- a/src/renderer/src/apps/host/ExtensionHost.ts
+++ b/src/renderer/src/apps/host/ExtensionHost.ts
@@ -70,7 +70,21 @@ export class ExtensionHost {
 
     const run = (async () => {
       try {
-        const url = `agent-code-ext://${id}/${entry.manifest.entry}`
+        // The version+sha query is a CACHE KEY, not decoration.
+        //
+        // The ES module registry caches by URL, and it caches FAILURES too: once
+        // `import(url)` rejects, every later import of that exact URL returns the
+        // same rejection for the life of the realm — even after the file on disk
+        // has been replaced. Without this, an extension that fails once can never
+        // be fixed by reinstalling; the user updates it, sees the identical error,
+        // and has no way to tell that their fix did land. Reloading the window is
+        // the only escape, and nothing tells them that.
+        //
+        // The sha is already the installer's integrity record, so it changes
+        // exactly when the bytes change — which is precisely the condition under
+        // which the module must be re-evaluated.
+        const cacheKey = `${entry.manifest.version}-${entry.sha256.slice(0, 12)}`
+        const url = `agent-code-ext://${id}/${entry.manifest.entry}?v=${cacheKey}`
         const module = (await import(/* @vite-ignore */ url)) as ExtensionModule
 
         if (typeof module.activate !== 'function') {
diff --git a/src/renderer/src/apps/host/viewBridge.tsx b/src/renderer/src/apps/host/viewBridge.tsx
index cd9e1cc5..e247fb60 100644
--- a/src/renderer/src/apps/host/viewBridge.tsx
+++ b/src/renderer/src/apps/host/viewBridge.tsx
@@ -48,13 +48,47 @@ export function viewComponentFor(
           return
         }
 
-        const element = containerRef.current
-        if (!element) return
+        const container = containerRef.current
+        if (!container) {
+          // Must set a status. An early return here leaves whatever the initial
+          // state was — and when the extension activated at startup that initial
+          // state is 'ready', producing a visible, EMPTY view with no error
+          // anywhere. That is exactly how this failed the first time it ran.
+          setError('view container was not mounted')
+          setStatus('failed')
+          return
+        }
+
+        // Each mount gets its OWN child element, thrown away on cleanup.
+        //
+        // WHY not just hand over the stable container: React.StrictMode runs
+        // effects mount -> cleanup -> mount. An extension whose cleanup defers
+        // its unmount (queueMicrotask, requestAnimationFrame, a transition) then
+        // tears down root #1 AFTER root #2 has already rendered into the same
+        // node — and root1.unmount() empties the element root2 is living in. The
+        // result is a view that mounted successfully and shows nothing, with no
+        // error to find. The timer extension does exactly this, which is how the
+        // bug surfaced.
+        //
+        // A per-mount element makes the host immune to that entirely: a late
+        // disposer operates on a node that is already detached and unreachable,
+        // and it cannot touch the live one. This costs one div and removes a
+        // whole class of extension-timing bug the host cannot otherwise control.
+        const element = document.createElement('div')
+        container.append(element)
 
         try {
-          cleanup = mount(element)
+          const disposer = mount(element)
+          cleanup = () => {
+            try {
+              disposer?.()
+            } finally {
+              element.remove()
+            }
+          }
           setStatus('ready')
         } catch (mountError) {
+          element.remove()
           // 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.
@@ -74,9 +108,10 @@ export function viewComponentFor(
           // unmount. Deliberately silent — the extension is already broken and
           // a second error here would only obscure the first.
         }
-        // Belt and braces: an extension that rendered into the element without
-        // returning a disposer would otherwise leave its DOM behind for the next
-        // mount to render on top of.
+        // Belt and braces: an extension that rendered into its element without
+        // returning a disposer leaves DOM behind, and a deferred disposer may
+        // still be pending. Clearing the CONTAINER (not the per-mount element)
+        // is safe because the next mount creates its own child.
         containerRef.current?.replaceChildren()
       }
       // Intentionally mount-once. `entry` and `viewId` are fixed for the lifetime