feat: add Host Adapter contract and Codex DOM foundation

README.md

@@ -1,12 +1,13 @@
 # Codex Git
 
-Codex Git is a planned local Git surface for Codex Desktop. This repository currently contains only the initial application scaffold; Worktree discovery, Git commands, Codex injection, packaging, and other product features are not implemented.
+Codex Git is a planned local Git surface for Codex Desktop. This repository contains the initial application scaffold and Host Adapter boundary; Worktree discovery, Git commands, packaging, and other product features are not implemented.
 
 ## Product and architecture
 
 - [Domain language](./CONTEXT.md)
 - [macOS MVP product requirements](./docs/product/mvp-prd.md)
 - [MVP technical architecture](./docs/architecture/mvp-technical-architecture.md)
+- [Codex Host Adapter compatibility and trust boundary](./docs/host-integration/codex-compatibility.md)
 - Architecture decisions:
   - [Isolate Codex host integration behind a Host Adapter](./docs/adr/0001-isolate-codex-host-integration.md)
   - [Use the system Git CLI behind a local Repository Engine](./docs/adr/0002-use-system-git-behind-repository-engine.md)
@@ -51,7 +52,7 @@ apps/ui                        Standalone React placeholder surface
 packages/protocol              Shared protocol types
 packages/repository-engine     Repository session boundary only
 packages/host-adapter          Host Adapter boundary
-packages/host-adapter/*        Codex CDP and standalone adapter placeholders
+packages/host-adapter/*        Codex CDP/DOM and standalone Host Adapters
 tests/                         Contract, integration, end-to-end, and fixture layers
 ```
 

apps/launcher/package.json

@@ -6,6 +6,7 @@
   "exports": "./src/index.ts",
   "types": "./src/index.ts",
   "dependencies": {
+    "@codex-git/host-adapter": "*",
     "@codex-git/host-adapter-standalone": "*",
     "@codex-git/server": "*"
   },

apps/launcher/src/standalone-runtime.ts

@@ -1,6 +1,7 @@
 import type { Server } from 'node:http';
 import { fileURLToPath } from 'node:url';
 
+import type { HostConnection } from '@codex-git/host-adapter';
 import { createAppServer } from '@codex-git/server';
 import { StandaloneHostAdapter } from '@codex-git/host-adapter-standalone';
 import { createServer as createViteServer, type ViteDevServer } from 'vite';
@@ -26,13 +27,11 @@ export async function startStandaloneRuntime(
 ): Promise<StandaloneRuntime> {
   const healthServer = createAppServer();
   let surfaceServer: ViteDevServer | undefined;
-  let hostConnection: Awaited<
-    ReturnType<StandaloneHostAdapter['attach']>
-  > | null = null;
+  let hostConnection: HostConnection | null = null;
 
   async function closeResources(): Promise<void> {
     await Promise.all([
-      hostConnection?.dispose(),
+      hostConnection?.close(),
       surfaceServer?.close(),
       closeServer(healthServer),
     ]);
@@ -53,10 +52,11 @@ export async function startStandaloneRuntime(
     await surfaceServer.listen();
 
     const surfaceUrl = serverUrl(surfaceServer.httpServer, '/');
-    hostConnection = await new StandaloneHostAdapter().attach({
+    const hostResult = await new StandaloneHostAdapter().attach({
       title: 'Codex Git',
       url: surfaceUrl,
     });
+    hostConnection = hostResult.connection;
 
     let closed = false;
 

docs/host-integration/codex-compatibility.md

@@ -0,0 +1,67 @@
+# Codex Host Adapter compatibility
+
+The Codex Host Adapter is an unsupported local CDP/DOM integration. It is not an
+official Codex extension interface. The standalone Host Adapter remains the
+supported fallback whenever discovery, compatibility, attachment, or remounting
+cannot be proven safe.
+
+This foundation implements the typed Host Adapter contract, strict compatibility
+probe, DOM lifecycle, message boundary, and CSP lease primitive. Production CDP
+discovery and transport, dedicated-instance ownership binding, renderer and DOM
+replacement, launcher composition, fallback transitions, and manual smoke
+verification are tracked in [#30](https://github.com/codeacme17/codex-git/issues/30).
+
+## Trust and ownership requirements
+
+Codex Git attaches only to a renderer selected through a loopback CDP endpoint
+owned by a dedicated Codex Git profile or instance. A renderer name, window
+title, route, or DOM resemblance is never ownership evidence. The renderer
+source must provide a non-empty stable target ID and the exact
+`codex-git-dedicated` ownership proof before the compatibility probe can mutate
+the document.
+
+Codex Desktop's Content Security Policy does not allow the loopback Git Surface
+as a frame. The dedicated renderer therefore grants a generation-scoped
+`Page.setBypassCSP` lease before mounting. The lease is released after any
+replacement, failed attachment, or connection close. Never grant this lease to
+a normal user-owned Codex window: bypassing CSP expands the effect of any script
+already executing in that renderer.
+
+CDP has no application-level authentication in this design. Treat access to the
+dedicated loopback debugging endpoint as trusted local-process authority. Do not
+bind it to a non-loopback interface, reuse a normal Codex profile, publish the
+endpoint, or record it in ordinary logs.
+
+## Tested profile
+
+| Codex Desktop                 | Chromium framework | Required anchors                                                | Evidence                                                                 |
+| ----------------------------- | ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `26.820.60940` (build `7119`) | `151.0.7922.170`   | `#app-shell-sidebar`; `[data-app-shell-main-surface="default"]` | Installed renderer bundle inspection plus automated DOM fixture coverage |
+
+The automated fixture covers read-only probing, fail-closed fallback,
+transactional attachment, one-entry mounting, native navigation, repeat
+attachment, context updates, opaque iframe sandboxing,
+generation/capability/challenge rejection, CSP lease restoration, and complete
+teardown.
+
+Any Codex version or DOM shape not listed here fails closed before mutation. A
+new version requires a new explicit profile and the same fixture and manual smoke
+matrix; do not widen selectors to make an unknown build appear compatible.
+
+## Pending manual smoke matrix
+
+Issue [#30](https://github.com/codeacme17/codex-git/issues/30) must run this
+matrix against a disposable dedicated profile with a loopback CDP endpoint and
+record the exact Codex and Chromium versions with the result.
+
+- Open `Git` and confirm exactly one entry and one full-page frame.
+- Select a native destination and confirm native content is restored with no
+  hidden overlay.
+- Open `Git` again after a renderer reload and confirm one new frame generation.
+- Change Current Project, theme, and task and confirm typed context updates.
+- Send missing, altered, replayed, and stale capability/challenge messages and
+  confirm they cause no action.
+- Close the connection and confirm all nodes, listeners, CDP sessions, and the
+  CSP bypass lease are gone.
+- Break either required selector and confirm the native UI remains byte-for-byte
+  unchanged while the standalone fallback is reported.