From 535facf9d75df7375746401222244b03434f9a1a Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 01:19:11 -0400
Subject: [PATCH 1/8] chore(harness): drive the e2e routes over the control
 socket

The snapshot route and the wizard-ci MCP server spawn the real binary with
`--ci --control-socket` in a PTY and drive it through the control API: the
run is released with POST /run, state is long polled, and every commit goes
through POST /actions. The in-process host, its store driver, and the action
registry are gone; the harness keeps the launcher, the detection picks, the
profiles, and the result payload. Harness tests run against the store's
ControlDriver and per-flow actions with unchanged goldens, and two process
specs exercise each surface end to end. Docs describe the API and the
launcher; the workbench environment contract is unchanged.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 .claude/skills/exploring-the-wizard/SKILL.md  |  61 +-
 docs/benchmarking.md                          | 167 ++--
 docs/local-dev.md                             | 115 +--
 e2e-harness/ARCHITECTURE.md                   | 286 ++++---
 .../__tests__/control-actions-parity.test.ts  |  54 --
 ...-driver.test.ts => control-driver.test.ts} |  59 +-
 .../__tests__/control-socket-headless.test.ts |  77 ++
 .../__tests__/control-socket-tui.test.ts      |  82 ++
 .../__tests__/e2e-flow-snapshot.test.ts       |   7 +-
 e2e-harness/__tests__/e2e-profile-ask.test.ts |  10 +-
 e2e-harness/__tests__/e2e-result.test.ts      |   4 +-
 .../__tests__/keyboard-equivalence.test.tsx   |   4 +-
 e2e-harness/__tests__/launch.test.ts          |  99 +++
 e2e-harness/action-registry.ts                | 402 ----------
 e2e-harness/e2e-profile.ts                    |  10 +-
 e2e-harness/e2e-result.ts                     |  33 +-
 e2e-harness/launch.ts                         | 109 +++
 e2e-harness/picks.ts                          | 101 +++
 e2e-harness/wizard-ci-driver.ts               | 220 -----
 scripts/README.md                             |  75 +-
 scripts/tui-host.no-jest.ts                   | 754 ------------------
 scripts/tui-snapshots.no-jest.ts              | 401 +++++++++-
 scripts/wizard-ci-mcp.no-jest.ts              | 144 ++--
 src/store/control/__tests__/state.test.ts     |  10 +-
 src/store/control/state.ts                    |   1 +
 src/store/control/types.ts                    |   1 +
 src/store/programs/index.ts                   |   1 +
 src/store/state/store-api.ts                  |   2 -
 28 files changed, 1343 insertions(+), 1946 deletions(-)
 delete mode 100644 e2e-harness/__tests__/control-actions-parity.test.ts
 rename e2e-harness/__tests__/{wizard-ci-driver.test.ts => control-driver.test.ts} (89%)
 create mode 100644 e2e-harness/__tests__/control-socket-headless.test.ts
 create mode 100644 e2e-harness/__tests__/control-socket-tui.test.ts
 create mode 100644 e2e-harness/__tests__/launch.test.ts
 delete mode 100644 e2e-harness/action-registry.ts
 create mode 100644 e2e-harness/launch.ts
 create mode 100644 e2e-harness/picks.ts
 delete mode 100644 e2e-harness/wizard-ci-driver.ts
 delete mode 100644 scripts/tui-host.no-jest.ts

diff --git a/.claude/skills/exploring-the-wizard/SKILL.md b/.claude/skills/exploring-the-wizard/SKILL.md
index 4310f08d1..23d64733f 100644
--- a/.claude/skills/exploring-the-wizard/SKILL.md
+++ b/.claude/skills/exploring-the-wizard/SKILL.md
@@ -9,7 +9,7 @@ compatibility:
   wizard-ci MCP server.
 metadata:
   author: posthog
-  version: '5.0'
+  version: '6.0'
 ---
 
 # Exploring the wizard as an agent
@@ -23,8 +23,8 @@ sequence, and gateway policy. For new exploration, launch the server with
 `SNAP_HARNESS=pi`; prefer `SNAP_SEQUENCE=orchestrator` for the integration flow.
 These are server environment variables, not MCP arguments. Restart an existing
 server to change its environment. See the
-[host architecture](../../../e2e-harness/ARCHITECTURE.md) for other programs,
-overrides, and current limitations.
+[harness architecture](../../../e2e-harness/ARCHITECTURE.md) for the control
+API, other programs, and overrides.
 
 ## Prepare the run
 
@@ -35,16 +35,14 @@ wizard, so finish recording one app before opening another.
 - **Detection only:** pass `appDir` and `projectId` (both required strings),
   with no key. Stop at `auth` without calling `run_agent`.
 - **Full integration:** reuse the authorized phx key file path, separate gateway
-  token file path, and project id;
-  ask only for missing inputs. Prefer `keyFile` so the key stays out of tool
-  arguments. Set `WIZARD_CI_GATEWAY_TOKEN_FILE` in the MCP server environment
-  before launch (restart an existing server); it is not an `open_app` argument.
-  The file must contain an already-issued gateway bearer, not the phx key.
-  CI does not mint or refresh it. Never print or commit either secret. See
-  [local credential setup](../../../docs/local-dev.md#credentials-for-local-ci-and-headless-runs). Read the
-  [credential and region limitations](../../../e2e-harness/ARCHITECTURE.md#current-host-limitations)
-  before starting: an inherited key can shadow `keyFile`, and the host currently
-  hardcodes the US region.
+  token file path, and project id; ask only for missing inputs. Prefer `keyFile`
+  so the key stays out of tool arguments. Set `WIZARD_CI_GATEWAY_TOKEN_FILE` in
+  the MCP server environment before launch (restart an existing server); it is
+  not an `open_app` argument. The file must contain an already-issued gateway
+  bearer, not the phx key. CI does not mint or refresh it. Never print or commit
+  either secret. See
+  [local credential setup](../../../docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
+  `region` selects the PostHog region for auth and the gateway.
 - **Questions during the run:** launch the server with `E2E_ASK=true` to keep
   `wizard_ask` available in this CI session. Handle questions yourself through
   the actions below; fixed-route answer profiles do not drive the MCP route.
@@ -79,31 +77,33 @@ own decisions through the same state and action contract.
    judging detection. Inspect `session.integration` and `setupQuestions`.
 2. Capture `render_screen` before each decision and during task or phase
    changes. Save numbered frames such as `/tmp/wz-explore-snaps/01-intro.txt`.
-3. Commit only actions currently offered. Common choices are below; the
-   [action registry](../../../e2e-harness/action-registry.ts) defines the full
-   set.
+3. Commit only actions currently offered. Common choices are below; the generic
+   set lives in
+   [`src/store/control/actions.ts`](../../../src/store/control/actions.ts) and a
+   program adds its own through `controlActions` on its steps.
 4. For a full run, confirm setup and call `run_agent` at `auth`. Continue
    reading state and handling overlays while it runs; polling alone cannot
    answer them.
 5. Check `runPhase` (`idle`, `running`, `completed`, `error`), background
    status, and the rendered outro. On error, capture the frame and reason before
    dismissing it. An error outro can wait for dismissal while `integration`
-   still says `running`; a host exit can instead surface as a socket error.
+   still says `running`; a wizard exit can instead surface as a socket error.
 6. After successful agent completion, finish the offered outro and follow-up
    actions. For the integration flow, `session.skillsComplete` marks the tail's
    completion. Other programs can have a terminal outro or exit screen.
 
-| Decision                                 | Action and `params`                                                                          |
-| ---------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Confirm intro / dismiss blocking outage  | `confirm_setup` / `dismiss_outage`                                                           |
-| Answer setup question                    | `choose`, `{ key, value }` from `setupQuestions`                                             |
-| Answer every question in a pending batch | `answer_question`, `{ answers: { questionId: value } }`; values are strings or string arrays |
-| Cancel a question batch                  | `cancel_question`                                                                            |
-| Accept or decline an optional task       | `resolve_notice`, `{ keep: true }` or `{ keep: false }`                                      |
-| Finish outro                             | `dismiss_outro`                                                                              |
-| Record MCP outcome                       | `set_mcp_outcome`, `{ outcome: "skipped" }` or `{ outcome: "installed", clients: [...] }`    |
-| Dismiss suggested prompts / Slack step   | `dismiss` / `dismiss_slack`                                                                  |
-| Record keep-skills choice                | `keep_skills`, `{ kept: true }` or `{ kept: false }`                                         |
+| Decision                                 | Action and `params`                                                                                              |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| Confirm intro / dismiss blocking outage  | `confirm_setup` / `dismiss_outage`                                                                               |
+| Answer setup question                    | `choose`, `{ key, value }` from `setupQuestions`                                                                 |
+| Answer every question in a pending batch | `answer_question`, `{ answers: { questionId: value } }`; values are strings or string arrays                     |
+| Cancel a question batch                  | `cancel_question`                                                                                                |
+| Accept or decline an optional task       | `resolve_notice`, `{ keep: true }` or `{ keep: false }`                                                          |
+| Finish outro                             | `dismiss_outro`                                                                                                  |
+| Record MCP outcome                       | `set_mcp_outcome`, `{ outcome: "skipped" }` or `{ outcome: "installed", clients: [...] }`                        |
+| Dismiss suggested prompts / Slack step   | `dismiss` / `dismiss_slack`                                                                                      |
+| Record keep-skills choice                | `keep_skills`, `{ kept: true }` or `{ kept: false }`                                                             |
+| Pick the project on a detect screen      | `pick_integration_target`, `{ path, integration }`; source maps: `pick_source_maps_project`, `{ variant, path }` |
 
 MCP and keep-skills actions commit store state; recording an outcome does not
 perform the corresponding installation or cleanup. Report which outcomes were
@@ -129,5 +129,6 @@ The shared log is `/tmp/posthog-wizard.log`. Record its byte count before a run
 and read from that count plus one afterward. Run sweeps serially so their logs
 remain attributable. `read_state` omits `frameworkContext`; an empty
 `setupQuestions` list alone does not prove a router mode. When necessary,
-inspect the detector under [`src/store/frameworks/`](../../../src/store/frameworks/) against
-the same fixture.
+inspect the detector under
+[`src/store/frameworks/`](../../../src/store/frameworks/) against the same
+fixture.
diff --git a/docs/benchmarking.md b/docs/benchmarking.md
index e5fadf4f7..17a4bc6e8 100644
--- a/docs/benchmarking.md
+++ b/docs/benchmarking.md
@@ -29,29 +29,29 @@ Selection criteria, checked in this order:
 1. **Real product, in production** — an open-source app people actually run
    (stars are a proxy; a hosted instance is better evidence).
 2. **Single-app repo** — reject monorepos: fetch the repo's top-level listing
-   and reject on `pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, or
-   top-level `apps/`/`packages/` directories.
+   and reject on `pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, or top-level
+   `apps/`/`packages/` directories.
 3. **Greenfield** — grep the repo for `posthog` (manifest and source). An app
    that already integrates PostHog measures augmentation discipline, not
    integration quality; keep at most one such app and exclude it from quality
    scoring.
 4. **Framework coverage** — spread picks across the frameworks the wizard
    supports; results do not transfer between them.
-5. **Locally installable** — its toolchain (node/python/php/ruby/gradle)
-   exists on the bench machine, or its runs will fail for reasons that are
-   yours, not the model's.
+5. **Locally installable** — its toolchain (node/python/php/ruby/gradle) exists
+   on the bench machine, or its runs will fail for reasons that are yours, not
+   the model's.
 
 Apps used in the 2026-07 benchmark, as worked examples of the spread:
 
-| app | upstream | stack |
-|---|---|---|
-| Maybe | `maybe-finance/maybe` | Rails |
-| Outline | `outline/outline` | React + Koa / TS |
-| WordPress-Android | `wordpress-mobile/WordPress-Android` | native Kotlin |
-| healthchecks | `healthchecks/healthchecks` | Django |
-| Firefly III | `firefly-iii/firefly-iii` | Laravel, server-rendered |
-| Monica | `monicahq/monica` | Laravel + Inertia/Vue |
-| Papermark | `mfts/papermark` | Next.js — already shipped posthog-js; kept as the augment-existing case, excluded from quality scoring |
+| app               | upstream                             | stack                                                                                                  |
+| ----------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------ |
+| Maybe             | `maybe-finance/maybe`                | Rails                                                                                                  |
+| Outline           | `outline/outline`                    | React + Koa / TS                                                                                       |
+| WordPress-Android | `wordpress-mobile/WordPress-Android` | native Kotlin                                                                                          |
+| healthchecks      | `healthchecks/healthchecks`          | Django                                                                                                 |
+| Firefly III       | `firefly-iii/firefly-iii`            | Laravel, server-rendered                                                                               |
+| Monica            | `monicahq/monica`                    | Laravel + Inertia/Vue                                                                                  |
+| Papermark         | `mfts/papermark`                     | Next.js — already shipped posthog-js; kept as the augment-existing case, excluded from quality scoring |
 
 ## Setup (from a bare machine)
 
@@ -90,21 +90,21 @@ Define each config as a `WIZARD_CI_FLAG_OVERRIDES` JSON, plus the baseline as
 Everything below ships in this repo (`wizard/`) and its workbench
 (`wizard-workbench/`); paths are from each repo's root.
 
-- **Headless run (snapshotting CI harness):** `wizard/scripts/tui-snapshots.no-jest.ts`
-  spawns the real TUI (`wizard/scripts/tui-host.no-jest.ts`) in a PTY via
+- **Headless run (snapshotting CI harness):**
+  `wizard/scripts/tui-snapshots.no-jest.ts` spawns the real wizard
+  (`bin.ts --ci --control-socket`) in a PTY via
   `wizard/e2e-harness/tui-capture.ts`, self-drives the fixed e2e profile
-  (`wizard/e2e-harness/wizard-ci-driver.ts`, `wizard/e2e-harness/profiles.ts`)
-  through auth, the agent run, and the outro, and writes each screen as an
-  `NN-<screen>.ans` frame. An `NN-outro.ans` frame is the flow-completion
-  signal. `tsx` runs source — no build step. Invocation: see the run-cell
-  recipe below.
+  (`wizard/e2e-harness/profiles.ts`) over the control socket through auth, the
+  agent run, and the outro, and writes each screen as an `NN-<screen>.ans`
+  frame. An `NN-outro.ans` frame is the flow-completion signal. `tsx` runs
+  source — no build step. Invocation: see the run-cell recipe below.
 - **Config selection:** the flag axis is `wizard-orchestrator` (on → the
   orchestrator on pi, per-task models from context-mill frontmatter; off → the
   linear anthropic default). Per-stage variations ride
-  `wizard-orchestrator-override` payloads (`{stage: {model?, effort?}}`,
-  variant keys in `wizard/src/agent/runner/switchboard/flags/schemes.ts`).
-  The baseline is `{"wizard-orchestrator":"false"}` — never an empty override,
-  or live remote flags leak into the baseline.
+  `wizard-orchestrator-override` payloads (`{stage: {model?, effort?}}`, variant
+  keys in `wizard/src/agent/runner/switchboard/flags/schemes.ts`). The baseline
+  is `{"wizard-orchestrator":"false"}` — never an empty override, or live remote
+  flags leak into the baseline.
 
 ## Running one cell
 
@@ -147,19 +147,19 @@ files=$(git -C "$WORK" diff --name-only main integ | wc -l | tr -d ' ')" \
   | tee "$OUT/result.txt"
 ```
 
-Both commits are `--no-verify` (see Traps). The diff, frames, stdout, and
-result line are the cell's complete artifact set — everything else (the shared
-debug log) is unreliable under parallelism.
+Both commits are `--no-verify` (see Traps). The diff, frames, stdout, and result
+line are the cell's complete artifact set — everything else (the shared debug
+log) is unreliable under parallelism.
 
 ## Running the matrix
 
-- One app at a time; per app, launch its configs in parallel (≤4 on one
-  machine) and `wait`. Contention inflates absolute times roughly uniformly.
+- One app at a time; per app, launch its configs in parallel (≤4 on one machine)
+  and `wait`. Contention inflates absolute times roughly uniformly.
 - Cost: anthropic-harness cells report `modelUsage.costUSD` in
-  `/tmp/posthog-wizard.log` — zero the log before each app's wave and slice
-  the block per baseline run. pi-harness cells do not persist token totals;
-  add a temporary hook in the pi harness success path that writes the session
-  token stats to a per-run file, and price them at list rates.
+  `/tmp/posthog-wizard.log` — zero the log before each app's wave and slice the
+  block per baseline run. pi-harness cells do not persist token totals; add a
+  temporary hook in the pi harness success path that writes the session token
+  stats to a per-run file, and price them at list rates.
 - Rerun any anomalous cell solo (zeroed log, no parallelism) before drawing a
   conclusion from it.
 
@@ -167,61 +167,61 @@ debug log) is unreliable under parallelism.
 
 - **Target-app git hooks.** Your `git commit` runs the app's husky/lint-staged
   hooks if a prior install activated them; a failing hook silently rolls the
-  tree back and the run measures as zero-diff. Always commit `--no-verify`.
-  On any zero-diff run, check `git stash list` before believing it.
-- **Zero-diff has many causes.** Distinguish: the agent honestly declined
-  (read its setup report), the agent's tool calls failed, your harness ate the
-  work, or `.gitignore` hid it (env files never show in diffs). Attribute
-  before you blame the model.
+  tree back and the run measures as zero-diff. Always commit `--no-verify`. On
+  any zero-diff run, check `git stash list` before believing it.
+- **Zero-diff has many causes.** Distinguish: the agent honestly declined (read
+  its setup report), the agent's tool calls failed, your harness ate the work,
+  or `.gitignore` hid it (env files never show in diffs). Attribute before you
+  blame the model.
 - **"Reached the outro" is not success.** The flow completes even when nothing
   was integrated. Treat completion as outro + a non-trivial diff.
 - **Parallel runs interleave shared state.** The shared debug log cannot be
   attributed per-run; capture everything per-run or run solo when attribution
   matters.
 - **Sandbox/allowlist gaps look like model failures.** If a config produces
-  empty or thin work, check whether a blocked command (package-manager
-  install, formatter) caused it, and whether other models worked around the
-  same block. File the gap; exclude the affected cells.
-- **Repo-wide format scripts.** An agent running the app's `format`/`lint
-  --fix` buries its real diff under hundreds of churn files. Count "real
-  files" excluding scaffolding, lockfiles, env files — and read a sample of
-  the churn before scoring.
-- **A stale credential fails silently mid-batch.** Read the key per run, not
-  per session.
+  empty or thin work, check whether a blocked command (package-manager install,
+  formatter) caused it, and whether other models worked around the same block.
+  File the gap; exclude the affected cells.
+- **Repo-wide format scripts.** An agent running the app's `format`/`lint --fix`
+  buries its real diff under hundreds of churn files. Count "real files"
+  excluding scaffolding, lockfiles, env files — and read a sample of the churn
+  before scoring.
+- **A stale credential fails silently mid-batch.** Read the key per run, not per
+  session.
 
 ## Judging
 
 Use the wizard-workbench PR evaluator's rubric — do not invent your own. It
 lives at `wizard-workbench/services/pr-evaluator/`:
 
-- **Rubric criteria:** `wizard-workbench/services/pr-evaluator/prompts/evaluation.md`
-  — per-item YES/NO/N-A checks grouped into four dimensions.
-- **Scoring math:** `wizard-workbench/services/pr-evaluator/evaluator.ts` —
-  each dimension scores `max(1, round(pass_rate × 5))` over its applicable
-  items; confidence = `min(app_sanity, round(mean of the four))`.
+- **Rubric criteria:**
+  `wizard-workbench/services/pr-evaluator/prompts/evaluation.md` — per-item
+  YES/NO/N-A checks grouped into four dimensions.
+- **Scoring math:** `wizard-workbench/services/pr-evaluator/evaluator.ts` — each
+  dimension scores `max(1, round(pass_rate × 5))` over its applicable items;
+  confidence = `min(app_sanity, round(mean of the four))`.
 - **Automated run:** from `wizard-workbench/`,
   `pnpm run evaluate --branch <integ> --base <base> --test-run` (needs
   `POSTHOG_PERSONAL_API_KEY`; judge model via `EVALUATOR_MODEL`). Output lands
   in `wizard-workbench/test-evaluations/<name>/` as `rubric.json` +
   `scores.json`.
-- **Manual run:** an agent applies the same rubric directly to each cell's
-  diff — faster for many cells, and what the 2026-07 benchmark did. Either
-  way, report the four dimensions under their full names, 1–5 each
-  (5 production-ready, 3 works with real issues, 1 broken or empty):
+- **Manual run:** an agent applies the same rubric directly to each cell's diff
+  — faster for many cells, and what the 2026-07 benchmark did. Either way,
+  report the four dimensions under their full names, 1–5 each (5
+  production-ready, 3 works with real issues, 1 broken or empty):
 
-- **Files** (`file_analysis`) — right files touched, nothing unrelated,
-  imports valid
+- **Files** (`file_analysis`) — right files touched, nothing unrelated, imports
+  valid
 - **App** (`app_sanity`) — nothing broken: builds, existing code and configs
   preserved, changes minimal
 - **PostHog** (`posthog_implementation`) — SDK installed, initialized at the
-  right entry points, env-based keys, real distinct id, identify, error
-  tracking
+  right entry points, env-based keys, real distinct id, identify, error tracking
 - **Events** (`event_quality`) — real user actions, useful properties, no PII,
   consistent names
 
-Verify claims against the diff (grep for `capture`/`identify` call sites,
-check the init file, check the manifest), and build or typecheck where cheap.
-Judge the same subset of apps for every config you compare.
+Verify claims against the diff (grep for `capture`/`identify` call sites, check
+the init file, check the manifest), and build or typecheck where cheap. Judge
+the same subset of apps for every config you compare.
 
 ## Publishing evidence
 
@@ -230,48 +230,55 @@ inspectable:
 
 1. Fork each app to the operator's account.
 2. Pin a `bench-base` branch at the exact commit the runs used.
-3. Per cell: branch from `bench-base`, apply the **sanitized** patch, push,
-   open a draft PR against `bench-base`.
+3. Per cell: branch from `bench-base`, apply the **sanitized** patch, push, open
+   a draft PR against `bench-base`.
 4. Sanitize before anything touches a public fork: drop env files, wizard
-   scaffolding, and lockfiles from the patch; redact every token literal.
-   Verify zero secrets in the pushed diff before opening the PR.
+   scaffolding, and lockfiles from the patch; redact every token literal. Verify
+   zero secrets in the pushed diff before opening the PR.
 
 ## Report template
 
 ```markdown
 # <project> — model benchmark
 
-<one paragraph: what ran, how many apps/configs, the cap, where the evidence PRs live>
+<one paragraph: what ran, how many apps/configs, the cap, where the evidence PRs
+live>
 
 ## Summary — configs that completed everywhere
-| config | completed | median time | median cost | quality (judged on) |
-<one row per config under consideration; drop dominated/dead configs into a
+
+| config | completed | median time | median cost | quality (judged on) | <one
+row per config under consideration; drop dominated/dead configs into a
 one-paragraph note with their numbers>
 
 ## Results
-<legend: cell format, cost source, symbols for timeout/excluded/not-run>
-| config | <app 1> | <app 2> | … |
-<time · cost per cell>
+
+<legend: cell format, cost source, symbols for timeout/excluded/not-run> |
+config | <app 1> | <app 2> | … | <time · cost per cell>
 
 ### Exclusions
+
 <each excluded cell: cause, evidence link. Root-cause analysis links here.>
 
 ## Per-app quality
-<per app: | config | real files | Files | App | PostHog | Events | notes |,
-one PR link per row. Full column names — never abbreviations.>
+
+<per app: | config | real files | Files | App | PostHog | Events | notes |, one
+PR link per row. Full column names — never abbreviations.>
 
 ## Code evidence
+
 <same-site snippets across configs: where they are identical, and where they
 differ (coverage, funnel depth, client vs server). Short, real excerpts.>
 
 ## Failure log
+
 | observation | where | evidence |
 
 ## Method & caveats
+
 <procedure in three sentences; n = 1; what was and wasn't build-verified;
 anything that changed mid-benchmark>
 ```
 
-Data only in the report: no verdicts or recommendations unless asked.
-Aggregates use medians; the completion column counts real (non-hollow,
-non-excluded) finishes.
+Data only in the report: no verdicts or recommendations unless asked. Aggregates
+use medians; the completion column counts real (non-hollow, non-excluded)
+finishes.
diff --git a/docs/local-dev.md b/docs/local-dev.md
index 65734d9a7..a82fda6a2 100644
--- a/docs/local-dev.md
+++ b/docs/local-dev.md
@@ -5,20 +5,20 @@ local, and this doc is the catalog of how to control each.
 
 ## Credentials for local CI and headless runs
 
-Local `--ci` runs, smoke tests, and full headless/snapshot agent runs need
-**two separate secrets**, plus the target project ID:
+Local `--ci` runs, smoke tests, and full headless/snapshot agent runs need **two
+separate secrets**, plus the target project ID:
 
-| Input | Purpose | How to pass it |
-|---|---|---|
-| PostHog personal API key (`phx_...`) | PostHog API and MCP authentication | CLI: `--api-key` / `POSTHOG_WIZARD_API_KEY`; smoke helper: `POSTHOG_PERSONAL_API_KEY`; headless host: `POSTHOG_PERSONAL_API_KEY` or `POSTHOG_KEY_FILE` |
-| Already-issued AI gateway bearer | Model calls | `WIZARD_CI_GATEWAY_TOKEN_FILE`, an absolute path to a file containing only the token |
-| Target project ID | Project selection and gateway attribution | CLI: `--project-id` / `POSTHOG_WIZARD_PROJECT_ID`; headless host: `PROJECT_ID` (MCP: `projectId`) |
+| Input                                | Purpose                                   | How to pass it                                                                                                                                         |
+| ------------------------------------ | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| PostHog personal API key (`phx_...`) | PostHog API and MCP authentication        | CLI: `--api-key` / `POSTHOG_WIZARD_API_KEY`; smoke helper: `POSTHOG_PERSONAL_API_KEY`; headless host: `POSTHOG_PERSONAL_API_KEY` or `POSTHOG_KEY_FILE` |
+| Already-issued AI gateway bearer     | Model calls                               | `WIZARD_CI_GATEWAY_TOKEN_FILE`, an absolute path to a file containing only the token                                                                   |
+| Target project ID                    | Project selection and gateway attribution | CLI: `--project-id` / `POSTHOG_WIZARD_PROJECT_ID`; headless host: `PROJECT_ID` (MCP: `projectId`)                                                      |
 
-The personal API key is not the gateway token. CI reads the gateway token
-from the file and uses it directly; it does not mint or refresh one. Keep the
-file outside the repo, restrict its permissions (`chmod 600`), and supply a
-valid token for the gateway being used. Missing, expired, or rejected tokens
-fail the run.
+The personal API key is not the gateway token. CI reads the gateway token from
+the file and uses it directly; it does not mint or refresh one. Keep the file
+outside the repo, restrict its permissions (`chmod 600`), and supply a valid
+token for the gateway being used. Missing, expired, or rejected tokens fail the
+run.
 
 With your personal API key already exported and gateway token saved locally:
 
@@ -32,9 +32,9 @@ pnpm try --ci --api-key "$POSTHOG_PERSONAL_API_KEY" \
   --region "$POSTHOG_WIZARD_REGION" --install-dir=/absolute/path/to/test-app
 ```
 
-`WIZARD_CI_GATEWAY_URL` optionally sets the gateway origin (no `/v1`);
-otherwise CI uses `https://ai-gateway.<region>.posthog.com`. The local service
-flags below do not override this CI gateway setting.
+`WIZARD_CI_GATEWAY_URL` optionally sets the gateway origin (no `/v1`); otherwise
+CI uses `https://ai-gateway.<region>.posthog.com`. The local service flags below
+do not override this CI gateway setting.
 
 For the `wizard-ci` MCP server, set `WIZARD_CI_GATEWAY_TOKEN_FILE` in the
 server's environment before launch; restart an existing server after changing
@@ -47,47 +47,53 @@ it. It is not an `open_app` argument. Pass the personal key via `keyFile` or
 `POSTHOG_PERSONAL_API_KEY`, while
 `GH_APP_POSTHOG_WIZARD_CI_BOT_POSTHOG_GATEWAY_TOKEN` is written to a temporary
 file referenced by `WIZARD_CI_GATEWAY_TOKEN_FILE`. CI also supplies
-`GH_APP_POSTHOG_WIZARD_CI_BOT_TARGET_PROJECT_ID` as
-`POSTHOG_WIZARD_PROJECT_ID`.
+`GH_APP_POSTHOG_WIZARD_CI_BOT_TARGET_PROJECT_ID` as `POSTHOG_WIZARD_PROJECT_ID`.
 
 Interactive runs authenticate normally and mint their gateway token through
-PostHog; they do not require this CI token file. Published builds reject
-`--ci`; use source, a development build, or `pnpm build:ci` for these recipes.
+PostHog; they do not require this CI token file. Published builds reject `--ci`;
+use source, a development build, or `pnpm build:ci` for these recipes.
 
 ## The four dimensions
 
-| # | What | Local target | How you control it |
-|---|---|---|---|
-| 1 | The wizard binary | your checkout | how you invoke it — see [Running the wizard](#running-the-wizard) |
-| 2 | context-mill (skills) | `http://localhost:8765` | `--local-context-mill` |
-| 3 | PostHog MCP server | `http://localhost:8787/mcp` | `--local-mcp` |
-| 4 | PostHog app / API | `http://localhost:8010` | `--local-posthog` |
+| #   | What                  | Local target                | How you control it                                                |
+| --- | --------------------- | --------------------------- | ----------------------------------------------------------------- |
+| 1   | The wizard binary     | your checkout               | how you invoke it — see [Running the wizard](#running-the-wizard) |
+| 2   | context-mill (skills) | `http://localhost:8765`     | `--local-context-mill`                                            |
+| 3   | PostHog MCP server    | `http://localhost:8787/mcp` | `--local-mcp`                                                     |
+| 4   | PostHog app / API     | `http://localhost:8010`     | `--local-posthog`                                                 |
 
-Select the skills, MCP, and PostHog servers independently. For example, CI
-runs local skills against production MCP and PostHog.
+Select the skills, MCP, and PostHog servers independently. For example, CI runs
+local skills against production MCP and PostHog.
 
 ## Flags
 
 These flags are available in dev/test builds. Published builds reject them.
 
-| Flag | Env | Effect |
-|---|---|---|
-| `--local-dev` | `POSTHOG_WIZARD_LOCAL_DEV` | all three below |
-| `--local-context-mill` | `POSTHOG_WIZARD_LOCAL_CONTEXT_MILL` | skills → `:8765` |
-| `--local-mcp` | `POSTHOG_WIZARD_LOCAL_MCP` | MCP → `:8787` |
-| `--local-posthog` | `POSTHOG_WIZARD_LOCAL_POSTHOG` | PostHog origins → `:8010` |
-| `--task-stream-log[=path]` | `POSTHOG_WIZARD_TASK_STREAM_LOG` | dump every attempted task-stream sync as JSONL (default `/tmp/posthog-wizard-task-stream.jsonl`) |
+| Flag                       | Env                                 | Effect                                                                                           |
+| -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------ |
+| `--local-dev`              | `POSTHOG_WIZARD_LOCAL_DEV`          | all three below                                                                                  |
+| `--local-context-mill`     | `POSTHOG_WIZARD_LOCAL_CONTEXT_MILL` | skills → `:8765`                                                                                 |
+| `--local-mcp`              | `POSTHOG_WIZARD_LOCAL_MCP`          | MCP → `:8787`                                                                                    |
+| `--local-posthog`          | `POSTHOG_WIZARD_LOCAL_POSTHOG`      | PostHog origins → `:8010`                                                                        |
+| `--task-stream-log[=path]` | `POSTHOG_WIZARD_TASK_STREAM_LOG`    | dump every attempted task-stream sync as JSONL (default `/tmp/posthog-wizard-task-stream.jsonl`) |
+| `--e2e-ask`                | `POSTHOG_WIZARD_E2E_ASK`            | keep `wizard_ask` wired in a `--ci` run so a controlling parent answers the agent's questions    |
+
+`--control-socket <path>` is not a dev flag: every build accepts it with the
+experimental headless flag and serves the control API over that unix socket (see
+[`e2e-harness/ARCHITECTURE.md`](../e2e-harness/ARCHITECTURE.md)). Dev builds
+also accept it with `--ci` to control the real TUI; published TUI runs refuse
+it.
 
 `--local-posthog` is sugar over `--base-url`. It pins the API host, app host,
 OAuth server, and the LLM gateway derived from them.
 
 `--task-stream-log` records what the run published, one JSON line per push,
-truncated per run. It rides beside the PostHog destination rather than
-replacing it, so a logged run is the same run the backend sees. A line means
-the payload was attempted, not accepted — `[task-stream] wizard/sessions push
-ok: 201` in the debug log is the delivery signal. `--ci` dumps to the default
-path on every run and never pushes, since a synthetic run would otherwise
-create a session row in a real project.
+truncated per run. It rides beside the PostHog destination rather than replacing
+it, so a logged run is the same run the backend sees. A line means the payload
+was attempted, not accepted — `[task-stream] wizard/sessions push ok: 201` in
+the debug log is the delivery signal. `--ci` dumps to the default path on every
+run and never pushes, since a synthetic run would otherwise create a session row
+in a real project.
 
 ### Precedence
 
@@ -130,17 +136,16 @@ requested it, and how to start it:
 Start the missing services, or drop the flag to use production.
 ```
 
-Preflight runs **before authentication** and stops both interactive and CI
-runs when a requested local service is unreachable.
+Preflight runs **before authentication** and stops both interactive and CI runs
+when a requested local service is unreachable.
 
 Only reachability is checked. Any HTTP reply counts, including 404 and 405.
 
 ## Selecting local MCP and skills servers
 
-`--local-mcp` selects the MCP server at `localhost:8787`.
-`--local-context-mill` selects the skills server at `localhost:8765`.
-Pass both flags to use both local services, or `--local-dev` to include local
-PostHog as well.
+`--local-mcp` selects the MCP server at `localhost:8787`. `--local-context-mill`
+selects the skills server at `localhost:8765`. Pass both flags to use both local
+services, or `--local-dev` to include local PostHog as well.
 
 ## Editor MCP configuration
 
@@ -157,21 +162,21 @@ builds and independent of the wizard run's `--local-*` flags.
 
 Choose the wizard binary through its invocation:
 
-| Mode | Command | Build |
-|---|---|---|
-| From source | `pnpm try --install-dir=<path>` | dev (`IS_DEV`) |
-| Globally linked | `pnpm dev`, then `wizard` | dev, rebuilt on change |
+| Mode              | Command                                           | Build                   |
+| ----------------- | ------------------------------------------------- | ----------------------- |
+| From source       | `pnpm try --install-dir=<path>`                   | dev (`IS_DEV`)          |
+| Globally linked   | `pnpm dev`, then `wizard`                         | dev, rebuilt on change  |
 | Workbench harness | `WIZARD_PATH=<repo>` → `$WIZARD_PATH/dist/bin.js` | whatever you last built |
-| Published | `npx @posthog/wizard` | production |
+| Published         | `npx @posthog/wizard`                             | production              |
 
 To confirm what a run actually used, pass `--debug` and look for the
-`[agent-runner] targets` line in `/tmp/posthog-wizard.log` — it prints the build,
-skills url, MCP url, and PostHog host together.
+`[agent-runner] targets` line in `/tmp/posthog-wizard.log` — it prints the
+build, skills url, MCP url, and PostHog host together.
 
 ## Implementation
 
 `src/store/local-dev.ts` defines the endpoints and precedence. Downstream code
 reads the resolved targets.
 
-The three service flags have no yargs default. An absent flag is `undefined`
-and inherits the umbrella setting; an explicit `false` overrides it.
+The three service flags have no yargs default. An absent flag is `undefined` and
+inherits the umbrella setting; an explicit `false` overrides it.
diff --git a/e2e-harness/ARCHITECTURE.md b/e2e-harness/ARCHITECTURE.md
index 5b17c8d56..6ec98f543 100644
--- a/e2e-harness/ARCHITECTURE.md
+++ b/e2e-harness/ARCHITECTURE.md
@@ -1,182 +1,226 @@
-# e2e-harness — Headless e2e Control Plane
+# e2e-harness: the headless control plane
 
-How an agent (or CI) drives a **real** wizard run end-to-end — the **real TUI**,
-no browser, no keystrokes — and captures what it rendered. Both e2e routes share
-one idea: run the real `startTUI` (the real ink render) and drive its store by
-**state manipulation**, then capture the real rendered screen from a PTY.
+How an agent or CI drives a **real** wizard run end to end: the real TUI, no
+browser, no keystrokes, and a capture of what it rendered. The wizard serves a
+control API over a unix socket; the harness is one of its clients.
 
-> If you're an agent that just wants to run and explore the wizard, use the
+> If you are an agent that wants to run and explore the wizard, use the
 > `exploring-the-wizard` skill
 > ([`.claude/skills/exploring-the-wizard/SKILL.md`](../.claude/skills/exploring-the-wizard/SKILL.md)).
-> This doc is the _how it works_ underneath.
+> This document is the _how it works_ underneath.
 
 ## The pieces
 
-This whole harness lives in `e2e-harness/` at the repo root — deliberately OUT
-of `src/` so none of it is part of the wizard's production source (nothing in
-`src/` imports it; the tsdown bundle never includes it).
+The harness lives in `e2e-harness/` at the repo root, out of `src/`, so none of
+it ships. The control API itself ships with the wizard, in
+[`src/store/control/`](../src/store/control/), because published headless runs
+use it.
 
 ```
+src/store/control/
+  server.ts             attachControlServer: HTTP/1.1 over a unix socket, one store
+  client.ts             ControlClient: the parent's side of the same API
+  actions.ts            generic actions per flow key; programs add controlActions
+  state.ts              the secret-free projection GET /state returns
+  driver.ts             ControlDriver: read and act on one store in process
+  runs.ts               the run ledger behind POST /runs and GET /runs
 e2e-harness/
-  wizard-ci-driver.ts   WizardCiDriver — read_state / perform_action over the store
-  action-registry.ts    screen → the actions legal on it (+ NO_ACTION_SCREENS)
-  e2e-profile.ts        WizardE2eProfile + decideE2eAction — the scripted walk policy
-  profiles.ts           per-program profiles + profileFor(programId) + resolveE2eProfile(env)
-  e2e-result.ts         the E2E_RESULT_JSON payload: E2eRunRecorder + buildE2eResult
-  tui-capture.ts        run a command in a PTY (node-pty) + read its real screen (@xterm/headless)
+  launch.ts             buildLaunch: the argv and env that start a controlled wizard
+  picks.ts              the detection picks a headless run supplies to picker screens
+  e2e-profile.ts        WizardE2eProfile and decideE2eAction: the scripted walk policy
+  profiles.ts           per-program profiles, profileFor(programId), resolveE2eProfile(env)
+  e2e-result.ts         the E2E_RESULT_JSON payload: E2eRunRecorder and buildE2eResult
+  tui-capture.ts        run a command in a PTY (node-pty) and read its real screen
 scripts/
-  tui-host.no-jest.ts   the real-TUI host: startTUI + WizardCiDriver, MODE=fixed | serve
-  tui-snapshots.no-jest.ts   CI route: host(fixed) in a PTY → per-screen real-TUI snapshots
-  wizard-ci-mcp.no-jest.ts   agent route: MCP server proxying host(serve)
+  tui-snapshots.no-jest.ts   CI route: the wizard in a PTY, driven over the socket, per-screen snapshots
+  wizard-ci-mcp.no-jest.ts   agent route: an MCP server that proxies the same API
 ```
 
-The driver reads and mutates the **real** `WizardStore` that the TUI renders
-from: the router resolves the active screen from session state, every action
-goes through a store setter, and the render is a pure projection of that state.
-So manipulating the store makes the real TUI react — the driver and the renderer
-share one store and never conflict; you never touch the TUI's input.
+The server reads and mutates the **real** `WizardStore` the TUI renders from.
+The router resolves the active screen from session state, every action goes
+through a store setter, and the render is a pure projection of that state. So a
+commit over the socket makes the real TUI react, and the parent never touches
+the TUI's input.
+
+## Launching a controlled wizard
+
+`buildLaunch` in `launch.ts` produces the command. Every program launches under
+its own command word (`self-driving`, `audit all`, `upload-source-maps`); the
+default flow has none. The flags are `--ci` (API-key auth, no browser),
+`--control-socket <path>`, `--install-dir`, `--project-id`, `--region`, and
+`--e2e-ask` when the parent answers the agent's questions. Switchboard overrides
+map to `--harness`, `--sequence`, and `--model`.
+
+The personal API key travels as `POSTHOG_WIZARD_API_KEY` in the child's
+environment, never in argv. The launcher strips `CLAUDE*`, `ANTHROPIC*`, and
+`AI_AGENT*` variables so the wizard's agent never defers to an outer agent
+session, and sets `WIZARD_ASK_AUTODRIVE=1` for the linear sequence.
+
+Published builds accept `--control-socket` only together with the experimental
+headless flag; a published TUI refuses it, and its bundle never contains the
+server (`scripts/smoke-test.sh` audits both).
+
+## The control API
+
+JSON in and out. Success is `{ ok: true, ... }`; failure is
+`{ ok: false, error }` with 400 (bad body, missing param, unknown action or
+program), 404 (unknown route), 409 (a run is in flight), 413 (body over 64 KB),
+415 (not JSON), 500 (a hook failed), or 501 (the other surface's route).
+
+| Route                                                                       | Behavior                                                                                    |
+| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `GET /health`                                                               | `{ ok, version, surface, pid, program }`                                                    |
+| `GET /state`                                                                | `{ ok, state }`, the projection below                                                       |
+| `GET /state?wait=<ms>&since=<version>`                                      | Long poll: resolves on the first commit with `version > since`, or after `wait` ms          |
+| `POST /actions/<id>` body `{ params }`                                      | Applies one action legal on the current screen through its store setter, returns the state  |
+| `POST /credentials`                                                         | Resolves the API key into project credentials and commits them, advancing `auth`            |
+| `POST /run`                                                                 | TUI surface: releases the runner's agent start. Idempotent                                  |
+| `POST /detect` body `{ programId?, installDir? }`                           | Headless surface: runs detection through the store's setters                                |
+| `POST /runs` body `{ programId, installDir?, frameworkContext?, skillId? }` | Headless surface: one independent agent run; 409 while one runs                             |
+| `GET /runs`                                                                 | The run ledger: `runId`, `programId`, `installDir`, `status`, `error`, timestamps, `result` |
+| `POST /shutdown`                                                            | Flushes and exits. Idempotent                                                               |
+
+`state` carries `version`, `currentScreen`, `hasOverlay`, `runPhase`,
+`run: { status, error }`, a session whitelist (credentials reduce to
+`hasCredentials` and `projectId`), `tasks`, `statusMessages`, `eventPlan`,
+`pendingQuestion`, `taskNotice`, `setupQuestions`, `actions`, `dashboardUrl`,
+`notebookUrl`, `handoffText`, a reduced `outroData`, and `frameworkContext` as
+`{ keys, digest, values }` after redaction: `secret:<id>` refs become
+`[secret-ref]` and secret-looking keys become `[redacted]`. No access token, API
+key, user record, or answer value is ever projected.
+
+The socket is created mode 0600 in a directory the caller owns. A stale socket
+file is replaced; a live one is refused. The wizard unlinks it on exit.
 
 ## Auth without a browser
 
-The real TUI runs `ci: true`. `run_agent` enters the normal program bootstrap,
+The TUI runs `ci: true`. `POST /run` releases the normal program bootstrap,
 which resolves the phx personal key into project credentials and commits them to
-the store. Gateway authentication then follows the shared runner path; see the
+the store; `POST /credentials` does the same commit without starting a run,
+which is how a detection-only exploration advances past `auth`. Gateway
+authentication follows the shared runner path; see the
 [runner policy](../.claude/skills/wizard-development/SKILL.md).
 
-The direct host reads `APP_DIR`, `PROJECT_ID`, and either
-`POSTHOG_PERSONAL_API_KEY` or `POSTHOG_KEY_FILE`. The MCP route accepts
-`appDir`, `projectId`, and optional `keyFile` or `apiKey` through `open_app`.
-Detection-only MCP runs omit the key and stop at `auth`. The internal socket's
-`set_credentials` command is not exposed as an MCP tool.
+The snapshot route reads `APP_DIR`, `PROJECT_ID`, `POSTHOG_REGION`, and either
+`POSTHOG_PERSONAL_API_KEY` or `POSTHOG_KEY_FILE` (the inline key wins). The MCP
+route takes `appDir`, `projectId`, `region`, and optional `keyFile` or `apiKey`
+through `open_app`. Detection-only MCP runs omit the key and stop at `auth`.
 
-Agent runs require `WIZARD_CI_GATEWAY_TOKEN_FILE` containing an already-issued
-gateway bearer. CI uses it directly and never mints or refreshes it; missing or
-rejected credentials fail the run. `WIZARD_CI_GATEWAY_URL` optionally overrides
-`https://ai-gateway.<region>.posthog.com`. `POSTHOG_KEY_FILE` /
-`POSTHOG_PERSONAL_API_KEY` remain separate credentials for PostHog API and MCP.
-The same gateway settings apply to development `--ci` runs.
+Agent runs need `WIZARD_CI_GATEWAY_TOKEN_FILE` with an already-issued gateway
+bearer. CI uses it directly and never mints or refreshes it.
+`WIZARD_CI_GATEWAY_URL` optionally overrides
+`https://ai-gateway.<region>.posthog.com`.
 
 ## The two routes
 
-- **CI snapshots** — `tui-snapshots.no-jest.ts` spawns `tui-host` (`MODE=fixed`)
-  in a PTY. The host self-drives the fixed profile (`decideE2eAction`) through
-  the real agent run and signals each key moment; the parent writes the real
-  rendered screen to `SNAP_OUT/NN-<screen>.ans`, preserving colors and
-  attributes.
-- **Agent** — `wizard-ci-mcp.no-jest.ts` is a stdio MCP server that spawns
-  `tui-host` (`MODE=serve`) and proxies: `read_state` / `perform_action` /
-  `run_agent` forward over a unix socket; `render_screen` returns the captured
-  frame as plain text with ANSI removed. The agent decides each screen itself.
+- **CI snapshots.** `tui-snapshots.no-jest.ts` spawns the wizard in a PTY,
+  releases the run with `POST /run`, and drives the fixed profile
+  (`decideE2eAction`) over the socket. It long polls `GET /state` and writes the
+  real rendered screen to `SNAP_OUT/NN-<screen>.ans` on every screen change,
+  task update, run-phase change, or in-place context change, colors preserved.
+- **Agent.** `wizard-ci-mcp.no-jest.ts` is a stdio MCP server that spawns the
+  wizard the same way and proxies `read_state`, `perform_action`, and
+  `run_agent` to the API; `render_screen` returns the captured frame as plain
+  text. The agent decides each screen itself.
 
-Both routes use a 180×50 PTY by default; `PTY_COLS` and `PTY_ROWS` override it.
-Snapshots capture screen transitions and within-screen progress, not just the
-final outro.
+Both routes use a 180x50 PTY by default; `PTY_COLS` and `PTY_ROWS` override it.
 
 ## Run selection and state
 
 `PROGRAM` selects a program id and defaults to `posthog-integration`.
-`SNAP_HARNESS`, `SNAP_SEQUENCE`, and `SNAP_MODEL` feed the development
-switchboard overrides. Omitted values use normal flag and binding resolution;
-the host does not force Pi or orchestration. For new exploration, follow the
-[runner policy](../.claude/skills/wizard-development/SKILL.md) and set the
-server's launch environment accordingly. These inputs are not `open_app`
-arguments; there is no MCP effort or system-prompt override.
-
-`read_state` adds background `integration` (`idle`, `running`, `done`, `failed`)
-and `integrationError` to the driver's state. Framework identity is the separate
-`session.integration`. `perform_action` returns only the driver's state, so read
-again to refresh background status. Legal actions come from
-`read_state.actions`; the MCP has no `list_actions` or `wait_for_change` tool.
+`SNAP_HARNESS`, `SNAP_SEQUENCE`, and `SNAP_MODEL` feed the switchboard
+overrides. Omitted values use normal flag and binding resolution. These are
+launcher environment inputs, not `open_app` arguments.
+
+`read_state` adds `integration` (`idle`, `running`, `done`, `failed`) and
+`integrationError`, copied from `state.run`. Framework identity is the separate
+`session.integration`. `perform_action` returns the state without those two
+fields, so read again to refresh the run status. Legal actions come from
+`state.actions`; there is no `list_actions` tool.
 
 Keep handling overlays while the agent runs. `runPhase=completed` ends the main
-work, while `session.skillsComplete` ends the integration flow's follow-up
-screens. Recording MCP or keep-skills outcomes only commits store state; it does
-not perform installation or cleanup. For failures, capture the error outro
-before dismissing it: `wizardAbort` can wait there with background status still
-`running`, then exit the host instead of returning `integration=failed`.
-
-## Current host limitations
-
-- `open_app` accepts `region`, but `tui-host` currently builds a US session
-  regardless of `POSTHOG_REGION`; this route cannot verify EU authentication.
-- The host reads `POSTHOG_PERSONAL_API_KEY` before `POSTHOG_KEY_FILE`. An
-  inherited personal key can therefore shadow an explicit MCP `keyFile`; unset
-  that variable in the server's launch environment when using a key file.
-- Some interactive pickers are not represented by driver actions. The fixed
-  route supplies its own detection picks for self-driving and source maps; those
-  conveniences do not automatically apply to the MCP route.
+work; `session.skillsComplete` ends the integration flow's follow-up screens.
+Recording MCP or keep-skills outcomes only commits store state; it does not
+install or delete anything. For failures, capture the error outro before
+dismissing it.
+
+## Picker screens
+
+Three screens resolve a pick the real TUI takes from an interactive list. The
+program declares the commit as a control action, and the harness computes the
+value client side in `picks.ts`:
+
+- `self-driving-integration-detect` and `error-tracking-detect` take
+  `pick_integration_target { path, integration }`: the repo root for a single
+  app, else the first instrumentable sub-app under `apps/` or `packages/`.
+- `source-maps-detect` takes `pick_source_maps_project { variant, path }`: the
+  static prerequisite detector's variant, else the native platform its manifest
+  names (Go, Rust, Flutter, iOS, Android).
+
+The MCP route offers the same actions; the agent supplies the values.
 
 ## Things that bite
 
-1. **Inherited agent auth.** The launchers strip Claude/Anthropic environment
-   variables so the legacy SDK does not defer authentication to an outer agent
-   session. Direct host callers must arrange the same isolation.
-2. **A project-scoped key needs its project id.** Use `PROJECT_ID` for the
-   direct host or `projectId` for MCP; the CLI's `--project-id` is a different
-   surface.
+1. **Inherited agent auth.** `buildLaunch` strips Claude and Anthropic
+   variables. A direct caller must do the same.
+2. **A project-scoped key needs its project id.** `PROJECT_ID` for the snapshot
+   route, `projectId` for MCP.
 3. **Never run on a real fixture.** Always a throwaway copy.
-4. **`run_agent` is minutes long and creates real resources** (a dashboard +
-   insights) each run; the agent log is one shared file — never run two at once.
-5. **node-pty's spawn-helper.** When the package is extracted without running
-   its build script (pnpm skips it), the prebuilt `spawn-helper` loses its
-   execute bit and `pty.spawn` fails with `posix_spawnp failed`.
-   `tui-capture.ts` restores it best-effort on each spawn.
+4. **A run is minutes long and creates real resources** (a dashboard and
+   insights). The agent log is one shared file; never run two at once.
+5. **node-pty's spawn-helper.** When the package is extracted without its build
+   script, the prebuilt helper loses its execute bit and `pty.spawn` fails with
+   `posix_spawnp failed`. `tui-capture.ts` restores it on each spawn.
 
 ## Changing what the run does
 
-Per-program UI choices live in the harness (`profiles.ts`, keyed by program id)
-— not on the program config — so this machinery stays out of production source.
-Edit the program's entry (typed by `WizardE2eProfile`); the fixed host asks
-`decideE2eAction(state, profile)` what to commit on each screen. The (screen →
-decision) trace is snapshot-tested offline in `__tests__/` (Vitest `--update`
-refreshes snapshots).
+Per-program UI choices live in the harness (`profiles.ts`, loaded from each
+program's `test/e2e.json`), not on the program config. Edit the program's entry
+(typed by `WizardE2eProfile`); the snapshot route asks
+`decideE2eAction(state, profile)` what to commit on each screen. The (screen,
+decision) trace is snapshot-tested offline in `__tests__/` against the store's
+`ControlDriver`; Vitest `--update` refreshes goldens after an intended flow
+change.
 
 ## Driving the agent-in-the-loop layer
 
 Two decision points ask a person to act, and the harness stands in for them.
 
-`wizard_ask` overlay. A `ci` session normally has no ask bridge at all. The host
-sets `session.e2eAsk` from `E2E_ASK=true`, which keeps the bridge wired (see
-`shouldDisableAsk`). In the fixed route, the profile answers every question:
+`wizard_ask` overlay. A `ci` session normally has no ask bridge. `--e2e-ask`
+keeps it wired (see `shouldDisableAsk`); the routes pass the flag when
+`E2E_ASK=true`. In the snapshot route the profile answers every question:
 `askAnswers` routes a question to a value, else the first option, else the
 `'e2e'` sentinel. Route credentials with `${ENV_VAR}` values, never literals.
 
 Mark a credential rule `"secret": true`. The skill names its own questions, so a
-rule matches text the agent controls — without the flag, a question called
-`password` takes the value, and by omitting `sensitive: true` gets it back
-unvaulted in plaintext. A secret rule answers only free text flagged sensitive
-and refuses every other question shape; refusals land in the payload's
-`refusedIds` / `refusedAsks`, so a run that withholds a credential says so
-instead of looking like an ordinary sentinel.
+rule matches text the agent controls. A secret rule answers only free text
+flagged sensitive and refuses every other question shape; refusals land in the
+payload's `refusedIds` and `refusedAsks`.
 
 Task-notice overlay. `profile.notice` decides `keep` or `decline`. `E2E_NOTICE`
 overrides it per run.
 
 Both env inputs are folded into the profile by `resolveE2eProfile`, at load.
-`decideE2eAction` must stay pure — it reads no env and no store.
+`decideE2eAction` stays pure: no env, no store, no socket.
 
-In the MCP route, use `perform_action` for `answer_question` (a complete answers
-map), `cancel_question`, or `resolve_notice` with `params: { keep }`. Read
-`pendingQuestion` and `taskNotice` for the decision. Profiles do not answer
-these overlays in `MODE=serve`.
+In the MCP route, use `perform_action` with `answer_question` (a complete
+answers map), `cancel_question`, or `resolve_notice` with `params: { keep }`.
 
 ## The result payload
 
-A `MODE=fixed` run writes `E2E_RESULT_JSON`: the run phase and screens walked,
-plus every ask batch, every task notice, the task list, the detected warehouse
+The snapshot route writes `E2E_RESULT_JSON`: the run phase and screens walked,
+every ask batch, every task notice, the task list, the detected warehouse
 sources, the program's report file, and the abort reason. `e2e-result.ts` builds
-it.
+it from the control state.
 
 **Only question prompt text and question ids go in the payload. No answer value
-ever does.** The decision function reports ids and a keep/decline verdict, so
-the recorder never holds an answer. Keep it that way — the workbench scans the
-file for its own injected credentials.
-
-The report file is the one payload field whose _content_ comes from the app
-directory, which is a checkout the run does not control. `readReportFile` reads
-only a regular file inside `appDir` — never a symlink, and never through a
-symlinked parent — so a committed `posthog-warehouse-report.md` pointing at a
-host file cannot copy it into the payload.
+ever does.** The decision function reports ids and a keep or decline verdict, so
+the recorder never holds an answer. The workbench scans the file for its own
+injected credentials.
+
+The report file is the one payload field whose content comes from the app
+directory. `readReportFile` reads only a regular file inside `appDir`, never a
+symlink, and never through a symlinked parent.
 
 ## Visual-regression snapshots (the workbench flow)
 
diff --git a/e2e-harness/__tests__/control-actions-parity.test.ts b/e2e-harness/__tests__/control-actions-parity.test.ts
deleted file mode 100644
index e99c31f61..000000000
--- a/e2e-harness/__tests__/control-actions-parity.test.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-  ACTION_REGISTRY,
-  NO_ACTION_SCREENS as HARNESS_NO_ACTION,
-} from '@e2e-harness/action-registry';
-import { Interrupt } from '@store';
-import { actionsFor, NO_ACTION_SCREENS } from '@store/control';
-import { flowFor, PROGRAM_REGISTRY } from '@store/programs';
-
-/** The store adds the pick the e2e host used to inject through raw setters. */
-const STORE_ONLY: Record<string, string[]> = {
-  'self-driving-integration-detect': ['pick_integration_target'],
-  'error-tracking-detect': ['pick_integration_target'],
-};
-
-describe('control actions parity with the e2e action registry', () => {
-  it('offers every harness action on every flow, plus only the documented picks', () => {
-    const drift: string[] = [];
-    for (const config of PROGRAM_REGISTRY) {
-      const { flow } = flowFor(config.id);
-      const screens = new Set<string>([
-        ...flow.steps.flatMap((s) => (s.screenId ? [s.screenId] : [])),
-        ...Object.values(Interrupt),
-      ]);
-      for (const screen of screens) {
-        const harness = (
-          (
-            ACTION_REGISTRY as Record<string, Array<{ id: string }> | undefined>
-          )[screen] ?? []
-        ).map((a) => a.id);
-        const store = actionsFor(flow, screen).map((a) => a.id);
-        for (const id of harness) {
-          if (!store.includes(id))
-            drift.push(`${config.id}:${screen} lost ${id}`);
-        }
-        for (const id of store) {
-          if (
-            !harness.includes(id) &&
-            !(STORE_ONLY[screen] ?? []).includes(id)
-          ) {
-            drift.push(`${config.id}:${screen} added ${id}`);
-          }
-        }
-      }
-    }
-    expect(drift).toEqual([]);
-  });
-
-  it('keeps every no-action screen the harness lists, minus the detect screens the picks now cover', () => {
-    for (const screen of NO_ACTION_SCREENS) {
-      expect(HARNESS_NO_ACTION.has(screen as never), screen).toBe(true);
-    }
-  });
-});
diff --git a/e2e-harness/__tests__/wizard-ci-driver.test.ts b/e2e-harness/__tests__/control-driver.test.ts
similarity index 89%
rename from e2e-harness/__tests__/wizard-ci-driver.test.ts
rename to e2e-harness/__tests__/control-driver.test.ts
index cfadd18cf..4c46280e6 100644
--- a/e2e-harness/__tests__/wizard-ci-driver.test.ts
+++ b/e2e-harness/__tests__/control-driver.test.ts
@@ -1,6 +1,6 @@
 /**
  * Control-plane test: drive a REAL WizardStore through the full integration
- * screen sequence using only the WizardCiDriver — proving read_state is a
+ * screen sequence using only the ControlDriver — proving read_state is a
  * truthful projection of router-resolved state and that perform_action commits
  * cause the same transitions the interactive UI would.
  *
@@ -23,18 +23,13 @@ import { FRAMEWORK_REGISTRY } from '@store/registry';
 import { WizardReadiness } from '@store/health-checks/readiness';
 import { ScreenId, Overlay } from '@tui/router';
 import { Program } from '@store/programs/program-registry';
-import {
-  WizardCiDriver,
-  UnknownActionError,
-} from '@e2e-harness/wizard-ci-driver';
-import {
-  ACTION_REGISTRY,
-  NO_ACTION_SCREENS,
-} from '@e2e-harness/action-registry';
+import { ControlDriver, UnknownActionError } from '@store/control';
 import { SOURCE_MAPS_CONTEXT_KEYS } from '@store/programs/error-tracking-upload-source-maps';
 import { OutroKind } from '@store/session/wizard-session';
 import { flowFor } from '@store/programs/flow-for';
 
+const IDLE = () => ({ status: 'idle' as const, error: null });
+
 function freshStore(): WizardStore {
   const store = new WizardStore(flowFor(Program.PostHogIntegration).flow);
   // Headless: a real store + StoreUI (which only forwards to the store), no Ink
@@ -56,11 +51,11 @@ const cleanReadiness = {
   reasons: [] as string[],
 };
 
-describe('WizardCiDriver — full integration flow', () => {
+describe('ControlDriver — full integration flow', () => {
   it('lets a failed run exit or continue to MCP', () => {
     const store = freshStore();
     const ui = new StoreUI(store);
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     store.setCredentials({
       accessToken: 'phx_secret_should_not_leak',
       projectApiKey: 'phc_public',
@@ -81,7 +76,7 @@ describe('WizardCiDriver — full integration flow', () => {
 
   it('walks intro → setup → run → outro → mcp → slack → keep-skills', () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     // 1. Intro
     expect(driver.readState().currentScreen).toBe(ScreenId.Intro);
@@ -144,7 +139,7 @@ describe('WizardCiDriver — full integration flow', () => {
 
   it('read_state is a truthful projection and never leaks the access token', () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     store.setCredentials({
       accessToken: 'phx_secret_should_not_leak',
       projectApiKey: 'phc_public',
@@ -162,7 +157,7 @@ describe('WizardCiDriver — full integration flow', () => {
 
   it('rejects actions that are not legal on the current screen', () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     expect(driver.readState().currentScreen).toBe(ScreenId.Intro);
     expect(() => driver.performAction('keep_skills')).toThrow(
       UnknownActionError,
@@ -170,10 +165,10 @@ describe('WizardCiDriver — full integration flow', () => {
   });
 });
 
-describe('WizardCiDriver — wizard_ask overlay', () => {
+describe('ControlDriver — wizard_ask overlay', () => {
   it('answers a pending question through the driver, resolving the agent promise', async () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     // The agent (via the ask bridge) opens a question and awaits the answers.
     const answersPromise = store.requestQuestion({
@@ -208,7 +203,7 @@ describe('WizardCiDriver — wizard_ask overlay', () => {
   });
 });
 
-describe('WizardCiDriver — self-driving integration check', () => {
+describe('ControlDriver — self-driving integration check', () => {
   function selfDrivingStore(): WizardStore {
     const store = new WizardStore(flowFor(Program.SelfDriving).flow);
     setUI(new StoreUI(store));
@@ -218,7 +213,7 @@ describe('WizardCiDriver — self-driving integration check', () => {
 
   it('exposes the integration check and commits set_integrate', () => {
     const store = selfDrivingStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     // Intro → integration-check.
     store.completeSetup();
@@ -239,7 +234,7 @@ describe('WizardCiDriver — self-driving integration check', () => {
       installDir: '/tmp/ci-driver-sd',
       integrate: true,
     });
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     store.completeSetup();
     expect(driver.readState().currentScreen).not.toBe(
@@ -248,7 +243,7 @@ describe('WizardCiDriver — self-driving integration check', () => {
   });
 });
 
-describe('WizardCiDriver — source-maps project pick', () => {
+describe('ControlDriver — source-maps project pick', () => {
   function sourceMapsStore(): WizardStore {
     const store = new WizardStore(
       flowFor(Program.ErrorTrackingUploadSourceMaps).flow,
@@ -271,7 +266,7 @@ describe('WizardCiDriver — source-maps project pick', () => {
 
   it('commits the pick the way the detect screen would and advances', () => {
     const store = sourceMapsStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     toDetectScreen(store);
     const state = driver.readState();
@@ -293,7 +288,7 @@ describe('WizardCiDriver — source-maps project pick', () => {
 
   it('requires the variant and path params', () => {
     const store = sourceMapsStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     toDetectScreen(store);
     expect(() =>
@@ -302,7 +297,7 @@ describe('WizardCiDriver — source-maps project pick', () => {
   });
 });
 
-describe('WizardCiDriver — task-notice overlay', () => {
+describe('ControlDriver — task-notice overlay', () => {
   const notice = {
     title: 'Connect your data sources',
     body: ['We detected some warehouse sources.'],
@@ -314,7 +309,7 @@ describe('WizardCiDriver — task-notice overlay', () => {
 
   it('projects the notice into read_state and keeps the step', async () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
 
     const kept = store.showTaskNotice(notice);
 
@@ -336,7 +331,7 @@ describe('WizardCiDriver — task-notice overlay', () => {
 
   it('skips the step when keep is false', async () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     const kept = store.showTaskNotice(notice);
     driver.performAction('resolve_notice', { keep: false });
     await expect(kept).resolves.toBe(false);
@@ -344,7 +339,7 @@ describe('WizardCiDriver — task-notice overlay', () => {
 
   it('defaults to keeping the step when keep is omitted', async () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     const kept = store.showTaskNotice(notice);
     driver.performAction('resolve_notice');
     await expect(kept).resolves.toBe(true);
@@ -352,18 +347,8 @@ describe('WizardCiDriver — task-notice overlay', () => {
 
   it('projects an empty items list when the notice has none', () => {
     const store = freshStore();
-    const driver = new WizardCiDriver(store);
+    const driver = new ControlDriver(store, IDLE);
     void store.showTaskNotice({ ...notice, items: undefined });
     expect(driver.readState().taskNotice?.items).toEqual([]);
   });
 });
-
-describe('action registry exhaustiveness', () => {
-  it('every screen and overlay is either actionable or explicitly no-action', () => {
-    const allScreens = [...Object.values(ScreenId), ...Object.values(Overlay)];
-    const uncovered = allScreens.filter(
-      (s) => !(s in ACTION_REGISTRY) && !NO_ACTION_SCREENS.has(s),
-    );
-    expect(uncovered).toEqual([]);
-  });
-});
diff --git a/e2e-harness/__tests__/control-socket-headless.test.ts b/e2e-harness/__tests__/control-socket-headless.test.ts
new file mode 100644
index 000000000..abecda03a
--- /dev/null
+++ b/e2e-harness/__tests__/control-socket-headless.test.ts
@@ -0,0 +1,77 @@
+/**
+ * The published headless surface, driven over its socket: a real `bin.ts`
+ * process, no agent run. Detection and runs need credentials, so this covers
+ * the plumbing every controlled run shares.
+ */
+import { spawn, type ChildProcess } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ControlClient } from '@store/control';
+import { HEADLESS_FLAG } from '@env';
+import { waitForSocket } from '@e2e-harness/launch';
+
+const REPO = path.resolve(__dirname, '../..');
+let child: ChildProcess | null = null;
+let dir: string | null = null;
+
+afterEach(() => {
+  child?.kill('SIGKILL');
+  child = null;
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  dir = null;
+});
+
+describe('controlled headless surface', () => {
+  it('serves the API, refuses the TUI route, and exits 0 on shutdown', async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wz-headless-'));
+    const app = path.join(dir, 'app');
+    fs.mkdirSync(app);
+    const socketPath = path.join(dir, 'w.sock');
+    const env = { ...process.env };
+    delete env.POSTHOG_WIZARD_API_KEY;
+    child = spawn(
+      path.join(REPO, 'node_modules/.bin/tsx'),
+      [
+        'bin.ts',
+        `--${HEADLESS_FLAG}`,
+        '--control-socket',
+        socketPath,
+        '--api-key',
+        'phx_test_only',
+        '--project-id',
+        '1',
+        '--region',
+        'us',
+        '--install-dir',
+        app,
+      ],
+      { cwd: REPO, env, stdio: ['ignore', 'pipe', 'pipe'] },
+    );
+    const exit = new Promise<number | null>((resolve) =>
+      child!.once('exit', (code) => resolve(code)),
+    );
+    await waitForSocket(socketPath, 90_000);
+    expect(fs.statSync(socketPath).mode & 0o777).toBe(0o600);
+
+    const client = new ControlClient(socketPath);
+    expect(await client.health()).toMatchObject({
+      surface: 'headless',
+      program: 'posthog-integration',
+    });
+    const state = await client.state();
+    expect(state.currentScreen).toBe('intro');
+    expect(state.run).toEqual({ status: 'idle', error: null });
+    expect(JSON.stringify(state)).not.toContain('phx_test_only');
+    await expect(client.startRun({ programId: 'nope' })).rejects.toMatchObject({
+      status: 400,
+    });
+    await expect(client.armRun()).rejects.toMatchObject({ status: 501 });
+    expect(await client.runs()).toEqual([]);
+
+    await client.shutdown();
+    expect(await exit).toBe(0);
+    expect(fs.existsSync(socketPath)).toBe(false);
+  }, 120_000);
+});
diff --git a/e2e-harness/__tests__/control-socket-tui.test.ts b/e2e-harness/__tests__/control-socket-tui.test.ts
new file mode 100644
index 000000000..4c202128a
--- /dev/null
+++ b/e2e-harness/__tests__/control-socket-tui.test.ts
@@ -0,0 +1,82 @@
+/**
+ * The controlled TUI surface: the real screens in a PTY, driven over the
+ * socket exactly as the snapshot route and the MCP proxy drive them. Stops
+ * before auth, so no credentials and no agent run.
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { ControlClient } from '@store/control';
+import { Program } from '@store/programs';
+import { buildLaunch, waitForSocket } from '@e2e-harness/launch';
+import { captureTui, type TuiCapture } from '@e2e-harness/tui-capture';
+
+const REPO = path.resolve(__dirname, '../..');
+let cap: TuiCapture | null = null;
+let dir: string | null = null;
+
+afterEach(() => {
+  cap?.kill();
+  cap = null;
+  if (dir) fs.rmSync(dir, { recursive: true, force: true });
+  dir = null;
+});
+
+describe.skipIf(process.env.WIZARD_PTY_TESTS === '0')(
+  'controlled TUI surface',
+  () => {
+    it('renders the intro, commits over the socket, refuses the headless route, and exits 0', async () => {
+      dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wz-tui-'));
+      const app = path.join(dir, 'app');
+      fs.mkdirSync(app);
+      const socketPath = path.join(dir, 'w.sock');
+      const launch = buildLaunch(
+        {
+          programId: Program.PostHogIntegration,
+          appDir: app,
+          socketPath,
+          projectId: '1',
+        },
+        REPO,
+      );
+      cap = captureTui({ ...launch, cwd: REPO });
+      await waitForSocket(socketPath, 90_000);
+      expect(fs.statSync(socketPath).mode & 0o777).toBe(0o600);
+
+      const client = new ControlClient(socketPath);
+      expect(await client.health()).toMatchObject({ surface: 'tui' });
+      const intro = await client.state();
+      expect(intro.currentScreen).toBe('intro');
+      expect(intro.actions.map((a) => a.id)).toEqual(['confirm_setup']);
+
+      let state = await client.performAction('confirm_setup');
+      // The readiness probe decides the health-check screen: wait for its verdict,
+      // then dismiss an outage the way a person would.
+      const deadline = Date.now() + 30_000;
+      while (state.currentScreen === 'health-check' && Date.now() < deadline) {
+        state = await client.waitForChange(state.version, 5_000);
+        if (state.currentScreen === 'health-check') {
+          const next = await client.performAction('dismiss_outage');
+          if (next.currentScreen !== 'health-check') state = next;
+        }
+      }
+      expect(state.currentScreen).toBe('auth');
+      expect(state.session.runRequested).toBe(false);
+      await expect(client.detect()).rejects.toMatchObject({ status: 501 });
+
+      const frameDeadline = Date.now() + 10_000;
+      while (
+        !cap.frame().includes('PostHog Wizard') &&
+        Date.now() < frameDeadline
+      ) {
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      expect(cap.frame()).toContain('PostHog Wizard');
+
+      await client.shutdown();
+      await cap.exited;
+      expect(fs.existsSync(socketPath)).toBe(false);
+    }, 120_000);
+  },
+);
diff --git a/e2e-harness/__tests__/e2e-flow-snapshot.test.ts b/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
index 72ac75930..49a3d0e68 100644
--- a/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
+++ b/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
@@ -28,7 +28,7 @@ import {
 } from '@store/programs/program-registry';
 import { ScreenId } from '@tui/router';
 import { SELF_DRIVING_INTEGRATE_PATH_KEY } from '@store/programs/self-driving/detect';
-import { WizardCiDriver } from '@e2e-harness/wizard-ci-driver';
+import { ControlDriver } from '@store/control';
 import {
   decideE2eAction,
   type WizardE2eProfile,
@@ -60,7 +60,10 @@ function traceFlow(
   }
   store.session = session;
 
-  const driver = new WizardCiDriver(store);
+  const driver = new ControlDriver(store, () => ({
+    status: 'idle',
+    error: null,
+  }));
 
   const trace: Array<{
     screen: string;
diff --git a/e2e-harness/__tests__/e2e-profile-ask.test.ts b/e2e-harness/__tests__/e2e-profile-ask.test.ts
index 6a9a2ed5f..715641aaa 100644
--- a/e2e-harness/__tests__/e2e-profile-ask.test.ts
+++ b/e2e-harness/__tests__/e2e-profile-ask.test.ts
@@ -19,7 +19,7 @@ import {
 } from '@e2e-harness/e2e-profile';
 import { profileFor, resolveE2eProfile } from '@e2e-harness/profiles';
 import { Program } from '@store/programs/program-registry';
-import type { CiState } from '@e2e-harness/wizard-ci-driver';
+import type { ControlState } from '@store/types';
 
 const text = (id: string, prompt = id): AskQuestion => ({
   id,
@@ -49,15 +49,15 @@ function profile(over: Partial<WizardE2eProfile> = {}): WizardE2eProfile {
   return { ...DEFAULT_E2E_PROFILE, ...over };
 }
 
-/** A CiState carrying just the fields the two overlay cases read. */
-function state(over: Partial<CiState>): CiState {
+/** A ControlState carrying just the fields the two overlay cases read. */
+function state(over: Partial<ControlState>): ControlState {
   return {
     currentScreen: ScreenId.Run,
     pendingQuestion: null,
     taskNotice: null,
     setupQuestions: [],
     ...over,
-  } as CiState;
+  } as ControlState;
 }
 
 describe('answerQuestions — the whole batch', () => {
@@ -490,7 +490,7 @@ describe('E2E_DRIVABLE_SCREENS', () => {
   it('has a decideE2eAction case for every screen it lists', () => {
     // A listed screen with no case would return `{ wait: true }` forever,
     // stalling the run instead of failing it.
-    const overlayState: Partial<Record<string, Partial<CiState>>> = {
+    const overlayState: Partial<Record<string, Partial<ControlState>>> = {
       [Overlay.WizardAsk]: {
         pendingQuestion: {
           id: 'a',
diff --git a/e2e-harness/__tests__/e2e-result.test.ts b/e2e-harness/__tests__/e2e-result.test.ts
index 2e00f93b2..03e97a8ca 100644
--- a/e2e-harness/__tests__/e2e-result.test.ts
+++ b/e2e-harness/__tests__/e2e-result.test.ts
@@ -23,7 +23,7 @@ import {
   readReportFile,
 } from '@e2e-harness/e2e-result';
 import { DEFAULT_E2E_PROFILE, decideE2eAction } from '@e2e-harness/e2e-profile';
-import type { CiState } from '@e2e-harness/wizard-ci-driver';
+import type { ControlState } from '@store/types';
 
 const SECRET = 'sk_live_do_not_leak_9f2b';
 
@@ -515,7 +515,7 @@ describe('security rail — no answer value reaches the payload', () => {
         pendingQuestion: pending,
         taskNotice: null,
         setupQuestions: [],
-      } as unknown as CiState,
+      } as unknown as ControlState,
       {
         ...DEFAULT_E2E_PROFILE,
         askAnswers: [{ match: 'stripe', value: SECRET }],
diff --git a/e2e-harness/__tests__/keyboard-equivalence.test.tsx b/e2e-harness/__tests__/keyboard-equivalence.test.tsx
index 1c4bb9d51..1aefd7f28 100644
--- a/e2e-harness/__tests__/keyboard-equivalence.test.tsx
+++ b/e2e-harness/__tests__/keyboard-equivalence.test.tsx
@@ -32,7 +32,7 @@ import {
   createServices,
   type ScreenServices,
 } from '@tui/screen-registry';
-import { ACTION_REGISTRY } from '@e2e-harness/action-registry';
+import { actionsFor } from '@store/control';
 import { flowFor } from '@store/programs/flow-for';
 import { UiStore } from '@tui/ui-store';
 
@@ -428,7 +428,7 @@ function applyAction(pair: Pair): Record<string, unknown> {
   const store = makeStore(pair);
   expect(store.currentScreen).toBe(pair.screen);
   const before = snap(store);
-  const action = ACTION_REGISTRY[pair.screen as ScreenId]?.find(
+  const action = actionsFor(flowFor(pair.program).flow, pair.screen).find(
     (a) => a.id === pair.action,
   );
   if (!action) throw new Error(`no action ${pair.action} on ${pair.screen}`);
diff --git a/e2e-harness/__tests__/launch.test.ts b/e2e-harness/__tests__/launch.test.ts
new file mode 100644
index 000000000..bb23c48ca
--- /dev/null
+++ b/e2e-harness/__tests__/launch.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from 'vitest';
+import { Program } from '@store/programs';
+import type { ProgramId } from '@store/types';
+import { buildLaunch, PROGRAM_COMMANDS } from '@e2e-harness/launch';
+import { hasProfile } from '@e2e-harness/profiles';
+
+const base = {
+  appDir: '/tmp/app',
+  socketPath: '/tmp/w/w.sock',
+  projectId: '228144',
+};
+
+describe('buildLaunch', () => {
+  it('launches every profiled program through its command words', () => {
+    for (const id of Object.keys(PROGRAM_COMMANDS)) {
+      expect(hasProfile(id), id).toBe(true);
+      const { args } = buildLaunch({ ...base, programId: id }, '/repo');
+      expect(args.slice(0, 1 + PROGRAM_COMMANDS[id]!.length)).toEqual([
+        'bin.ts',
+        ...PROGRAM_COMMANDS[id]!,
+      ]);
+    }
+  });
+
+  it('maps the run inputs to flags and keeps the key in the environment', () => {
+    const { cmd, args, env } = buildLaunch(
+      {
+        ...base,
+        programId: Program.SelfDriving,
+        apiKey: 'phx_secret',
+        region: 'eu',
+        e2eAsk: true,
+        integrate: true,
+        harness: 'pi',
+        sequence: 'orchestrator',
+        model: 'openai/gpt-5.6-terra',
+        taskStreamLog: '',
+        env: {
+          PATH: '/bin',
+          CLAUDE_CODE: '1',
+          ANTHROPIC_API_KEY: 'x',
+          AI_AGENT_X: 'y',
+          HOME: '/h',
+        },
+      },
+      '/repo',
+    );
+    expect(cmd).toBe('/repo/node_modules/.bin/tsx');
+    expect(args).toEqual([
+      'bin.ts',
+      'self-driving',
+      '--ci',
+      '--control-socket',
+      '/tmp/w/w.sock',
+      '--install-dir',
+      '/tmp/app',
+      '--project-id',
+      '228144',
+      '--region',
+      'eu',
+      '--e2e-ask',
+      '--integrate',
+      '--harness',
+      'pi',
+      '--sequence',
+      'orchestrator',
+      '--model',
+      'openai/gpt-5.6-terra',
+      '--task-stream-log',
+      '',
+    ]);
+    expect(args.join(' ')).not.toContain('phx_secret');
+    expect(env).toEqual({
+      PATH: '/bin',
+      HOME: '/h',
+      WIZARD_ASK_AUTODRIVE: '1',
+      POSTHOG_WIZARD_API_KEY: 'phx_secret',
+    });
+  });
+
+  it('drops an inherited key when the run has none', () => {
+    const { env, args } = buildLaunch(
+      {
+        ...base,
+        programId: Program.PostHogIntegration,
+        env: { POSTHOG_WIZARD_API_KEY: 'stale' },
+      },
+      '/repo',
+    );
+    expect(env.POSTHOG_WIZARD_API_KEY).toBeUndefined();
+    expect(args[1]).toBe('--ci');
+  });
+
+  it('refuses a program with no launch command', () => {
+    expect(() =>
+      buildLaunch({ ...base, programId: 'mcp-add' as ProgramId }, '/repo'),
+    ).toThrow(/no launch command/);
+  });
+});
diff --git a/e2e-harness/action-registry.ts b/e2e-harness/action-registry.ts
deleted file mode 100644
index 00d346777..000000000
--- a/e2e-harness/action-registry.ts
+++ /dev/null
@@ -1,402 +0,0 @@
-/**
- * Screen → action registry for the CI driver.
- *
- * Maps every screen/overlay to the set of *commit* actions a user could
- * perform on it — and, for each, the single WizardStore setter/resolver that
- * commit goes through. This is the actuation half of the driver: instead of
- * injecting keystrokes, a harness names an action and the driver invokes the
- * same store method the Ink screen's keyboard handler would.
- *
- * Discipline mirrors screen-registry.tsx: one entry per screen, kept exhaustive
- * by a test over the ScreenId/Overlay enums. No product knowledge leaks in —
- * actions speak only in store setters and generic params.
- */
-
-import type { WizardStore } from '@store/state/store';
-import { ScreenId, Overlay, type ScreenName } from '@tui/router';
-import { McpOutcome, OutroKind } from '@store/session/wizard-session';
-import type { AskAnswers } from '@store/session/wizard-session';
-import {
-  SOURCE_MAPS_CONTEXT_KEYS,
-  VARIANT_DISPLAY_NAME,
-} from '@store/programs/error-tracking-upload-source-maps';
-import {
-  GITHUB_REQUIRED_BODY,
-  GITHUB_REQUIRED_MESSAGE,
-} from '@store/programs/self-driving/detect';
-
-/** One commit action legal on a given screen. */
-export interface DriverAction {
-  /** Stable action id named in perform_action. */
-  id: string;
-  /** One-line description of what committing this does. */
-  description: string;
-  /**
-   * Parameter name → human/type hint. Absent = no params. The driver
-   * validates presence of required params before applying.
-   */
-  params?: Record<string, string>;
-  /** Apply the commit by calling exactly one store setter/resolver. */
-  apply: (store: WizardStore, params: Record<string, unknown>) => void;
-}
-
-/** Thrown when perform_action references a missing required param. */
-export class MissingParamError extends Error {
-  constructor(action: string, param: string) {
-    super(`Action "${action}" requires param "${param}".`);
-    this.name = 'MissingParamError';
-  }
-}
-
-function requireString(
-  action: string,
-  params: Record<string, unknown>,
-  key: string,
-): string {
-  const v = params[key];
-  if (typeof v !== 'string' || v.length === 0) {
-    throw new MissingParamError(action, key);
-  }
-  return v;
-}
-
-/**
- * Screens the driver does not commit an action on, listed explicitly so the
- * exhaustiveness test can tell "intentionally empty" from "forgotten". Two
- * kinds:
- *   - the runner or agent advances them: auth (runner sets credentials), run
- *     (agent sets runPhase), ai-opt-in (org approval / ci auto-consent), exit,
- *     and the no-dismiss terminal overlays.
- *   - screens of programs the integration e2e profile never enters (doctor).
- */
-export const NO_ACTION_SCREENS: ReadonlySet<ScreenName> = new Set<ScreenName>([
-  ScreenId.Auth,
-  ScreenId.Run,
-  ScreenId.AiOptIn,
-  ScreenId.Exit,
-  // The agent advances the audit run, the same way it advances `run`.
-  ScreenId.AuditRun,
-  ScreenId.DoctorReport,
-  // The detector + picker are interactive; no headless e2e drives this screen.
-  ScreenId.SelfDrivingIntegrationDetect,
-  ScreenId.SelfDrivingIntegrationCheck,
-  ScreenId.SelfDrivingIntegrationDetect,
-  ScreenId.SelfDrivingHandoff,
-  // The e2e host injects the pick, as it does for self-driving's detect screen.
-  ScreenId.ErrorTrackingDetect,
-  Overlay.ManagedSettings,
-  Overlay.AuthError,
-  Overlay.SessionTimeout,
-]);
-
-/**
- * Intro-style screens whose only action is "confirm and continue", committing
- * the same `setupConfirmed` flag the IntroScreen sets. Several programs reuse
- * this shape, so they share one action via this helper.
- */
-const confirmSetupAction: DriverAction = {
-  id: 'confirm_setup',
-  description: 'Confirm the intro and continue (sets setupConfirmed).',
-  apply: (store) => store.completeSetup(),
-};
-
-export const ACTION_REGISTRY: Partial<Record<ScreenName, DriverAction[]>> = {
-  // ── Program intros — confirm & continue ───────────────────────────────
-  [ScreenId.Intro]: [confirmSetupAction],
-  [ScreenId.RevenueIntro]: [confirmSetupAction],
-  [ScreenId.SourceMapsIntro]: [confirmSetupAction],
-  [ScreenId.MigrationIntro]: [confirmSetupAction],
-  [ScreenId.AgentSkillIntro]: [confirmSetupAction],
-  [ScreenId.AiObservabilityIntro]: [confirmSetupAction],
-  [ScreenId.MetricsIntro]: [confirmSetupAction],
-  [ScreenId.ErrorTrackingIntro]: [confirmSetupAction],
-  [ScreenId.AuditIntro]: [confirmSetupAction],
-  [ScreenId.DoctorIntro]: [confirmSetupAction],
-  [ScreenId.WarehouseIntro]: [confirmSetupAction],
-  [ScreenId.SelfDrivingIntro]: [confirmSetupAction],
-
-  // ── Self-driving integration check ────────────────────────────────────
-  [ScreenId.SelfDrivingIntegrationCheck]: [
-    {
-      id: 'set_integrate',
-      description:
-        'Answer the self-driving integration check. integrate=true sets up ' +
-        'the PostHog SDK first; false goes straight to Self-driving.',
-      params: { integrate: 'boolean (default false)' },
-      apply: (store, params) => store.setIntegrate(params.integrate === true),
-    },
-  ],
-
-  // ── Self-driving handoff (after the integration run) ───────────────────
-  [ScreenId.SelfDrivingHandoff]: [
-    {
-      id: 'confirm_self_driving_handoff',
-      description:
-        'Acknowledge the post-integration handoff and start the Self-driving run.',
-      apply: (store) => store.confirmSelfDrivingHandoff(),
-    },
-  ],
-
-  // ── Source-maps project pick + outro ───────────────────────────────────
-  [ScreenId.SourceMapsDetect]: [
-    {
-      id: 'pick_source_maps_project',
-      description:
-        'Commit the project to wire source-map upload for, as the detect ' +
-        "screen's picker would. The candidate list lives in the screen's " +
-        'agentic report, so the caller supplies the pick.',
-      params: {
-        variant: 'skill variant (e.g. "node", "nextjs")',
-        path: 'project path relative to the repo root ("." = root)',
-      },
-      apply: (store, params) => {
-        const variant = requireString(
-          'pick_source_maps_project',
-          params,
-          'variant',
-        );
-        const path = requireString('pick_source_maps_project', params, 'path');
-        store.setFrameworkContext(
-          SOURCE_MAPS_CONTEXT_KEYS.selectedVariant,
-          variant,
-        );
-        store.setFrameworkContext(
-          SOURCE_MAPS_CONTEXT_KEYS.selectedDisplayName,
-          (VARIANT_DISPLAY_NAME as Record<string, string>)[variant] ?? variant,
-        );
-        store.setFrameworkContext(SOURCE_MAPS_CONTEXT_KEYS.selectedPath, path);
-      },
-    },
-  ],
-  [ScreenId.SourceMapsOutro]: [
-    {
-      id: 'dismiss_outro',
-      description: 'Dismiss the source-maps outro (sets outroDismissed).',
-      apply: (store) => store.setOutroDismissed(),
-    },
-  ],
-
-  // ── Health check — dismiss a blocking outage ──────────────────────────
-  [ScreenId.HealthCheck]: [
-    {
-      id: 'dismiss_outage',
-      description: 'Dismiss the blocking outage screen and continue.',
-      apply: (store) => store.dismissOutage(),
-    },
-  ],
-
-  // ── Framework disambiguation ──────────────────────────────────────────
-  [ScreenId.Setup]: [
-    {
-      id: 'choose',
-      description:
-        'Answer one setup question by committing a framework-context value. ' +
-        'Read read_state.setupQuestions for the key and allowed values.',
-      params: { key: 'setup question key', value: 'chosen option value' },
-      apply: (store, params) => {
-        const key = requireString('choose', params, 'key');
-        const value = requireString('choose', params, 'value');
-        store.setFrameworkContext(key, value);
-      },
-    },
-  ],
-
-  // ── Outro ─────────────────────────────────────────────────────────────
-  [ScreenId.Outro]: [
-    {
-      id: 'dismiss_outro',
-      description: 'Dismiss the outro and advance to the MCP step.',
-      apply: (store) => store.setOutroDismissed(),
-    },
-  ],
-  [ScreenId.AuditOutro]: [
-    {
-      id: 'dismiss_outro',
-      description:
-        'Dismiss the audit outro, which carries the report, dashboard, and notebook links.',
-      apply: (store) => store.setOutroDismissed(),
-    },
-  ],
-  [ScreenId.MintFailure]: [
-    {
-      id: 'continue_setup',
-      description: 'Continue to MCP and Slack after the skill is saved.',
-      apply: (store) => store.setMintHandoff('continue'),
-    },
-    {
-      id: 'dismiss_outro',
-      description: 'Exit the wizard from the mint failure screen.',
-      apply: (store) => store.setMintHandoff('exit'),
-    },
-  ],
-
-  // ── MCP install ───────────────────────────────────────────────────────
-  [ScreenId.Mcp]: [
-    {
-      id: 'set_mcp_outcome',
-      description:
-        'Complete the MCP step. outcome ∈ {installed, skipped}; clients optional.',
-      params: {
-        outcome: '"installed" | "skipped"',
-        clients: 'string[] (optional)',
-      },
-      apply: (store, params) => {
-        const raw = (params.outcome as string) ?? 'skipped';
-        const outcome =
-          raw === 'installed' ? McpOutcome.Installed : McpOutcome.Skipped;
-        const clients = Array.isArray(params.clients)
-          ? (params.clients as string[])
-          : [];
-        store.setMcpComplete(outcome, clients);
-      },
-    },
-  ],
-  [ScreenId.McpAdd]: [
-    {
-      id: 'set_mcp_outcome',
-      description: 'Complete the standalone MCP-add flow.',
-      params: { outcome: '"installed" | "skipped"' },
-      apply: (store, params) => {
-        const raw = (params.outcome as string) ?? 'skipped';
-        store.setMcpComplete(
-          raw === 'installed' ? McpOutcome.Installed : McpOutcome.Skipped,
-        );
-      },
-    },
-  ],
-  [ScreenId.McpRemove]: [
-    {
-      id: 'set_mcp_outcome',
-      description: 'Complete the standalone MCP-remove flow.',
-      params: { outcome: '"installed" | "skipped"' },
-      apply: (store, params) => {
-        const raw = (params.outcome as string) ?? 'skipped';
-        store.setMcpComplete(
-          raw === 'installed' ? McpOutcome.Installed : McpOutcome.Skipped,
-        );
-      },
-    },
-  ],
-  [ScreenId.McpSuggestedPrompts]: [
-    {
-      id: 'dismiss',
-      description: 'Dismiss the suggested-prompts step.',
-      apply: (store) => store.setMcpSuggestedPromptsDismissed(),
-    },
-  ],
-
-  // ── Slack ─────────────────────────────────────────────────────────────
-  [ScreenId.SelfDrivingGithub]: [
-    {
-      id: 'set_github_connected',
-      description: 'Resolve the GitHub App connection check',
-      params: { connected: 'boolean' },
-      apply: (store, params) =>
-        store.setGithubConnected(params.connected !== false),
-    },
-    {
-      id: 'decline_github',
-      description: 'Answer "I can\'t connect right now" and end the run',
-      apply: (store) =>
-        store.declineGithub({
-          kind: OutroKind.Cancel,
-          message: GITHUB_REQUIRED_MESSAGE,
-          body: GITHUB_REQUIRED_BODY,
-        }),
-    },
-  ],
-  [ScreenId.SlackConnect]: [
-    {
-      id: 'dismiss_slack',
-      description: 'Skip or finish the Connect-Slack step.',
-      apply: (store) => store.setSlackStepDismissed(),
-    },
-    {
-      id: 'set_slack_connected',
-      description: 'Mark Slack as connected (then dismiss to advance).',
-      params: { connected: 'boolean' },
-      apply: (store, params) =>
-        store.setSlackConnected(params.connected !== false),
-    },
-  ],
-
-  // ── Keep skills (terminal step of the integration flow) ───────────────
-  [ScreenId.KeepSkills]: [
-    {
-      id: 'keep_skills',
-      description:
-        'Decide whether to keep installed skills; completes the run.',
-      params: { kept: 'boolean (default true)' },
-      apply: (store, params) => store.setSkillsComplete(params.kept !== false),
-    },
-  ],
-
-  // ── Overlays ──────────────────────────────────────────────────────────
-  [Overlay.WizardAsk]: [
-    {
-      id: 'answer_question',
-      description:
-        'Resolve the pending wizard_ask request. Supply a complete answers ' +
-        'map: { [questionId]: string | string[] }. See read_state.pendingQuestion.',
-      params: { answers: 'Record<questionId, string | string[]>' },
-      apply: (store, params) => {
-        const answers = (params.answers ?? {}) as AskAnswers;
-        store.resolvePendingQuestion(answers);
-      },
-    },
-    {
-      id: 'cancel_question',
-      description: 'Cancel the pending wizard_ask request (sentinel answers).',
-      apply: (store) => store.cancelPendingQuestion(),
-    },
-  ],
-  [Overlay.TaskNotice]: [
-    {
-      id: 'resolve_notice',
-      description:
-        'Resolve the task-notice overlay a program shows before an optional ' +
-        'step. keep=true runs the step, keep=false skips it. See ' +
-        'read_state.taskNotice.',
-      params: { keep: 'boolean (default true)' },
-      apply: (store, params) => store.resolveTaskNotice(params.keep !== false),
-    },
-  ],
-  [Overlay.SettingsOverride]: [
-    {
-      id: 'backup_and_fix',
-      description: 'Back up and fix conflicting .claude/settings.json.',
-      apply: (store) => {
-        store.backupAndFixSettingsOverride();
-      },
-    },
-  ],
-  [Overlay.PortConflict]: [
-    {
-      id: 'resolve_port_conflict',
-      description:
-        'Dismiss the port-conflict overlay and retry the OAuth port loop.',
-      apply: (store) => store.resolvePortConflict(),
-    },
-  ],
-  [Overlay.ManualAuthCode]: [
-    {
-      id: 'submit_auth_code',
-      description: 'Submit a manually-entered OAuth authorization code.',
-      params: { code: 'authorization code' },
-      apply: (store, params) =>
-        store.submitManualAuthCode(
-          requireString('submit_auth_code', params, 'code'),
-        ),
-    },
-    {
-      id: 'dismiss_auth_code',
-      description: 'Dismiss the manual auth-code overlay without submitting.',
-      apply: (store) => store.dismissManualAuthCode(),
-    },
-  ],
-};
-
-/** Actions legal on the given screen — empty array if none. */
-export function actionsForScreen(screen: ScreenName): DriverAction[] {
-  return ACTION_REGISTRY[screen] ?? [];
-}
diff --git a/e2e-harness/e2e-profile.ts b/e2e-harness/e2e-profile.ts
index 9ea905962..e24401a32 100644
--- a/e2e-harness/e2e-profile.ts
+++ b/e2e-harness/e2e-profile.ts
@@ -9,7 +9,13 @@
 
 import { ScreenId, Overlay, type ScreenName } from '@tui/router';
 import type { AskAnswers, AskQuestion } from '@store/session/wizard-session';
-import type { CiState } from '@e2e-harness/wizard-ci-driver';
+import type { ControlState } from '@store/types';
+
+/** The slice of the control state a decision reads. */
+export type E2eObservedState = Pick<
+  ControlState,
+  'currentScreen' | 'setupQuestions' | 'pendingQuestion' | 'taskNotice'
+>;
 
 /** Which option to pick for a setup disambiguation question. */
 export type SetupChoice = 'first' | 'last';
@@ -273,7 +279,7 @@ function acceptsSecret(question: AskQuestion): boolean {
  * not doing that.
  */
 export function decideE2eAction(
-  state: CiState,
+  state: E2eObservedState,
   profile: WizardE2eProfile,
 ): E2eDecision {
   switch (state.currentScreen) {
diff --git a/e2e-harness/e2e-result.ts b/e2e-harness/e2e-result.ts
index d3d245fb6..50a8c30dc 100644
--- a/e2e-harness/e2e-result.ts
+++ b/e2e-harness/e2e-result.ts
@@ -1,7 +1,8 @@
+import type { OutroData, PendingQuestion } from '@store/session/wizard-session';
 /**
  * The structured record an e2e run writes to `E2E_RESULT_JSON`.
  *
- * Split out of `scripts/tui-host.no-jest.ts` so the shape, and the security
+ * Kept apart from `scripts/tui-snapshots.no-jest.ts` so the shape, and the security
  * rail that guards it, can be unit-tested without booting a TUI.
  *
  * Two halves:
@@ -21,7 +22,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { OutroKind, type WizardSession } from '@store/session/wizard-session';
+import { OutroKind } from '@store/session/wizard-session';
 import { DETECTED_WAREHOUSE_SOURCES_KEY } from '@store/programs/warehouse-source/detect';
 import type { DetectedSource } from '@store/services/warehouse-sources/types';
 import type { E2eDecisionReport } from '@e2e-harness/e2e-profile';
@@ -55,7 +56,16 @@ export interface E2eNoticeRecord {
 }
 
 /** The session fields the recorder watches. */
-type ObservedSession = Pick<WizardSession, 'pendingQuestion' | 'taskNotice'>;
+type ObservedSession = {
+  pendingQuestion: PendingQuestion | null;
+  taskNotice: { title: string; items?: string[] } | null;
+};
+
+/** The outro fields the payload reads; the control state carries exactly these. */
+export type E2eOutro = Pick<
+  OutroData,
+  'kind' | 'errorCode' | 'message' | 'body'
+>;
 
 /**
  * Log every ask batch and task notice a run passes through.
@@ -203,18 +213,18 @@ function isInside(root: string, child: string): boolean {
  * `wizardAbort` renders an error outro and then exits, so `outroData` is the
  * only durable trace of *why* by the time the host writes its result.
  */
-export function abortReasonFrom(
-  session: Pick<WizardSession, 'outroData'>,
-): string | null {
+export function abortReasonFrom(session: {
+  outroData: E2eOutro | null;
+}): string | null {
   const outro = session.outroData;
   if (!outro || outro.kind !== OutroKind.Error) return null;
   return outro.message ?? outro.body ?? 'aborted';
 }
 
 /** The warehouse sources detection wrote into frameworkContext. */
-export function detectedSourcesFrom(
-  session: Pick<WizardSession, 'frameworkContext'>,
-): DetectedSource[] {
+export function detectedSourcesFrom(session: {
+  frameworkContext: Record<string, unknown>;
+}): DetectedSource[] {
   const raw = session.frameworkContext[DETECTED_WAREHOUSE_SOURCES_KEY];
   return Array.isArray(raw) ? (raw as DetectedSource[]) : [];
 }
@@ -236,7 +246,10 @@ export interface E2eResultBase {
 export function buildE2eResult(args: {
   base: E2eResultBase;
   recorder: E2eRunRecorder;
-  session: Pick<WizardSession, 'frameworkContext' | 'outroData'>;
+  session: {
+    frameworkContext: Record<string, unknown>;
+    outroData: E2eOutro | null;
+  };
   tasks: Array<{ label: string; status: string }>;
   reportFile: E2eReportFile | null;
 }): Record<string, unknown> {
diff --git a/e2e-harness/launch.ts b/e2e-harness/launch.ts
new file mode 100644
index 000000000..f3aaf3635
--- /dev/null
+++ b/e2e-harness/launch.ts
@@ -0,0 +1,109 @@
+/**
+ * How the harness starts a controlled wizard: the real binary, `--ci` for
+ * API-key auth, `--control-socket` for the parent, one program per command.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { Program } from '@store/programs';
+import type { ProgramId } from '@store/types';
+
+/** The command words that launch each program; the default flow has none. */
+export const PROGRAM_COMMANDS: Partial<Record<ProgramId, readonly string[]>> = {
+  [Program.PostHogIntegration]: [],
+  [Program.AiObservability]: ['ai-observability'],
+  [Program.Metrics]: ['metrics'],
+  [Program.ReplayVision]: ['replay-vision'],
+  [Program.SelfDriving]: ['self-driving'],
+  [Program.ErrorTrackingUploadSourceMaps]: ['upload-source-maps'],
+  [Program.ErrorTracking]: ['error-tracking'],
+  [Program.WarehouseSource]: ['warehouse'],
+  [Program.Audit]: ['audit', 'all'],
+};
+
+export interface LaunchOptions {
+  programId: ProgramId;
+  appDir: string;
+  socketPath: string;
+  projectId: string;
+  region?: 'us' | 'eu';
+  /** The personal API key. Travels in the environment, never in argv. */
+  apiKey?: string;
+  /** Keep `wizard_ask` wired so the parent answers the agent's questions. */
+  e2eAsk?: boolean;
+  /** Self-driving only: skip the integration check and integrate first. */
+  integrate?: boolean;
+  harness?: string;
+  sequence?: string;
+  model?: string;
+  /** Dump task-stream payloads; '' means the default path. */
+  taskStreamLog?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface Launch {
+  cmd: string;
+  args: string[];
+  env: NodeJS.ProcessEnv;
+}
+
+/** Outer agent credentials would make the wizard's agent defer to them. */
+const STRIPPED_ENV = /^(CLAUDE|ANTHROPIC|AI_AGENT)/;
+
+export function buildLaunch(o: LaunchOptions, cwd = process.cwd()): Launch {
+  const words = PROGRAM_COMMANDS[o.programId];
+  if (!words) throw new Error(`no launch command for program ${o.programId}`);
+  const args = [
+    'bin.ts',
+    ...words,
+    '--ci',
+    '--control-socket',
+    o.socketPath,
+    '--install-dir',
+    o.appDir,
+    '--project-id',
+    o.projectId,
+    '--region',
+    o.region ?? 'us',
+  ];
+  if (o.e2eAsk) args.push('--e2e-ask');
+  if (o.integrate === true && o.programId === Program.SelfDriving)
+    args.push('--integrate');
+  if (o.harness) args.push('--harness', o.harness);
+  if (o.sequence) args.push('--sequence', o.sequence);
+  if (o.model) args.push('--model', o.model);
+  if (o.taskStreamLog !== undefined)
+    args.push('--task-stream-log', o.taskStreamLog);
+
+  const env: NodeJS.ProcessEnv = {};
+  for (const [k, v] of Object.entries(o.env ?? process.env)) {
+    if (!STRIPPED_ENV.test(k)) env[k] = v;
+  }
+  // The linear sequence honours this; the orchestrator asks regardless.
+  env.WIZARD_ASK_AUTODRIVE = '1';
+  if (o.apiKey) env.POSTHOG_WIZARD_API_KEY = o.apiKey;
+  else delete env.POSTHOG_WIZARD_API_KEY;
+  return { cmd: path.join(cwd, 'node_modules/.bin/tsx'), args, env };
+}
+
+/** Resolve once the wizard listens on its socket, or reject after `timeoutMs`. */
+export async function waitForSocket(
+  socketPath: string,
+  timeoutMs: number,
+): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(socketPath)) return;
+    await new Promise((r) => setTimeout(r, 150));
+  }
+  throw new Error(
+    `the wizard did not open ${socketPath} within ${timeoutMs}ms`,
+  );
+}
+
+/** The key from the environment: inline first, else the key file. */
+export function readApiKey(env: NodeJS.ProcessEnv = process.env): string {
+  return (
+    env.POSTHOG_PERSONAL_API_KEY ??
+    (env.POSTHOG_KEY_FILE ? fs.readFileSync(env.POSTHOG_KEY_FILE, 'utf8') : '')
+  ).trim();
+}
diff --git a/e2e-harness/picks.ts b/e2e-harness/picks.ts
new file mode 100644
index 000000000..ba407cf97
--- /dev/null
+++ b/e2e-harness/picks.ts
@@ -0,0 +1,101 @@
+/**
+ * The detection picks a headless run supplies where the real screen would show
+ * an interactive picker: the project to set up, and the source-maps variant.
+ * Computed here, on the parent's side of the socket, and committed through the
+ * program's control actions.
+ */
+import * as fs from 'node:fs';
+import { join } from 'node:path';
+import { FRAMEWORK_REGISTRY, buildSession } from '@store';
+import { detectFramework } from '@store/detection';
+import {
+  detectSourceMapsPrerequisites,
+  SOURCE_MAPS_CONTEXT_KEYS,
+} from '@store/programs';
+import type { Integration } from '@store/types';
+
+/**
+ * The repo root for a single app, else the first instrumentable sub-app of a
+ * monorepo under `apps/` or `packages/`.
+ */
+export async function pickIntegrationTarget(
+  root: string,
+): Promise<{ integration: Integration; path: string } | null> {
+  for (const group of ['apps', 'packages']) {
+    let entries: string[];
+    try {
+      entries = fs.readdirSync(join(root, group)).sort();
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const rel = `${group}/${name}`;
+      if (!fs.statSync(join(root, rel)).isDirectory()) continue;
+      const fw = await detectFramework(join(root, rel));
+      if (fw && FRAMEWORK_REGISTRY[fw]) return { integration: fw, path: rel };
+    }
+  }
+  const rootFw = await detectFramework(root);
+  return rootFw && FRAMEWORK_REGISTRY[rootFw]
+    ? { integration: rootFw, path: '.' }
+    : null;
+}
+
+/**
+ * The variant to drive when the static prerequisite detector names none: the
+ * platform it recognised but would not automate, else the manifest that
+ * identifies a Go, Rust, Flutter, iOS, or Android fixture.
+ */
+export function nativeVariantFor(
+  root: string,
+  detectError: unknown,
+): string | null {
+  const detected = (detectError as { detected?: string } | undefined)?.detected;
+  if (detected && detected !== 'unknown') return detected;
+  const manifests: ReadonlyArray<readonly [string, string]> = [
+    ['go.mod', 'go'],
+    ['Cargo.toml', 'rust'],
+    ['pubspec.yaml', 'flutter'],
+    ['Package.swift', 'ios'],
+    ['settings.gradle.kts', 'android'],
+    ['settings.gradle', 'android'],
+  ];
+  for (const [file, variant] of manifests) {
+    if (fs.existsSync(join(root, file))) return variant;
+  }
+  try {
+    if (
+      fs
+        .readdirSync(root)
+        .some((f) => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))
+    ) {
+      return 'ios';
+    }
+  } catch {
+    /* unreadable root: the caller reports the original detect error */
+  }
+  return null;
+}
+
+/** The source-maps variant for a fixture, or the detect error when none applies. */
+export function pickSourceMapsVariant(
+  root: string,
+): { variant: string; fallback: boolean } | { error: unknown } {
+  const ctx: Record<string, unknown> = {};
+  detectSourceMapsPrerequisites(
+    buildSession({ installDir: root }),
+    (k: string, v: unknown) => {
+      ctx[k] = v;
+    },
+  );
+  const detected = ctx[SOURCE_MAPS_CONTEXT_KEYS.skillVariant];
+  if (typeof detected === 'string')
+    return { variant: detected, fallback: false };
+  const native = nativeVariantFor(
+    root,
+    ctx[SOURCE_MAPS_CONTEXT_KEYS.detectError],
+  );
+  return native
+    ? { variant: native, fallback: true }
+    : { error: ctx[SOURCE_MAPS_CONTEXT_KEYS.detectError] };
+}
diff --git a/e2e-harness/wizard-ci-driver.ts b/e2e-harness/wizard-ci-driver.ts
deleted file mode 100644
index c068d95e9..000000000
--- a/e2e-harness/wizard-ci-driver.ts
+++ /dev/null
@@ -1,220 +0,0 @@
-/**
- * WizardCiDriver — the read/act control plane over a live WizardStore.
- *
- * This is the read/act core both e2e routes drive. A test harness or a driver
- * LLM uses these primitives to run a real wizard end-to-end without keystrokes:
- *
- *   readState()      — a truthful projection of the committed store state
- *                      (the same state the Ink render is a pure function of),
- *                      plus the derived currentScreen/hasOverlay so the snapshot
- *                      is complete without reaching into router internals.
- *   listActions()    — the commit actions legal on the current screen.
- *   performAction()  — invoke one, via the exact store setter the Ink screen's
- *                      keyboard handler would call, and return the next state.
- *
- * It observes *committed* state and actuates *commits*. In-progress keystroke
- * state (typed-but-unsubmitted text, highlighted option, the wizard_ask
- * per-question accumulator) is React-local and deliberately invisible here —
- * the driver issues the final commit directly instead.
- */
-
-import type { WizardStore } from '@store/state/store';
-import type { ScreenName } from '@tui/router';
-import type { PendingQuestion, RunPhase } from '@store/session/wizard-session';
-import {
-  actionsForScreen,
-  MissingParamError,
-} from '@e2e-harness/action-registry';
-
-/** A setup question projected for the harness (no `detect` fn, no closures). */
-export interface SetupQuestionView {
-  key: string;
-  message: string;
-  options: Array<{ label: string; value: string; hint?: string }>;
-}
-
-/** The action surface as seen by a caller (no `apply` closure). */
-export interface ActionView {
-  id: string;
-  description: string;
-  params?: Record<string, string>;
-}
-
-/**
- * A task notice projected for the harness. Title, items and prompt only — the
- * decision function needs to know a notice is up and what it covers, not the
- * full body copy the screen renders.
- */
-export interface TaskNoticeView {
-  title: string;
-  items: string[];
-  prompt: string;
-}
-
-/**
- * The serialized observable state. A whitelist of WizardSession — credentials
- * are reduced to a boolean so secrets never reach a driver LLM.
- */
-export interface CiState {
-  currentScreen: ScreenName;
-  hasOverlay: boolean;
-  runPhase: RunPhase;
-  session: {
-    installDir: string;
-    integration: string | null;
-    detectedFrameworkLabel: string | null;
-    detectionComplete: boolean;
-    setupConfirmed: boolean;
-    /** Self-driving integration-check answer; null until decided. */
-    integrate: boolean | null;
-    hasCredentials: boolean;
-    projectId: number | null;
-    mcpComplete: boolean;
-    slackStepDismissed: boolean;
-    skillsComplete: boolean;
-    outroDismissed: boolean;
-    llmOptIn: boolean;
-    discoveredFeatures: string[];
-  };
-  tasks: Array<{ label: string; status: string; activeForm?: string }>;
-  statusMessages: string[];
-  eventPlan: Array<{ name: string; description: string }>;
-  /** Present iff a wizard_ask overlay is up. */
-  pendingQuestion: PendingQuestion | null;
-  /** Present iff a task-notice overlay is up. */
-  taskNotice: TaskNoticeView | null;
-  /** Unresolved framework-setup questions when on the setup screen. */
-  setupQuestions: SetupQuestionView[];
-  /** Commit actions legal on currentScreen. */
-  actions: ActionView[];
-}
-
-export class UnknownActionError extends Error {
-  constructor(action: string, screen: ScreenName) {
-    super(
-      `No action "${action}" on screen "${screen}". ` +
-        `Call list_actions / read read_state.actions first.`,
-    );
-    this.name = 'UnknownActionError';
-  }
-}
-
-export class WizardCiDriver {
-  constructor(private readonly store: WizardStore) {}
-
-  /** Snapshot the committed state plus the derived screen. */
-  readState(): CiState {
-    const s = this.store.session;
-    const screen = this.store.currentScreen as ScreenName;
-    return {
-      currentScreen: screen,
-      hasOverlay: this.store.hasInterrupt,
-      runPhase: s.runPhase,
-      session: {
-        installDir: s.installDir,
-        integration: s.integration,
-        detectedFrameworkLabel: s.detectedFrameworkLabel,
-        detectionComplete: s.detectionComplete,
-        setupConfirmed: s.setupConfirmed,
-        integrate: s.integrate,
-        hasCredentials: s.credentials !== null,
-        projectId: s.credentials?.projectId ?? null,
-        mcpComplete: s.mcpComplete,
-        slackStepDismissed: s.slackStepDismissed,
-        skillsComplete: s.skillsComplete,
-        outroDismissed: s.outroDismissed,
-        llmOptIn: s.llmOptIn,
-        discoveredFeatures: [...s.discoveredFeatures],
-      },
-      tasks: this.store.tasks.map((t) => ({
-        label: t.label,
-        status: t.status,
-        activeForm: t.activeForm,
-      })),
-      statusMessages: [...this.store.statusMessages],
-      eventPlan: this.store.eventPlan.map((e) => ({
-        name: e.name,
-        description: e.description,
-      })),
-      pendingQuestion: s.pendingQuestion ?? null,
-      taskNotice: s.taskNotice
-        ? {
-            title: s.taskNotice.title,
-            items: [...(s.taskNotice.items ?? [])],
-            prompt: s.taskNotice.prompt,
-          }
-        : null,
-      setupQuestions: this.unresolvedSetupQuestions(),
-      actions: this.listActions(),
-    };
-  }
-
-  /** Exposed through read_state.actions; there is no list_actions MCP tool. */
-  listActions(): ActionView[] {
-    return actionsForScreen(this.store.currentScreen as ScreenName).map(
-      (a) => ({
-        id: a.id,
-        description: a.description,
-        ...(a.params ? { params: a.params } : {}),
-      }),
-    );
-  }
-
-  /**
-   * Apply a named action via its store setter, then return the next state.
-   * Throws UnknownActionError if the action isn't legal on the current screen,
-   * or MissingParamError if a required param is absent.
-   */
-  performAction(
-    actionId: string,
-    params: Record<string, unknown> = {},
-  ): CiState {
-    const screen = this.store.currentScreen as ScreenName;
-    const action = actionsForScreen(screen).find((a) => a.id === actionId);
-    if (!action) throw new UnknownActionError(actionId, screen);
-    action.apply(this.store, params); // may throw MissingParamError
-    return this.readState();
-  }
-
-  /**
-   * Resolve once the rendered screen changes (or a wizard_ask overlay opens),
-   * or after timeoutMs. Lets a driver loop block on the next decision point
-   * instead of polling — the store fires its version listener on every commit,
-   * including the agent's getUI() calls.
-   */
-  waitForChange(timeoutMs = 120_000): Promise<CiState> {
-    const before = this.store.currentScreen;
-    return new Promise<CiState>((resolve) => {
-      let settled = false;
-      const finish = () => {
-        if (settled) return;
-        settled = true;
-        clearTimeout(timer);
-        unsub();
-        resolve(this.readState());
-      };
-      const timer = setTimeout(finish, timeoutMs);
-      const unsub = this.store.subscribe(() => {
-        if (this.store.currentScreen !== before) finish();
-      });
-    });
-  }
-
-  private unresolvedSetupQuestions(): SetupQuestionView[] {
-    const s = this.store.session;
-    const questions = s.frameworkConfig?.metadata.setup?.questions ?? [];
-    return questions
-      .filter((q) => !(q.key in s.frameworkContext))
-      .map((q) => ({
-        key: q.key,
-        message: q.message,
-        options: q.options.map((o) => ({
-          label: o.label,
-          value: o.value,
-          ...(o.hint ? { hint: o.hint } : {}),
-        })),
-      }));
-  }
-}
-
-export { MissingParamError };
diff --git a/scripts/README.md b/scripts/README.md
index 725eda866..90b7d408a 100644
--- a/scripts/README.md
+++ b/scripts/README.md
@@ -2,50 +2,55 @@
 
 Helper scripts. The build-related ones (`generate-version.cjs`,
 `smoke-test*.sh`, `check-screens.tsx`) are wired into `package.json`. The rest
-below are **manual, runnable tools** for headless e2e + snapshots — each is a
-standalone `tsx` entry, named `*.no-jest.ts` so Jest ignores it.
+below are **manual, runnable tools** for headless e2e and snapshots. Each is a
+standalone `tsx` entry, named `*.no-jest.ts` so the test runners ignore it.
 
 Run from the repo root, e.g. `npx tsx scripts/<name>.no-jest.ts`.
 
-Both e2e routes share one primitive: the **real TUI host** runs `startTUI` (the
-real ink render) and is driven purely by store state manipulation; a PTY parent
-([`e2e-harness/tui-capture.ts`](../e2e-harness/tui-capture.ts), node-pty +
-`@xterm/headless`) captures the real rendered screen.
+Both e2e routes spawn the real wizard with `--ci --control-socket` in a PTY
+([`e2e-harness/tui-capture.ts`](../e2e-harness/tui-capture.ts), node-pty and
+`@xterm/headless`) and drive it over the control API
+([`src/store/control/`](../src/store/control/)). See
+[`e2e-harness/ARCHITECTURE.md`](../e2e-harness/ARCHITECTURE.md).
 
-| Script                          | What it does                                                                                                                                                                                          | Needs                                                              |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| **`tui-host.no-jest.ts`** | Real TUI host: `MODE=fixed` follows a profile; `MODE=serve` accepts socket commands. | `APP_DIR`, `PROJECT_ID`, key for a full run, `SNAP_CTRL`; run under a PTY, with `CONTROL_SOCK` in serve mode |
-| **`tui-snapshots.no-jest.ts`** | Runs the fixed host and saves colored `SNAP_OUT/NN-<screen>.ans` frames, including within-screen progress. | `SNAP_OUT`, `APP_DIR`, `PROJECT_ID`, `POSTHOG_KEY_FILE` or `POSTHOG_PERSONAL_API_KEY` |
-| **`wizard-ci-mcp.no-jest.ts`** | Stdio MCP server: `open_app`, `read_state`, `perform_action`, `render_screen`, `run_agent`. Screen output is plain text. | Spawns the host; `open_app` requires `appDir` and `projectId`, with optional `keyFile`, `apiKey`, `region` |
-| **`chunk-manifest.no-jest.ts`** | Prints a structural manifest of `dist/`: per chunk, the source files it contains and the chunks it imports, hash suffixes stripped. Baselines live in `scripts/__fixtures__/chunk-manifest.{prod,ci}.json`. | A built `dist/` |
-| **`wizard-ci-explore.no-jest.ts`** | `pnpm wizard-ci-explore`: opens an app, confirms setup, reads state, prints one frame, and exits. It does not run the agent. | `APP_DIR`, `PROJECT_ID`; optional `POSTHOG_KEY_FILE` |
+| Script                             | What it does                                                                                                                                                                                                | Needs                                                                                                                         |
+| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| **`tui-snapshots.no-jest.ts`**     | Drives the program's fixed e2e profile over the socket and saves colored `SNAP_OUT/NN-<screen>.ans` frames, including within-screen progress. Writes `E2E_RESULT_JSON` when set.                            | `SNAP_OUT`, `APP_DIR`, `PROJECT_ID`, `POSTHOG_KEY_FILE` or `POSTHOG_PERSONAL_API_KEY`; `E2E_ASK=true` for ask-driven programs |
+| **`wizard-ci-mcp.no-jest.ts`**     | Stdio MCP server: `open_app`, `read_state`, `perform_action`, `render_screen`, `run_agent`. Screen output is plain text.                                                                                    | `open_app` requires `appDir` and `projectId`, with optional `keyFile`, `apiKey`, `region`                                     |
+| **`chunk-manifest.no-jest.ts`**    | Prints a structural manifest of `dist/`: per chunk, the source files it contains and the chunks it imports, hash suffixes stripped. Baselines live in `scripts/__fixtures__/chunk-manifest.{prod,ci}.json`. | A built `dist/`                                                                                                               |
+| **`wizard-ci-explore.no-jest.ts`** | `pnpm wizard-ci-explore`: opens an app, confirms setup, reads state, prints one frame, and exits. It does not run the agent.                                                                                | `APP_DIR`, `PROJECT_ID`; optional `POSTHOG_KEY_FILE`                                                                          |
 
-> You usually don't call these directly — `pnpm wizard-ci-snapshots` (in
+> You usually do not call these directly. `pnpm wizard-ci-snapshots` (in
 > [wizard-workbench](https://github.com/PostHog/wizard-workbench)) orchestrates
-> the snapshot route; the MCP server is registered in this repo's `.mcp.json` and
-> used via the `exploring-the-wizard` skill.
+> the snapshot route; the MCP server is registered in this repo's `.mcp.json`
+> and used via the `exploring-the-wizard` skill.
 
-`PROGRAM`, `SNAP_HARNESS`, `SNAP_SEQUENCE`, `SNAP_MODEL`, and `E2E_ASK` are host
-environment inputs, inherited from the launcher; they are not MCP tool
-arguments. For new runs follow the
-[runner policy](../.claude/skills/wizard-development/SKILL.md). Read the
-[current host limitations](../e2e-harness/ARCHITECTURE.md#current-host-limitations)
-before choosing credentials or an EU project.
+`PROGRAM`, `SNAP_HARNESS`, `SNAP_SEQUENCE`, `SNAP_MODEL`, and `E2E_ASK` are
+launcher environment inputs; they are not MCP tool arguments. For new runs
+follow the [runner policy](../.claude/skills/wizard-development/SKILL.md).
 
 ## Credentials for full agent runs
 
-Full TUI host and snapshot runs require both the personal API key (or
-`POSTHOG_KEY_FILE`) and `WIZARD_CI_GATEWAY_TOKEN_FILE`, plus `PROJECT_ID`.
-For MCP runs, pass the personal key through `open_app` and set the gateway
-token file path in the server environment before launch. Restart the server
-after changing it; the gateway path is not an MCP tool argument.
-Detection-only exploration does not need either secret. See
+Full snapshot runs require the personal API key (or `POSTHOG_KEY_FILE`) and
+`WIZARD_CI_GATEWAY_TOKEN_FILE`, plus `PROJECT_ID`. For MCP runs, pass the
+personal key through `open_app` and set the gateway token file path in the
+server environment before launch. Restart the server after changing it; the
+gateway path is not an MCP tool argument. Detection-only exploration needs
+neither secret. See
 [local credential setup](../docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 
-## Background
-
-The control plane lives in [`e2e-harness/`](../e2e-harness/) — out of `src/`, so
-none of it ships in prod. `WizardCiDriver` (read/act over the store), the
-screen→action registry, the e2e profiles, and `tui-capture` (real-TUI PTY
-capture). See [`ARCHITECTURE.md`](../e2e-harness/ARCHITECTURE.md) for how the two
-routes drive these (env strip, scoped project id, gotchas).
+## Driving the wizard yourself
+
+Any HTTP client works against the socket. A dev build attaches the server to the
+TUI with `--ci --control-socket`; every build attaches it to a headless run with
+the headless flag:
+
+```bash
+POSTHOG_WIZARD_API_KEY=phx_... npx tsx bin.ts --ci --control-socket /tmp/w/w.sock \
+  --project-id <id> --region us --install-dir /tmp/app
+curl -s --unix-socket /tmp/w/w.sock http://localhost/state | jq '.state.currentScreen, [.state.actions[].id]'
+curl -s --unix-socket /tmp/w/w.sock -X POST -H 'content-type: application/json' -d '{}' http://localhost/actions/confirm_setup
+curl -s --unix-socket /tmp/w/w.sock -X POST http://localhost/run
+curl -s --unix-socket /tmp/w/w.sock 'http://localhost/state?wait=30000&since=12' | jq .state.currentScreen
+curl -s --unix-socket /tmp/w/w.sock -X POST http://localhost/shutdown
+```
diff --git a/scripts/tui-host.no-jest.ts b/scripts/tui-host.no-jest.ts
deleted file mode 100644
index a45d72fe8..000000000
--- a/scripts/tui-host.no-jest.ts
+++ /dev/null
@@ -1,754 +0,0 @@
-/**
- * Shared real-TUI host — the one primitive both e2e routes use.
- *
- * Runs the real `startTUI` (real ink render → this process's stdout, which the
- * PTY parent captures) and drives its store by pure state manipulation via
- * `WizardCiDriver` — no keystrokes. Auth is satisfied by `setCredentials` with
- * the phx key (same bearer as an OAuth token).
- *
- *   MODE=fixed  — self-drive the fixed e2e profile, snapshotting each screen
- *                 (the CI snapshot route).
- *   MODE=serve  — listen on CONTROL_SOCK for {read_state, perform_action,
- *                 set_credentials, run_agent} commands (the agent/MCP route).
- *
- * Never writes to stdout (that's the TUI); diagnostics go to the wizard log file.
- */
-import fs from 'fs';
-import net from 'net';
-import { spawnSync } from 'child_process';
-import { startTUI } from '@tui/start-tui';
-import { setDetectionAgent } from '@store/detection/agentic';
-import { setMcpPromptRunner } from '@store/agent-protocol/mcp-prompt';
-import { detectProjectsWithAgent } from '@agent/detection/agentic';
-import { runMcpPromptViaSdk } from '@agent/mcp-prompt-streaming';
-import { VERSION } from '@store/shared/version';
-import {
-  Program,
-  getProgramConfig,
-  type ProgramId,
-} from '@store/programs/program-registry';
-import type { Harness, Sequence } from '@store/shared/constants';
-import { buildSession } from '@store/session/wizard-session';
-import { initLocalDev } from '@store/local-dev';
-import { configureGatewayFromCIEnvironment } from '@agent/gateway/gateway-session';
-import { runAgent } from '@agent';
-import { runConfigFor } from '@store/programs/run-config';
-import { TaskStreamPush, createFileDestination } from '@store/task-stream';
-import { getAuditChecks } from '@store/programs/audit/types';
-import { authenticate } from '@store/services/authenticate';
-import { getOrAskForProjectData } from '@store/shared/setup-utils';
-import { logToFile } from '@store/shared/debug';
-import { join } from 'path';
-import { detectFramework } from '@store/detection';
-import { FRAMEWORK_REGISTRY } from '@store/registry';
-import type { Integration } from '@store/shared/constants';
-import { SELF_DRIVING_INTEGRATE_PATH_KEY } from '@store/programs/self-driving/detect';
-import { ERROR_TRACKING_PROJECT_PATH_KEY } from '@store/programs/error-tracking/detect-agentic';
-import {
-  detectSourceMapsPrerequisites,
-  SOURCE_MAPS_CONTEXT_KEYS,
-} from '@store/programs/error-tracking-upload-source-maps';
-import { ScreenId, Overlay } from '@tui/router';
-import { WizardCiDriver } from '@e2e-harness/wizard-ci-driver';
-import {
-  decideE2eAction,
-  type AskAnswerRule,
-  type WizardE2eProfile,
-} from '@e2e-harness/e2e-profile';
-import { profileFor, resolveE2eProfile } from '@e2e-harness/profiles';
-import {
-  E2eRunRecorder,
-  buildE2eResult,
-  readReportFile,
-} from '@e2e-harness/e2e-result';
-
-/** Cheap 32-bit FNV-1a, to fold framework-context values into a signature. */
-function digest(s: string): string {
-  let h = 0x811c9dc5;
-  for (let i = 0; i < s.length; i++) {
-    h ^= s.charCodeAt(i);
-    h = Math.imul(h, 0x01000193);
-  }
-  return (h >>> 0).toString(36);
-}
-
-const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-const mark = (m: string) => logToFile(`[tui-host] ${m}`);
-
-/** Tri-state: absent ⇒ `undefined`, so `resolveLocalDev` can apply the umbrella. */
-function envFlag(name: string): boolean | undefined {
-  const raw = process.env[name];
-  if (raw === undefined || raw === '') return undefined;
-  return raw === 'true';
-}
-
-/**
- * Pick the project to set PostHog up in, headlessly: the repo root if it's a
- * single app, else the first instrumentable sub-app of a monorepo (under
- * `apps/` or `packages/`). Mirrors what the detect screen's picker commits, so
- * the e2e host can drive a monorepo fixture (e.g. a Turborepo) without
- * keystrokes — the store driver can't actuate the interactive picker.
- */
-async function pickIntegrationTarget(
-  root: string,
-): Promise<{ integration: Integration; path: string } | null> {
-  // A monorepo: integrate a real sub-app, not the workspace root (which tends
-  // to detect as generic node). Scan apps/ then packages/ for the first one
-  // with a framework. Fall back to the root for a single-app fixture.
-  for (const group of ['apps', 'packages']) {
-    let entries: string[];
-    try {
-      entries = fs.readdirSync(join(root, group)).sort();
-    } catch {
-      continue; // group dir absent
-    }
-    for (const name of entries) {
-      const rel = `${group}/${name}`;
-      if (!fs.statSync(join(root, rel)).isDirectory()) continue;
-      const fw = await detectFramework(join(root, rel));
-      if (fw && FRAMEWORK_REGISTRY[fw]) return { integration: fw, path: rel };
-    }
-  }
-  const rootFw = await detectFramework(root);
-  return rootFw && FRAMEWORK_REGISTRY[rootFw]
-    ? { integration: rootFw, path: '.' }
-    : null;
-}
-
-/**
- * The variant to drive when the static prerequisite detector won't name one.
- *
- * `detectSourceMapsPrerequisites` deliberately does not automate native
- * platforms ("the legacy filesystem detector does not automate native
- * platforms" — detect.ts); the real screen resolves those through the agentic
- * picker, which the store driver cannot actuate. So mirror its verdict here,
- * or the run exits at the detect screen and no native fixture is ever
- * e2e-drivable.
- *
- * Two cases: the detector recognised the platform and only refused to automate
- * it (the name is in `detected`), or it returned "unknown" — Go and Rust,
- * which it never classifies — and the identifying manifest names it.
- */
-function nativeVariantFor(root: string, detectError: unknown): string | null {
-  const detected = (detectError as { detected?: string } | undefined)?.detected;
-  if (detected && detected !== 'unknown') return detected;
-
-  const manifests: ReadonlyArray<readonly [string, string]> = [
-    ['go.mod', 'go'],
-    ['Cargo.toml', 'rust'],
-    ['pubspec.yaml', 'flutter'],
-    ['Package.swift', 'ios'],
-    ['settings.gradle.kts', 'android'],
-    ['settings.gradle', 'android'],
-  ];
-  for (const [file, variant] of manifests) {
-    if (fs.existsSync(join(root, file))) return variant;
-  }
-  // CocoaPods-style iOS fixtures carry no Package.swift.
-  try {
-    if (
-      fs
-        .readdirSync(root)
-        .some((f) => f.endsWith('.xcodeproj') || f.endsWith('.xcworkspace'))
-    ) {
-      return 'ios';
-    }
-  } catch {
-    /* unreadable root — the caller reports the original detect error */
-  }
-  return null;
-}
-
-// Run the app's build, returning success — stands in for the human the source-maps skill defers `npm run build` to. Opt in with SOURCE_MAPS_RUN_BUILD=1.
-function runAppBuild(root: string): boolean {
-  // Load the app's env file: the Next.js posthog plugin reads credentials from process.env at build time (unlike posthog-cli, which self-loads). The app's file wins over any POSTHOG_* the host inherited, else a stray host key shadows the fixture's upload key.
-  const env: NodeJS.ProcessEnv = { ...process.env, CI: 'true' };
-  for (const name of ['.env.local', '.env']) {
-    try {
-      for (const line of fs
-        .readFileSync(join(root, name), 'utf8')
-        .split('\n')) {
-        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
-        if (m) env[m[1]] = m[2].replace(/^["']|["']$/g, '');
-      }
-    } catch {
-      /* no env file of this name */
-    }
-  }
-  const r = spawnSync('npm', ['run', 'build'], {
-    cwd: root,
-    encoding: 'utf8',
-    timeout: 300_000,
-    env,
-  });
-  if (r.error || r.status !== 0) {
-    mark(
-      `app build failed (status=${r.status}): ${(
-        r.stderr ||
-        r.error?.message ||
-        ''
-      ).slice(-800)}`,
-    );
-    return false;
-  }
-  mark('app build succeeded');
-  return true;
-}
-
-async function main() {
-  const apiKey = (
-    process.env.POSTHOG_PERSONAL_API_KEY ??
-    (process.env.POSTHOG_KEY_FILE
-      ? fs.readFileSync(process.env.POSTHOG_KEY_FILE, 'utf8')
-      : '')
-  ).trim();
-  const projectId = process.env.PROJECT_ID!;
-  // Which program to drive — defaults to the integration flow. Set PROGRAM to
-  // an id (e.g. `self-driving`) to host a different one.
-  const programId =
-    (process.env.PROGRAM as ProgramId) || Program.PostHogIntegration;
-  const programConfig = getProgramConfig(programId);
-
-  // This host answers wizard_ask via its e2e driver, so keep the ask bridge
-  // wired even though the session is `ci` (which here is only for headless
-  // auth). Without it, ask-driven flows like self-driving abort with
-  // requires-interactive-mode the moment they need to ask a question.
-  process.env.WIZARD_ASK_AUTODRIVE = '1';
-
-  // The bin initializes the local-dev singleton from its yargs middleware;
-  // this host bypasses yargs, so `getSkillsBaseUrl()` would silently resolve
-  // to production even when the session carries the local flags. Initialize it
-  // here from the same env-backed spellings, before anything reads it.
-  initLocalDev({
-    localDev: process.env.POSTHOG_WIZARD_LOCAL_DEV === 'true',
-    localMcp: envFlag('POSTHOG_WIZARD_LOCAL_MCP'),
-    localContextMill: envFlag('POSTHOG_WIZARD_LOCAL_CONTEXT_MILL'),
-    localPosthog: envFlag('POSTHOG_WIZARD_LOCAL_POSTHOG'),
-  });
-
-  setDetectionAgent(detectProjectsWithAgent);
-  setMcpPromptRunner({ runMcpPrompt: runMcpPromptViaSdk });
-  const { store } = startTUI(VERSION, programId);
-  store.session = buildSession({
-    installDir: process.env.APP_DIR!,
-    ci: true,
-    // Keep the `wizard_ask` bridge wired despite `ci: true`. The driver loop
-    // below is the answerer — without this the agent-in-the-loop layer of a
-    // flow (credential questions, the orchestrator's seeded warehouse task) is
-    // never exercised. Only this host sets it; see `shouldDisableAsk`.
-    e2eAsk: process.env.E2E_ASK === 'true',
-    apiKey,
-    projectId,
-    region: 'us',
-    // Same env-backed flags the bin declares. The harness usually wants local
-    // skills (:8765) against the production MCP.
-    localDev: process.env.POSTHOG_WIZARD_LOCAL_DEV === 'true',
-    localMcp: envFlag('POSTHOG_WIZARD_LOCAL_MCP'),
-    localContextMill: envFlag('POSTHOG_WIZARD_LOCAL_CONTEXT_MILL'),
-    localPosthog: envFlag('POSTHOG_WIZARD_LOCAL_POSTHOG'),
-    // Switchboard variation overrides (see e2e.json `variations`), threaded by
-    // the snapshot driver as one run per variation. Empty ⇒ resolved default.
-    harness: (process.env.SNAP_HARNESS || undefined) as Harness | undefined,
-    sequence: (process.env.SNAP_SEQUENCE || undefined) as Sequence | undefined,
-    model: process.env.SNAP_MODEL || undefined,
-  });
-  // Dumped, never pushed: an e2e run is synthetic, like `--ci`.
-  const streamLog = createFileDestination(process.env.TASK_STREAM_LOG ?? '');
-  if (streamLog) {
-    const stream = new TaskStreamPush({
-      store,
-      programId,
-      destinations: [streamLog],
-      eventPlanPath: programConfig.eventPlanFile
-        ? join(store.session.installDir, programConfig.eventPlanFile)
-        : undefined,
-      auditChecks: programConfig.auditLedgerFile
-        ? () => getAuditChecks(store.session)
-        : undefined,
-    });
-    stream.attach();
-    process.on('exit', () => void stream.shutdown(0));
-    mark(`task stream dump → ${streamLog.path}`);
-  }
-
-  // Optional skip-ahead: pre-resolve the self-driving integration check so its
-  // screen never shows (INTEGRATE=true integrates first; false = already set up).
-  if (process.env.INTEGRATE === 'true' || process.env.INTEGRATE === 'false') {
-    store.setIntegrate(process.env.INTEGRATE === 'true');
-  }
-  const driver = new WizardCiDriver(store);
-
-  // Resolve credentials from the phx key (same bearer as an OAuth token) and set
-  // them on the store — advances the auth screen with no browser, no keystrokes.
-  const authByState = async () => {
-    const d = await getOrAskForProjectData({
-      signup: false,
-      ci: true,
-      apiKey,
-      projectId: Number(projectId),
-      programId,
-    });
-    store.setCredentials({
-      accessToken: d.accessToken,
-      projectApiKey: d.projectApiKey,
-      host: d.host,
-      projectId: d.projectId,
-    });
-  };
-
-  // Pass the pre-run gates and run the program's real agent. The auth and run
-  // screens never advance on their own; this is what moves them. Mirrors
-  // run-wizard's flow, including in-program run phases.
-  let gatewayConfigured = false;
-  const runProgram = async () => {
-    if (!gatewayConfigured) {
-      configureGatewayFromCIEnvironment(
-        Number(projectId),
-        store.session.region ?? 'us',
-      );
-      gatewayConfigured = true;
-    }
-    await store.getGate('intro');
-    await store.getGate('integration-check');
-    await store.getGate('health-check');
-
-    // Mirror run-wizard's composed walk for programs whose steps splice in
-    // their own run steps (self-driving: detect → integrate → handoff → run),
-    // or scope their own run to a picked project (error-tracking).
-    // `authenticate` here resolves the phx key, not OAuth, since the session is
-    // built with ci + apiKey.
-    if (programConfig.steps.some((s) => s.run || s.targetDir)) {
-      const runSessionFor = async (
-        step: (typeof programConfig.steps)[number],
-      ) => {
-        const live = store.session;
-        const runSession = step.targetDir
-          ? {
-              ...live,
-              installDir: step.targetDir(live),
-              frameworkContext: { ...live.frameworkContext },
-            }
-          : live;
-        if (step.onRunPrep) await step.onRunPrep(runSession);
-        return runSession;
-      };
-      for (const step of programConfig.steps) {
-        if (step.screenId === 'outro') break;
-        if (step.show && !step.show(store.session)) continue;
-        if (step.screenId === 'auth') {
-          await authenticate(store.session, programConfig.id);
-        } else if (step.run) {
-          await runAgent(
-            runConfigFor(getProgramConfig(step.run.programId)),
-            await runSessionFor(step),
-            { composed: true },
-          );
-          store.completeRunStep(step.id);
-        } else if (step.screenId === 'run') {
-          await runAgent(
-            runConfigFor(programConfig),
-            await runSessionFor(step),
-          );
-        } else if (step.isComplete) {
-          await store.waitUntil(step.isComplete);
-        }
-      }
-    } else {
-      await runAgent(runConfigFor(programConfig), store.session);
-    }
-  };
-
-  if (process.env.MODE === 'serve') return serve();
-  return fixed();
-
-  // ---- agent route: drive commands over a unix socket ----
-  function serve() {
-    let runStatus: 'idle' | 'running' | 'done' | 'failed' = 'idle';
-    let runError: string | null = null;
-    const handle = async (req: {
-      type: string;
-      action?: string;
-      params?: Record<string, unknown>;
-    }) => {
-      try {
-        switch (req.type) {
-          case 'read_state':
-            return {
-              ok: true,
-              state: {
-                ...driver.readState(),
-                integration: runStatus,
-                integrationError: runError,
-              },
-            };
-          case 'perform_action':
-            return {
-              ok: true,
-              state: driver.performAction(req.action!, req.params ?? {}),
-            };
-          case 'set_credentials':
-            await authByState();
-            return { ok: true, state: driver.readState() };
-          case 'run_agent': {
-            if (runStatus === 'running' || runStatus === 'done')
-              return { ok: true, runStatus };
-            runStatus = 'running';
-            void (async () => {
-              try {
-                await runProgram();
-                runStatus = 'done';
-              } catch (e) {
-                runStatus = 'failed';
-                runError = (e as Error).message;
-                mark('run_agent error ' + runError);
-              }
-            })();
-            return { ok: true, runStatus: 'running' };
-          }
-          default:
-            return { ok: false, error: `unknown command ${req.type}` };
-        }
-      } catch (e) {
-        return { ok: false, error: (e as Error).message };
-      }
-    };
-    const server = net.createServer((sock) => {
-      let buf = '';
-      sock.on('data', (d) => {
-        buf += d;
-        let i;
-        while ((i = buf.indexOf('\n')) >= 0) {
-          const line = buf.slice(0, i);
-          buf = buf.slice(i + 1);
-          if (!line.trim()) continue;
-          void handle(JSON.parse(line)).then((res) =>
-            sock.write(JSON.stringify(res) + '\n'),
-          );
-        }
-      });
-    });
-    const sockPath = process.env.CONTROL_SOCK!;
-    try {
-      fs.unlinkSync(sockPath);
-    } catch {
-      /* fresh */
-    }
-    server.listen(sockPath, () => mark(`serving on ${sockPath}`));
-    void store.runReadyHooks(); // detection so the intro screen fills in
-  }
-
-  // ---- CI route: self-drive the fixed profile, snapshot each screen ----
-  async function fixed() {
-    const CTRL = process.env.SNAP_CTRL!;
-    // Fold the run's env inputs into the profile once, here. `decideE2eAction`
-    // stays pure, so the same state + profile always yields the same decision.
-    const profile: WizardE2eProfile = resolveE2eProfile(profileFor(programId), {
-      notice: process.env.E2E_NOTICE,
-      extraAskAnswers: readAnswersFile(process.env.E2E_ANSWERS_FILE),
-      env: process.env,
-    });
-    // Source-maps ask answers: the upload key is vaulted to a secretRef; the test build runs only under SOURCE_MAPS_RUN_BUILD=1, else it's declined.
-    const runBuild = process.env.SOURCE_MAPS_RUN_BUILD === '1';
-    const askOverrides: Record<string, Record<string, string | undefined>> = {
-      [Program.ErrorTrackingUploadSourceMaps]: {
-        'api-key': process.env.SOURCE_MAPS_CLI_KEY,
-        'test-affordance': runBuild ? 'yes' : 'no',
-      },
-    };
-    const recorder = new E2eRunRecorder();
-    const screenPath: string[] = [];
-    let resultWritten = false;
-    // An abort exits from inside the runner, so hook `exit` too — see writeResult.
-    process.on('exit', () => writeResult());
-    // Snapshot on key moments — a screen change, a task-list update, or a
-    // runPhase change — so the run screen's progression (the agent working) is
-    // captured, not just screen transitions. The driver loop snaps each screen
-    // before acting on it (so transitions are caught as presented); a store
-    // subscription catches within-screen changes (the run). Deduped by
-    // signature and serialized.
-    let lastSig = '';
-    let chain: Promise<void> = Promise.resolve();
-    const signature = () =>
-      JSON.stringify({
-        screen: store.currentScreen,
-        overlay: store.hasInterrupt,
-        tasks: store.tasks.map((t) => [t.label, t.status, t.done]),
-        phase: store.session.runPhase,
-        // Values, not just keys: a screen rerendering from an artifact updated
-        // in place (the audit ledger) keeps its key and would snap once, empty.
-        ctx: digest(JSON.stringify(store.session.frameworkContext)),
-      });
-    const snap = (): Promise<void> => {
-      const sig = signature();
-      if (sig === lastSig) return chain;
-      lastSig = sig;
-      const screen = store.currentScreen;
-      if (screenPath[screenPath.length - 1] !== screen) screenPath.push(screen);
-      chain = chain.then(async () => {
-        await sleep(500); // settle: let the frame finish drawing
-        fs.appendFileSync(CTRL, store.currentScreen + '\n');
-        await sleep(300); // let the capturer capture before the screen moves on
-      });
-      return chain;
-    };
-    // Log every ask batch and task notice as it opens. The store fires on every
-    // commit, so an overlay that opens and closes between two driver-loop turns
-    // is still recorded.
-    const unsub = store.subscribe(() => {
-      recorder.observe(store.session);
-      void snap();
-    });
-
-    let stop = false;
-    const driverLoop = async () => {
-      while (!stop && !store.session.skillsComplete) {
-        await snap(); // capture this screen as presented, before acting
-        recorder.observe(store.session);
-        const state = driver.readState();
-        const before = state.currentScreen;
-
-        // Headless detect: the screen runs a real detector + an interactive
-        // pick the store driver can't actuate. Inject the pick — the repo root
-        // for a single app, or a monorepo's first instrumentable sub-app — so
-        // the composed integrate-run can proceed.
-        if (
-          state.currentScreen === ScreenId.SelfDrivingIntegrationDetect &&
-          state.session.integration == null
-        ) {
-          const pick = await pickIntegrationTarget(store.session.installDir);
-          if (pick) {
-            store.setFrameworkContext(
-              SELF_DRIVING_INTEGRATE_PATH_KEY,
-              pick.path,
-            );
-            store.setFrameworkConfig(
-              pick.integration,
-              FRAMEWORK_REGISTRY[pick.integration],
-            );
-          }
-          continue;
-        }
-
-        // Headless error-tracking detect: the same pick injection as above, into
-        // the error-tracking path key, so the run is scoped to the picked app.
-        if (
-          state.currentScreen === ScreenId.ErrorTrackingDetect &&
-          state.session.integration == null
-        ) {
-          const pick = await pickIntegrationTarget(store.session.installDir);
-          if (!pick) {
-            mark('error-tracking detect found no framework to set up');
-            process.exit(1);
-          }
-          store.setFrameworkContext(ERROR_TRACKING_PROJECT_PATH_KEY, pick.path);
-          store.setFrameworkConfig(
-            pick.integration,
-            FRAMEWORK_REGISTRY[pick.integration],
-          );
-          continue;
-        }
-
-        // Headless source-maps detect: the screen's candidate list lives in
-        // its own agentic report (React state), so compute the pick here with
-        // the static prerequisite detector — right for a single-app fixture —
-        // and commit it through the driver the way the picker would.
-        if (
-          state.currentScreen === ScreenId.SourceMapsDetect &&
-          store.session.frameworkContext[
-            SOURCE_MAPS_CONTEXT_KEYS.selectedVariant
-          ] == null
-        ) {
-          const ctx: Record<string, unknown> = {};
-          detectSourceMapsPrerequisites(store.session, (k, v) => {
-            ctx[k] = v;
-          });
-          const detected = ctx[SOURCE_MAPS_CONTEXT_KEYS.skillVariant];
-          const variant =
-            typeof detected === 'string'
-              ? detected
-              : nativeVariantFor(
-                  store.session.installDir,
-                  ctx[SOURCE_MAPS_CONTEXT_KEYS.detectError],
-                );
-          if (typeof variant !== 'string') {
-            mark(
-              'source-maps detect found nothing to instrument: ' +
-                JSON.stringify(ctx[SOURCE_MAPS_CONTEXT_KEYS.detectError]),
-            );
-            process.exit(1);
-          }
-          if (typeof detected !== 'string') {
-            mark(`source-maps detect: native fallback picked ${variant}`);
-          }
-          driver.performAction('pick_source_maps_project', {
-            variant,
-            path: '.',
-          });
-          continue;
-        }
-
-        // Program-specific ask answers take precedence over the generic
-        // profile strategy.
-        if (state.currentScreen === Overlay.WizardAsk) {
-          const q = state.pendingQuestion?.questions[0];
-          const override = q ? askOverrides[programId]?.[q.id] : undefined;
-          if (q && override !== undefined) {
-            driver.performAction('answer_question', {
-              answers: { [q.id]: override },
-            });
-            continue;
-          }
-          // test-done: run the real build, answer by outcome.
-          if (
-            runBuild &&
-            programId === Program.ErrorTrackingUploadSourceMaps &&
-            q?.id === 'test-done'
-          ) {
-            const ok = runAppBuild(store.session.installDir);
-            driver.performAction('answer_question', {
-              answers: { [q.id]: ok ? 'yes' : 'no' },
-            });
-            continue;
-          }
-        }
-
-        let acted = false;
-        try {
-          const decision = decideE2eAction(state, profile);
-          if (decision.action) {
-            driver.performAction(
-              decision.action.id,
-              decision.action.params ?? {},
-            );
-            acted = true;
-          }
-          // Only the decision knows how it resolved an ask or a notice; the
-          // report is ids and a verdict, never an answer value.
-          if (decision.report) recorder.applyReport(decision.report);
-          if (decision.done) stop = true;
-        } catch (e) {
-          mark(`action error on ${before}: ${(e as Error).message}`);
-        }
-        if (acted && store.currentScreen !== before) continue;
-        if (!stop) await driver.waitForChange(600_000);
-      }
-    };
-    const drive = driverLoop();
-
-    // Write the structured result the --e2e assertion path reads. Programs whose
-    // outro is terminal (self-driving) exit via the outro's ExitScreen before
-    // the end-of-run path below, so capture it the moment the outro is reached;
-    // integration re-writes it after keep-skills (skillsComplete). Registered
-    // on `exit` too: `wizardAbort` renders the error outro and exits, and an
-    // aborted run would otherwise write nothing at all.
-    const writeResult = (): void => {
-      if (!process.env.E2E_RESULT_JSON || resultWritten) return;
-      resultWritten = true;
-      const appDir = process.env.APP_DIR!;
-      // One dependency-name pattern per ecosystem manifest. A run only needs
-      // the names, so a line-level scan beats per-format parsers.
-      const MANIFESTS: Array<[string, RegExp]> = [
-        ['pubspec.yaml', /^ {2}([A-Za-z_][A-Za-z0-9_]*)\s*:/gm],
-        ['go.mod', /^\s*([\w.\/-]+)\s+v[\w.-]+/gm],
-        ['Cargo.toml', /^([A-Za-z0-9_-]+)\s*=/gm],
-        ['pom.xml', /<artifactId>([^<]+)<\/artifactId>/g],
-        ['build.gradle', /['"]([\w.-]+:[\w.-]+)[:'"]/g],
-        ['mix.exs', /\{:([a-z_]+)\s*,/g],
-      ];
-      const deps: string[] = [];
-      try {
-        // package.json needs a real parse: a line scan would also match script
-        // names, and only the dependency blocks carry dependencies.
-        const pkg = JSON.parse(
-          fs.readFileSync(`${appDir}/package.json`, 'utf8'),
-        );
-        deps.push(
-          ...Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }),
-        );
-      } catch {
-        /* not a JS project */
-      }
-      for (const [file, pattern] of MANIFESTS) {
-        try {
-          const text = fs.readFileSync(`${appDir}/${file}`, 'utf8');
-          for (const match of text.matchAll(pattern)) deps.push(match[1]);
-        } catch {
-          /* app doesn't use this ecosystem */
-        }
-      }
-      const posthogDeps = [
-        ...new Set(deps.filter((d) => d.toLowerCase().includes('posthog'))),
-      ];
-      let envFile: string | null = null;
-      try {
-        const hit = fs
-          .readdirSync(appDir)
-          .find(
-            (f) =>
-              (f.startsWith('.env') || f.endsWith('.env')) &&
-              /posthog/i.test(fs.readFileSync(`${appDir}/${f}`, 'utf8')),
-          );
-        envFile = hit ? `${appDir}/${hit}` : null;
-      } catch {
-        /* none */
-      }
-      fs.writeFileSync(
-        process.env.E2E_RESULT_JSON,
-        JSON.stringify(
-          buildE2eResult({
-            base: {
-              runPhase: store.session.runPhase,
-              hasPosthogDep: posthogDeps.length > 0,
-              newDeps: posthogDeps,
-              envFile,
-              screenPath,
-              skillsComplete: store.session.skillsComplete,
-            },
-            recorder,
-            session: store.session,
-            tasks: store.tasks,
-            reportFile: readReportFile(appDir, programConfig.reportFile),
-          }),
-          null,
-          2,
-        ),
-      );
-    };
-    const unsubResult = store.subscribe(() => {
-      if (store.currentScreen === 'outro') writeResult();
-    });
-
-    await store.runReadyHooks();
-    await runProgram();
-    const deadline = Date.now() + 120_000;
-    while (!store.session.skillsComplete && Date.now() < deadline)
-      await driver.waitForChange(5_000);
-    // The run reached skillsComplete, so the driver loop is done — but it may be
-    // parked in waitForChange, so don't block on it; the process exit ends it.
-    stop = true;
-    void drive;
-    unsub();
-    unsubResult();
-    await snap(); // the final screen
-    await chain; // flush any pending snapshots
-    writeResult(); // final write (integration: after keep-skills)
-    process.exit(0);
-  }
-}
-
-/** Extra `askAnswers` rules from `E2E_ANSWERS_FILE`, or none. */
-function readAnswersFile(file: string | undefined): AskAnswerRule[] {
-  if (!file) return [];
-  try {
-    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
-    return Array.isArray(parsed) ? (parsed as AskAnswerRule[]) : [];
-  } catch (e) {
-    mark(`could not read E2E_ANSWERS_FILE ${file}: ${(e as Error).message}`);
-    return [];
-  }
-}
-
-main().catch((e) => {
-  mark('FATAL ' + (e?.stack ?? e));
-  process.exit(1);
-});
diff --git a/scripts/tui-snapshots.no-jest.ts b/scripts/tui-snapshots.no-jest.ts
index c306fd01e..0aaea7607 100644
--- a/scripts/tui-snapshots.no-jest.ts
+++ b/scripts/tui-snapshots.no-jest.ts
@@ -1,61 +1,376 @@
 /**
- * Fixed-route snapshots of the REAL TUI (Node, single-stack).
+ * CI snapshot route. Spawns the real wizard TUI in a PTY with a control socket,
+ * self-drives the program's fixed e2e profile over that socket, and writes the
+ * real rendered screen to SNAP_OUT/NN-<screen>.ans at every screen change,
+ * task update, or run-phase change. Colors are preserved.
  *
- * Spawns the real-TUI host (MODE=fixed) in a PTY, lets it self-drive the fixed
- * e2e profile through the real agent run, and writes the real rendered screen —
- * serialized back to ANSI, colors preserved — to SNAP_OUT/NN-<screen>.ans at
- * each key moment the host signals.
- *
- *   SNAP_OUT=/tmp/snaps APP_DIR=/tmp/app POSTHOG_KEY_FILE=… PROJECT_ID=… \
+ *   SNAP_OUT=/tmp/snaps APP_DIR=/tmp/app PROJECT_ID=… POSTHOG_KEY_FILE=… \
  *     npx tsx scripts/tui-snapshots.no-jest.ts
+ *
+ * PROGRAM picks the program (default posthog-integration). SNAP_HARNESS,
+ * SNAP_SEQUENCE, SNAP_MODEL feed the switchboard overrides. E2E_ASK=true keeps
+ * wizard_ask wired so the profile answers questions. E2E_RESULT_JSON, when set,
+ * receives the structured result. Never prints the key.
  */
 import fs from 'fs';
+import os from 'os';
 import path from 'path';
+import { spawnSync } from 'child_process';
+import { logToFile } from '@store';
+import { getProgramConfig, Program } from '@store/programs';
+import { ControlClient } from '@store/control';
+import type { ControlState, ProgramId } from '@store/types';
 import { captureTui } from '@e2e-harness/tui-capture';
+import { buildLaunch, readApiKey, waitForSocket } from '@e2e-harness/launch';
+import {
+  decideE2eAction,
+  type AskAnswerRule,
+  type WizardE2eProfile,
+} from '@e2e-harness/e2e-profile';
+import { profileFor, resolveE2eProfile } from '@e2e-harness/profiles';
+import {
+  E2eRunRecorder,
+  buildE2eResult,
+  readReportFile,
+} from '@e2e-harness/e2e-result';
+import {
+  pickIntegrationTarget,
+  pickSourceMapsVariant,
+} from '@e2e-harness/picks';
 
 const OUT = process.env.SNAP_OUT!;
-const CTRL = path.join(OUT, 'ctrl');
+const APP_DIR = process.env.APP_DIR!;
 fs.mkdirSync(OUT, { recursive: true });
-fs.writeFileSync(CTRL, '');
-
-const env: NodeJS.ProcessEnv = {
-  ...process.env,
-  MODE: 'fixed',
-  SNAP_CTRL: CTRL,
-};
-for (const k of Object.keys(env))
-  if (/^(CLAUDE|ANTHROPIC)/.test(k)) delete env[k]; // gateway auth via phx, not host creds
-
-const cap = captureTui({
-  cmd: path.join(process.cwd(), 'node_modules/.bin/tsx'),
-  args: ['scripts/tui-host.no-jest.ts'],
-  cwd: process.cwd(),
-  env,
-});
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
-let pos = 0;
-let seq = 0;
-async function drainCtrl() {
-  const data = fs.readFileSync(CTRL, 'utf8').slice(pos);
-  pos += data.length;
-  for (const raw of data.split('\n')) {
-    const label = raw.trim();
-    if (!label) continue;
-    await sleep(200); // let xterm apply the final writes for this screen
-    seq += 1;
-    const fn = path.join(OUT, `${String(seq).padStart(2, '0')}-${label}.ans`);
-    fs.writeFileSync(fn, cap.frameAnsi());
-    // eslint-disable-next-line no-console
-    console.log('snap ->', path.basename(fn));
+const mark = (m: string) => logToFile(`[tui-snapshots] ${m}`);
+
+/** Extra `askAnswers` rules from `E2E_ANSWERS_FILE`, or none. */
+function readAnswersFile(file: string | undefined): AskAnswerRule[] {
+  if (!file) return [];
+  try {
+    const parsed: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+    return Array.isArray(parsed) ? (parsed as AskAnswerRule[]) : [];
+  } catch (e) {
+    mark(`could not read E2E_ANSWERS_FILE ${file}: ${(e as Error).message}`);
+    return [];
+  }
+}
+
+/** Run the app's build, standing in for the human the source-maps skill defers `npm run build` to. */
+function runAppBuild(root: string): boolean {
+  const env: NodeJS.ProcessEnv = { ...process.env, CI: 'true' };
+  for (const name of ['.env.local', '.env']) {
+    try {
+      for (const line of fs
+        .readFileSync(path.join(root, name), 'utf8')
+        .split('\n')) {
+        const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/);
+        if (m) env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+      }
+    } catch {
+      /* no env file of this name */
+    }
+  }
+  const r = spawnSync('npm', ['run', 'build'], {
+    cwd: root,
+    encoding: 'utf8',
+    timeout: 300_000,
+    env,
+  });
+  if (r.error || r.status !== 0) {
+    mark(
+      `app build failed (status=${r.status}): ${(
+        r.stderr ||
+        r.error?.message ||
+        ''
+      ).slice(-800)}`,
+    );
+    return false;
+  }
+  mark('app build succeeded');
+  return true;
+}
+
+/** The dependency names an app manifest declares, one pattern per ecosystem. */
+function posthogDependencies(appDir: string): string[] {
+  const MANIFESTS: Array<[string, RegExp]> = [
+    ['pubspec.yaml', /^ {2}([A-Za-z_][A-Za-z0-9_]*)\s*:/gm],
+    ['go.mod', /^\s*([\w./-]+)\s+v[\w.-]+/gm],
+    ['Cargo.toml', /^([A-Za-z0-9_-]+)\s*=/gm],
+    ['pom.xml', /<artifactId>([^<]+)<\/artifactId>/g],
+    ['build.gradle', /['"]([\w.-]+:[\w.-]+)[:'"]/g],
+    ['mix.exs', /\{:([a-z_]+)\s*,/g],
+  ];
+  const deps: string[] = [];
+  try {
+    const pkg = JSON.parse(
+      fs.readFileSync(`${appDir}/package.json`, 'utf8'),
+    ) as {
+      dependencies?: Record<string, string>;
+      devDependencies?: Record<string, string>;
+    };
+    deps.push(...Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }));
+  } catch {
+    /* not a JS project */
+  }
+  for (const [file, pattern] of MANIFESTS) {
+    try {
+      const text = fs.readFileSync(`${appDir}/${file}`, 'utf8');
+      for (const match of text.matchAll(pattern)) deps.push(match[1]);
+    } catch {
+      /* app doesn't use this ecosystem */
+    }
+  }
+  return [...new Set(deps.filter((d) => d.toLowerCase().includes('posthog')))];
+}
+
+function envFileWithPosthog(appDir: string): string | null {
+  try {
+    const hit = fs
+      .readdirSync(appDir)
+      .find(
+        (f) =>
+          (f.startsWith('.env') || f.endsWith('.env')) &&
+          /posthog/i.test(fs.readFileSync(`${appDir}/${f}`, 'utf8')),
+      );
+    return hit ? `${appDir}/${hit}` : null;
+  } catch {
+    return null;
   }
 }
 
-const timer = setInterval(() => void drainCtrl(), 150);
-void cap.exited.then(async () => {
-  await drainCtrl();
-  clearInterval(timer);
-  // eslint-disable-next-line no-console
+async function main(): Promise<void> {
+  const programId =
+    (process.env.PROGRAM as ProgramId) || Program.PostHogIntegration;
+  const programConfig = getProgramConfig(programId);
+  const profile: WizardE2eProfile = resolveE2eProfile(profileFor(programId), {
+    notice: process.env.E2E_NOTICE,
+    extraAskAnswers: readAnswersFile(process.env.E2E_ANSWERS_FILE),
+    env: process.env,
+  });
+  const runBuild = process.env.SOURCE_MAPS_RUN_BUILD === '1';
+  const askOverrides: Record<string, Record<string, string | undefined>> = {
+    [Program.ErrorTrackingUploadSourceMaps]: {
+      'api-key': process.env.SOURCE_MAPS_CLI_KEY,
+      'test-affordance': runBuild ? 'yes' : 'no',
+    },
+  };
+
+  const socketDir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-snap-'));
+  const socketPath = path.join(socketDir, 'w.sock');
+  const launch = buildLaunch({
+    programId,
+    appDir: APP_DIR,
+    socketPath,
+    projectId: process.env.PROJECT_ID!,
+    region: (process.env.POSTHOG_REGION as 'us' | 'eu' | undefined) ?? 'us',
+    apiKey: readApiKey() || undefined,
+    e2eAsk: process.env.E2E_ASK === 'true',
+    integrate: process.env.INTEGRATE === 'true',
+    harness: process.env.SNAP_HARNESS || undefined,
+    sequence: process.env.SNAP_SEQUENCE || undefined,
+    model: process.env.SNAP_MODEL || undefined,
+    // Dumped, never pushed: an e2e run is synthetic, like `--ci`.
+    taskStreamLog: process.env.TASK_STREAM_LOG ?? '',
+  });
+  const cap = captureTui({ ...launch, cwd: process.cwd() });
+  let exited = false;
+  void cap.exited.then(() => {
+    exited = true;
+  });
+  await waitForSocket(socketPath, 120_000);
+  const client = new ControlClient(socketPath);
+  mark(`controlling ${programId} on ${socketPath}`);
+
+  const recorder = new E2eRunRecorder();
+  const screenPath: string[] = [];
+  let seq = 0;
+  let lastSig = '';
+  let lastState: ControlState | null = null;
+  let resultWritten = false;
+
+  // Snapshot on key moments: a screen change, a task-list update, a phase
+  // change, or a context value changing in place. Deduped by signature.
+  const snap = async (state: ControlState): Promise<void> => {
+    const sig = JSON.stringify({
+      screen: state.currentScreen,
+      overlay: state.hasOverlay,
+      tasks: state.tasks.map((t) => [t.label, t.status]),
+      phase: state.runPhase,
+      ctx: state.frameworkContext.digest,
+    });
+    if (sig === lastSig) return;
+    lastSig = sig;
+    const screen = state.currentScreen;
+    if (screenPath[screenPath.length - 1] !== screen) screenPath.push(screen);
+    await sleep(500); // settle: let the frame finish drawing
+    seq += 1;
+    const file = path.join(
+      OUT,
+      `${String(seq).padStart(2, '0')}-${screen}.ans`,
+    );
+    fs.writeFileSync(file, cap.frameAnsi());
+    console.log('snap ->', path.basename(file));
+  };
+
+  // Write the structured result once at the outro (terminal programs exit from
+  // there) and again at the end, so an abort still leaves a payload behind.
+  const writeResult = (state: ControlState | null): void => {
+    if (!process.env.E2E_RESULT_JSON || resultWritten || !state) return;
+    resultWritten = true;
+    const deps = posthogDependencies(APP_DIR);
+    fs.writeFileSync(
+      process.env.E2E_RESULT_JSON,
+      JSON.stringify(
+        buildE2eResult({
+          base: {
+            runPhase: state.runPhase,
+            hasPosthogDep: deps.length > 0,
+            newDeps: deps,
+            envFile: envFileWithPosthog(APP_DIR),
+            screenPath,
+            skillsComplete: state.session.skillsComplete,
+          },
+          recorder,
+          session: {
+            frameworkContext: state.frameworkContext.values,
+            outroData: state.outroData,
+          },
+          tasks: state.tasks,
+          reportFile: readReportFile(APP_DIR, programConfig.reportFile),
+        }),
+        null,
+        2,
+      ),
+    );
+  };
+  process.on('exit', () => writeResult(lastState));
+
+  // Release the run now: the runner still waits for the intro gate, so the
+  // parent confirms setup in its own time, as the host's run_agent did.
+  await client.armRun();
+
+  let stop = false;
+  while (!stop && !exited) {
+    let state: ControlState;
+    try {
+      state = await client.state();
+    } catch {
+      break; // the wizard exited between polls
+    }
+    lastState = state;
+    await snap(state);
+    recorder.observe(state);
+    if (state.currentScreen === 'outro') {
+      writeResult(state);
+      resultWritten = false; // the tail (keep-skills) rewrites it at the end
+    }
+    const before = state.currentScreen;
+
+    // Detection picks the real screen resolves interactively.
+    if (
+      (before === 'self-driving-integration-detect' ||
+        before === 'error-tracking-detect') &&
+      state.session.integration == null
+    ) {
+      const pick = await pickIntegrationTarget(APP_DIR);
+      if (!pick) {
+        mark(`${before} found no framework to set up`);
+        process.exit(1);
+      }
+      await client.performAction('pick_integration_target', pick);
+      continue;
+    }
+    if (
+      before === 'source-maps-detect' &&
+      !state.frameworkContext.keys.includes('selectedVariant')
+    ) {
+      const picked = pickSourceMapsVariant(APP_DIR);
+      if ('error' in picked) {
+        mark(
+          `source-maps detect found nothing to instrument: ${JSON.stringify(
+            picked.error,
+          )}`,
+        );
+        process.exit(1);
+      }
+      if (picked.fallback)
+        mark(`source-maps detect: native fallback picked ${picked.variant}`);
+      await client.performAction('pick_source_maps_project', {
+        variant: picked.variant,
+        path: '.',
+      });
+      continue;
+    }
+
+    // Program-specific ask answers take precedence over the profile strategy.
+    if (before === 'wizard-ask') {
+      const q = state.pendingQuestion?.questions[0];
+      const override = q ? askOverrides[programId]?.[q.id] : undefined;
+      if (q && override !== undefined) {
+        await client.performAction('answer_question', {
+          answers: { [q.id]: override },
+        });
+        continue;
+      }
+      if (
+        runBuild &&
+        programId === Program.ErrorTrackingUploadSourceMaps &&
+        q?.id === 'test-done'
+      ) {
+        const ok = runAppBuild(APP_DIR);
+        await client.performAction('answer_question', {
+          answers: { [q.id]: ok ? 'yes' : 'no' },
+        });
+        continue;
+      }
+    }
+
+    let acted = false;
+    try {
+      const decision = decideE2eAction(state, profile);
+      if (decision.action) {
+        await client.performAction(
+          decision.action.id,
+          decision.action.params ?? {},
+        );
+        acted = true;
+      }
+      if (decision.report) recorder.applyReport(decision.report);
+      if (decision.done) stop = true;
+    } catch (e) {
+      mark(`action error on ${before}: ${(e as Error).message}`);
+    }
+    if (stop) break;
+    try {
+      if (acted && (await client.state()).currentScreen !== before) continue;
+      state = await client.waitForChange(state.version, 600_000);
+    } catch {
+      break;
+    }
+  }
+
+  // The integration flow ends on skillsComplete; the runner exits after that.
+  const deadline = Date.now() + 120_000;
+  while (!exited && Date.now() < deadline) {
+    try {
+      lastState = await client.waitForChange(lastState?.version ?? 0, 5_000);
+      await snap(lastState);
+    } catch {
+      break;
+    }
+    if (lastState.session.skillsComplete) break;
+  }
+  if (lastState) await snap(lastState);
+  resultWritten = false;
+  writeResult(lastState);
   console.log(`done; ${seq} snapshots in ${OUT}`);
+  cap.kill();
   process.exit(0);
+}
+
+main().catch((e: unknown) => {
+  mark(`FATAL ${(e as Error)?.stack ?? String(e)}`);
+  process.exit(1);
 });
diff --git a/scripts/wizard-ci-mcp.no-jest.ts b/scripts/wizard-ci-mcp.no-jest.ts
index 41bf7631b..dd475b8ee 100644
--- a/scripts/wizard-ci-mcp.no-jest.ts
+++ b/scripts/wizard-ci-mcp.no-jest.ts
@@ -1,11 +1,10 @@
 /**
- * wizard-ci-mcp — MCP server that lets an agent drive the REAL wizard TUI.
+ * wizard-ci-mcp: an MCP server that lets an agent drive the real wizard TUI.
  *
- * A thin proxy: it spawns the shared real-TUI host (scripts/tui-host.no-jest.ts,
- * MODE=serve) in a PTY via the Node capturer, forwards read_state/perform_action/
- * run_agent to it over a unix socket, and returns the REAL rendered screen for
- * render_screen. No store or rendering lives here — same host the CI snapshot
- * route uses. stdout is the JSON-RPC channel; nothing else writes to it.
+ * A thin proxy. `open_app` spawns the real wizard (`--ci --control-socket`) in
+ * a PTY, then read_state / perform_action / run_agent go to the wizard's
+ * control API over its unix socket and render_screen returns the real rendered
+ * frame. stdout is the JSON-RPC channel; nothing else writes to it.
  *
  * Registered in this repo's `.mcp.json`, so the tools are bound in every session.
  */
@@ -15,8 +14,11 @@ import { z } from 'zod';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import net from 'net';
+import { ControlClient } from '@store/control';
+import { Program } from '@store/programs';
+import type { ControlState, ProgramId } from '@store/types';
 import { captureTui, type TuiCapture } from '@e2e-harness/tui-capture';
+import { buildLaunch, waitForSocket } from '@e2e-harness/launch';
 
 const text = (data: unknown) => ({
   content: [
@@ -35,43 +37,23 @@ const errorOut = (e: unknown) => ({
   ],
   isError: true,
 });
-
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
 let cap: TuiCapture | null = null;
-let sockPath = '';
+let client: ControlClient | null = null;
 
-/** One request/response over the host's control socket (newline-delimited JSON). */
-function rpc(req: object): Promise<{
-  ok: boolean;
-  state?: unknown;
-  error?: string;
-  runStatus?: string;
-}> {
-  return new Promise((resolve, reject) => {
-    if (!sockPath)
-      return reject(new Error('No app open. Call open_app first.'));
-    const sock = net.connect(sockPath);
-    let buf = '';
-    const timer = setTimeout(() => {
-      sock.destroy();
-      reject(new Error('control socket timeout'));
-    }, 600_000);
-    sock.on('connect', () => sock.write(JSON.stringify(req) + '\n'));
-    sock.on('data', (d) => {
-      buf += d;
-      const i = buf.indexOf('\n');
-      if (i >= 0) {
-        clearTimeout(timer);
-        sock.end();
-        resolve(JSON.parse(buf.slice(0, i)));
-      }
-    });
-    sock.on('error', (e) => {
-      clearTimeout(timer);
-      reject(e);
-    });
-  });
+function active(): ControlClient {
+  if (!client) throw new Error('No app open. Call open_app first.');
+  return client;
+}
+
+/** read_state adds the background run status under its historical names. */
+function withRunStatus(state: ControlState): Record<string, unknown> {
+  return {
+    ...state,
+    integration: state.run.status,
+    integrationError: state.run.error,
+  };
 }
 
 async function waitFor(cond: () => boolean, ms: number): Promise<boolean> {
@@ -84,11 +66,11 @@ async function waitFor(cond: () => boolean, ms: number): Promise<boolean> {
 }
 
 async function main() {
-  const server = new McpServer({ name: 'wizard-ci', version: '1.0.0' });
+  const server = new McpServer({ name: 'wizard-ci', version: '2.0.0' });
 
   server.tool(
     'open_app',
-    'Boot the real wizard TUI on an app and make it active. Call once before the other tools. appDir is a throwaway copy of the app to integrate. Returns the first screen.',
+    'Boot the real wizard TUI on an app and make it active. Call once before the other tools. appDir is a throwaway copy of the app to integrate. Returns the first state.',
     {
       appDir: z
         .string()
@@ -113,37 +95,28 @@ async function main() {
       try {
         if (cap) cap.kill();
         const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-ci-'));
-        sockPath = path.join(dir, 'host.sock');
-        // Strip the host's Claude Code / Anthropic auth so the wizard's agent
-        // subprocess authenticates with the phx key instead of deferring to the
-        // host session (which yields apiKeySource=none → 401).
-        const env: NodeJS.ProcessEnv = { ...process.env };
-        for (const k of Object.keys(env))
-          if (/^(CLAUDE|ANTHROPIC|AI_AGENT)/.test(k)) delete env[k];
-        Object.assign(env, {
-          MODE: 'serve',
-          CONTROL_SOCK: sockPath,
-          SNAP_CTRL: path.join(dir, 'ctrl'),
-          APP_DIR: appDir,
-          PROJECT_ID: projectId,
-          POSTHOG_REGION: region ?? 'us',
-          // Pass the key the way the caller gave it; never write an inline key to
-          // disk. The host reads either form (POSTHOG_PERSONAL_API_KEY wins).
-          ...(keyFile
-            ? { POSTHOG_KEY_FILE: keyFile }
-            : { POSTHOG_PERSONAL_API_KEY: (apiKey ?? '').trim() }),
+        const socketPath = path.join(dir, 'w.sock');
+        const key = (
+          keyFile ? fs.readFileSync(keyFile, 'utf8') : apiKey ?? ''
+        ).trim();
+        const launch = buildLaunch({
+          programId:
+            (process.env.PROGRAM as ProgramId) || Program.PostHogIntegration,
+          appDir,
+          socketPath,
+          projectId,
+          region: region ?? 'us',
+          apiKey: key || undefined,
+          e2eAsk: process.env.E2E_ASK === 'true',
+          harness: process.env.SNAP_HARNESS || undefined,
+          sequence: process.env.SNAP_SEQUENCE || undefined,
+          model: process.env.SNAP_MODEL || undefined,
         });
-        cap = captureTui({
-          cmd: path.join(process.cwd(), 'node_modules/.bin/tsx'),
-          args: ['scripts/tui-host.no-jest.ts'],
-          cwd: process.cwd(),
-          env,
-        });
-        if (!(await waitFor(() => fs.existsSync(sockPath), 30_000)))
-          return errorOut(new Error('the TUI host did not start'));
+        cap = captureTui({ ...launch, cwd: process.cwd() });
+        await waitForSocket(socketPath, 60_000);
+        client = new ControlClient(socketPath);
         await waitFor(() => cap!.frame().includes('PostHog'), 30_000);
-        const r = await rpc({ type: 'read_state' });
-        return text(r.state ?? r);
+        return text(withRunStatus(await client.state()));
       } catch (e) {
         return errorOut(e);
       }
@@ -152,12 +125,11 @@ async function main() {
 
   server.tool(
     'read_state',
-    "Read the wizard's committed state: current screen, run phase, a secret-free session view, tasks, pending question, and the actions legal now. Call after every perform_action and to poll run_agent (integration: running → done).",
+    "Read the wizard's committed state: current screen, run phase, a secret-free session view, tasks, pending question, and the actions legal now. Call after every perform_action and to poll run_agent (integration: running -> done).",
     {},
     async () => {
       try {
-        const r = await rpc({ type: 'read_state' });
-        return text(r.state ?? r);
+        return text(withRunStatus(await active().state()));
       } catch (e) {
         return errorOut(e);
       }
@@ -176,12 +148,7 @@ async function main() {
     },
     async ({ action, params }) => {
       try {
-        const r = await rpc({
-          type: 'perform_action',
-          action,
-          params: params ?? {},
-        });
-        return text(r.state ?? r);
+        return text(await active().performAction(action, params ?? {}));
       } catch (e) {
         return errorOut(e);
       }
@@ -190,7 +157,7 @@ async function main() {
 
   server.tool(
     'render_screen',
-    'Return the REAL rendered TUI screen (ANSI-stripped text) — exactly what the user would see.',
+    'Return the REAL rendered TUI screen (ANSI-stripped text), exactly what the user would see.',
     {},
     async () => {
       try {
@@ -205,15 +172,16 @@ async function main() {
 
   server.tool(
     'run_agent',
-    'Kick off the real integration in the background and return immediately. It advances the auth and run screens (they never advance on their own). Then poll read_state — integration goes running → done and currentScreen advances to outro, or → failed with the reason in integrationError. Creates real PostHog resources (a dashboard + insights). Call once setup is confirmed.',
+    'Release the real program run in the background and return immediately. The runner then advances the auth and run screens (they never advance on their own). Poll read_state: integration goes running -> done and currentScreen advances to outro, or -> failed with the reason in integrationError. Creates real PostHog resources (a dashboard + insights). Call once setup is confirmed.',
     {},
     async () => {
       try {
-        const r = await rpc({ type: 'run_agent' });
+        const run = await active().armRun();
         return text({
           status:
-            'integration started in the background — poll read_state (integration: running → done; screen advances to outro)',
-          ...r,
+            'integration started in the background; poll read_state (integration: running -> done; screen advances to outro)',
+          ok: true,
+          runStatus: run.status,
         });
       } catch (e) {
         return errorOut(e);
@@ -225,7 +193,9 @@ async function main() {
   process.stderr.write('wizard-ci-mcp: proxy ready on stdio\n');
 }
 
-main().catch((e) => {
-  process.stderr.write(`wizard-ci-mcp fatal: ${e?.stack ?? e}\n`);
+main().catch((e: unknown) => {
+  process.stderr.write(
+    `wizard-ci-mcp fatal: ${(e as Error)?.stack ?? String(e)}\n`,
+  );
   process.exit(1);
 });
diff --git a/src/store/control/__tests__/state.test.ts b/src/store/control/__tests__/state.test.ts
index 85d752ab6..d35c2f986 100644
--- a/src/store/control/__tests__/state.test.ts
+++ b/src/store/control/__tests__/state.test.ts
@@ -111,14 +111,18 @@ describe('projectState', () => {
         kind: OutroKind.Error,
         errorCode: 'PHW_INTERNAL_UNHANDLED',
         message: 'boom',
+        body: 'long body copy',
       },
       dashboardUrl: 'https://us.posthog.com/project/1/dashboard/2',
       notebookUrl: null,
       handoffText: null,
     });
-    expect(JSON.stringify(projectState(store, RUN))).not.toContain(
-      'long body copy',
-    );
+    expect(projectState(store, RUN).outroData).toEqual({
+      kind: OutroKind.Error,
+      errorCode: 'PHW_INTERNAL_UNHANDLED',
+      message: 'boom',
+      body: 'long body copy',
+    });
   });
 
   it('redacts by key and by secret ref only', () => {
diff --git a/src/store/control/state.ts b/src/store/control/state.ts
index 0169590c8..6b5600704 100644
--- a/src/store/control/state.ts
+++ b/src/store/control/state.ts
@@ -43,6 +43,7 @@ export function outroView(store: WizardStore): OutroView | null {
     kind: data.kind,
     ...(data.errorCode ? { errorCode: data.errorCode } : {}),
     ...(data.message ? { message: data.message } : {}),
+    ...(data.body ? { body: data.body } : {}),
     ...(data.docsUrl ? { docsUrl: data.docsUrl } : {}),
   };
 }
diff --git a/src/store/control/types.ts b/src/store/control/types.ts
index ab5ddf2bb..aa562199f 100644
--- a/src/store/control/types.ts
+++ b/src/store/control/types.ts
@@ -43,6 +43,7 @@ export interface OutroView {
   kind: OutroKind;
   errorCode?: ErrorCode;
   message?: string;
+  body?: string;
   docsUrl?: string;
 }
 
diff --git a/src/store/programs/index.ts b/src/store/programs/index.ts
index d2881c969..9d9f6284e 100644
--- a/src/store/programs/index.ts
+++ b/src/store/programs/index.ts
@@ -16,6 +16,7 @@ export {
 } from './error-tracking-upload-source-maps/detect.js';
 export {
   VARIANT_DISPLAY_NAME,
+  detectSourceMapsPrerequisites,
   errorTrackingUploadSourceMapsConfig,
 } from './error-tracking-upload-source-maps/index.js';
 export {
diff --git a/src/store/state/store-api.ts b/src/store/state/store-api.ts
index c0012df58..f59a81b99 100644
--- a/src/store/state/store-api.ts
+++ b/src/store/state/store-api.ts
@@ -10,7 +10,6 @@ export const STORE_BOUNDARY_MEMBERS = [
   'addDiscoveredFeature',
   'analyticsProgramId',
   'backupAndFixSettingsOverride',
-  'cancelPendingQuestion',
   'chooseProvisionAccount',
   'completeRunStep',
   'completeSetup',
@@ -27,7 +26,6 @@ export const STORE_BOUNDARY_MEMBERS = [
   'getGate',
   'getSnapshot',
   'grantSharing',
-  'hasInterrupt',
   'interruptDepth',
   'pushStatus',
   'requestRun',

From 303fdfbdefbb834c5fb67cfc2821eedd9481eb83 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 11:48:42 -0400
Subject: [PATCH 2/8] chore(cli): route every command through the surface
 dispatch

self-driving, upload-source-maps, doctor, and skill branched on --ci
themselves and never saw the control socket. They dispatch through
dispatchProgram now, so --ci with --control-socket drives the real TUI for
every command, and self-driving refuses --ci only when no parent is attached.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 src/cli/__tests__/control-surface.test.ts   | 45 ++++++++++++++++++++-
 src/cli/commands/basic-integration/skill.ts |  9 +----
 src/cli/commands/doctor.ts                  |  5 ++-
 src/cli/commands/self-driving.ts            | 17 +++-----
 src/cli/commands/upload-sourcemaps.ts       | 15 +------
 5 files changed, 56 insertions(+), 35 deletions(-)

diff --git a/src/cli/__tests__/control-surface.test.ts b/src/cli/__tests__/control-surface.test.ts
index ee0178071..3e78442bc 100644
--- a/src/cli/__tests__/control-surface.test.ts
+++ b/src/cli/__tests__/control-surface.test.ts
@@ -9,7 +9,13 @@ const runners = vi.hoisted(() => ({
 vi.mock('../runners/index.js', () => runners);
 
 import { HEADLESS_FLAG } from '@env';
-import { posthogIntegrationConfig } from '@store/programs';
+import {
+  errorTrackingUploadSourceMapsConfig,
+  posthogIntegrationConfig,
+  selfDrivingConfig,
+} from '@store/programs';
+import { selfDrivingCommand } from '../commands/self-driving.js';
+import { uploadSourcemapsCommand } from '../commands/upload-sourcemaps.js';
 import { dispatchProgram } from '../commands/factories/shared.js';
 import { GLOBAL_OPTIONS } from '../wizard.js';
 
@@ -57,3 +63,40 @@ describe('surface dispatch', () => {
     );
   });
 });
+
+describe('commands with their own handlers follow the same dispatch', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('self-driving refuses --ci alone and accepts it with a control socket', () => {
+    expect(() => selfDrivingCommand.check?.(argv({ ci: true }))).toThrow(
+      /cannot run in CI mode/,
+    );
+    expect(
+      selfDrivingCommand.check?.(
+        argv({ ci: true, controlSocket: '/tmp/c.sock' }),
+      ),
+    ).toBe(true);
+  });
+
+  it.each([
+    ['self-driving', selfDrivingCommand, selfDrivingConfig],
+    [
+      'upload-source-maps',
+      uploadSourcemapsCommand,
+      errorTrackingUploadSourceMapsConfig,
+    ],
+  ] as const)(
+    '%s routes ci + socket to the controlled TUI',
+    (_name, command, config) => {
+      command.handler?.(argv({ ci: true, controlSocket: '/tmp/c.sock' }));
+      expect(runners.runWizard).toHaveBeenCalledWith(
+        config,
+        expect.objectContaining({ ci: true, controlSocket: '/tmp/c.sock' }),
+      );
+      expect(runners.runWizardCI).not.toHaveBeenCalled();
+      vi.clearAllMocks();
+      command.handler?.(argv({ ci: true }));
+      expect(runners.runWizardCI).toHaveBeenCalledTimes(1);
+    },
+  );
+});
diff --git a/src/cli/commands/basic-integration/skill.ts b/src/cli/commands/basic-integration/skill.ts
index 100693e39..8cd0e6b13 100644
--- a/src/cli/commands/basic-integration/skill.ts
+++ b/src/cli/commands/basic-integration/skill.ts
@@ -1,6 +1,6 @@
 import type { Arguments } from 'yargs';
 import { POSTHOG_DOCS_URL } from '@store';
-import { runWizard, runWizardCI } from '../../runners/index.js';
+import { dispatchProgram } from '../factories/shared.js';
 import { createSkillProgram } from '@store/programs';
 
 /** Run an arbitrary context-mill skill by id (`wizard skill <id>`, headless with `--ci`). */
@@ -18,10 +18,5 @@ export function runSkillMode(argv: Arguments): void {
     spinnerMessage: `Running ${skillId}...`,
     estimatedDurationMinutes: 5,
   });
-  const options = { ...argv, skillId };
-  if (argv.ci) {
-    runWizardCI(config, options);
-  } else {
-    runWizard(config, options);
-  }
+  dispatchProgram(config, { ...argv, skillId });
 }
diff --git a/src/cli/commands/doctor.ts b/src/cli/commands/doctor.ts
index 6db0d18a6..e389c6a32 100644
--- a/src/cli/commands/doctor.ts
+++ b/src/cli/commands/doctor.ts
@@ -28,8 +28,9 @@ export const doctorCommand: Command = {
       {};
     const options = { ...argv, ...extras };
     // doctor is otherwise a TUI-only diagnostic (it has no agent run); in CI we
-    // fetch the project's health issues headlessly and report them instead.
-    if (options.ci) {
+    // fetch the project's health issues headlessly and report them instead. A
+    // control socket means a parent drives the real TUI.
+    if (options.ci && !options.controlSocket) {
       void runDoctorCI(options);
     } else {
       runWizard(posthogDoctorConfig, options);
diff --git a/src/cli/commands/self-driving.ts b/src/cli/commands/self-driving.ts
index 48953163a..130f5108d 100644
--- a/src/cli/commands/self-driving.ts
+++ b/src/cli/commands/self-driving.ts
@@ -1,4 +1,4 @@
-import { runWizard, runWizardCI } from '../runners/index.js';
+import { dispatchProgram } from './factories/shared.js';
 import { selfDrivingConfig } from '@store/programs';
 import { skillProgramOptions } from './skill-program-options.js';
 import type { Command } from './command.js';
@@ -29,7 +29,9 @@ export const selfDrivingCommand: Command = {
           '(no flag needed).',
       );
     }
-    if (argv.ci) {
+    // A controlling parent on the socket answers those steps, so `--ci` is
+    // fine when a control socket is attached.
+    if (argv.ci && !argv.controlSocket) {
       throw new Error(
         '`self-driving` cannot run in CI mode — it requires interactive steps ' +
           '(GitHub connect, issue-tracker selection, custom-scout approval).',
@@ -37,14 +39,5 @@ export const selfDrivingCommand: Command = {
     }
     return true;
   },
-  handler: (argv) => {
-    const extras =
-      selfDrivingConfig.mapCliOptions?.(argv as Record<string, unknown>) ?? {};
-    const options = { ...argv, ...extras };
-    if (options.ci) {
-      runWizardCI(selfDrivingConfig, options);
-    } else {
-      runWizard(selfDrivingConfig, options);
-    }
-  },
+  handler: (argv) => dispatchProgram(selfDrivingConfig, argv),
 };
diff --git a/src/cli/commands/upload-sourcemaps.ts b/src/cli/commands/upload-sourcemaps.ts
index 47ba9e9ff..dcafcf9a5 100644
--- a/src/cli/commands/upload-sourcemaps.ts
+++ b/src/cli/commands/upload-sourcemaps.ts
@@ -1,4 +1,4 @@
-import { runWizard, runWizardCI } from '../runners/index.js';
+import { dispatchProgram } from './factories/shared.js';
 import { errorTrackingUploadSourceMapsConfig } from '@store/programs';
 import { skillProgramOptions } from './skill-program-options.js';
 import type { Command } from './command.js';
@@ -11,16 +11,5 @@ export const uploadSourcemapsCommand: Command = {
     ...skillProgramOptions,
     ...(errorTrackingUploadSourceMapsConfig.cliOptions ?? {}),
   },
-  handler: (argv) => {
-    const extras =
-      errorTrackingUploadSourceMapsConfig.mapCliOptions?.(
-        argv as Record<string, unknown>,
-      ) ?? {};
-    const options = { ...argv, ...extras };
-    if (options.ci) {
-      runWizardCI(errorTrackingUploadSourceMapsConfig, options);
-    } else {
-      runWizard(errorTrackingUploadSourceMapsConfig, options);
-    }
-  },
+  handler: (argv) => dispatchProgram(errorTrackingUploadSourceMapsConfig, argv),
 };

From fa416ddf9efe5b4b4d2cd06b40226b0f2a5cfe50 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 11:53:09 -0400
Subject: [PATCH 3/8] chore(harness): exit a failed run from the handoff screen

A failed run parks the TUI on the handoff screen until someone chooses. The
fixed profile now exits from it and ends the walk, so the result payload
carries the abort reason instead of the run waiting out its timeout.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 e2e-harness/ARCHITECTURE.md                   |  4 ++++
 .../__tests__/e2e-profile-failure.test.ts     | 19 +++++++++++++++++++
 e2e-harness/e2e-profile.ts                    |  5 +++++
 3 files changed, 28 insertions(+)
 create mode 100644 e2e-harness/__tests__/e2e-profile-failure.test.ts

diff --git a/e2e-harness/ARCHITECTURE.md b/e2e-harness/ARCHITECTURE.md
index 6ec98f543..4eefe11a6 100644
--- a/e2e-harness/ARCHITECTURE.md
+++ b/e2e-harness/ARCHITECTURE.md
@@ -123,6 +123,10 @@ bearer. CI uses it directly and never mints or refreshes it.
   `run_agent` to the API; `render_screen` returns the captured frame as plain
   text. The agent decides each screen itself.
 
+A run that fails parks the TUI on the handoff screen (flow key `mint-failure`,
+any failed run, not only a gateway mint). The snapshot route exits from it and
+the result payload carries the abort reason from the outro.
+
 Both routes use a 180x50 PTY by default; `PTY_COLS` and `PTY_ROWS` override it.
 
 ## Run selection and state
diff --git a/e2e-harness/__tests__/e2e-profile-failure.test.ts b/e2e-harness/__tests__/e2e-profile-failure.test.ts
new file mode 100644
index 000000000..e92075b2e
--- /dev/null
+++ b/e2e-harness/__tests__/e2e-profile-failure.test.ts
@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { ScreenId } from '@tui/router';
+import type { ControlState } from '@store/types';
+import { DEFAULT_E2E_PROFILE, decideE2eAction } from '@e2e-harness/e2e-profile';
+
+describe('a failed run', () => {
+  it('exits from the handoff screen and ends the walk', () => {
+    const state = {
+      currentScreen: ScreenId.MintFailure,
+      pendingQuestion: null,
+      taskNotice: null,
+      setupQuestions: [],
+    } as unknown as ControlState;
+    expect(decideE2eAction(state, DEFAULT_E2E_PROFILE)).toEqual({
+      action: { id: 'dismiss_outro' },
+      done: true,
+    });
+  });
+});
diff --git a/e2e-harness/e2e-profile.ts b/e2e-harness/e2e-profile.ts
index e24401a32..2b7f19772 100644
--- a/e2e-harness/e2e-profile.ts
+++ b/e2e-harness/e2e-profile.ts
@@ -391,6 +391,10 @@ export function decideE2eAction(
       };
     }
 
+    // A failed run parks on the handoff screen until someone chooses; a
+    // headless run exits from it and reports the abort through outroData.
+    case ScreenId.MintFailure:
+      return { action: { id: 'dismiss_outro' }, done: true };
     // auth (runner), run (agent), ai-opt-in (ci), exit, terminal overlays.
     default:
       return { wait: true };
@@ -409,6 +413,7 @@ export const E2E_DRIVABLE_SCREENS: readonly ScreenName[] = [
   ScreenId.McpSuggestedPrompts,
   ScreenId.SlackConnect,
   ScreenId.KeepSkills,
+  ScreenId.MintFailure,
   Overlay.WizardAsk,
   Overlay.TaskNotice,
 ];

From a1bc654e3ee5a9d02b4f89528fcfe6494d231bb9 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 12:09:22 -0400
Subject: [PATCH 4/8] chore(harness): let the TUI spec ride out the readiness
 verdict

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 .../__tests__/control-socket-tui.test.ts        | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/e2e-harness/__tests__/control-socket-tui.test.ts b/e2e-harness/__tests__/control-socket-tui.test.ts
index 4c202128a..d96c94e60 100644
--- a/e2e-harness/__tests__/control-socket-tui.test.ts
+++ b/e2e-harness/__tests__/control-socket-tui.test.ts
@@ -7,7 +7,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { ControlClient } from '@store/control';
+import { ControlClient, ControlClientError } from '@store/control';
 import { Program } from '@store/programs';
 import { buildLaunch, waitForSocket } from '@e2e-harness/launch';
 import { captureTui, type TuiCapture } from '@e2e-harness/tui-capture';
@@ -51,14 +51,19 @@ describe.skipIf(process.env.WIZARD_PTY_TESTS === '0')(
       expect(intro.actions.map((a) => a.id)).toEqual(['confirm_setup']);
 
       let state = await client.performAction('confirm_setup');
-      // The readiness probe decides the health-check screen: wait for its verdict,
-      // then dismiss an outage the way a person would.
+      // The readiness probe decides the health-check screen. Dismiss an outage
+      // the way a person would; a 400 means the probe moved the screen first.
       const deadline = Date.now() + 30_000;
       while (state.currentScreen === 'health-check' && Date.now() < deadline) {
-        state = await client.waitForChange(state.version, 5_000);
+        try {
+          state = await client.performAction('dismiss_outage');
+        } catch (err) {
+          if (!(err instanceof ControlClientError && err.status === 400))
+            throw err;
+          state = await client.state();
+        }
         if (state.currentScreen === 'health-check') {
-          const next = await client.performAction('dismiss_outage');
-          if (next.currentScreen !== 'health-check') state = next;
+          state = await client.waitForChange(state.version, 5_000);
         }
       }
       expect(state.currentScreen).toBe('auth');

From d1f164a6ec120956e0abde9db73819df0ac8b923 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 12:20:13 -0400
Subject: [PATCH 5/8] chore(harness): document how to run every route

The harness architecture doc gains the commands for the snapshot route, the
MCP route, the controlled headless smoke, and the process specs; AGENTS.md
points at it. The store boundary constant matches this tree's usage.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 AGENTS.md                   | 31 +++++++++++++++++--------------
 e2e-harness/ARCHITECTURE.md | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 31ceaa57f..10d375858 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -34,11 +34,13 @@ Each domain has a dedicated boundary:
 - **TUI** → screen components and primitives in `src/tui/`
 
 The tree is three surfaces plus a composition root: `src/store` (state and
-contracts), `src/agent` (one agent run), `src/tui` (rendering), `src/cli`
-(argv and wiring). Surfaces import each other only through `@store`,
-`@store/types`, `@store/programs`, `@agent`, `@agent/types`, `@tui`,
-`@tui/types`, and `@tui/console`; `src/__tests__/architecture` enforces it.
-Each surface's `README.md` lists what it owns and may import.
+contracts), `src/agent` (one agent run), `src/tui` (rendering), `src/cli` (argv
+and wiring). Surfaces import each other only through `@store`, `@store/types`,
+`@store/programs`, `@agent`, `@agent/types`, `@tui`, `@tui/types`, and
+`@tui/console`; `src/__tests__/architecture` enforces it. Each surface's
+`README.md` lists what it owns and may import. To drive a run without a keyboard
+(snapshots, an agent, CI), use the control socket described in
+[`e2e-harness/ARCHITECTURE.md`](e2e-harness/ARCHITECTURE.md).
 
 Adding a new concern means finding the narrowest existing surface, not adding
 logic to the runner. Keep changes local to the boundary that owns them.
@@ -104,8 +106,8 @@ aliases.
 
 | Subcommand                    | What it audits                                       |
 | ----------------------------- | ---------------------------------------------------- |
-| `wizard audit events`         | event capture quality + cost                        |
-| `wizard audit all`            | comprehensive audit across every area (**default**) |
+| `wizard audit events`         | event capture quality + cost                         |
+| `wizard audit all`            | comprehensive audit across every area (**default**)  |
 | `wizard audit autocapture`    | autocapture setup + cost                             |
 | `wizard audit feature-flags`  | feature flag usage + cost                            |
 | `wizard audit identify`       | `$identify` implementation                           |
@@ -129,16 +131,16 @@ confuse it with the top-level `wizard skill` command.
 - **Registration:** [`src/cli/main.ts`](src/cli/main.ts) — the `.use()` chain
   wires each command. [`bin.ts`](bin.ts) runs the Node preflight, then imports
   it.
-- **Command shape:** [`src/cli/commands/command.ts`](src/cli/commands/command.ts) — the
-  `Command` interface every command implements.
+- **Command shape:**
+  [`src/cli/commands/command.ts`](src/cli/commands/command.ts) — the `Command`
+  interface every command implements.
 - **Flat native commands** (e.g. `revenue-analytics`, `upload-source-maps`) are
   built with `nativeCommandFactory`
   ([`src/cli/commands/factories/native-command-factory.ts`](src/cli/commands/factories/native-command-factory.ts)).
 - **Family commands** (e.g. `audit`) resolve subcommands at runtime against the
   `cliEntries` in `skill-menu.json`. Logic lives in
-  [`src/cli/dispatch-family.ts`](src/cli/dispatch-family.ts).
-  Adding a skill-backed subcommand is a **context-mill** release, not a wizard
-  change.
+  [`src/cli/dispatch-family.ts`](src/cli/dispatch-family.ts). Adding a
+  skill-backed subcommand is a **context-mill** release, not a wizard change.
 
 ### Commands vs. programs (don't confuse these)
 
@@ -166,6 +168,7 @@ pnpm try --install-dir=<path>      # Run the wizard locally against a test proje
 pnpm build                         # Compile TypeScript
 pnpm test                          # Unit tests (builds first)
 pnpm test:<surface>                # One Vitest project: store, agent, tui, cli, harness, arch
+                                   # harness spawns the real binary over its control socket; WIZARD_PTY_TESTS=0 skips the PTY spec
 pnpm typecheck                     # tsc -b over the surface projects (tsconfig.solution.json)
 pnpm typecheck:<surface>           # One surface project
 pnpm test:watch                    # Unit tests in watch mode
@@ -182,8 +185,8 @@ nonmutating lint checks, and scope formatting fixes to edited files. Do not add
 tests for prose, compiler-enforced shapes, or duplicated implementation. Keep
 new code comments to one line; put longer explanations in linked docs.
 
-Local `--ci`, smoke-test, and full headless runs require two separate secrets:
-a PostHog personal API key and an already-issued gateway token supplied through
+Local `--ci`, smoke-test, and full headless runs require two separate secrets: a
+PostHog personal API key and an already-issued gateway token supplied through
 `WIZARD_CI_GATEWAY_TOKEN_FILE`, plus the target project ID. Follow the
 [credential setup](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 
diff --git a/e2e-harness/ARCHITECTURE.md b/e2e-harness/ARCHITECTURE.md
index 4eefe11a6..010cec0d4 100644
--- a/e2e-harness/ARCHITECTURE.md
+++ b/e2e-harness/ARCHITECTURE.md
@@ -111,6 +111,40 @@ bearer. CI uses it directly and never mints or refreshes it.
 `WIZARD_CI_GATEWAY_URL` optionally overrides
 `https://ai-gateway.<region>.posthog.com`.
 
+## Run it
+
+Every route needs a throwaway copy of an app, the PostHog project id, and for a
+full run the personal API key plus the issued gateway bearer in
+`WIZARD_CI_GATEWAY_TOKEN_FILE` (no run ever mints). Detection-only walks need
+neither secret.
+
+```bash
+# Snapshot route: the fixed profile, frames, and the result payload
+PROGRAM=posthog-integration E2E_ASK=true \
+POSTHOG_KEY_FILE=/path/to/phx-key.txt WIZARD_CI_GATEWAY_TOKEN_FILE=/path/to/token.txt \
+PROJECT_ID=<id> POSTHOG_REGION=us APP_DIR=/tmp/app \
+SNAP_OUT=/tmp/snaps E2E_RESULT_JSON=/tmp/snaps/result.json \
+npx tsx scripts/tui-snapshots.no-jest.ts
+ls /tmp/snaps            # 01-intro.ans … NN-keep-skills.ans
+jq .screenPath /tmp/snaps/result.json
+
+# MCP route: open an app, confirm setup, read state, print one frame
+APP_DIR=/tmp/app PROJECT_ID=<id> POSTHOG_KEY_FILE=/path/to/phx-key.txt \
+npx tsx scripts/wizard-ci-explore.no-jest.ts
+
+# Controlled headless: detect, independent runs, the ledger, shutdown
+POSTHOG_WIZARD_API_KEY=phx_... WIZARD_CI_GATEWAY_TOKEN_FILE=/path/to/token.txt \
+npx tsx scripts/controlled-headless-smoke.no-jest.ts --app /tmp/app --project-id <id> posthog-integration metrics
+
+# Process specs: the real binary on both surfaces, no credentials, no agent run
+pnpm test:harness                       # WIZARD_PTY_TESTS=0 skips the PTY spec
+```
+
+`SNAP_HARNESS`, `SNAP_SEQUENCE`, `SNAP_MODEL` override the switchboard;
+`E2E_NOTICE`, `E2E_ANSWERS_FILE`, `INTEGRATE`, `TASK_STREAM_LOG`,
+`SOURCE_MAPS_RUN_BUILD`, and `SOURCE_MAPS_CLI_KEY` keep their meanings from the
+workbench contract. `PTY_COLS` and `PTY_ROWS` size the terminal.
+
 ## The two routes
 
 - **CI snapshots.** `tui-snapshots.no-jest.ts` spawns the wizard in a PTY,

From 67a7044b7c88199d2a1d3a94cb277077acae0cbd Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 13:01:43 -0400
Subject: [PATCH 6/8] chore(harness): read the store mirror over the socket

The routes, the profile, the recorder, and the process specs read
session.runPhase, session.pendingQuestion, session.taskNotice, and the
redacted session.frameworkContext where the control state now mirrors the
store; the MCP proxy derives its integration status from the run phase.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 .claude/skills/exploring-the-wizard/SKILL.md  | 26 +++++----
 e2e-harness/ARCHITECTURE.md                   | 41 +++++++------
 e2e-harness/__tests__/control-driver.test.ts  | 58 ++++++++++---------
 .../__tests__/control-socket-headless.test.ts |  2 +-
 .../__tests__/e2e-flow-snapshot.test.ts       |  5 +-
 e2e-harness/__tests__/e2e-profile-ask.test.ts | 17 ++++--
 .../__tests__/e2e-profile-failure.test.ts     |  3 +-
 e2e-harness/__tests__/e2e-result.test.ts      |  3 +-
 e2e-harness/e2e-profile.ts                    | 10 ++--
 e2e-harness/e2e-result.ts                     |  2 +-
 scripts/tui-snapshots.no-jest.ts              | 18 +++---
 scripts/wizard-ci-mcp.no-jest.ts              | 19 ++++--
 src/cli/README.md                             | 10 ++--
 13 files changed, 119 insertions(+), 95 deletions(-)

diff --git a/.claude/skills/exploring-the-wizard/SKILL.md b/.claude/skills/exploring-the-wizard/SKILL.md
index 23d64733f..d7a302517 100644
--- a/.claude/skills/exploring-the-wizard/SKILL.md
+++ b/.claude/skills/exploring-the-wizard/SKILL.md
@@ -62,11 +62,16 @@ It exposes exactly these tools:
 | `run_agent`      | None                                                                         | Starts the real program in the background and returns immediately |
 
 Use `read_state.actions` for action ids and parameters; there is no
-`list_actions` MCP tool. Framework identity is `session.integration`, with
+`list_actions` MCP tool. The state mirrors the wizard's store: `session` holds
+the detection, setup, run, and follow-up fields (`session.runPhase`,
+`session.pendingQuestion`, `session.taskNotice`, `session.outroData`, a redacted
+`session.frameworkContext`), beside `tasks`, `setupQuestions`, and `actions`.
+Framework identity is `session.integration`, with
 `session.detectedFrameworkLabel` and `session.detectionComplete`. The separate
 top-level `integration` field is the background status: `idle`, `running`,
-`done`, or `failed`; `integrationError` holds a caught failure. Those two fields
-are added by `read_state` and are absent from `perform_action` replies.
+`done`, or `failed`, derived from `session.runPhase`; `integrationError` holds a
+caught failure. Those two fields are added by `read_state` and are absent from
+`perform_action` replies.
 
 ## Drive and record
 
@@ -84,10 +89,11 @@ own decisions through the same state and action contract.
 4. For a full run, confirm setup and call `run_agent` at `auth`. Continue
    reading state and handling overlays while it runs; polling alone cannot
    answer them.
-5. Check `runPhase` (`idle`, `running`, `completed`, `error`), background
-   status, and the rendered outro. On error, capture the frame and reason before
-   dismissing it. An error outro can wait for dismissal while `integration`
-   still says `running`; a wizard exit can instead surface as a socket error.
+5. Check `session.runPhase` (`idle`, `running`, `completed`, `error`),
+   background status, and the rendered outro. On error, capture the frame and
+   reason before dismissing it. An error outro can wait for dismissal while
+   `integration` still says `running`; a wizard exit can instead surface as a
+   socket error.
 6. After successful agent completion, finish the offered outro and follow-up
    actions. For the integration flow, `session.skillsComplete` marks the tail's
    completion. Other programs can have a terminal outro or exit screen.
@@ -127,8 +133,8 @@ copies after recording their results.
 
 The shared log is `/tmp/posthog-wizard.log`. Record its byte count before a run
 and read from that count plus one afterward. Run sweeps serially so their logs
-remain attributable. `read_state` omits `frameworkContext`; an empty
-`setupQuestions` list alone does not prove a router mode. When necessary,
-inspect the detector under
+remain attributable. `read_state` shows `session.frameworkContext` after
+redaction; an empty `setupQuestions` list alone does not prove a router mode.
+When necessary, inspect the detector under
 [`src/store/frameworks/`](../../../src/store/frameworks/) against the same
 fixture.
diff --git a/e2e-harness/ARCHITECTURE.md b/e2e-harness/ARCHITECTURE.md
index 010cec0d4..1d4bfa378 100644
--- a/e2e-harness/ARCHITECTURE.md
+++ b/e2e-harness/ARCHITECTURE.md
@@ -74,20 +74,24 @@ program), 404 (unknown route), 409 (a run is in flight), 413 (body over 64 KB),
 | `GET /state?wait=<ms>&since=<version>`                                      | Long poll: resolves on the first commit with `version > since`, or after `wait` ms          |
 | `POST /actions/<id>` body `{ params }`                                      | Applies one action legal on the current screen through its store setter, returns the state  |
 | `POST /credentials`                                                         | Resolves the API key into project credentials and commits them, advancing `auth`            |
-| `POST /run`                                                                 | TUI surface: releases the runner's agent start. Idempotent                                  |
+| `POST /run`                                                                 | TUI surface: `requestRun` on the store, releasing the runner's agent start. Idempotent      |
 | `POST /detect` body `{ programId?, installDir? }`                           | Headless surface: runs detection through the store's setters                                |
 | `POST /runs` body `{ programId, installDir?, frameworkContext?, skillId? }` | Headless surface: one independent agent run; 409 while one runs                             |
 | `GET /runs`                                                                 | The run ledger: `runId`, `programId`, `installDir`, `status`, `error`, timestamps, `result` |
 | `POST /shutdown`                                                            | Flushes and exits. Idempotent                                                               |
 
-`state` carries `version`, `currentScreen`, `hasOverlay`, `runPhase`,
-`run: { status, error }`, a session whitelist (credentials reduce to
-`hasCredentials` and `projectId`), `tasks`, `statusMessages`, `eventPlan`,
-`pendingQuestion`, `taskNotice`, `setupQuestions`, `actions`, `dashboardUrl`,
-`notebookUrl`, `handoffText`, a reduced `outroData`, and `frameworkContext` as
-`{ keys, digest, values }` after redaction: `secret:<id>` refs become
-`[secret-ref]` and secret-looking keys become `[redacted]`. No access token, API
-key, user record, or answer value is ever projected.
+`state` mirrors the store: `version`, `currentScreen`, `session`, `tasks`,
+`statusMessages`, `eventPlan`, `handoffText`, the unanswered `setupQuestions`,
+and the `actions` legal on the current screen. `session` holds the fields in
+`CONTROL_SESSION_KEYS` (`src/store/control/state.ts`): detection, setup, and
+follow-up flags, `runRequested`, `runPhase`, `pendingQuestion`, `taskNotice`,
+`outroData`, `dashboardUrl`, `notebookUrl`, and `frameworkContext` after
+redaction (`secret:<id>` refs become `[secret-ref]`, secret-looking keys become
+`[redacted]`); credentials reduce to `hasCredentials` and `projectId`.
+`session.runPhase` is the run status and `session.outroData` carries a failed
+run's reason. No access token, API key, user record, or answer value is ever
+projected. A ledger record's `result` is this state as it read when the run
+ended.
 
 The socket is created mode 0600 in a directory the caller owns. A stale socket
 file is replaced; a live one is refused. The wizard unlinks it on exit.
@@ -171,15 +175,16 @@ overrides. Omitted values use normal flag and binding resolution. These are
 launcher environment inputs, not `open_app` arguments.
 
 `read_state` adds `integration` (`idle`, `running`, `done`, `failed`) and
-`integrationError`, copied from `state.run`. Framework identity is the separate
-`session.integration`. `perform_action` returns the state without those two
-fields, so read again to refresh the run status. Legal actions come from
-`state.actions`; there is no `list_actions` tool.
-
-Keep handling overlays while the agent runs. `runPhase=completed` ends the main
-work; `session.skillsComplete` ends the integration flow's follow-up screens.
-Recording MCP or keep-skills outcomes only commits store state; it does not
-install or delete anything. For failures, capture the error outro before
+`integrationError`, derived from `session.runPhase`, `session.runRequested`, and
+`session.outroData`. Framework identity is the separate `session.integration`.
+`perform_action` returns the state without those two fields, so read again to
+refresh the run status. Legal actions come from `state.actions`; there is no
+`list_actions` tool.
+
+Keep handling overlays while the agent runs. `session.runPhase=completed` ends
+the main work; `session.skillsComplete` ends the integration flow's follow-up
+screens. Recording MCP or keep-skills outcomes only commits store state; it does
+not install or delete anything. For failures, capture the error outro before
 dismissing it.
 
 ## Picker screens
diff --git a/e2e-harness/__tests__/control-driver.test.ts b/e2e-harness/__tests__/control-driver.test.ts
index 4c46280e6..644552a57 100644
--- a/e2e-harness/__tests__/control-driver.test.ts
+++ b/e2e-harness/__tests__/control-driver.test.ts
@@ -28,8 +28,6 @@ import { SOURCE_MAPS_CONTEXT_KEYS } from '@store/programs/error-tracking-upload-
 import { OutroKind } from '@store/session/wizard-session';
 import { flowFor } from '@store/programs/flow-for';
 
-const IDLE = () => ({ status: 'idle' as const, error: null });
-
 function freshStore(): WizardStore {
   const store = new WizardStore(flowFor(Program.PostHogIntegration).flow);
   // Headless: a real store + StoreUI (which only forwards to the store), no Ink
@@ -55,7 +53,7 @@ describe('ControlDriver — full integration flow', () => {
   it('lets a failed run exit or continue to MCP', () => {
     const store = freshStore();
     const ui = new StoreUI(store);
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     store.setCredentials({
       accessToken: 'phx_secret_should_not_leak',
       projectApiKey: 'phc_public',
@@ -76,11 +74,13 @@ describe('ControlDriver — full integration flow', () => {
 
   it('walks intro → setup → run → outro → mcp → slack → keep-skills', () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     // 1. Intro
     expect(driver.readState().currentScreen).toBe(ScreenId.Intro);
-    expect(driver.listActions().map((a) => a.id)).toContain('confirm_setup');
+    expect(driver.readState().actions.map((a) => a.id)).toContain(
+      'confirm_setup',
+    );
     driver.performAction('confirm_setup');
 
     // 2. Health check — blocks until a readiness result lands (mirrors onInit
@@ -139,7 +139,7 @@ describe('ControlDriver — full integration flow', () => {
 
   it('read_state is a truthful projection and never leaks the access token', () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     store.setCredentials({
       accessToken: 'phx_secret_should_not_leak',
       projectApiKey: 'phc_public',
@@ -157,7 +157,7 @@ describe('ControlDriver — full integration flow', () => {
 
   it('rejects actions that are not legal on the current screen', () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     expect(driver.readState().currentScreen).toBe(ScreenId.Intro);
     expect(() => driver.performAction('keep_skills')).toThrow(
       UnknownActionError,
@@ -168,7 +168,7 @@ describe('ControlDriver — full integration flow', () => {
 describe('ControlDriver — wizard_ask overlay', () => {
   it('answers a pending question through the driver, resolving the agent promise', async () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     // The agent (via the ask bridge) opens a question and awaits the answers.
     const answersPromise = store.requestQuestion({
@@ -189,9 +189,10 @@ describe('ControlDriver — wizard_ask overlay', () => {
 
     const state = driver.readState();
     expect(state.currentScreen).toBe(Overlay.WizardAsk);
-    expect(state.hasOverlay).toBe(true);
-    expect(state.pendingQuestion?.questions[0].id).toBe('router');
-    expect(driver.listActions().map((a) => a.id)).toContain('answer_question');
+    expect(state.session.pendingQuestion?.questions[0].id).toBe('router');
+    expect(driver.readState().actions.map((a) => a.id)).toContain(
+      'answer_question',
+    );
 
     // The driver commits the complete answer map directly — skipping the
     // per-question keystroke walk that lives in React-local state.
@@ -213,7 +214,7 @@ describe('ControlDriver — self-driving integration check', () => {
 
   it('exposes the integration check and commits set_integrate', () => {
     const store = selfDrivingStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     // Intro → integration-check.
     store.completeSetup();
@@ -234,7 +235,7 @@ describe('ControlDriver — self-driving integration check', () => {
       installDir: '/tmp/ci-driver-sd',
       integrate: true,
     });
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     store.completeSetup();
     expect(driver.readState().currentScreen).not.toBe(
@@ -266,7 +267,7 @@ describe('ControlDriver — source-maps project pick', () => {
 
   it('commits the pick the way the detect screen would and advances', () => {
     const store = sourceMapsStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     toDetectScreen(store);
     const state = driver.readState();
@@ -288,7 +289,7 @@ describe('ControlDriver — source-maps project pick', () => {
 
   it('requires the variant and path params', () => {
     const store = sourceMapsStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     toDetectScreen(store);
     expect(() =>
@@ -309,29 +310,27 @@ describe('ControlDriver — task-notice overlay', () => {
 
   it('projects the notice into read_state and keeps the step', async () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
 
     const kept = store.showTaskNotice(notice);
 
     const state = driver.readState();
     expect(state.currentScreen).toBe(Overlay.TaskNotice);
-    expect(state.taskNotice).toEqual({
-      title: 'Connect your data sources',
-      items: ['Postgres', 'Stripe'],
-      prompt: 'Connect these during setup?',
-    });
-    expect(driver.listActions().map((a) => a.id)).toContain('resolve_notice');
+    expect(state.session.taskNotice).toEqual(notice);
+    expect(driver.readState().actions.map((a) => a.id)).toContain(
+      'resolve_notice',
+    );
 
     driver.performAction('resolve_notice', { keep: true });
 
     await expect(kept).resolves.toBe(true);
-    expect(driver.readState().taskNotice).toBeNull();
+    expect(driver.readState().session.taskNotice).toBeNull();
     expect(driver.readState().currentScreen).not.toBe(Overlay.TaskNotice);
   });
 
   it('skips the step when keep is false', async () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     const kept = store.showTaskNotice(notice);
     driver.performAction('resolve_notice', { keep: false });
     await expect(kept).resolves.toBe(false);
@@ -339,16 +338,19 @@ describe('ControlDriver — task-notice overlay', () => {
 
   it('defaults to keeping the step when keep is omitted', async () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     const kept = store.showTaskNotice(notice);
     driver.performAction('resolve_notice');
     await expect(kept).resolves.toBe(true);
   });
 
-  it('projects an empty items list when the notice has none', () => {
+  it('projects the notice as the store holds it, items included', () => {
     const store = freshStore();
-    const driver = new ControlDriver(store, IDLE);
+    const driver = new ControlDriver(store);
     void store.showTaskNotice({ ...notice, items: undefined });
-    expect(driver.readState().taskNotice?.items).toEqual([]);
+    expect(driver.readState().session.taskNotice).toEqual(
+      store.session.taskNotice,
+    );
+    expect(driver.readState().session.taskNotice?.items).toBeUndefined();
   });
 });
diff --git a/e2e-harness/__tests__/control-socket-headless.test.ts b/e2e-harness/__tests__/control-socket-headless.test.ts
index abecda03a..f88f56918 100644
--- a/e2e-harness/__tests__/control-socket-headless.test.ts
+++ b/e2e-harness/__tests__/control-socket-headless.test.ts
@@ -62,7 +62,7 @@ describe('controlled headless surface', () => {
     });
     const state = await client.state();
     expect(state.currentScreen).toBe('intro');
-    expect(state.run).toEqual({ status: 'idle', error: null });
+    expect(state.session.runPhase).toBe('idle');
     expect(JSON.stringify(state)).not.toContain('phx_test_only');
     await expect(client.startRun({ programId: 'nope' })).rejects.toMatchObject({
       status: 400,
diff --git a/e2e-harness/__tests__/e2e-flow-snapshot.test.ts b/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
index 49a3d0e68..16d400999 100644
--- a/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
+++ b/e2e-harness/__tests__/e2e-flow-snapshot.test.ts
@@ -60,10 +60,7 @@ function traceFlow(
   }
   store.session = session;
 
-  const driver = new ControlDriver(store, () => ({
-    status: 'idle',
-    error: null,
-  }));
+  const driver = new ControlDriver(store);
 
   const trace: Array<{
     screen: string;
diff --git a/e2e-harness/__tests__/e2e-profile-ask.test.ts b/e2e-harness/__tests__/e2e-profile-ask.test.ts
index 715641aaa..346653106 100644
--- a/e2e-harness/__tests__/e2e-profile-ask.test.ts
+++ b/e2e-harness/__tests__/e2e-profile-ask.test.ts
@@ -49,14 +49,21 @@ function profile(over: Partial<WizardE2eProfile> = {}): WizardE2eProfile {
   return { ...DEFAULT_E2E_PROFILE, ...over };
 }
 
+type StateOverrides = Partial<Omit<ControlState, 'session'>> & {
+  pendingQuestion?: ControlState['session']['pendingQuestion'];
+  taskNotice?: Partial<
+    NonNullable<ControlState['session']['taskNotice']>
+  > | null;
+};
+
 /** A ControlState carrying just the fields the two overlay cases read. */
-function state(over: Partial<ControlState>): ControlState {
+function state(over: StateOverrides): ControlState {
+  const { pendingQuestion = null, taskNotice = null, ...rest } = over;
   return {
     currentScreen: ScreenId.Run,
-    pendingQuestion: null,
-    taskNotice: null,
     setupQuestions: [],
-    ...over,
+    session: { pendingQuestion, taskNotice },
+    ...rest,
   } as ControlState;
 }
 
@@ -490,7 +497,7 @@ describe('E2E_DRIVABLE_SCREENS', () => {
   it('has a decideE2eAction case for every screen it lists', () => {
     // A listed screen with no case would return `{ wait: true }` forever,
     // stalling the run instead of failing it.
-    const overlayState: Partial<Record<string, Partial<ControlState>>> = {
+    const overlayState: Partial<Record<string, StateOverrides>> = {
       [Overlay.WizardAsk]: {
         pendingQuestion: {
           id: 'a',
diff --git a/e2e-harness/__tests__/e2e-profile-failure.test.ts b/e2e-harness/__tests__/e2e-profile-failure.test.ts
index e92075b2e..c5dd48482 100644
--- a/e2e-harness/__tests__/e2e-profile-failure.test.ts
+++ b/e2e-harness/__tests__/e2e-profile-failure.test.ts
@@ -7,9 +7,8 @@ describe('a failed run', () => {
   it('exits from the handoff screen and ends the walk', () => {
     const state = {
       currentScreen: ScreenId.MintFailure,
-      pendingQuestion: null,
-      taskNotice: null,
       setupQuestions: [],
+      session: { pendingQuestion: null, taskNotice: null },
     } as unknown as ControlState;
     expect(decideE2eAction(state, DEFAULT_E2E_PROFILE)).toEqual({
       action: { id: 'dismiss_outro' },
diff --git a/e2e-harness/__tests__/e2e-result.test.ts b/e2e-harness/__tests__/e2e-result.test.ts
index 03e97a8ca..2b503da88 100644
--- a/e2e-harness/__tests__/e2e-result.test.ts
+++ b/e2e-harness/__tests__/e2e-result.test.ts
@@ -512,9 +512,8 @@ describe('security rail — no answer value reaches the payload', () => {
     const decision = decideE2eAction(
       {
         currentScreen: Overlay.WizardAsk,
-        pendingQuestion: pending,
-        taskNotice: null,
         setupQuestions: [],
+        session: { pendingQuestion: pending, taskNotice: null },
       } as unknown as ControlState,
       {
         ...DEFAULT_E2E_PROFILE,
diff --git a/e2e-harness/e2e-profile.ts b/e2e-harness/e2e-profile.ts
index 2b7f19772..5039c3857 100644
--- a/e2e-harness/e2e-profile.ts
+++ b/e2e-harness/e2e-profile.ts
@@ -14,8 +14,10 @@ import type { ControlState } from '@store/types';
 /** The slice of the control state a decision reads. */
 export type E2eObservedState = Pick<
   ControlState,
-  'currentScreen' | 'setupQuestions' | 'pendingQuestion' | 'taskNotice'
->;
+  'currentScreen' | 'setupQuestions'
+> & {
+  session: Pick<ControlState['session'], 'pendingQuestion' | 'taskNotice'>;
+};
 
 /** Which option to pick for a setup disambiguation question. */
 export type SetupChoice = 'first' | 'last';
@@ -357,7 +359,7 @@ export function decideE2eAction(
       };
 
     case Overlay.WizardAsk: {
-      const pending = state.pendingQuestion;
+      const pending = state.session.pendingQuestion;
       if (!pending || pending.questions.length === 0) return { wait: true };
       // Answer the whole batch. The bridge resolves on one answers map, so a
       // partial map would leave the unanswered fields empty for the agent.
@@ -378,7 +380,7 @@ export function decideE2eAction(
     }
 
     case Overlay.TaskNotice: {
-      const notice = state.taskNotice;
+      const notice = state.session.taskNotice;
       if (!notice) return { wait: true };
       const keep = profile.notice !== 'decline';
       return {
diff --git a/e2e-harness/e2e-result.ts b/e2e-harness/e2e-result.ts
index 50a8c30dc..59779be1a 100644
--- a/e2e-harness/e2e-result.ts
+++ b/e2e-harness/e2e-result.ts
@@ -55,7 +55,7 @@ export interface E2eNoticeRecord {
   at: string;
 }
 
-/** The session fields the recorder watches. */
+/** The session fields the recorder watches; `state.session` satisfies it. */
 type ObservedSession = {
   pendingQuestion: PendingQuestion | null;
   taskNotice: { title: string; items?: string[] } | null;
diff --git a/scripts/tui-snapshots.no-jest.ts b/scripts/tui-snapshots.no-jest.ts
index 0aaea7607..c5ac38b86 100644
--- a/scripts/tui-snapshots.no-jest.ts
+++ b/scripts/tui-snapshots.no-jest.ts
@@ -195,10 +195,9 @@ async function main(): Promise<void> {
   const snap = async (state: ControlState): Promise<void> => {
     const sig = JSON.stringify({
       screen: state.currentScreen,
-      overlay: state.hasOverlay,
       tasks: state.tasks.map((t) => [t.label, t.status]),
-      phase: state.runPhase,
-      ctx: state.frameworkContext.digest,
+      phase: state.session.runPhase,
+      ctx: state.session.frameworkContext,
     });
     if (sig === lastSig) return;
     lastSig = sig;
@@ -225,7 +224,7 @@ async function main(): Promise<void> {
       JSON.stringify(
         buildE2eResult({
           base: {
-            runPhase: state.runPhase,
+            runPhase: state.session.runPhase,
             hasPosthogDep: deps.length > 0,
             newDeps: deps,
             envFile: envFileWithPosthog(APP_DIR),
@@ -233,10 +232,7 @@ async function main(): Promise<void> {
             skillsComplete: state.session.skillsComplete,
           },
           recorder,
-          session: {
-            frameworkContext: state.frameworkContext.values,
-            outroData: state.outroData,
-          },
+          session: state.session,
           tasks: state.tasks,
           reportFile: readReportFile(APP_DIR, programConfig.reportFile),
         }),
@@ -261,7 +257,7 @@ async function main(): Promise<void> {
     }
     lastState = state;
     await snap(state);
-    recorder.observe(state);
+    recorder.observe(state.session);
     if (state.currentScreen === 'outro') {
       writeResult(state);
       resultWritten = false; // the tail (keep-skills) rewrites it at the end
@@ -284,7 +280,7 @@ async function main(): Promise<void> {
     }
     if (
       before === 'source-maps-detect' &&
-      !state.frameworkContext.keys.includes('selectedVariant')
+      !('selectedVariant' in state.session.frameworkContext)
     ) {
       const picked = pickSourceMapsVariant(APP_DIR);
       if ('error' in picked) {
@@ -306,7 +302,7 @@ async function main(): Promise<void> {
 
     // Program-specific ask answers take precedence over the profile strategy.
     if (before === 'wizard-ask') {
-      const q = state.pendingQuestion?.questions[0];
+      const q = state.session.pendingQuestion?.questions[0];
       const override = q ? askOverrides[programId]?.[q.id] : undefined;
       if (q && override !== undefined) {
         await client.performAction('answer_question', {
diff --git a/scripts/wizard-ci-mcp.no-jest.ts b/scripts/wizard-ci-mcp.no-jest.ts
index dd475b8ee..38326c0c1 100644
--- a/scripts/wizard-ci-mcp.no-jest.ts
+++ b/scripts/wizard-ci-mcp.no-jest.ts
@@ -14,6 +14,7 @@ import { z } from 'zod';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import { RunPhase } from '@store';
 import { ControlClient } from '@store/control';
 import { Program } from '@store/programs';
 import type { ControlState, ProgramId } from '@store/types';
@@ -47,12 +48,22 @@ function active(): ControlClient {
   return client;
 }
 
+const RUN_STATUS: Record<RunPhase, string> = {
+  [RunPhase.Idle]: 'idle',
+  [RunPhase.Running]: 'running',
+  [RunPhase.Completed]: 'done',
+  [RunPhase.Error]: 'failed',
+};
+
 /** read_state adds the background run status under its historical names. */
 function withRunStatus(state: ControlState): Record<string, unknown> {
+  const { runPhase, runRequested, outroData } = state.session;
+  const armed = runPhase === RunPhase.Idle && runRequested;
   return {
     ...state,
-    integration: state.run.status,
-    integrationError: state.run.error,
+    integration: armed ? 'running' : RUN_STATUS[runPhase],
+    integrationError:
+      runPhase === RunPhase.Error ? outroData?.message ?? null : null,
   };
 }
 
@@ -176,12 +187,12 @@ async function main() {
     {},
     async () => {
       try {
-        const run = await active().armRun();
+        const state = await active().armRun();
         return text({
           status:
             'integration started in the background; poll read_state (integration: running -> done; screen advances to outro)',
           ok: true,
-          runStatus: run.status,
+          runRequested: state.session.runRequested,
         });
       } catch (e) {
         return errorOut(e);
diff --git a/src/cli/README.md b/src/cli/README.md
index 69a9c4028..1ac77c7e2 100644
--- a/src/cli/README.md
+++ b/src/cli/README.md
@@ -11,11 +11,11 @@ surfaces' public entries. Holds no domain logic.
 - `wizard.ts`, `commands/`: yargs surface. `runners/`: TUI and headless runners
   that sequence independent agent runs and pass context between them.
 - `control-hooks.ts`: what the store's control server asks the composition root
-  to do: resolve credentials, release the run, detect, start one independent run
-  with explicit context, shut down. `--control-socket` attaches the server in
-  `run-non-interactive.ts` (headless, every build) and in `run-wizard.ts` (TUI,
-  dev builds only). Published TUI runs refuse the flag unless the headless flag
-  is present.
+  to do because the store cannot: resolve credentials, detect, start one
+  independent run with explicit context, shut down. `--control-socket` attaches
+  the server in `run-non-interactive.ts` (headless, every build) and in
+  `run-wizard.ts` (TUI, dev builds only). Published TUI runs refuse the flag
+  unless the headless flag is present.
 - Every `POST /runs` is one independent run: the hook clears the previous run's
   state and gives the run its own task stream session; credentials and framework
   context persist. A headless run with `WIZARD_CI_GATEWAY_TOKEN_FILE` in its

From 0be398b32699f24dc67cee3d41bd7789421bf710 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sat, 19 Sep 2026 14:11:13 -0400
Subject: [PATCH 7/8] chore(harness): derive launch commands, tighten the
 parity tests, correct the docs

launchWords reads each program's command instead of a second table;
waitForSocket waits for the server to answer; the headless smoke script
shares buildLaunch, readApiKey, and the APP_DIR/PROJECT_ID/POSTHOG_KEY_FILE
contract; the snapshot route rethrows client errors instead of treating
them as an exit; the MCP run status lives in run-status.ts with a test.
Keyboard equivalence asserts equality per pair and names the next screen's
mount effects; E2E_DRIVABLE_SCREENS is derived from decideE2eAction; picks,
the route table, and the doctor dispatch gain tests; dead fixtures go.
Docs drop the stale aliases, the router-as-resolver claim, the bin.ts
registration, InkUI, and the .txt frames, and list @store/control.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 .claude/skills/wizard-development/SKILL.md    |   2 +-
 .../references/ARCHITECTURE.md                |  34 +-
 AGENTS.md                                     |   7 +-
 README.md                                     | 411 ++++++++++--------
 e2e-harness/ARCHITECTURE.md                   |  40 +-
 .../__fixtures__/control-frame-auth.txt       |  49 ---
 .../__fixtures__/control-frame-intro.txt      |  49 ---
 .../__fixtures__/control-state-baseline.json  | 107 -----
 .../keyboard-equivalence.test.tsx.snap        |  18 +-
 .../__tests__/control-socket-headless.test.ts |   4 +-
 .../__tests__/control-socket-tui.test.ts      |   1 -
 e2e-harness/__tests__/docs-routes.test.ts     |  19 +
 e2e-harness/__tests__/e2e-profile-ask.test.ts |  23 +
 .../__tests__/e2e-profile-failure.test.ts     |   1 -
 .../__tests__/keyboard-equivalence.test.tsx   |  32 +-
 e2e-harness/__tests__/launch.test.ts          |  63 ++-
 e2e-harness/__tests__/picks.test.ts           |  77 ++++
 e2e-harness/__tests__/run-status.test.ts      |  40 ++
 e2e-harness/e2e-profile.ts                    |  15 +-
 e2e-harness/launch.ts                         |  81 ++--
 e2e-harness/picks.ts                          |   7 +-
 e2e-harness/profiles.ts                       |   2 +-
 e2e-harness/run-status.ts                     |  31 ++
 scripts/controlled-headless-smoke.no-jest.ts  |  95 ++--
 scripts/mcp-install-smoke-test.ts             |   2 +-
 scripts/smoke-test.sh                         |   7 +-
 scripts/tui-replay.no-jest.ts                 |   6 +-
 scripts/tui-snapshots.no-jest.ts              |   8 +-
 scripts/wizard-ci-mcp.no-jest.ts              |  23 +-
 src/agent/README.md                           |   4 +-
 .../__tests__/auth-error-context.test.ts      |   1 -
 src/cli/README.md                             |  13 +-
 src/cli/__tests__/bin-preflight.test.ts       |   1 -
 src/cli/__tests__/control-refusal.test.ts     |   2 -
 src/cli/__tests__/control-surface.test.ts     |  11 +-
 src/cli/commands/doctor.ts                    |   8 +-
 src/cli/commands/self-driving.ts              |   6 +-
 src/cli/index.ts                              |   2 +-
 src/cli/main.ts                               |   2 +-
 src/cli/wizard.ts                             |   2 +-
 src/env.ts                                    |   2 +-
 src/store/README.md                           |   4 +-
 src/store/control/__tests__/actions.test.ts   |   1 -
 src/store/index.ts                            |   1 +
 src/store/ui/wizard-ui.ts                     |   2 +-
 .../audit-checks-viewer-layout.test.ts        |   1 -
 src/tui/__tests__/error-tracking-tips.test.ts |   1 -
 src/tui/router.ts                             |   4 +-
 48 files changed, 702 insertions(+), 620 deletions(-)
 delete mode 100644 e2e-harness/__fixtures__/control-frame-auth.txt
 delete mode 100644 e2e-harness/__fixtures__/control-frame-intro.txt
 delete mode 100644 e2e-harness/__fixtures__/control-state-baseline.json
 create mode 100644 e2e-harness/__tests__/docs-routes.test.ts
 create mode 100644 e2e-harness/__tests__/picks.test.ts
 create mode 100644 e2e-harness/__tests__/run-status.test.ts
 create mode 100644 e2e-harness/run-status.ts

diff --git a/.claude/skills/wizard-development/SKILL.md b/.claude/skills/wizard-development/SKILL.md
index a751e2a78..d7395f719 100644
--- a/.claude/skills/wizard-development/SKILL.md
+++ b/.claude/skills/wizard-development/SKILL.md
@@ -19,7 +19,7 @@ infrastructure should consume those boundaries.
 
 | Concern                                               | Owner                                                                                                                                                                              |
 | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Framework detection, context, env conventions         | [FrameworkConfig](../../../src/store/framework-config.ts) and [framework configs](../../../src/frameworks/)                                                                        |
+| Framework detection, context, env conventions         | [FrameworkConfig](../../../src/store/framework-config.ts) and [framework configs](../../../src/store/frameworks/)                                                                  |
 | Integration instructions and orchestrator flows/tasks | [context-mill](https://github.com/PostHog/context-mill)                                                                                                                            |
 | Programs, steps, prerequisites and outcomes           | [programs](../../../src/store/programs/)                                                                                                                                           |
 | Sequence, harness, model and effort selection         | [switchboard](../../../src/agent/runner/switchboard/)                                                                                                                              |
diff --git a/.claude/skills/wizard-development/references/ARCHITECTURE.md b/.claude/skills/wizard-development/references/ARCHITECTURE.md
index f13384acc..75183874c 100644
--- a/.claude/skills/wizard-development/references/ARCHITECTURE.md
+++ b/.claude/skills/wizard-development/references/ARCHITECTURE.md
@@ -19,9 +19,7 @@ lifecycle in
 
 [runner/index.ts](../../../../src/agent/runner/index.ts) resolves a program's
 `run` definition, calls shared bootstrap, selects a binding, dispatches the
-sequence, and flushes the scanner report on cleanup. The old
-[agent-runner.ts](../../../../src/agent/runner/index.ts) is a compatibility
-export.
+sequence, and flushes the scanner report on cleanup.
 
 | Layer           | Source and responsibility                                                                                                                                                  |
 | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -57,7 +55,8 @@ Do not migrate a linear program merely by changing its binding if it depends on
 these hooks. Inspect the orchestrator's flow and completion path instead.
 [Metrics](../../../../src/store/programs/metrics/) is a current Pi/orchestrator
 example. Native command modules still need registration in
-[bin.ts](../../../../bin.ts); screen sequences derive from the program registry.
+[src/cli/main.ts](../../../../src/cli/main.ts); flows derive from the program
+registry.
 
 ## Switchboard contract
 
@@ -138,7 +137,7 @@ durable credentials.
 ## UI state and agent output
 
 Business logic uses [WizardUI](../../../../src/store/ui/wizard-ui.ts) through
-`getUI()`. [InkUI](../../../../src/store/ui/store-ui.ts) updates the TUI store;
+`getUI()`. [StoreUI](../../../../src/store/ui/store-ui.ts) updates the store;
 [LoggingUI](../../../../src/tui/console/logging-ui.ts) is available for
 noninteractive callers that select it. A missing TTY does not automatically mean
 an arbitrary caller uses LoggingUI; snapshot CI drives Ink in a PTY.
@@ -152,11 +151,11 @@ session event handlers. Orchestrated tasks also have queue and handoff state. Do
 not assume all harness output passes through `handleSDKMessage`.
 
 Session changes go through explicit store setters. They emit updates,
-re-evaluate gates, detect transitions, and refresh rendering. The
-[router](../../../../src/tui/router.ts) resolves overlays first, then the first
-visible incomplete screen from
-[screen-sequences.ts](../../../../src/tui/screen-sequences.ts). Those sequences
-are projected from registered program steps. Change the state/predicate that
+re-evaluate gates, detect transitions, and refresh rendering. The store's
+[flow resolution](../../../../src/store/state/flow-resolution.ts) resolves
+interrupts first, then the first visible incomplete step of the program's flow
+([flowFor](../../../../src/store/programs/flow-for.ts)). Those flows are
+projected from registered program steps. Change the state/predicate that
 represents progress rather than adding imperative navigation.
 
 ## MCP and instrumentation
@@ -167,9 +166,8 @@ them differently; inspect the selected harness rather than assuming identical
 tool names or discovery. Context-mill supplies skills and flow/task prompts.
 
 [Middleware](../../../../src/agent/middleware/) provides opt-in message/phase
-instrumentation. The linear sequence creates the benchmark pipeline; there is no
-pipeline construction in the compatibility `agent-runner.ts`. Inspect the actual
-consumer before extending instrumentation to another sequence or harness.
+instrumentation. The linear sequence creates the benchmark pipeline. Inspect the
+actual consumer before extending instrumentation to another sequence or harness.
 
 ## Surfaces and the control API
 
@@ -184,9 +182,10 @@ lists what it owns and may import:
 | `src/cli`   | argv, command tree, runners that sequence runs and pass context, `ControlHooks` | every surface, through its public entries only      |
 
 Cross-surface imports go through `@store`, `@store/types`, `@store/programs`,
-`@agent`, `@agent/types`, `@tui`, `@tui/types`, and `@tui/console`.
-`src/__tests__/architecture` enforces the matrix and the public-entry rule;
-`tsc -b tsconfig.solution.json` mirrors it with project references.
+`@agent`, `@agent/types`, `@tui`, `@tui/types`, and `@tui/console`; the two cli
+runners load `@store/control` lazily. `src/__tests__/architecture` enforces the
+matrix and the public-entry rule; `tsc -b tsconfig.solution.json` mirrors it
+with project references.
 
 `--control-socket <path>` serves an HTTP/1.1 API over a unix socket from
 `src/store/control`: state with long polling, actions that call one store setter
@@ -203,13 +202,14 @@ Run it:
 
 ```bash
 # headless, every build; the key travels in the environment
+mkdir -p /tmp/w
 POSTHOG_WIZARD_API_KEY=phx_... WIZARD_CI_GATEWAY_TOKEN_FILE=/path/to/token \
   npx tsx bin.ts --headless-DONOTUSE-EXPERIMENTAL --control-socket /tmp/w/w.sock \
   --project-id <id> --region us --install-dir /tmp/app
 curl -s --unix-socket /tmp/w/w.sock -X POST -H 'content-type: application/json' -d '{}' http://localhost/detect
 curl -s --unix-socket /tmp/w/w.sock -X POST -H 'content-type: application/json' \
   -d '{"programId":"posthog-integration"}' http://localhost/runs
-curl -s --unix-socket /tmp/w/w.sock 'http://localhost/state?wait=60000&since=0' | jq '.state.run, .state.tasks'
+curl -s --unix-socket /tmp/w/w.sock 'http://localhost/state?wait=60000&since=0' | jq '.state.session.runPhase, .state.tasks'
 curl -s --unix-socket /tmp/w/w.sock http://localhost/runs
 curl -s --unix-socket /tmp/w/w.sock -X POST http://localhost/shutdown
 
diff --git a/AGENTS.md b/AGENTS.md
index 10d375858..98f9bf562 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -37,9 +37,10 @@ The tree is three surfaces plus a composition root: `src/store` (state and
 contracts), `src/agent` (one agent run), `src/tui` (rendering), `src/cli` (argv
 and wiring). Surfaces import each other only through `@store`, `@store/types`,
 `@store/programs`, `@agent`, `@agent/types`, `@tui`, `@tui/types`, and
-`@tui/console`; `src/__tests__/architecture` enforces it. Each surface's
-`README.md` lists what it owns and may import. To drive a run without a keyboard
-(snapshots, an agent, CI), use the control socket described in
+`@tui/console`, plus `@store/control` loaded lazily by the two cli runners;
+`src/__tests__/architecture` enforces it. Each surface's `README.md` lists what
+it owns and may import. To drive a run without a keyboard (snapshots, an agent,
+CI), use the control socket described in
 [`e2e-harness/ARCHITECTURE.md`](e2e-harness/ARCHITECTURE.md).
 
 Adding a new concern means finding the narrowest existing surface, not adding
diff --git a/README.md b/README.md
index 481d49d9d..37fe55b7c 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,8 @@
   <img alt="posthoglogo" src="https://user-images.githubusercontent.com/65415371/205059737-c8a4f836-4889-4654-902e-f302b187b6a0.png">
 </p>
 
-
-> have any feedback, please drop an email to **[wizard@posthog.com](mailto:wizard@posthog.com)**.
+> have any feedback, please drop an email to
+> **[wizard@posthog.com](mailto:wizard@posthog.com)**.
 
 <h1>PostHog wizard ✨</h1>
 
@@ -19,22 +19,36 @@ To use the wizard, you can run it directly using:
 npx @posthog/wizard@latest
 ```
 
-Currently the wizard can be used for over 16+ frameworks for frontend, backend, and mobile applications. If you have other integrations you would like the wizard to
-support, please open a [GitHub issue](https://github.com/posthog/wizard/issues)!
+Currently the wizard can be used for over 16+ frameworks for frontend, backend,
+and mobile applications. If you have other integrations you would like the
+wizard to support, please open a
+[GitHub issue](https://github.com/posthog/wizard/issues)!
 
-Visit our [docs](https://posthog.com/docs/ai-engineering/ai-wizard) to learn more. 
+Visit our [docs](https://posthog.com/docs/ai-engineering/ai-wizard) to learn
+more.
 
 ## Privacy & data usage
 
-The wizard uses **AI models from Anthropic or OpenAI**, routed through PostHog's AI gateway, to read your project's source files and integrate PostHog. A few things worth knowing up front:
-
-- **Source files** are sent to the selected model provider as part of the agent's context.
-- **`.env*` files and secrets** stay on your machine. The wizard's security scanner blocks anything it identifies as a secret from being read by the agent.
-- **Telemetry** (run metadata — phase, task list, planned events) is sent to PostHog by default. Pass `--no-telemetry` (or set `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable.
-- **AI opt-in**: for existing organizations in interactive runs, the wizard checks `is_ai_data_processing_approved` and waits for approval before agent work. CI and signup runs bypass this interactive gate.
-- **Prefer your own AI?** The wizard's integration knowledge ships as a context-mill skill you can download and run inside your own agent.
-
-The wizard's "Privacy & data usage" menu (intro screen) and the `[I]` shortcut on the auth screen surface the same information in-terminal.
+The wizard uses **AI models from Anthropic or OpenAI**, routed through PostHog's
+AI gateway, to read your project's source files and integrate PostHog. A few
+things worth knowing up front:
+
+- **Source files** are sent to the selected model provider as part of the
+  agent's context.
+- **`.env*` files and secrets** stay on your machine. The wizard's security
+  scanner blocks anything it identifies as a secret from being read by the
+  agent.
+- **Telemetry** (run metadata — phase, task list, planned events) is sent to
+  PostHog by default. Pass `--no-telemetry` (or set
+  `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable.
+- **AI opt-in**: for existing organizations in interactive runs, the wizard
+  checks `is_ai_data_processing_approved` and waits for approval before agent
+  work. CI and signup runs bypass this interactive gate.
+- **Prefer your own AI?** The wizard's integration knowledge ships as a
+  context-mill skill you can download and run inside your own agent.
+
+The wizard's "Privacy & data usage" menu (intro screen) and the `[I]` shortcut
+on the auth screen surface the same information in-terminal.
 
 ## MCP Commands
 
@@ -51,33 +65,43 @@ npx @posthog/wizard@latest mcp remove
 
 ## Wizard programs
 
-The wizard's commands are grouped into **programs** — self-contained agentic jobs that install, audit, or wire up a specific piece of PostHog. They're powered by skills from the [context mill](https://github.com/PostHog/context-mill).
+The wizard's commands are grouped into **programs** — self-contained agentic
+jobs that install, audit, or wire up a specific piece of PostHog. They're
+powered by skills from the
+[context mill](https://github.com/PostHog/context-mill).
 
 ### PostHog integration (default)
 
-Running the wizard with no arguments installs PostHog into your project. It detects your framework, wires up initialization, instruments a starter set of events, and walks you through a first dashboard:
+Running the wizard with no arguments installs PostHog into your project. It
+detects your framework, wires up initialization, instruments a starter set of
+events, and walks you through a first dashboard:
 
 ```bash
 npx @posthog/wizard@latest
 ```
 
-Powered by the `posthog-integration` program. Most other programs below build on it (they declare `requires: ['posthog-integration']`) and will offer to run it first if PostHog isn't already set up.
+Powered by the `posthog-integration` program. Most other programs below build on
+it (they declare `requires: ['posthog-integration']`) and will offer to run it
+first if PostHog isn't already set up.
 
 ### Self-driving
 
-Autonomously sets up PostHog self-driving end-to-end. It connects GitHub, enables Session Replay and Error Tracking, wires up signal sources, and configures a Signals scout troop that watches your project for you.
+Autonomously sets up PostHog self-driving end-to-end. It connects GitHub,
+enables Session Replay and Error Tracking, wires up signal sources, and
+configures a Signals scout troop that watches your project for you.
 
 ```bash
 npx @posthog/wizard@latest self-driving
 ```
 
-If PostHog isn't already installed, the wizard runs the default integration first (composed run) before starting the self-driving setup.
+If PostHog isn't already installed, the wizard runs the default integration
+first (composed run) before starting the self-driving setup.
 
 ### Audit
 
 Audit an existing PostHog integration for correctness and best practices. The
-`audit` command is a **family**. With no subcommand it runs the **events**
-audit (the default); pass a subcommand to run a specific one:
+`audit` command is a **family**. With no subcommand it runs the **events** audit
+(the default); pass a subcommand to run a specific one:
 
 ```bash
 # Runs the events audit (the default) — no subcommand needed
@@ -96,12 +120,12 @@ npx @posthog/wizard@latest audit web-analytics    # web analytics setup
 Most audit subcommands resolve at runtime from the published skill registry, so
 new audits appear without a wizard release (`web-analytics` is wizard-native).
 
-> **`audit <subcommand>` chooses an audit area — it does not take a skill name.**
-> The audit subcommands above *are* context-mill skills promoted to commands (via
-> a `cli: role: command` block); [`wizard skill <skill-name>`](#run-a-single-skill)
-> runs a skill that hasn't been promoted. Same machinery, two surfaces.
-> (`wizard audit --help` still labels the positional `[skill]` — read it as "pick
-> a subcommand.")
+> **`audit <subcommand>` chooses an audit area — it does not take a skill
+> name.** The audit subcommands above _are_ context-mill skills promoted to
+> commands (via a `cli: role: command` block);
+> [`wizard skill <skill-name>`](#run-a-single-skill) runs a skill that hasn't
+> been promoted. Same machinery, two surfaces. (`wizard audit --help` still
+> labels the positional `[skill]` — read it as "pick a subcommand.")
 
 ### Revenue Analytics
 
@@ -129,7 +153,8 @@ OAuth sources open the PostHog app's new-source flow in your browser.
 
 ### Upload source maps
 
-Upload JavaScript source maps to PostHog error tracking so stack traces are symbolicated back to your original code:
+Upload JavaScript source maps to PostHog error tracking so stack traces are
+symbolicated back to your original code:
 
 ```bash
 npx @posthog/wizard@latest upload-source-maps
@@ -149,36 +174,35 @@ npx @posthog/wizard@latest skill <skill-name>      # run one by name
 
 Reviews are auto-requested via [`.github/CODEOWNERS`](.github/CODEOWNERS) — the
 file is the source of truth; this table just mirrors it for readability.
-`team-wizard-docs` is the default reviewer; the team-owned programs below
-route review to their owning team instead.
-
-| Path | Owning team |
-|---|---|
-| `*` (everything else, including all other programs) | `@PostHog/team-wizard-docs` |
-| `src/agent/` | `@PostHog/team-wizard-docs` |
-| `src/store/programs/posthog-integration/` | `@PostHog/team-wizard-docs` |
-| `src/store/programs/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking` |
-| `src/store/programs/mcp-analytics/` | `@PostHog/team-mcp-analytics` |
-| `src/store/programs/revenue-analytics/` | `@PostHog/team-web-analytics` |
-| `src/store/programs/self-driving/` | `@PostHog/team-self-driving` |
-| `src/store/programs/warehouse-source/` | `@PostHog/team-warehouse-sources` |
-| `src/store/programs/web-analytics-doctor/` | `@PostHog/team-web-analytics` |
-
-Ownership is by directory. Programs not listed above
-(`agent-skill`, `audit`, `events-audit`, `mcp`, `migration`, `posthog-doctor`,
-`shared`, `slack`) fall through the default and are owned by
-`team-wizard-docs`. Today CODEOWNERS only auto-requests review — approval is
-not a merge gate.
+`team-wizard-docs` is the default reviewer; the team-owned programs below route
+review to their owning team instead.
+
+| Path                                                    | Owning team                       |
+| ------------------------------------------------------- | --------------------------------- |
+| `*` (everything else, including all other programs)     | `@PostHog/team-wizard-docs`       |
+| `src/agent/`                                            | `@PostHog/team-wizard-docs`       |
+| `src/store/programs/posthog-integration/`               | `@PostHog/team-wizard-docs`       |
+| `src/store/programs/error-tracking-upload-source-maps/` | `@PostHog/team-error-tracking`    |
+| `src/store/programs/mcp-analytics/`                     | `@PostHog/team-mcp-analytics`     |
+| `src/store/programs/revenue-analytics/`                 | `@PostHog/team-web-analytics`     |
+| `src/store/programs/self-driving/`                      | `@PostHog/team-self-driving`      |
+| `src/store/programs/warehouse-source/`                  | `@PostHog/team-warehouse-sources` |
+| `src/store/programs/web-analytics-doctor/`              | `@PostHog/team-web-analytics`     |
+
+Ownership is by directory. Programs not listed above (`agent-skill`, `audit`,
+`events-audit`, `mcp`, `migration`, `posthog-doctor`, `shared`, `slack`) fall
+through the default and are owned by `team-wizard-docs`. Today CODEOWNERS only
+auto-requests review — approval is not a merge gate.
 
 ## Headless signup + install (agents / CI)
 
-> ⚠️ `--ci` is **not currently supported in published builds** (see [CI Mode](#ci-mode)).
-> This flow works in development builds only.
+> ⚠️ `--ci` is **not currently supported in published builds** (see
+> [CI Mode](#ci-mode)). This flow works in development builds only.
 
-For a fully non-interactive first-run (no existing PostHog account, no TTY,
-no browser), combine `--ci --signup --email`. The wizard provisions a new
-account, uses the returned personal API key to run the normal CI install,
-and wires PostHog into the project at `--install-dir`:
+For a fully non-interactive first-run (no existing PostHog account, no TTY, no
+browser), combine `--ci --signup --email`. The wizard provisions a new account,
+uses the returned personal API key to run the normal CI install, and wires
+PostHog into the project at `--install-dir`:
 
 ```bash
 npx @posthog/wizard@latest --ci --signup \
@@ -204,38 +228,37 @@ npx @posthog/wizard@latest provision --email user@example.com --region eu --json
 ```
 
 Success prints the full `ProvisioningResult` (`projectApiKey`, `host`,
-`projectId`, `accountId`, `accessToken`, `refreshToken`, and
-`personalApiKey` if present). Failure exits 1; in `--json` mode the error
-is emitted to stderr as `{"error":"...","code":"..."}`, with `code` set to
-`email_exists` when the address is already registered.
+`projectId`, `accountId`, `accessToken`, `refreshToken`, and `personalApiKey` if
+present). Failure exits 1; in `--json` mode the error is emitted to stderr as
+`{"error":"...","code":"..."}`, with `code` set to `email_exists` when the
+address is already registered.
 
-> ⚠️ **Output contains live credentials.** Pipe it into a secrets store —
-> do not let it be captured by shared CI logs. Mask the step output or
-> redirect stdout to a file your job reads and discards.
+> ⚠️ **Output contains live credentials.** Pipe it into a secrets store — do not
+> let it be captured by shared CI logs. Mask the step output or redirect stdout
+> to a file your job reads and discards.
 
 # Options
 
 The following CLI arguments are available:
 
-| Option            | Description                                                      | Type    | Default | Choices                                              | Environment Variable           |
-| ----------------- | ---------------------------------------------------------------- | ------- | ------- | ---------------------------------------------------- | ------------------------------ |
-| `--help`          | Show help                                                        | boolean |         |                                                      |                                |
-| `--version`       | Show version number                                              | boolean |         |                                                      |                                |
-| `--debug`         | Enable verbose logging                                           | boolean | `false` |                                                      | `POSTHOG_WIZARD_DEBUG`         |
-| `--signup`        | Create a new PostHog account during setup                        | boolean | `false` |                                                      | `POSTHOG_WIZARD_SIGNUP`        |
-| `--install-dir`   | Directory to install PostHog in                                  | string  |         |                                                      | `POSTHOG_WIZARD_INSTALL_DIR`   |
-| `--ci`            | Enable CI mode for non-interactive execution                     | boolean | `false` |                                                      | `POSTHOG_WIZARD_CI`            |
-| `--api-key`       | PostHog personal API key (phx_xxx) for authentication            | string  |         |                                                      | `POSTHOG_WIZARD_API_KEY`       |
-| `--no-telemetry`  | Disable wizard run-state telemetry                               | boolean | `false` |                                                      | `POSTHOG_WIZARD_NO_TELEMETRY`  |
-
+| Option           | Description                                           | Type    | Default | Choices | Environment Variable          |
+| ---------------- | ----------------------------------------------------- | ------- | ------- | ------- | ----------------------------- |
+| `--help`         | Show help                                             | boolean |         |         |                               |
+| `--version`      | Show version number                                   | boolean |         |         |                               |
+| `--debug`        | Enable verbose logging                                | boolean | `false` |         | `POSTHOG_WIZARD_DEBUG`        |
+| `--signup`       | Create a new PostHog account during setup             | boolean | `false` |         | `POSTHOG_WIZARD_SIGNUP`       |
+| `--install-dir`  | Directory to install PostHog in                       | string  |         |         | `POSTHOG_WIZARD_INSTALL_DIR`  |
+| `--ci`           | Enable CI mode for non-interactive execution          | boolean | `false` |         | `POSTHOG_WIZARD_CI`           |
+| `--api-key`      | PostHog personal API key (phx_xxx) for authentication | string  |         |         | `POSTHOG_WIZARD_API_KEY`      |
+| `--no-telemetry` | Disable wizard run-state telemetry                    | boolean | `false` |         | `POSTHOG_WIZARD_NO_TELEMETRY` |
 
 # CI Mode
 
 **CI mode is available only in development/test builds.** Published builds
 reject `--ci`; use an interactive terminal for `npx @posthog/wizard@latest`.
 
-Local CI runs require a PostHog personal API key **and a separate gateway
-token file**, plus the target project ID. See
+Local CI runs require a PostHog personal API key **and a separate gateway token
+file**, plus the target project ID. See
 [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs)
 for setup and the CI secret names. With both secrets configured:
 
@@ -257,8 +280,10 @@ The CLI args override environment variables in CI mode.
 
 ### Required Flags for CI Mode
 
-- `--api-key`: Personal API key (`phx_xxx`) from your [PostHog settings](https://app.posthog.com/settings/user-api-keys)
-- `--install-dir`: Directory to install PostHog in (e.g., `.` for current directory)
+- `--api-key`: Personal API key (`phx_xxx`) from your
+  [PostHog settings](https://app.posthog.com/settings/user-api-keys)
+- `--install-dir`: Directory to install PostHog in (e.g., `.` for current
+  directory)
 
 ### Required API Key Scopes
 
@@ -270,8 +295,8 @@ dashboard:write insight:write notebook:write event_definition:write
 health_issue:read wizard_session:read wizard_session:write
 ```
 
-The source of truth is `WIZARD_OAUTH_SCOPES` in `src/store/shared/constants.ts`, which
-documents why each scope is needed — if this block drifts, trust the code.
+The source of truth is `WIZARD_OAUTH_SCOPES` in `src/store/shared/constants.ts`,
+which documents why each scope is needed — if this block drifts, trust the code.
 Some programs request more on top (`PROGRAM_SCOPE_ADDITIONS` in
 `src/store/services/oauth/program-scopes.ts`); the default integration flow adds
 `integration:read` and `external_data_source:read` /
@@ -279,23 +304,23 @@ Some programs request more on top (`PROGRAM_SCOPE_ADDITIONS` in
 
 ### OAuth app scope ceiling
 
-The wizard's OAuth app on the PostHog side caps the scopes its tokens may
-carry (`OAuthApplication.scopes`). Any scope requested in this repo (see
-`src/store/services/oauth/program-scopes.ts`) must be grantable under that ceiling, or
-`/authorize` drops it and the call that needs it 403s.
+The wizard's OAuth app on the PostHog side caps the scopes its tokens may carry
+(`OAuthApplication.scopes`). Any scope requested in this repo (see
+`src/store/services/oauth/program-scopes.ts`) must be grantable under that
+ceiling, or `/authorize` drops it and the call that needs it 403s.
 
 **A granted token can be narrower than the request even with a correct
 ceiling.** The consent screen lets the user deselect any scope the app doesn't
 mark required (`OAuthApplication.required_scopes`), and out-of-ceiling scopes
 are clamped silently (`clamp_scopes_to_ceiling`) — neither path errors;
-`/oauth/token` just returns a smaller `scope`. So never assume the token
-carries what was requested: the token response's `scope` field is the truth.
-The wizard diffs granted vs requested at login (`missingOAuthScopes` in
-`src/store/shared/oauth.ts`), warns the user which permissions are missing, and emits
-`wizard: oauth grant narrowed` so narrowed runs are countable in analytics.
-The diff also rides on the session (`credentials.missingScopes`), so when a
-run does fail on a scope-gated step, the error names the missing permission
-and the fix instead of the generic report-a-bug line.
+`/oauth/token` just returns a smaller `scope`. So never assume the token carries
+what was requested: the token response's `scope` field is the truth. The wizard
+diffs granted vs requested at login (`missingOAuthScopes` in
+`src/store/shared/oauth.ts`), warns the user which permissions are missing, and
+emits `wizard: oauth grant narrowed` so narrowed runs are countable in
+analytics. The diff also rides on the session (`credentials.missingScopes`), so
+when a run does fail on a scope-gated step, the error names the missing
+permission and the fix instead of the generic report-a-bug line.
 
 **To make scopes impossible to deselect, list them explicitly in the app's
 `scopes`.** `required_scopes` is not a separate field — it is derived
@@ -305,8 +330,8 @@ consent POST 400s with `invalid_scope` if the grant misses one), while scopes
 covered only by `@default` stay deselectable and `optional_scopes` are
 declinable extras. That is why `llm_gateway:read` and `wizard_session:*` are
 already un-deselectable today, and everything else is not. To pin the base set
-the wizard cannot run without, seed each region's app with `@default` plus
-every scope in `WIZARD_OAUTH_SCOPES`:
+the wizard cannot run without, seed each region's app with `@default` plus every
+scope in `WIZARD_OAUTH_SCOPES`:
 
 ```
 python manage.py seed_oauth_app_scopes --client-id <id> --dry-run \
@@ -314,10 +339,10 @@ python manage.py seed_oauth_app_scopes --client-id <id> --dry-run \
 ```
 
 then re-run without `--dry-run`. Keep `@default` in the list — dropping it
-narrows the ceiling to only the explicit entries and strips the
-program-specific additions. The wizard has no client-side lever for any of
-this; the login diff and prompt-threaded degrade above handle a narrowed
-grant, but only pinning prevents one.
+narrows the ceiling to only the explicit entries and strips the program-specific
+additions. The wizard has no client-side lever for any of this; the login diff
+and prompt-threaded degrade above handle a narrowed grant, but only pinning
+prevents one.
 
 **The live wizard apps use the `@default` sentinel, so most net-new scopes need
 no ceiling edit.** The prod US app's `scopes` is:
@@ -362,18 +387,18 @@ used to silently add permissions.
 The CLI was overhauled to consolidate commands into a smaller, extensible
 surface. If you used an older command, here's where it went:
 
-| Old command | New command | What changed |
-|---|---|---|
-| `wizard integrate` | `wizard` (default flow) | Command removed; the default flow runs the integration |
-| `wizard events-audit` | `wizard audit events` | Now an `audit`-family subcommand |
-| `wizard audit` (single audit) | `wizard audit <subcommand>` | Now a family; see [Audit](#audit) for the subcommands |
-| `wizard audit-3000` | *removed* | Retired |
-| `wizard revenue` | `wizard revenue-analytics` | Renamed (old `revenue` removed) |
-| `wizard upload-sourcemaps` | `wizard upload-source-maps` | Renamed; `upload-sourcemaps` still works as an alias |
-
-> **Commands vs. programs:** `integrate` was the *command*; the program behind it
-> is `posthog-integration`, which still exists and now powers the default flow.
-> Other commands depend on it via `requires: ['posthog-integration']`. The
+| Old command                   | New command                 | What changed                                           |
+| ----------------------------- | --------------------------- | ------------------------------------------------------ |
+| `wizard integrate`            | `wizard` (default flow)     | Command removed; the default flow runs the integration |
+| `wizard events-audit`         | `wizard audit events`       | Now an `audit`-family subcommand                       |
+| `wizard audit` (single audit) | `wizard audit <subcommand>` | Now a family; see [Audit](#audit) for the subcommands  |
+| `wizard audit-3000`           | _removed_                   | Retired                                                |
+| `wizard revenue`              | `wizard revenue-analytics`  | Renamed (old `revenue` removed)                        |
+| `wizard upload-sourcemaps`    | `wizard upload-source-maps` | Renamed; `upload-sourcemaps` still works as an alias   |
+
+> **Commands vs. programs:** `integrate` was the _command_; the program behind
+> it is `posthog-integration`, which still exists and now powers the default
+> flow. Other commands depend on it via `requires: ['posthog-integration']`. The
 > program id is internal — it was never a command you typed.
 
 # Steal this code
@@ -396,8 +421,8 @@ and set up the general flow of the application.
 ## Analytics
 
 Did you know you can capture PostHog events even for smaller, supporting
-products like a command line tool? `src/store/shared/analytics.ts` is a great example
-of how to do it.
+products like a command line tool? `src/store/shared/analytics.ts` is a great
+example of how to do it.
 
 This file wraps `posthog-node` with some convenience functions to set up an
 analytics session and log events. We can see the usage and outcomes of this
@@ -409,8 +434,8 @@ When the user authenticates, the wizard also streams live run state — current
 phase, task list, planned events — to `POST /api/projects/{id}/wizard/sessions/`
 so the PostHog web app can render real-time progress. Updates are debounced
 (250ms) with phase changes flushed immediately; failures fall back silently to
-the wizard's debug log without disturbing the TUI. Pass `--no-telemetry` (or
-set `POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable.
+the wizard's debug log without disturbing the TUI. Pass `--no-telemetry` (or set
+`POSTHOG_WIZARD_NO_TELEMETRY=1`) to disable.
 
 ## Leave rules behind
 
@@ -445,17 +470,16 @@ users of the wizard, no training delays or other ambiguity.
 
 ## Keep secrets out of the LLM
 
-The wizard somtimes needs to move a secret. The agent
-orchestrates that journey, but the raw value should _never_ enter the LLM
-conversation, where it would be sent to the model provider, written to
-transcripts, and captured in logs.
+The wizard somtimes needs to move a secret. The agent orchestrates that journey,
+but the raw value should _never_ enter the LLM conversation, where it would be
+sent to the model provider, written to transcripts, and captured in logs.
 
-`src/store/session/secret-vault.ts` is a small, reusable pattern for exactly this. It's a
-session-scoped, in-memory vault: a tool that handles a secret calls `put()` to
-store the raw value and hands the agent an opaque `secret:<uuid>` reference
-instead. The agent passes that ref between tools as if it were the value; the
-host resolves it back to the real secret only at the last moment, inside the
-process, when it writes the file.
+`src/store/session/secret-vault.ts` is a small, reusable pattern for exactly
+this. It's a session-scoped, in-memory vault: a tool that handles a secret calls
+`put()` to store the raw value and hands the agent an opaque `secret:<uuid>`
+reference instead. The agent passes that ref between tools as if it were the
+value; the host resolves it back to the real secret only at the last moment,
+inside the process, when it writes the file.
 
 Two tools in `src/store/tools/tools.ts` form the ends of that pipe:
 
@@ -471,48 +495,59 @@ drive the work end to end, but the only thing it ever sees is an opaque handle.
 
 ## Build system
 
-Built with [tsdown](https://tsdown.dev/) (Rolldown). `pnpm build` bundles `bin.ts` into ESM chunks in `dist/`, inlining all local source and keeping npm dependencies external.
+Built with [tsdown](https://tsdown.dev/) (Rolldown). `pnpm build` bundles
+`bin.ts` into ESM chunks in `dist/`, inlining all local source and keeping npm
+dependencies external.
 
 ### Environment variables
 
-**Build-time (locked).** `NODE_ENV` is replaced with `"production"` at compile time. It cannot be overridden at runtime. All URLs, OAuth client IDs, and dev-mode code paths resolve to their production values unconditionally.
+**Build-time (locked).** `NODE_ENV` is replaced with `"production"` at compile
+time. It cannot be overridden at runtime. All URLs, OAuth client IDs, and
+dev-mode code paths resolve to their production values unconditionally.
 
-To add a new build-time constant, add it to `env` in `tsdown.config.ts` and export it from `src/env.ts`.
+To add a new build-time constant, add it to `env` in `tsdown.config.ts` and
+export it from `src/env.ts`.
 
-**Runtime (allowlisted).** Runtime env reads go through `runtimeEnv()` in `src/env.ts`, which only accepts keys in the `RuntimeEnvKey` union:
+**Runtime (allowlisted).** Runtime env reads go through `runtimeEnv()` in
+`src/env.ts`, which only accepts keys in the `RuntimeEnvKey` union:
 
-| Variable | Purpose |
-|---|---|
-| `POSTHOG_WIZARD_BENCHMARK_CONFIG` | Path to benchmark config file |
-| `POSTHOG_WIZARD_BENCHMARK_FILE` | Output path for benchmark results |
-| `POSTHOG_WIZARD_LOG_DIR` | Log directory override |
-| `POSTHOG_WIZARD_DEBUG` / `DEBUG` | Enable debug output |
-| `MCP_URL` | Override MCP server URL |
-| `POSTHOG_API_KEY` | API key for MCP subprocess auth |
-| `TERM`, `TERM_PROGRAM`, `CI`, etc. | Terminal/platform detection |
-| `APPDATA`, `XDG_CONFIG_HOME` | Platform path resolution |
+| Variable                           | Purpose                           |
+| ---------------------------------- | --------------------------------- |
+| `POSTHOG_WIZARD_BENCHMARK_CONFIG`  | Path to benchmark config file     |
+| `POSTHOG_WIZARD_BENCHMARK_FILE`    | Output path for benchmark results |
+| `POSTHOG_WIZARD_LOG_DIR`           | Log directory override            |
+| `POSTHOG_WIZARD_DEBUG` / `DEBUG`   | Enable debug output               |
+| `MCP_URL`                          | Override MCP server URL           |
+| `POSTHOG_API_KEY`                  | API key for MCP subprocess auth   |
+| `TERM`, `TERM_PROGRAM`, `CI`, etc. | Terminal/platform detection       |
+| `APPDATA`, `XDG_CONFIG_HOME`       | Platform path resolution          |
 
 To add a new runtime env var, add its key to `RuntimeEnvKey` in `src/env.ts`.
 
-**Direct `process.env` access** is only used for subprocess environment writes (e.g. `agent-interface.ts` setting `ANTHROPIC_BASE_URL`), vendored code, and tests.
+**Direct `process.env` access** is only used for subprocess environment writes
+(e.g. `agent-interface.ts` setting `ANTHROPIC_BASE_URL`), vendored code, and
+tests.
 
 ### Import aliases
 
 Path aliases defined in `tsconfig.build.json`, resolved by tsdown:
 
-| Alias | Maps to |
-|---|---|
-| `@env` | `src/env.ts` |
-| `@store`, `@store/types`, `@store/programs` | `src/store/{index,types,programs/index}.ts` |
-| `@agent`, `@agent/types` | `src/agent/{index,types}.ts` |
-| `@tui`, `@tui/types`, `@tui/console` | `src/tui/{index,types,console/index}.ts` |
-| `@cli/*` | `src/cli/*` (composition root, internal) |
-| `@store/*`, `@agent/*`, `@tui/*` | surface internals; tests only, never across surfaces |
+| Alias                                       | Maps to                                                                    |
+| ------------------------------------------- | -------------------------------------------------------------------------- |
+| `@env`                                      | `src/env.ts`                                                               |
+| `@store`, `@store/types`, `@store/programs` | `src/store/{index,types,programs/index}.ts`                                |
+| `@agent`, `@agent/types`                    | `src/agent/{index,types}.ts`                                               |
+| `@tui`, `@tui/types`, `@tui/console`        | `src/tui/{index,types,console/index}.ts`                                   |
+| `@cli/*`                                    | `src/cli/*` (composition root, internal)                                   |
+| `@store/control`                            | `src/store/control/index.ts`; the cli runners only, by dynamic import      |
+| `@e2e-harness/*`                            | `e2e-harness/*` (harness, scripts, tests)                                  |
+| `@store/*`, `@agent/*`, `@tui/*`            | surface internals; harness, scripts, and tests only, never across surfaces |
 
 ## Running locally
 
 For `--ci`, smoke tests, and full headless runs, configure both the personal API
-key and gateway token file first: [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
+key and gateway token file first:
+[local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 Interactive runs mint their gateway token after authentication.
 
 ### Quick test without linking
@@ -527,7 +562,8 @@ pnpm try --install-dir=[a path]
 pnpm run dev
 ```
 
-This builds, links globally, and watches for changes. Leave it running - any `.ts` file changes will auto-rebuild. Then from any project:
+This builds, links globally, and watches for changes. Leave it running - any
+`.ts` file changes will auto-rebuild. Then from any project:
 
 ```bash
 wizard --integration=nextjs
@@ -538,8 +574,8 @@ wizard --integration=nextjs --local-mcp            # MCP from localhost:8787
 wizard --integration=nextjs --local-dev            # context-mill + MCP + PostHog
 ```
 
-See [`docs/local-dev.md`](docs/local-dev.md) for the full catalog.
-`--local-mcp` selects the MCP server; `--local-context-mill` selects the skills server.
+See [`docs/local-dev.md`](docs/local-dev.md) for the full catalog. `--local-mcp`
+selects the MCP server; `--local-context-mill` selects the skills server.
 
 ### Testing
 
@@ -564,8 +600,8 @@ You can hand the wizard to an AI agent and have it drive the real flow itself 
 deciding each screen and snapshotting the TUI to see what happened. The agent
 drives through the `wizard-ci` MCP tools (`open_app` / `read_state` /
 `perform_action` / `render_screen` / `run_agent`), which are registered in this
-repo's `.mcp.json` and bound in every session here — approve `wizard-ci` the first
-time you're prompted. The how-to is the `exploring-the-wizard` skill
+repo's `.mcp.json` and bound in every session here — approve `wizard-ci` the
+first time you're prompted. The how-to is the `exploring-the-wizard` skill
 (`.claude/skills/exploring-the-wizard/SKILL.md`), which an agent discovers
 automatically.
 
@@ -573,12 +609,12 @@ Example prompt — explore against
 [open-saas](https://github.com/wasp-lang/open-saas):
 
 > Explore the PostHog wizard against open-saas, following the
-> `exploring-the-wizard` skill. Reuse my phx key file path, gateway token file path, and project id,
-> asking only for missing inputs. Launch the MCP server with
-> `WIZARD_CI_GATEWAY_TOKEN_FILE` set to the gateway token file path;
-> then clone `https://github.com/wasp-lang/open-saas` into a throwaway `/tmp`
-> copy. Drive the whole flow yourself through the `wizard-ci` MCP tools, deciding
-> each screen:
+> `exploring-the-wizard` skill. Reuse my phx key file path, gateway token file
+> path, and project id, asking only for missing inputs. Launch the MCP server
+> with `WIZARD_CI_GATEWAY_TOKEN_FILE` set to the gateway token file path; then
+> clone `https://github.com/wasp-lang/open-saas` into a throwaway `/tmp` copy.
+> Drive the whole flow yourself through the `wizard-ci` MCP tools, deciding each
+> screen:
 >
 > 1. `open_app` on the `/tmp` copy, then `read_state` to see the screen and the
 >    actions legal right now.
@@ -605,23 +641,24 @@ To make your version of a tool usable with a one-line `npx` command:
 
 # Health checks
 
-`src/store/health-checks/` checks skills download origins before the wizard runs.
-The entry point is `evaluateWizardReadiness()`, which only blocks on skill downloads:
+`src/store/health-checks/` checks skills download origins before the wizard
+runs. The entry point is `evaluateWizardReadiness()`, which only blocks on skill
+downloads:
 
-| Decision            | Meaning                                                         |
-| ------------------- | --------------------------------------------------------------- |
-| `yes`               | Skills are reachable — proceed without outage warnings.         |
-| `no`                | Neither skills origin is reachable — do not run.                |
+| Decision | Meaning                                                 |
+| -------- | ------------------------------------------------------- |
+| `yes`    | Skills are reachable — proceed without outage warnings. |
+| `no`     | Neither skills origin is reachable — do not run.        |
 
 ### Module layout
 
-| File | Responsibility |
-| --- | --- |
-| `types.ts` | Enums, interfaces (`ServiceHealthStatus`, `AllServicesHealth`, etc.) |
+| File           | Responsibility                                                          |
+| -------------- | ----------------------------------------------------------------------- |
+| `types.ts`     | Enums, interfaces (`ServiceHealthStatus`, `AllServicesHealth`, etc.)    |
 | `endpoints.ts` | Direct gateway (`/readyz`) and skills origin (`skill-menu.json`) checks |
 | `readiness.ts` | `checkAllExternalServices`, `evaluateWizardReadiness`, readiness config |
-| `index.ts` | Barrel re-export |
-| `testme.md` | Test running instructions and endpoint reference |
+| `index.ts`     | Barrel re-export                                                        |
+| `testme.md`    | Test running instructions and endpoint reference                        |
 
 ## What blocks a run
 
@@ -643,29 +680,35 @@ The same policy applies during signup. Third-party status pages are not queried.
 After minting a token, `gateway-session.ts` checks `/readyz` on the returned
 gateway URL and reports an unavailable gateway through the existing error path.
 
-`skillsOrigin` is one entry covering two origins: skills are published to
-GitHub Releases and an AWS mirror under the same filenames, and downloads fail
-over between them (`src/store/fetch-retry.ts`). Both are probed in parallel, so
-the key only reports **Down** when neither origin answers — a GitHub Releases
-outage on its own doesn't block a run, including a 403 or 404, which is as
-often about the origin (expired asset redirect, blocked region, a publish that
-reached one origin and not the other) as about the asset.
+`skillsOrigin` is one entry covering two origins: skills are published to GitHub
+Releases and an AWS mirror under the same filenames, and downloads fail over
+between them (`src/store/fetch-retry.ts`). Both are probed in parallel, so the
+key only reports **Down** when neither origin answers — a GitHub Releases outage
+on its own doesn't block a run, including a 403 or 404, which is as often about
+the origin (expired asset redirect, blocked region, a publish that reached one
+origin and not the other) as about the asset.
 
 ## Smoke test helper (`scripts/smoke-test-ci.sh`)
 
-This repo includes a helper script to run a full end‑to‑end smoke test of the wizard packaged in a tarball against a real app from [`posthog/wizard-workbench`](https://github.com/PostHog/wizard-workbench). This will catch certain packaging issues that might not be caught by other tests.
+This repo includes a helper script to run a full end‑to‑end smoke test of the
+wizard packaged in a tarball against a real app from
+[`posthog/wizard-workbench`](https://github.com/PostHog/wizard-workbench). This
+will catch certain packaging issues that might not be caught by other tests.
 
 **Prerequisites**
 
 - Point to a `wizard-workbench` checkout either by:
   - Setting `WIZARD_WORKBENCH_ROOT=/absolute/path/to/wizard-workbench`, or
-  - Cloning `wizard-workbench` next to this repo (so it lives at `../wizard-workbench`).
-- Set `POSTHOG_PERSONAL_API_KEY` either in your shell or in `../wizard-workbench/.env`.
+  - Cloning `wizard-workbench` next to this repo (so it lives at
+    `../wizard-workbench`).
+- Set `POSTHOG_PERSONAL_API_KEY` either in your shell or in
+  `../wizard-workbench/.env`.
 - Set `WIZARD_CI_GATEWAY_TOKEN_FILE` to an absolute path containing the separate
-  AI gateway token. See [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
+  AI gateway token. See
+  [local credentials](docs/local-dev.md#credentials-for-local-ci-and-headless-runs).
 - Set `POSTHOG_WIZARD_PROJECT_ID` to the intended test project and
-  `POSTHOG_WIZARD_REGION` to `us` or `eu` (CI uses `us`). The helper also accepts
-  `POSTHOG_PROJECT_ID` and `POSTHOG_REGION` as fallback names.
+  `POSTHOG_WIZARD_REGION` to `us` or `eu` (CI uses `us`). The helper also
+  accepts `POSTHOG_PROJECT_ID` and `POSTHOG_REGION` as fallback names.
 
 **Usage**
 
@@ -695,8 +738,10 @@ The script will:
 - Copy the selected app into a temp directory
 - Install dependencies for the app
 - Install the packed wizard tarball into an isolated temp project
-- Run `wizard` in `--ci` mode against the copied app and perform basic post‑install checks
+- Run `wizard` in `--ci` mode against the copied app and perform basic
+  post‑install checks
 
 ## Contributing
 
-Start with [AGENTS.md](AGENTS.md) for the development skills and execution policy.
+Start with [AGENTS.md](AGENTS.md) for the development skills and execution
+policy.
diff --git a/e2e-harness/ARCHITECTURE.md b/e2e-harness/ARCHITECTURE.md
index 1d4bfa378..cecd792d9 100644
--- a/e2e-harness/ARCHITECTURE.md
+++ b/e2e-harness/ARCHITECTURE.md
@@ -24,8 +24,12 @@ src/store/control/
   state.ts              the secret-free projection GET /state returns
   driver.ts             ControlDriver: read and act on one store in process
   runs.ts               the run ledger behind POST /runs and GET /runs
+  params.ts             body and param validation; every bad input is a 400
+  marker.ts             the string the bundle audit looks for
+  index.ts              the barrel the cli runners import dynamically
 e2e-harness/
-  launch.ts             buildLaunch: the argv and env that start a controlled wizard
+  launch.ts             launchWords, buildLaunch, waitForSocket: how a controlled wizard starts
+  run-status.ts         the MCP route's integration status, read off the run phase
   picks.ts              the detection picks a headless run supplies to picker screens
   e2e-profile.ts        WizardE2eProfile and decideE2eAction: the scripted walk policy
   profiles.ts           per-program profiles, profileFor(programId), resolveE2eProfile(env)
@@ -34,6 +38,8 @@ e2e-harness/
 scripts/
   tui-snapshots.no-jest.ts   CI route: the wizard in a PTY, driven over the socket, per-screen snapshots
   wizard-ci-mcp.no-jest.ts   agent route: an MCP server that proxies the same API
+  controlled-headless-smoke.no-jest.ts   headless surface: detect, runs, ledger, shutdown
+  wizard-ci-explore.no-jest.ts           open an app, confirm setup, print one frame
 ```
 
 The server reads and mutates the **real** `WizardStore` the TUI renders from.
@@ -48,7 +54,8 @@ the TUI's input.
 its own command word (`self-driving`, `audit all`, `upload-source-maps`); the
 default flow has none. The flags are `--ci` (API-key auth, no browser),
 `--control-socket <path>`, `--install-dir`, `--project-id`, `--region`, and
-`--e2e-ask` when the parent answers the agent's questions. Switchboard overrides
+`--e2e-ask` when the parent answers the agent's questions, `--integrate` for
+self-driving, and `--task-stream-log` to dump the stream. Switchboard overrides
 map to `--harness`, `--sequence`, and `--model`.
 
 The personal API key travels as `POSTHOG_WIZARD_API_KEY` in the child's
@@ -67,18 +74,18 @@ JSON in and out. Success is `{ ok: true, ... }`; failure is
 program), 404 (unknown route), 409 (a run is in flight), 413 (body over 64 KB),
 415 (not JSON), 500 (a hook failed), or 501 (the other surface's route).
 
-| Route                                                                       | Behavior                                                                                    |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `GET /health`                                                               | `{ ok, version, surface, pid, program }`                                                    |
-| `GET /state`                                                                | `{ ok, state }`, the projection below                                                       |
-| `GET /state?wait=<ms>&since=<version>`                                      | Long poll: resolves on the first commit with `version > since`, or after `wait` ms          |
-| `POST /actions/<id>` body `{ params }`                                      | Applies one action legal on the current screen through its store setter, returns the state  |
-| `POST /credentials`                                                         | Resolves the API key into project credentials and commits them, advancing `auth`            |
-| `POST /run`                                                                 | TUI surface: `requestRun` on the store, releasing the runner's agent start. Idempotent      |
-| `POST /detect` body `{ programId?, installDir? }`                           | Headless surface: runs detection through the store's setters                                |
-| `POST /runs` body `{ programId, installDir?, frameworkContext?, skillId? }` | Headless surface: one independent agent run; 409 while one runs                             |
-| `GET /runs`                                                                 | The run ledger: `runId`, `programId`, `installDir`, `status`, `error`, timestamps, `result` |
-| `POST /shutdown`                                                            | Flushes and exits. Idempotent                                                               |
+| Route                                                                       | Behavior                                                                                             |
+| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `GET /health`                                                               | `{ ok, version, surface, pid, program }`                                                             |
+| `GET /state`                                                                | `{ ok, state }`, the projection below                                                                |
+| `GET /state?wait=<ms>&since=<version>`                                      | Long poll: resolves on the first commit with `version > since`, or after `wait` ms, capped at 10 min |
+| `POST /actions/<id>` body `{ params }`                                      | Applies one action legal on the current screen through its store setter, returns the state           |
+| `POST /credentials`                                                         | Resolves the API key into project credentials and commits them, advancing `auth`                     |
+| `POST /run`                                                                 | TUI surface: `requestRun` on the store, releasing the runner's agent start. Idempotent               |
+| `POST /detect` body `{ programId?, installDir? }`                           | Headless surface: runs detection through the store's setters                                         |
+| `POST /runs` body `{ programId, installDir?, frameworkContext?, skillId? }` | Headless surface: one independent agent run; 409 while one runs                                      |
+| `GET /runs`                                                                 | The run ledger: `runId`, `programId`, `installDir`, `status`, `error`, timestamps, `result`          |
+| `POST /shutdown`                                                            | Flushes and exits. Idempotent                                                                        |
 
 `state` mirrors the store: `version`, `currentScreen`, `session`, `tasks`,
 `statusMessages`, `eventPlan`, `handoffText`, the unanswered `setupQuestions`,
@@ -137,8 +144,9 @@ APP_DIR=/tmp/app PROJECT_ID=<id> POSTHOG_KEY_FILE=/path/to/phx-key.txt \
 npx tsx scripts/wizard-ci-explore.no-jest.ts
 
 # Controlled headless: detect, independent runs, the ledger, shutdown
-POSTHOG_WIZARD_API_KEY=phx_... WIZARD_CI_GATEWAY_TOKEN_FILE=/path/to/token.txt \
-npx tsx scripts/controlled-headless-smoke.no-jest.ts --app /tmp/app --project-id <id> posthog-integration metrics
+APP_DIR=/tmp/app PROJECT_ID=<id> POSTHOG_KEY_FILE=/path/to/phx-key.txt \
+WIZARD_CI_GATEWAY_TOKEN_FILE=/path/to/token.txt \
+npx tsx scripts/controlled-headless-smoke.no-jest.ts posthog-integration metrics
 
 # Process specs: the real binary on both surfaces, no credentials, no agent run
 pnpm test:harness                       # WIZARD_PTY_TESTS=0 skips the PTY spec
diff --git a/e2e-harness/__fixtures__/control-frame-auth.txt b/e2e-harness/__fixtures__/control-frame-auth.txt
deleted file mode 100644
index 644e86286..000000000
--- a/e2e-harness/__fixtures__/control-frame-auth.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-                               PostHog Wizard v2.76.0                                                                    Feedback: wizard@posthog.com 
-
-                               PostHog Setup Wizard
-                               ✔ Framework: Node.js
-
-                               Privacy & data
-                               • Source files are read by Claude for AI context
-                               • .env* and secrets stay on your machine
-                               • Press [I] for full privacy & usage info
-
-                               ⠴ Waiting for authentication...
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-                                I privacy & data
diff --git a/e2e-harness/__fixtures__/control-frame-intro.txt b/e2e-harness/__fixtures__/control-frame-intro.txt
deleted file mode 100644
index 493bdcb50..000000000
--- a/e2e-harness/__fixtures__/control-frame-intro.txt
+++ /dev/null
@@ -1,49 +0,0 @@
-                               PostHog Wizard v2.76.0                                                                    Feedback: wizard@posthog.com 
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-                                                                               ███ PostHog Wizard 🦔
-
-                                                               We'll use AI to analyze your project and complete work.
-                                                                   Review what data is shared in "Privacy & data."
-                                                                         .env* values stay on your machine.
-
-                                                                    Let's do two hours of work in eight minutes.
-
-                                                                        Directory ✔ /wz-baseline-express-todo
-                                                                        Framework ✔ Node.js (detected)
-
-                                                                              ▸ Continue
-                                                                                Change framework
-                                                                                More info
-                                                                                Privacy & data
-                                                                                Cancel
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-                                ↑↓ navigate  enter select
diff --git a/e2e-harness/__fixtures__/control-state-baseline.json b/e2e-harness/__fixtures__/control-state-baseline.json
deleted file mode 100644
index 9797a94c0..000000000
--- a/e2e-harness/__fixtures__/control-state-baseline.json
+++ /dev/null
@@ -1,107 +0,0 @@
-{
-  "recordedFrom": "scripts/tui-host.no-jest.ts MODE=serve via scripts/wizard-ci-mcp.no-jest.ts, wizard 2.76.0",
-  "app": "wizard-workbench/apps/basic-integration/javascript-node/express-todo (throwaway copy, detection only, no key)",
-  "projectId": "228144",
-  "steps": [
-    {
-      "call": "open_app",
-      "state": {
-        "currentScreen": "intro",
-        "hasOverlay": false,
-        "runPhase": "idle",
-        "session": {
-          "installDir": "<APP_DIR>",
-          "integration": "javascript_node",
-          "detectedFrameworkLabel": "Node.js",
-          "detectionComplete": true,
-          "setupConfirmed": false,
-          "integrate": null,
-          "hasCredentials": false,
-          "projectId": null,
-          "mcpComplete": false,
-          "slackStepDismissed": false,
-          "skillsComplete": false,
-          "outroDismissed": false,
-          "llmOptIn": false,
-          "discoveredFeatures": []
-        },
-        "tasks": [],
-        "statusMessages": [],
-        "eventPlan": [],
-        "pendingQuestion": null,
-        "taskNotice": null,
-        "setupQuestions": [],
-        "actions": [
-          { "id": "confirm_setup", "description": "Confirm the intro and continue (sets setupConfirmed)." }
-        ],
-        "integration": "idle",
-        "integrationError": null
-      }
-    },
-    {
-      "call": "perform_action",
-      "action": "confirm_setup",
-      "state": {
-        "currentScreen": "auth",
-        "hasOverlay": false,
-        "runPhase": "idle",
-        "session": {
-          "installDir": "<APP_DIR>",
-          "integration": "javascript_node",
-          "detectedFrameworkLabel": "Node.js",
-          "detectionComplete": true,
-          "setupConfirmed": true,
-          "integrate": null,
-          "hasCredentials": false,
-          "projectId": null,
-          "mcpComplete": false,
-          "slackStepDismissed": false,
-          "skillsComplete": false,
-          "outroDismissed": false,
-          "llmOptIn": false,
-          "discoveredFeatures": []
-        },
-        "tasks": [],
-        "statusMessages": [],
-        "eventPlan": [],
-        "pendingQuestion": null,
-        "taskNotice": null,
-        "setupQuestions": [],
-        "actions": []
-      }
-    },
-    {
-      "call": "read_state",
-      "state": {
-        "currentScreen": "auth",
-        "hasOverlay": false,
-        "runPhase": "idle",
-        "session": {
-          "installDir": "<APP_DIR>",
-          "integration": "javascript_node",
-          "detectedFrameworkLabel": "Node.js",
-          "detectionComplete": true,
-          "setupConfirmed": true,
-          "integrate": null,
-          "hasCredentials": false,
-          "projectId": null,
-          "mcpComplete": false,
-          "slackStepDismissed": false,
-          "skillsComplete": false,
-          "outroDismissed": false,
-          "llmOptIn": false,
-          "discoveredFeatures": []
-        },
-        "tasks": [],
-        "statusMessages": [],
-        "eventPlan": [],
-        "pendingQuestion": null,
-        "taskNotice": null,
-        "setupQuestions": [],
-        "actions": [],
-        "integration": "idle",
-        "integrationError": null
-      }
-    }
-  ]
-}
diff --git a/e2e-harness/__tests__/__snapshots__/keyboard-equivalence.test.tsx.snap b/e2e-harness/__tests__/__snapshots__/keyboard-equivalence.test.tsx.snap
index c9b7a24f5..8ec99706e 100644
--- a/e2e-harness/__tests__/__snapshots__/keyboard-equivalence.test.tsx.snap
+++ b/e2e-harness/__tests__/__snapshots__/keyboard-equivalence.test.tsx.snap
@@ -6,7 +6,6 @@ exports[`keyboard commit vs control action commit > audit-outro: any key vs dism
     "outroDismissed": true,
     "screen": "keep-skills",
   },
-  "equal": false,
   "keyboard": {
     "outroDismissed": true,
     "screen": "keep-skills",
@@ -18,10 +17,11 @@ exports[`keyboard commit vs control action commit > audit-outro: any key vs dism
 exports[`keyboard commit vs control action commit > intro: enter on Continue vs confirm_setup 1`] = `
 {
   "action": {
+    "scanConsent": "granted",
     "screen": "health-check",
     "setupConfirmed": true,
+    "warehouseSourcesReported": true,
   },
-  "equal": false,
   "keyboard": {
     "scanConsent": "granted",
     "screen": "health-check",
@@ -36,7 +36,6 @@ exports[`keyboard commit vs control action commit > keep-skills: mount with no s
   "action": {
     "skillsComplete": true,
   },
-  "equal": false,
   "keyboard": {},
 }
 `;
@@ -47,7 +46,6 @@ exports[`keyboard commit vs control action commit > manual-auth-code: escape vs
     "overlay": false,
     "screen": "auth",
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "screen": "auth",
@@ -61,7 +59,6 @@ exports[`keyboard commit vs control action commit > manual-auth-code: paste code
     "overlay": false,
     "screen": "auth",
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "screen": "auth",
@@ -76,7 +73,6 @@ exports[`keyboard commit vs control action commit > mcp: decline install vs set_
     "mcpOutcome": "skipped",
     "screen": "slack-connect",
   },
-  "equal": false,
   "keyboard": {
     "mcpComplete": true,
     "mcpOutcome": "skipped",
@@ -92,7 +88,6 @@ exports[`keyboard commit vs control action commit > outro: any key vs dismiss_ou
     "outroDismissed": true,
     "screen": "mcp",
   },
-  "equal": true,
   "keyboard": {
     "outroDismissed": true,
     "screen": "mcp",
@@ -107,7 +102,6 @@ exports[`keyboard commit vs control action commit > port-conflict: enter vs reso
     "portConflictProcess": null,
     "screen": "auth",
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "portConflictProcess": null,
@@ -122,7 +116,6 @@ exports[`keyboard commit vs control action commit > self-driving-handoff: enter
     "screen": "self-driving-github",
     "selfDrivingHandoffConfirmed": true,
   },
-  "equal": true,
   "keyboard": {
     "screen": "self-driving-github",
     "selfDrivingHandoffConfirmed": true,
@@ -136,7 +129,6 @@ exports[`keyboard commit vs control action commit > self-driving-integration-che
     "integrate": true,
     "screen": "health-check",
   },
-  "equal": true,
   "keyboard": {
     "integrate": true,
     "screen": "health-check",
@@ -152,7 +144,6 @@ exports[`keyboard commit vs control action commit > setup: enter on first router
     },
     "screen": "auth",
   },
-  "equal": true,
   "keyboard": {
     "frameworkContext": {
       "router": "app-router",
@@ -168,7 +159,6 @@ exports[`keyboard commit vs control action commit > slack-connect: skip vs dismi
     "screen": "keep-skills",
     "slackStepDismissed": true,
   },
-  "equal": false,
   "keyboard": {
     "screen": "keep-skills",
     "skillsComplete": true,
@@ -183,7 +173,6 @@ exports[`keyboard commit vs control action commit > source-maps-outro: any key v
     "outroDismissed": true,
     "screen": "keep-skills",
   },
-  "equal": false,
   "keyboard": {
     "outroDismissed": true,
     "screen": "keep-skills",
@@ -199,7 +188,6 @@ exports[`keyboard commit vs control action commit > task-notice: enter vs resolv
     "screen": "intro",
     "taskNotice": null,
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "screen": "intro",
@@ -215,7 +203,6 @@ exports[`keyboard commit vs control action commit > task-notice: escape vs resol
     "screen": "intro",
     "taskNotice": null,
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "screen": "intro",
@@ -231,7 +218,6 @@ exports[`keyboard commit vs control action commit > wizard-ask: type answer and
     "pendingQuestion": null,
     "screen": "intro",
   },
-  "equal": true,
   "keyboard": {
     "overlay": false,
     "pendingQuestion": null,
diff --git a/e2e-harness/__tests__/control-socket-headless.test.ts b/e2e-harness/__tests__/control-socket-headless.test.ts
index f88f56918..1eb4c0206 100644
--- a/e2e-harness/__tests__/control-socket-headless.test.ts
+++ b/e2e-harness/__tests__/control-socket-headless.test.ts
@@ -7,10 +7,10 @@ import { spawn, type ChildProcess } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
 import { ControlClient } from '@store/control';
 import { HEADLESS_FLAG } from '@env';
 import { waitForSocket } from '@e2e-harness/launch';
+import { expectNoSecrets } from '@store/testing';
 
 const REPO = path.resolve(__dirname, '../..');
 let child: ChildProcess | null = null;
@@ -63,7 +63,7 @@ describe('controlled headless surface', () => {
     const state = await client.state();
     expect(state.currentScreen).toBe('intro');
     expect(state.session.runPhase).toBe('idle');
-    expect(JSON.stringify(state)).not.toContain('phx_test_only');
+    expectNoSecrets(JSON.stringify(state));
     await expect(client.startRun({ programId: 'nope' })).rejects.toMatchObject({
       status: 400,
     });
diff --git a/e2e-harness/__tests__/control-socket-tui.test.ts b/e2e-harness/__tests__/control-socket-tui.test.ts
index d96c94e60..6311545bc 100644
--- a/e2e-harness/__tests__/control-socket-tui.test.ts
+++ b/e2e-harness/__tests__/control-socket-tui.test.ts
@@ -6,7 +6,6 @@
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
 import { ControlClient, ControlClientError } from '@store/control';
 import { Program } from '@store/programs';
 import { buildLaunch, waitForSocket } from '@e2e-harness/launch';
diff --git a/e2e-harness/__tests__/docs-routes.test.ts b/e2e-harness/__tests__/docs-routes.test.ts
new file mode 100644
index 000000000..e8a58728c
--- /dev/null
+++ b/e2e-harness/__tests__/docs-routes.test.ts
@@ -0,0 +1,19 @@
+import fs from 'fs';
+import path from 'path';
+import { ROUTES } from '@store/control';
+
+/** The route table in ARCHITECTURE.md is the contract the workbench reads; it must name what the server answers. */
+describe('the documented control API', () => {
+  it('lists exactly the routes the server serves', () => {
+    const doc = fs.readFileSync(
+      path.resolve(__dirname, '../ARCHITECTURE.md'),
+      'utf8',
+    );
+    const documented = new Set(
+      [...doc.matchAll(/^\| `((?:GET|POST) \/[^`?]*)/gm)].map((m) =>
+        m[1].replace('<id>', ':id').trim(),
+      ),
+    );
+    expect([...documented].sort()).toEqual([...ROUTES].sort());
+  });
+});
diff --git a/e2e-harness/__tests__/e2e-profile-ask.test.ts b/e2e-harness/__tests__/e2e-profile-ask.test.ts
index 346653106..ca4a2fe93 100644
--- a/e2e-harness/__tests__/e2e-profile-ask.test.ts
+++ b/e2e-harness/__tests__/e2e-profile-ask.test.ts
@@ -494,6 +494,29 @@ describe('E2E_DRIVABLE_SCREENS', () => {
     expect(E2E_DRIVABLE_SCREENS).toContain(Overlay.TaskNotice);
   });
 
+  it('is exactly the set of screens decideE2eAction commits on', () => {
+    // A rich state lets every conditional case act; screens that still wait
+    // are not drivable and must not be listed.
+    const rich: StateOverrides = {
+      setupQuestions: [
+        {
+          key: 'router',
+          message: 'router?',
+          options: [{ label: 'a', value: 'a' }],
+        },
+      ],
+      pendingQuestion: { id: 'a', source: 's', questions: [text('q')] },
+      taskNotice: { title: 't', items: [], prompt: 'p' },
+    };
+    const every = [...Object.values(ScreenId), ...Object.values(Overlay)];
+    const acting = every.filter(
+      (screen) =>
+        decideE2eAction(state({ currentScreen: screen, ...rich }), profile())
+          .action !== undefined,
+    );
+    expect([...acting].sort()).toEqual([...E2E_DRIVABLE_SCREENS].sort());
+  });
+
   it('has a decideE2eAction case for every screen it lists', () => {
     // A listed screen with no case would return `{ wait: true }` forever,
     // stalling the run instead of failing it.
diff --git a/e2e-harness/__tests__/e2e-profile-failure.test.ts b/e2e-harness/__tests__/e2e-profile-failure.test.ts
index c5dd48482..97ef9b1bd 100644
--- a/e2e-harness/__tests__/e2e-profile-failure.test.ts
+++ b/e2e-harness/__tests__/e2e-profile-failure.test.ts
@@ -1,4 +1,3 @@
-import { describe, expect, it } from 'vitest';
 import { ScreenId } from '@tui/router';
 import type { ControlState } from '@store/types';
 import { DEFAULT_E2E_PROFILE, decideE2eAction } from '@e2e-harness/e2e-profile';
diff --git a/e2e-harness/__tests__/keyboard-equivalence.test.tsx b/e2e-harness/__tests__/keyboard-equivalence.test.tsx
index 1aefd7f28..3db83fc8c 100644
--- a/e2e-harness/__tests__/keyboard-equivalence.test.tsx
+++ b/e2e-harness/__tests__/keyboard-equivalence.test.tsx
@@ -3,7 +3,7 @@
  * keyboard on one store and apply the control action on another, then golden
  * both session diffs. Pairs whose diffs differ today are recorded, not hidden.
  */
-import { vi, describe, it, expect, afterEach, beforeAll } from 'vitest';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
 import { render, cleanup } from 'ink-testing-library';
 import {
   WizardStore,
@@ -436,6 +436,18 @@ function applyAction(pair: Pair): Record<string, unknown> {
   return diff(before, snap(store));
 }
 
+/**
+ * Keys the rendered walk commits from the *next* screen's mount effect (keep-skills
+ * completes with no skills dir; slack-connect records "not connected"), which no
+ * control action produces. Everything else must match exactly.
+ */
+const MOUNT_EFFECTS: Record<string, readonly string[]> = {
+  'mcp: decline install vs set_mcp_outcome skipped': ['slackConnected'],
+  'slack-connect: skip vs dismiss_slack': ['skillsComplete'],
+  'audit-outro: any key vs dismiss_outro': ['skillsComplete'],
+  'source-maps-outro: any key vs dismiss_outro': ['skillsComplete'],
+};
+
 describe('keyboard commit vs control action commit', () => {
   beforeAll(() => {
     vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
@@ -446,11 +458,19 @@ describe('keyboard commit vs control action commit', () => {
     it(pair.name, async () => {
       const keyboard = await driveKeyboard(pair);
       const action = applyAction(pair);
-      expect({
-        keyboard,
-        action,
-        equal: JSON.stringify(keyboard) === JSON.stringify(action),
-      }).toMatchSnapshot();
+      const mountOnly = MOUNT_EFFECTS[pair.name] ?? [];
+      const keyboardOwn = Object.fromEntries(
+        Object.entries(keyboard).filter(([k]) => !mountOnly.includes(k)),
+      );
+      if (pair.keys.length === 0) {
+        // A bare mount commits nothing in this harness; the action still must.
+        expect(keyboard).toEqual({});
+        expect(Object.keys(action).length).toBeGreaterThan(0);
+      } else {
+        expect(action).toEqual(keyboardOwn);
+        for (const key of mountOnly) expect(keyboard).toHaveProperty(key);
+      }
+      expect({ keyboard, action }).toMatchSnapshot();
     });
   }
 });
diff --git a/e2e-harness/__tests__/launch.test.ts b/e2e-harness/__tests__/launch.test.ts
index bb23c48ca..dfb206d6a 100644
--- a/e2e-harness/__tests__/launch.test.ts
+++ b/e2e-harness/__tests__/launch.test.ts
@@ -1,7 +1,7 @@
-import { describe, expect, it } from 'vitest';
-import { Program } from '@store/programs';
+import { HEADLESS_FLAG } from '@env';
+import { getProgramConfig, Program, PROGRAM_REGISTRY } from '@store/programs';
 import type { ProgramId } from '@store/types';
-import { buildLaunch, PROGRAM_COMMANDS } from '@e2e-harness/launch';
+import { buildLaunch, launchWords } from '@e2e-harness/launch';
 import { hasProfile } from '@e2e-harness/profiles';
 
 const base = {
@@ -10,18 +10,28 @@ const base = {
   projectId: '228144',
 };
 
-describe('buildLaunch', () => {
-  it('launches every profiled program through its command words', () => {
-    for (const id of Object.keys(PROGRAM_COMMANDS)) {
-      expect(hasProfile(id), id).toBe(true);
-      const { args } = buildLaunch({ ...base, programId: id }, '/repo');
-      expect(args.slice(0, 1 + PROGRAM_COMMANDS[id]!.length)).toEqual([
-        'bin.ts',
-        ...PROGRAM_COMMANDS[id]!,
-      ]);
+describe('launchWords', () => {
+  it('launches every profiled program through the command its config declares', () => {
+    const profiled = PROGRAM_REGISTRY.map((c) => c.id).filter((id) =>
+      hasProfile(id),
+    );
+    expect(profiled.length).toBeGreaterThanOrEqual(9);
+    for (const id of profiled) {
+      const words = launchWords(id);
+      if (id === Program.PostHogIntegration) expect(words).toEqual([]);
+      else if (id === Program.Audit) expect(words).toEqual(['audit', 'all']);
+      else expect(words, id).toEqual([getProgramConfig(id).command]);
     }
   });
 
+  it('refuses a program with no command', () => {
+    expect(() => launchWords('mcp-add' as ProgramId)).toThrow(
+      /no launch command/,
+    );
+  });
+});
+
+describe('buildLaunch', () => {
   it('maps the run inputs to flags and keeps the key in the environment', () => {
     const { cmd, args, env } = buildLaunch(
       {
@@ -78,6 +88,29 @@ describe('buildLaunch', () => {
     });
   });
 
+  it('launches the headless surface under its flag, without the ask flag', () => {
+    const { cmd, args } = buildLaunch(
+      {
+        ...base,
+        programId: Program.PostHogIntegration,
+        surface: 'headless',
+        e2eAsk: true,
+        bin: 'dist/bin.js',
+        env: {},
+      },
+      '/repo',
+    );
+    expect(cmd).toBe('node');
+    expect(args.slice(0, 4)).toEqual([
+      'dist/bin.js',
+      `--${HEADLESS_FLAG}`,
+      '--control-socket',
+      '/tmp/w/w.sock',
+    ]);
+    expect(args).not.toContain('--ci');
+    expect(args).not.toContain('--e2e-ask');
+  });
+
   it('drops an inherited key when the run has none', () => {
     const { env, args } = buildLaunch(
       {
@@ -90,10 +123,4 @@ describe('buildLaunch', () => {
     expect(env.POSTHOG_WIZARD_API_KEY).toBeUndefined();
     expect(args[1]).toBe('--ci');
   });
-
-  it('refuses a program with no launch command', () => {
-    expect(() =>
-      buildLaunch({ ...base, programId: 'mcp-add' as ProgramId }, '/repo'),
-    ).toThrow(/no launch command/);
-  });
 });
diff --git a/e2e-harness/__tests__/picks.test.ts b/e2e-harness/__tests__/picks.test.ts
new file mode 100644
index 000000000..2812206c0
--- /dev/null
+++ b/e2e-harness/__tests__/picks.test.ts
@@ -0,0 +1,77 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { nativeVariantFor, pickIntegrationTarget } from '@e2e-harness/picks';
+
+const dirs: string[] = [];
+afterEach(() => {
+  for (const d of dirs.splice(0)) {
+    fs.rmSync(d, { recursive: true, force: true });
+  }
+});
+
+function fixture(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'wz-picks-'));
+  dirs.push(root);
+  for (const [rel, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), text);
+  }
+  return root;
+}
+
+const pkg = (deps: Record<string, string>) =>
+  JSON.stringify({ name: 'x', dependencies: deps });
+
+describe('pickIntegrationTarget', () => {
+  it('prefers the first instrumentable app under apps/ over packages/ and the root', async () => {
+    const root = fixture({
+      'package.json': pkg({ express: '4.19.0' }),
+      'apps/web/package.json': pkg({ next: '15.0.0', react: '19.0.0' }),
+      'packages/api/package.json': pkg({ express: '4.19.0' }),
+    });
+    expect(await pickIntegrationTarget(root)).toEqual({
+      integration: 'nextjs',
+      path: 'apps/web',
+    });
+  });
+
+  it('falls back to the root for a single app, and to null for nothing detectable', async () => {
+    expect(
+      await pickIntegrationTarget(
+        fixture({ 'package.json': pkg({ express: '4.19.0' }) }),
+      ),
+    ).toEqual({ integration: 'javascript_node', path: '.' });
+    expect(
+      await pickIntegrationTarget(fixture({ 'README.md': '' })),
+    ).toBeNull();
+  });
+});
+
+describe('nativeVariantFor', () => {
+  it('trusts what the detector recognised before reading manifests', () => {
+    const root = fixture({ 'go.mod': 'module x' });
+    expect(nativeVariantFor(root, { detected: 'flutter' })).toBe('flutter');
+    expect(nativeVariantFor(root, { detected: 'unknown' })).toBe('go');
+    expect(nativeVariantFor(root, undefined)).toBe('go');
+  });
+
+  it('names the platform from its manifest, or an Xcode project, else null', () => {
+    expect(nativeVariantFor(fixture({ 'Cargo.toml': '' }), undefined)).toBe(
+      'rust',
+    );
+    expect(
+      nativeVariantFor(fixture({ 'settings.gradle': '' }), undefined),
+    ).toBe('android');
+    expect(
+      nativeVariantFor(
+        fixture({ 'App.xcodeproj/project.pbxproj': '' }),
+        undefined,
+      ),
+    ).toBe('ios');
+    expect(
+      nativeVariantFor(fixture({ 'README.md': '' }), undefined),
+    ).toBeNull();
+    expect(nativeVariantFor('/nonexistent/root', undefined)).toBeNull();
+  });
+});
diff --git a/e2e-harness/__tests__/run-status.test.ts b/e2e-harness/__tests__/run-status.test.ts
new file mode 100644
index 000000000..7a82cd64d
--- /dev/null
+++ b/e2e-harness/__tests__/run-status.test.ts
@@ -0,0 +1,40 @@
+import { OutroKind, RunPhase } from '@store';
+import { runStatus } from '@e2e-harness/run-status';
+
+const session = (
+  runPhase: RunPhase,
+  over: { runRequested?: boolean; message?: string } = {},
+) => ({
+  runPhase,
+  runRequested: over.runRequested ?? false,
+  outroData: over.message
+    ? { kind: OutroKind.Error, message: over.message }
+    : null,
+});
+
+describe('the MCP run status', () => {
+  it.each([
+    [RunPhase.Idle, 'idle'],
+    [RunPhase.Running, 'running'],
+    [RunPhase.Completed, 'done'],
+    [RunPhase.Error, 'failed'],
+  ])('maps %s to %s', (phase, status) => {
+    expect(runStatus(session(phase)).integration).toBe(status);
+  });
+
+  it('reports an armed but not yet started run as running', () => {
+    expect(
+      runStatus(session(RunPhase.Idle, { runRequested: true })).integration,
+    ).toBe('running');
+  });
+
+  it('carries the failure reason only for a failed run', () => {
+    expect(
+      runStatus(session(RunPhase.Error, { message: 'gateway refused' })),
+    ).toEqual({ integration: 'failed', integrationError: 'gateway refused' });
+    expect(
+      runStatus(session(RunPhase.Completed, { message: 'stale' }))
+        .integrationError,
+    ).toBeNull();
+  });
+});
diff --git a/e2e-harness/e2e-profile.ts b/e2e-harness/e2e-profile.ts
index 5039c3857..1c4ea95de 100644
--- a/e2e-harness/e2e-profile.ts
+++ b/e2e-harness/e2e-profile.ts
@@ -403,14 +403,27 @@ export function decideE2eAction(
   }
 }
 
-/** Screens this profile knows how to act on — for completeness checks/tests. */
+/** Every screen `decideE2eAction` commits on; a test derives the same set from the function. */
 export const E2E_DRIVABLE_SCREENS: readonly ScreenName[] = [
   ScreenId.Intro,
+  ScreenId.RevenueIntro,
+  ScreenId.MigrationIntro,
+  ScreenId.AgentSkillIntro,
+  ScreenId.AiObservabilityIntro,
+  ScreenId.MetricsIntro,
+  ScreenId.ErrorTrackingIntro,
+  ScreenId.AuditIntro,
+  ScreenId.SourceMapsIntro,
+  ScreenId.DoctorIntro,
+  ScreenId.WarehouseIntro,
+  ScreenId.SelfDrivingIntro,
   ScreenId.HealthCheck,
   ScreenId.Setup,
   ScreenId.SelfDrivingIntegrationCheck,
+  ScreenId.SelfDrivingHandoff,
   ScreenId.Outro,
   ScreenId.SourceMapsOutro,
+  ScreenId.AuditOutro,
   ScreenId.Mcp,
   ScreenId.McpSuggestedPrompts,
   ScreenId.SlackConnect,
diff --git a/e2e-harness/launch.ts b/e2e-harness/launch.ts
index f3aaf3635..c9804fb82 100644
--- a/e2e-harness/launch.ts
+++ b/e2e-harness/launch.ts
@@ -1,25 +1,31 @@
-/**
- * How the harness starts a controlled wizard: the real binary, `--ci` for
- * API-key auth, `--control-socket` for the parent, one program per command.
- */
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import { Program } from '@store/programs';
+/** How the harness starts a controlled wizard: the real binary, API-key auth, a control socket, one program per command. */
+import fs from 'fs';
+import path from 'path';
+import { HEADLESS_FLAG } from '@env';
+import { ControlClient } from '@store/control';
+import { getProgramConfig, Program } from '@store/programs';
 import type { ProgramId } from '@store/types';
 
-/** The command words that launch each program; the default flow has none. */
-export const PROGRAM_COMMANDS: Partial<Record<ProgramId, readonly string[]>> = {
+/** Programs whose launch words are not their `command`: the default flow has none, audit runs `audit all`. */
+const COMMAND_OVERRIDES: Partial<Record<ProgramId, readonly string[]>> = {
   [Program.PostHogIntegration]: [],
-  [Program.AiObservability]: ['ai-observability'],
-  [Program.Metrics]: ['metrics'],
-  [Program.ReplayVision]: ['replay-vision'],
-  [Program.SelfDriving]: ['self-driving'],
-  [Program.ErrorTrackingUploadSourceMaps]: ['upload-source-maps'],
-  [Program.ErrorTracking]: ['error-tracking'],
-  [Program.WarehouseSource]: ['warehouse'],
   [Program.Audit]: ['audit', 'all'],
 };
 
+/** The command words that launch a program: the `command` its config declares, unless overridden. */
+export function launchWords(programId: ProgramId): readonly string[] {
+  const override = COMMAND_OVERRIDES[programId];
+  if (override) return override;
+  let command: string | undefined;
+  try {
+    command = getProgramConfig(programId).command;
+  } catch {
+    command = undefined;
+  }
+  if (!command) throw new Error(`no launch command for program ${programId}`);
+  return [command];
+}
+
 export interface LaunchOptions {
   programId: ProgramId;
   appDir: string;
@@ -28,7 +34,9 @@ export interface LaunchOptions {
   region?: 'us' | 'eu';
   /** The personal API key. Travels in the environment, never in argv. */
   apiKey?: string;
-  /** Keep `wizard_ask` wired so the parent answers the agent's questions. */
+  /** `tui` (default) drives the real screens with `--ci`; `headless` uses the published headless flag. */
+  surface?: 'tui' | 'headless';
+  /** Keep `wizard_ask` wired so the parent answers the agent's questions (TUI surface). */
   e2eAsk?: boolean;
   /** Self-driving only: skip the integration check and integrate first. */
   integrate?: boolean;
@@ -37,6 +45,8 @@ export interface LaunchOptions {
   model?: string;
   /** Dump task-stream payloads; '' means the default path. */
   taskStreamLog?: string;
+  /** The entry to run; a `.js` file runs under node, anything else under tsx. */
+  bin?: string;
   env?: NodeJS.ProcessEnv;
 }
 
@@ -50,12 +60,12 @@ export interface Launch {
 const STRIPPED_ENV = /^(CLAUDE|ANTHROPIC|AI_AGENT)/;
 
 export function buildLaunch(o: LaunchOptions, cwd = process.cwd()): Launch {
-  const words = PROGRAM_COMMANDS[o.programId];
-  if (!words) throw new Error(`no launch command for program ${o.programId}`);
+  const bin = o.bin ?? 'bin.ts';
+  const headless = o.surface === 'headless';
   const args = [
-    'bin.ts',
-    ...words,
-    '--ci',
+    bin,
+    ...launchWords(o.programId),
+    headless ? `--${HEADLESS_FLAG}` : '--ci',
     '--control-socket',
     o.socketPath,
     '--install-dir',
@@ -65,14 +75,16 @@ export function buildLaunch(o: LaunchOptions, cwd = process.cwd()): Launch {
     '--region',
     o.region ?? 'us',
   ];
-  if (o.e2eAsk) args.push('--e2e-ask');
-  if (o.integrate === true && o.programId === Program.SelfDriving)
+  if (o.e2eAsk && !headless) args.push('--e2e-ask');
+  if (o.integrate === true && o.programId === Program.SelfDriving) {
     args.push('--integrate');
+  }
   if (o.harness) args.push('--harness', o.harness);
   if (o.sequence) args.push('--sequence', o.sequence);
   if (o.model) args.push('--model', o.model);
-  if (o.taskStreamLog !== undefined)
+  if (o.taskStreamLog !== undefined) {
     args.push('--task-stream-log', o.taskStreamLog);
+  }
 
   const env: NodeJS.ProcessEnv = {};
   for (const [k, v] of Object.entries(o.env ?? process.env)) {
@@ -82,21 +94,32 @@ export function buildLaunch(o: LaunchOptions, cwd = process.cwd()): Launch {
   env.WIZARD_ASK_AUTODRIVE = '1';
   if (o.apiKey) env.POSTHOG_WIZARD_API_KEY = o.apiKey;
   else delete env.POSTHOG_WIZARD_API_KEY;
-  return { cmd: path.join(cwd, 'node_modules/.bin/tsx'), args, env };
+  const cmd = bin.endsWith('.js')
+    ? 'node'
+    : path.join(cwd, 'node_modules/.bin/tsx');
+  return { cmd, args, env };
 }
 
-/** Resolve once the wizard listens on its socket, or reject after `timeoutMs`. */
+/** Resolve once the wizard answers on its socket, or reject after `timeoutMs`. */
 export async function waitForSocket(
   socketPath: string,
   timeoutMs: number,
 ): Promise<void> {
   const deadline = Date.now() + timeoutMs;
+  const client = new ControlClient(socketPath);
   while (Date.now() < deadline) {
-    if (fs.existsSync(socketPath)) return;
+    if (fs.existsSync(socketPath)) {
+      try {
+        await client.health();
+        return;
+      } catch {
+        // A stale file or a server still binding; try again.
+      }
+    }
     await new Promise((r) => setTimeout(r, 150));
   }
   throw new Error(
-    `the wizard did not open ${socketPath} within ${timeoutMs}ms`,
+    `the wizard did not answer on ${socketPath} within ${timeoutMs}ms`,
   );
 }
 
diff --git a/e2e-harness/picks.ts b/e2e-harness/picks.ts
index ba407cf97..5fb679eb4 100644
--- a/e2e-harness/picks.ts
+++ b/e2e-harness/picks.ts
@@ -4,10 +4,9 @@
  * Computed here, on the parent's side of the socket, and committed through the
  * program's control actions.
  */
-import * as fs from 'node:fs';
-import { join } from 'node:path';
-import { FRAMEWORK_REGISTRY, buildSession } from '@store';
-import { detectFramework } from '@store/detection';
+import fs from 'fs';
+import { join } from 'path';
+import { FRAMEWORK_REGISTRY, buildSession, detectFramework } from '@store';
 import {
   detectSourceMapsPrerequisites,
   SOURCE_MAPS_CONTEXT_KEYS,
diff --git a/e2e-harness/profiles.ts b/e2e-harness/profiles.ts
index 38f8271f7..a6af5072a 100644
--- a/e2e-harness/profiles.ts
+++ b/e2e-harness/profiles.ts
@@ -3,7 +3,7 @@
  * program's flow.
  *
  * Each program declares its test path as JSON next to it
- * (`src/lib/programs/<program>/test/e2e.json`): a `profile` (the options the run
+ * (`src/store/programs/<program>/test/e2e.json`): a `profile` (the options the run
  * auto-takes) plus a documented `path`. {@link profileFor} loads the `profile`
  * and maps it by program id.
  *
diff --git a/e2e-harness/run-status.ts b/e2e-harness/run-status.ts
new file mode 100644
index 000000000..cb358b341
--- /dev/null
+++ b/e2e-harness/run-status.ts
@@ -0,0 +1,31 @@
+import { RunPhase } from '@store';
+import type { ControlState } from '@store/types';
+
+const RUN_STATUS: Record<RunPhase, string> = {
+  [RunPhase.Idle]: 'idle',
+  [RunPhase.Running]: 'running',
+  [RunPhase.Completed]: 'done',
+  [RunPhase.Error]: 'failed',
+};
+
+/** The MCP route's background run status, read off the store's run phase. */
+export function runStatus(
+  session: Pick<
+    ControlState['session'],
+    'runPhase' | 'runRequested' | 'outroData'
+  >,
+): { integration: string; integrationError: string | null } {
+  const armed = session.runPhase === RunPhase.Idle && session.runRequested;
+  return {
+    integration: armed ? 'running' : RUN_STATUS[session.runPhase],
+    integrationError:
+      session.runPhase === RunPhase.Error
+        ? session.outroData?.message ?? null
+        : null,
+  };
+}
+
+/** `read_state` adds the run status under its historical names. */
+export function withRunStatus(state: ControlState): Record<string, unknown> {
+  return { ...state, ...runStatus(state.session) };
+}
diff --git a/scripts/controlled-headless-smoke.no-jest.ts b/scripts/controlled-headless-smoke.no-jest.ts
index 318050691..94ed2339d 100644
--- a/scripts/controlled-headless-smoke.no-jest.ts
+++ b/scripts/controlled-headless-smoke.no-jest.ts
@@ -3,86 +3,59 @@
  * one independent run per program named on the command line, then shutdown.
  * Prints every request and a redacted view of every response.
  *
- *   POSTHOG_WIZARD_API_KEY=… npx tsx scripts/controlled-headless-smoke.no-jest.ts \
- *     --app /tmp/app --project-id 228144 [--region us] [--bin dist/bin.js] posthog-integration [metrics …]
+ *   APP_DIR=/tmp/app PROJECT_ID=228144 POSTHOG_REGION=us POSTHOG_KEY_FILE=… \
+ *   WIZARD_CI_GATEWAY_TOKEN_FILE=… npx tsx scripts/controlled-headless-smoke.no-jest.ts \
+ *     posthog-integration [metrics …]
+ *
+ * WIZARD_BIN=dist/bin.js runs a built binary instead of the source tree.
  */
-import { spawn } from 'node:child_process';
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { HEADLESS_FLAG } from '@env';
+import { spawn } from 'child_process';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
 import { RunPhase } from '@store';
 import { ControlClient } from '@store/control';
-import type { ControlState } from '@store/types';
+import type { ControlState, ProgramId } from '@store/types';
+import { buildLaunch, readApiKey, waitForSocket } from '@e2e-harness/launch';
 
-async function waitForSocket(p: string, timeoutMs: number): Promise<void> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (fs.existsSync(p)) return;
-    await new Promise((r) => setTimeout(r, 150));
-  }
-  throw new Error(`the wizard did not open ${p} within ${timeoutMs}ms`);
-}
-
-const args = process.argv.slice(2);
-const opt = (name: string, fallback?: string): string | undefined => {
-  const i = args.indexOf(`--${name}`);
-  return i >= 0 ? args[i + 1] : fallback;
-};
-const programs = args.filter(
-  (a, i) => !a.startsWith('--') && (i === 0 || !args[i - 1].startsWith('--')),
-);
-const app = opt('app');
-const projectId = opt('project-id');
-const region = opt('region', 'us')!;
-const bin = opt('bin', 'bin.ts')!;
-if (!app || !projectId || programs.length === 0) {
+const programs = process.argv.slice(2) as ProgramId[];
+const appDir = process.env.APP_DIR;
+const projectId = process.env.PROJECT_ID;
+const apiKey = readApiKey();
+if (!appDir || !projectId || programs.length === 0 || !apiKey) {
   process.stderr.write(
-    'usage: --app <dir> --project-id <id> [--region us|eu] [--bin dist/bin.js] <program> [program…]\n',
-  );
-  process.exit(2);
-}
-if (!process.env.POSTHOG_WIZARD_API_KEY) {
-  process.stderr.write(
-    'POSTHOG_WIZARD_API_KEY must be set in the environment\n',
+    'usage: APP_DIR=<dir> PROJECT_ID=<id> [POSTHOG_REGION=us|eu] POSTHOG_KEY_FILE=<file> ' +
+      'npx tsx scripts/controlled-headless-smoke.no-jest.ts <program> [program…]\n',
   );
   process.exit(2);
 }
 
 const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'wizard-ctl-'));
 const socketPath = path.join(dir, 'w.sock');
-const cmd = bin.endsWith('.ts')
-  ? path.join(process.cwd(), 'node_modules/.bin/tsx')
-  : 'node';
-const argv = [
-  bin,
-  `--${HEADLESS_FLAG}`,
-  '--control-socket',
+const launch = buildLaunch({
+  programId: programs[0],
+  appDir,
   socketPath,
-  '--project-id',
   projectId,
-  '--region',
-  region,
-  '--install-dir',
-  app,
-];
+  region: process.env.POSTHOG_REGION === 'eu' ? 'eu' : 'us',
+  apiKey,
+  surface: 'headless',
+  bin: process.env.WIZARD_BIN,
+});
 const log = (line: string) => process.stdout.write(`${line}\n`);
 log(
-  `$ ${cmd === 'node' ? 'node' : 'npx tsx'} ${argv.join(
+  `$ ${launch.cmd.endsWith('tsx') ? 'npx tsx' : launch.cmd} ${launch.args.join(
     ' ',
   )}   # POSTHOG_WIZARD_API_KEY in env`,
 );
-const env = { ...process.env };
-for (const k of Object.keys(env))
-  if (/^(CLAUDE|ANTHROPIC|AI_AGENT)/.test(k)) delete env[k];
-const child = spawn(cmd, argv, {
+const child = spawn(launch.cmd, launch.args, {
   cwd: process.cwd(),
-  env,
+  env: launch.env,
   stdio: ['ignore', 'pipe', 'pipe'],
 });
-const wizardOut: string[] = [];
-child.stdout.on('data', (d: Buffer) => wizardOut.push(d.toString()));
-child.stderr.on('data', (d: Buffer) => wizardOut.push(d.toString()));
+const childOutput: string[] = [];
+child.stdout.on('data', (d: Buffer) => childOutput.push(d.toString()));
+child.stderr.on('data', (d: Buffer) => childOutput.push(d.toString()));
 const exit = new Promise<number | null>((resolve) =>
   child.once('exit', (code) => resolve(code)),
 );
@@ -136,11 +109,11 @@ async function main(): Promise<void> {
   const code = await exit;
   log(`wizard exit code: ${code}`);
   log(`socket removed: ${!fs.existsSync(socketPath)}`);
-  const console = wizardOut
+  const output = childOutput
     .join('')
     .replace(/phx_[A-Za-z0-9_]+/g, 'phx_<redacted>')
     .trim();
-  if (console) log(`wizard console:\n${console}`);
+  if (output) log(`wizard console:\n${output}`);
   process.exit(code === 0 ? 0 : 1);
 }
 
diff --git a/scripts/mcp-install-smoke-test.ts b/scripts/mcp-install-smoke-test.ts
index 633a57f3a..fc7eb76c7 100644
--- a/scripts/mcp-install-smoke-test.ts
+++ b/scripts/mcp-install-smoke-test.ts
@@ -100,7 +100,7 @@ function wizard(...args: string[]): Run {
 
 /**
  * The non-interactive install. Reuses the run pipeline's headless flag, so the
- * name is imported rather than spelled out — see @lib/headless-mode.
+ * name is imported rather than spelled out — see src/store/shared/headless-mode.ts.
  */
 function mcpAdd(...extra: string[]): Run {
   return wizard('mcp', 'add', `--${HEADLESS_FLAG}`, ...extra);
diff --git a/scripts/smoke-test.sh b/scripts/smoke-test.sh
index 32ca4e36b..ae62d0b15 100755
--- a/scripts/smoke-test.sh
+++ b/scripts/smoke-test.sh
@@ -11,6 +11,8 @@
 #      non-interactive published-build path) — it must not be rejected as an
 #      unknown argument. It is intentionally undocumented; this check only keeps
 #      the published binary from silently dropping the flag the cloud runs need.
+#   5. The control server ships in its own chunk that the TUI path never imports,
+#      and --control-socket is refused without the headless flag.
 #
 # Runs from the wizard repo root via `pnpm test:smoke` (postbuild hook).
 set -e
@@ -24,7 +26,7 @@ node --input-type=module -e "import '$DIST_BIN'" 2>&1 | head -5 | grep -q 'PostH
 }
 
 # ── 2. CI flag overrides physically absent from production builds ───────────
-# The override path (src/utils/ci-flag-overrides.ts) is dead code in published
+# The override path (src/store/shared/ci-flag-overrides.ts) is dead code in published
 # builds and tsdown strips it; its env var name appearing in dist/*.js means
 # dead-code elimination regressed and a prod surface leaked. Sourcemaps keep
 # the original source, so only .js output counts.
@@ -86,7 +88,7 @@ fi
 # not reject the flag, and it must not fall through to the --ci rejection. With
 # no api-key the run exits fast on "Headless mode requires --api-key" — all this
 # asserts is that the flag is recognized and live in the published binary. The
-# flag name is intentionally undocumented; keep it in sync with @lib/headless-mode.
+# flag name is intentionally undocumented; keep it in sync with src/store/shared/headless-mode.ts.
 HEADLESS_FLAG='--headless-DONOTUSE-EXPERIMENTAL'
 hl_output=$(node "$DIST_BIN" "$HEADLESS_FLAG" --install-dir /tmp/wizard-smoke-probe 2>&1) || true
 if echo "$hl_output" | grep -qiE 'unknown argument|not currently supported'; then
@@ -106,6 +108,7 @@ fi
 # The control API ships for headless runs only. Exactly one chunk carries the
 # server; the TUI entry chunk and bin.js never import it; the published binary
 # refuses --control-socket without the headless flag and accepts it with it.
+# Defined in src/store/control/marker.ts and src/tui/start-tui.ts.
 CONTROL_MARKER='wizard-control-server'
 TUI_MARKER='wizard-tui-entry'
 control_chunks=$(grep -l "$CONTROL_MARKER" ./dist/*.js || true)
diff --git a/scripts/tui-replay.no-jest.ts b/scripts/tui-replay.no-jest.ts
index 55b2fa4b8..cc9f2f907 100644
--- a/scripts/tui-replay.no-jest.ts
+++ b/scripts/tui-replay.no-jest.ts
@@ -1,6 +1,6 @@
 /**
  * Replay captured real-TUI snapshots in the terminal — step through or auto-play
- * the `NN-<screen>.txt` frames a snapshot run dropped in SNAP_OUT.
+ * the `NN-<screen>.ans` frames a snapshot run dropped in SNAP_OUT.
  *
  *   npx tsx scripts/tui-replay.no-jest.ts <snap-dir> [--step | --delay <ms>]
  *   pnpm wizard-ci-replay /tmp/snaps                 # Enter ▸ advance (default)
@@ -35,10 +35,10 @@ async function main() {
   }
   const frames = fs
     .readdirSync(dir)
-    .filter((f) => f.endsWith('.txt') && f !== 'latest.txt')
+    .filter((f) => f.endsWith('.ans'))
     .sort();
   if (frames.length === 0) {
-    console.error(`✖ no NN-<screen>.txt snapshots in ${dir}`);
+    console.error(`✖ no NN-<screen>.ans snapshots in ${dir}`);
     process.exit(1);
   }
   // Step (Enter to advance) is the default; fall back to a timed play when not a
diff --git a/scripts/tui-snapshots.no-jest.ts b/scripts/tui-snapshots.no-jest.ts
index c5ac38b86..cec42e04c 100644
--- a/scripts/tui-snapshots.no-jest.ts
+++ b/scripts/tui-snapshots.no-jest.ts
@@ -18,7 +18,7 @@ import path from 'path';
 import { spawnSync } from 'child_process';
 import { logToFile } from '@store';
 import { getProgramConfig, Program } from '@store/programs';
-import { ControlClient } from '@store/control';
+import { ControlClient, ControlClientError } from '@store/control';
 import type { ControlState, ProgramId } from '@store/types';
 import { captureTui } from '@e2e-harness/tui-capture';
 import { buildLaunch, readApiKey, waitForSocket } from '@e2e-harness/launch';
@@ -252,7 +252,8 @@ async function main(): Promise<void> {
     let state: ControlState;
     try {
       state = await client.state();
-    } catch {
+    } catch (e) {
+      if (e instanceof ControlClientError) throw e; // a server fault, not an exit
       break; // the wizard exited between polls
     }
     lastState = state;
@@ -342,7 +343,8 @@ async function main(): Promise<void> {
     try {
       if (acted && (await client.state()).currentScreen !== before) continue;
       state = await client.waitForChange(state.version, 600_000);
-    } catch {
+    } catch (e) {
+      if (e instanceof ControlClientError) throw e;
       break;
     }
   }
diff --git a/scripts/wizard-ci-mcp.no-jest.ts b/scripts/wizard-ci-mcp.no-jest.ts
index 38326c0c1..cbbb06658 100644
--- a/scripts/wizard-ci-mcp.no-jest.ts
+++ b/scripts/wizard-ci-mcp.no-jest.ts
@@ -14,12 +14,12 @@ import { z } from 'zod';
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
-import { RunPhase } from '@store';
 import { ControlClient } from '@store/control';
 import { Program } from '@store/programs';
-import type { ControlState, ProgramId } from '@store/types';
+import type { ProgramId } from '@store/types';
 import { captureTui, type TuiCapture } from '@e2e-harness/tui-capture';
 import { buildLaunch, waitForSocket } from '@e2e-harness/launch';
+import { withRunStatus } from '@e2e-harness/run-status';
 
 const text = (data: unknown) => ({
   content: [
@@ -48,25 +48,6 @@ function active(): ControlClient {
   return client;
 }
 
-const RUN_STATUS: Record<RunPhase, string> = {
-  [RunPhase.Idle]: 'idle',
-  [RunPhase.Running]: 'running',
-  [RunPhase.Completed]: 'done',
-  [RunPhase.Error]: 'failed',
-};
-
-/** read_state adds the background run status under its historical names. */
-function withRunStatus(state: ControlState): Record<string, unknown> {
-  const { runPhase, runRequested, outroData } = state.session;
-  const armed = runPhase === RunPhase.Idle && runRequested;
-  return {
-    ...state,
-    integration: armed ? 'running' : RUN_STATUS[runPhase],
-    integrationError:
-      runPhase === RunPhase.Error ? outroData?.message ?? null : null,
-  };
-}
-
 async function waitFor(cond: () => boolean, ms: number): Promise<boolean> {
   const end = Date.now() + ms;
   while (Date.now() < end) {
diff --git a/src/agent/README.md b/src/agent/README.md
index 7a189021a..e19da06a0 100644
--- a/src/agent/README.md
+++ b/src/agent/README.md
@@ -13,7 +13,9 @@ Runs exactly one independent agent run per `runAgent` call.
 
 ## Never contains
 
-Ink, screens, program definitions, or session mutation outside `WizardUI`.
+Ink, screens, program definitions, or session mutation outside `WizardUI`. One
+exception: `runner/shared/bootstrap.ts` stamps `skillId` on the run's own
+session copy before the run starts.
 
 ## May import
 
diff --git a/src/agent/__tests__/auth-error-context.test.ts b/src/agent/__tests__/auth-error-context.test.ts
index 580a5b4b5..001702033 100644
--- a/src/agent/__tests__/auth-error-context.test.ts
+++ b/src/agent/__tests__/auth-error-context.test.ts
@@ -1,7 +1,6 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 vi.mock('@store/shared/analytics', () => ({
   analytics: { captureException: vi.fn(), wizardCapture: vi.fn() },
diff --git a/src/cli/README.md b/src/cli/README.md
index 1ac77c7e2..899dfcb69 100644
--- a/src/cli/README.md
+++ b/src/cli/README.md
@@ -23,10 +23,21 @@ surfaces' public entries. Holds no domain logic.
   `scripts/controlled-headless-smoke.no-jest.ts` drives the surface end to end
   and prints every request and response.
 
+## Never contains
+
+Domain logic, Ink, or an agent run of its own: every function parses input,
+picks a surface, or forwards to a surface's public entry.
+
 ## May import
 
 Every surface, but only through `@store`, `@store/types`, `@store/programs`,
-`@agent`, `@agent/types`, `@tui`, `@tui/types`, and `@tui/console`.
+`@agent`, `@agent/types`, `@tui`, `@tui/types`, and `@tui/console`; the two
+runners import `@store/control` dynamically.
+
+## Public entries
+
+None for other surfaces: `bin.ts` imports `main.ts`, and nothing else imports
+`@cli/*`.
 
 ## Tests
 
diff --git a/src/cli/__tests__/bin-preflight.test.ts b/src/cli/__tests__/bin-preflight.test.ts
index fa4b771b2..e1eb1cfa5 100644
--- a/src/cli/__tests__/bin-preflight.test.ts
+++ b/src/cli/__tests__/bin-preflight.test.ts
@@ -1,7 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { describe, expect, it } from 'vitest';
 import { ErrorCodes } from '@store';
 import { PHW_ERROR_PREFIX } from '@store/shared/errors/emit';
 
diff --git a/src/cli/__tests__/control-refusal.test.ts b/src/cli/__tests__/control-refusal.test.ts
index 0657a5ef0..f090c4c1f 100644
--- a/src/cli/__tests__/control-refusal.test.ts
+++ b/src/cli/__tests__/control-refusal.test.ts
@@ -1,5 +1,3 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
 vi.mock('@env', async (importOriginal) => ({
   ...(await importOriginal<typeof import('@env')>()),
   IS_PRODUCTION_BUILD: true,
diff --git a/src/cli/__tests__/control-surface.test.ts b/src/cli/__tests__/control-surface.test.ts
index 3e78442bc..5802222e4 100644
--- a/src/cli/__tests__/control-surface.test.ts
+++ b/src/cli/__tests__/control-surface.test.ts
@@ -1,4 +1,3 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { Arguments } from 'yargs';
 
 const runners = vi.hoisted(() => ({
@@ -11,9 +10,11 @@ vi.mock('../runners/index.js', () => runners);
 import { HEADLESS_FLAG } from '@env';
 import {
   errorTrackingUploadSourceMapsConfig,
+  posthogDoctorConfig,
   posthogIntegrationConfig,
   selfDrivingConfig,
 } from '@store/programs';
+import { doctorCommand } from '../commands/doctor.js';
 import { selfDrivingCommand } from '../commands/self-driving.js';
 import { uploadSourcemapsCommand } from '../commands/upload-sourcemaps.js';
 import { dispatchProgram } from '../commands/factories/shared.js';
@@ -99,4 +100,12 @@ describe('commands with their own handlers follow the same dispatch', () => {
       expect(runners.runWizardCI).toHaveBeenCalledTimes(1);
     },
   );
+
+  it('doctor drives the real TUI when a parent holds the socket', () => {
+    doctorCommand.handler?.(argv({ ci: true, controlSocket: '/tmp/c.sock' }));
+    expect(runners.runWizard).toHaveBeenCalledWith(
+      posthogDoctorConfig,
+      expect.objectContaining({ ci: true, controlSocket: '/tmp/c.sock' }),
+    );
+  });
 });
diff --git a/src/cli/commands/doctor.ts b/src/cli/commands/doctor.ts
index e389c6a32..764f41998 100644
--- a/src/cli/commands/doctor.ts
+++ b/src/cli/commands/doctor.ts
@@ -1,6 +1,7 @@
 import {
   getUI,
   setUI,
+  isControlledTui,
   readApiKeyFromEnv,
   ErrorCodes,
   emitWizardError,
@@ -27,10 +28,9 @@ export const doctorCommand: Command = {
       posthogDoctorConfig.mapCliOptions?.(argv as Record<string, unknown>) ??
       {};
     const options = { ...argv, ...extras };
-    // doctor is otherwise a TUI-only diagnostic (it has no agent run); in CI we
-    // fetch the project's health issues headlessly and report them instead. A
-    // control socket means a parent drives the real TUI.
-    if (options.ci && !options.controlSocket) {
+    // doctor has no agent run: `--ci` reports the project's health issues
+    // headlessly, unless a parent on the socket drives the real TUI.
+    if (options.ci && !isControlledTui(options)) {
       void runDoctorCI(options);
     } else {
       runWizard(posthogDoctorConfig, options);
diff --git a/src/cli/commands/self-driving.ts b/src/cli/commands/self-driving.ts
index 130f5108d..cfeecedf5 100644
--- a/src/cli/commands/self-driving.ts
+++ b/src/cli/commands/self-driving.ts
@@ -1,3 +1,4 @@
+import { isControlledTui } from '@store';
 import { dispatchProgram } from './factories/shared.js';
 import { selfDrivingConfig } from '@store/programs';
 import { skillProgramOptions } from './skill-program-options.js';
@@ -29,9 +30,8 @@ export const selfDrivingCommand: Command = {
           '(no flag needed).',
       );
     }
-    // A controlling parent on the socket answers those steps, so `--ci` is
-    // fine when a control socket is attached.
-    if (argv.ci && !argv.controlSocket) {
+    // A controlling parent on the socket answers those steps.
+    if (argv.ci && !isControlledTui(argv)) {
       throw new Error(
         '`self-driving` cannot run in CI mode — it requires interactive steps ' +
           '(GitHub connect, issue-tracker selection, custom-scout approval).',
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 7a07c7eb7..85b1d9cb9 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -1,2 +1,2 @@
-/** Entry of the cli composition root. Populated by the surface split (P3). */
+/** The cli composition root has no public runtime API; `bin.ts` imports `main.ts`. */
 export {};
diff --git a/src/cli/main.ts b/src/cli/main.ts
index bdedaf416..b946f595f 100644
--- a/src/cli/main.ts
+++ b/src/cli/main.ts
@@ -29,7 +29,7 @@ import { skillCommand } from './commands/skill.js';
 import { cliCommand } from './commands/cli/index.js';
 import { LoggingUI } from '@tui/console';
 
-// The entry point owns the default renderer; @ui ships with none.
+// The entry point owns the default renderer; the store ships with none.
 setUI(new LoggingUI());
 // The store and the TUI never import the agent; the entry point installs it,
 // lazily, so `--version` and `--help` never load the SDK or Ink.
diff --git a/src/cli/wizard.ts b/src/cli/wizard.ts
index 1a0823686..2852c3a79 100644
--- a/src/cli/wizard.ts
+++ b/src/cli/wizard.ts
@@ -104,7 +104,7 @@ export class Wizard {
     // flag. init() additionally detects it up front to print a clearer message.
     // The published-build, non-interactive path is the experimental headless
     // flag, declared per-command on basic integration + audit via
-    // `headlessOption` (see @lib/headless-mode), so no other command accepts
+    // `headlessOption` (see src/store/shared/headless-mode.ts), so no other command accepts
     // it. CI needs `region` globally because the workbench passes it to every
     // command. --ci and headless stay separate so their behavior can diverge.
     if (!IS_PRODUCTION_BUILD) {
diff --git a/src/env.ts b/src/env.ts
index 8a35cd70a..24a28345d 100644
--- a/src/env.ts
+++ b/src/env.ts
@@ -49,7 +49,7 @@ export const RUN_SURFACE: 'cloud' | 'local' = process.argv.some(
  * Add new keys here when a new runtime dependency is needed.
  */
 type RuntimeEnvKey =
-  // CI-build-only flag overrides (see utils/ci-flag-overrides.ts).
+  // CI-build-only flag overrides (see src/store/shared/ci-flag-overrides.ts).
   // Deliberately NOT POSTHOG_WIZARD_-prefixed: yargs .env('POSTHOG_WIZARD')
   // would claim it as an unknown CLI option and strict-reject the run.
   | 'WIZARD_CI_FLAG_OVERRIDES'
diff --git a/src/store/README.md b/src/store/README.md
index 92a66a7e9..75c5d6171 100644
--- a/src/store/README.md
+++ b/src/store/README.md
@@ -25,7 +25,9 @@ Render-agnostic state and the contract between the agent and whatever renders.
 
 ## Never contains
 
-Ink, console output, or any import of `@agent`, `@tui`, or `@cli`.
+Ink, rendering, or any import of `@agent`, `@tui`, or `@cli`. Two shared helpers
+write to stderr on purpose: the terminal bell and the machine-readable error
+line.
 
 ## May import
 
diff --git a/src/store/control/__tests__/actions.test.ts b/src/store/control/__tests__/actions.test.ts
index 3c2027978..71650ebe9 100644
--- a/src/store/control/__tests__/actions.test.ts
+++ b/src/store/control/__tests__/actions.test.ts
@@ -1,4 +1,3 @@
-import { describe, expect, it } from 'vitest';
 import { ERROR_TRACKING_PROJECT_PATH_KEY } from '../../programs/error-tracking/detect-agentic.js';
 import { SOURCE_MAPS_CONTEXT_KEYS } from '../../programs/error-tracking-upload-source-maps/detect.js';
 import { flowFor } from '../../programs/flow-for.js';
diff --git a/src/store/index.ts b/src/store/index.ts
index 1b716db11..ad459dafc 100644
--- a/src/store/index.ts
+++ b/src/store/index.ts
@@ -196,6 +196,7 @@ export {
   logToFile,
 } from './shared/debug.js';
 export { readApiKeyFromEnv } from './shared/env-api-key.js';
+export { detectFramework } from './detection/index.js';
 export { isTemplateEnvFileName } from './shared/env-scan.js';
 export {
   isNonInteractiveEnvironment,
diff --git a/src/store/ui/wizard-ui.ts b/src/store/ui/wizard-ui.ts
index 0c68f9c86..898b8a18d 100644
--- a/src/store/ui/wizard-ui.ts
+++ b/src/store/ui/wizard-ui.ts
@@ -36,7 +36,7 @@ export function isTaskStatus(value: string): value is TaskStatus {
  * the main session, and some programs override to Haiku, so pricing must key
  * off the per-turn model rather than a single run-wide assumption. Omit only
  * when the caller genuinely has no model context (falls back to Sonnet
- * pricing — see `pricePerMtokForModel` in `@lib/agent/token-pricing`).
+ * pricing — see `pricePerMtokForModel` in `store/agent-protocol/token-pricing.ts`).
  */
 export interface TokenUsageDelta {
   inputTokens: number;
diff --git a/src/tui/__tests__/audit-checks-viewer-layout.test.ts b/src/tui/__tests__/audit-checks-viewer-layout.test.ts
index b97f35230..2f23d1fb5 100644
--- a/src/tui/__tests__/audit-checks-viewer-layout.test.ts
+++ b/src/tui/__tests__/audit-checks-viewer-layout.test.ts
@@ -1,4 +1,3 @@
-import { describe, expect, it } from 'vitest';
 import { AUDIT_SEED_CHECKS } from '@store/programs/audit/seed';
 import { COL_AREA_WIDTH } from '../screens/audit/AuditChecksViewer/layout.js';
 
diff --git a/src/tui/__tests__/error-tracking-tips.test.ts b/src/tui/__tests__/error-tracking-tips.test.ts
index acfdb80b3..1c17f1646 100644
--- a/src/tui/__tests__/error-tracking-tips.test.ts
+++ b/src/tui/__tests__/error-tracking-tips.test.ts
@@ -1,4 +1,3 @@
-import { describe, expect, test } from 'vitest';
 import { Integration } from '@store';
 import { ERROR_TRACKING_TIPS } from '../programs/error-tracking/content/tips.js';
 
diff --git a/src/tui/router.ts b/src/tui/router.ts
index 8af34dda2..0cc6b6897 100644
--- a/src/tui/router.ts
+++ b/src/tui/router.ts
@@ -1,6 +1,6 @@
 /**
  * Screen name vocabulary for the TUI. Resolution of the active screen lives in
- * the store (`WizardStore.currentScreen` over `@lib/flow-resolution`).
+ * the store (`WizardStore.currentScreen` over `state/flow-resolution.ts`).
  */
 
 import { ScreenId } from './screen-sequences.js';
@@ -10,6 +10,6 @@ import type { ProgramId } from '@store/types';
 
 export { ScreenId, Program };
 export type { ProgramId };
-/** Interrupts, under the name the TUI has always used for them. */
+/** Interrupts, exported as `Overlay` for the screens. */
 export { Interrupt as Overlay };
 export type ScreenName = ScreenId | Interrupt;

From 917199e155efef07914c9e4a7b522e6d49baa648 Mon Sep 17 00:00:00 2001
From: "Vincent (Wen Yu) Ge" <vincent@posthog.com>
Date: Sun, 20 Sep 2026 23:03:44 -0400
Subject: [PATCH 8/8] chore(build): refresh the chunk manifest fixtures

The bundle audit compares these with the manifests CI builds; the new modules
and the regrouped chunks belong in them. A failed comparison now uploads its
manifests and reports both files.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
---
 scripts/__fixtures__/chunk-manifest.ci.json   | 87 +++++++------------
 scripts/__fixtures__/chunk-manifest.prod.json | 87 ++++++++++++++-----
 2 files changed, 99 insertions(+), 75 deletions(-)

diff --git a/scripts/__fixtures__/chunk-manifest.ci.json b/scripts/__fixtures__/chunk-manifest.ci.json
index 2e2ade035..1f1d937b5 100644
--- a/scripts/__fixtures__/chunk-manifest.ci.json
+++ b/scripts/__fixtures__/chunk-manifest.ci.json
@@ -23,9 +23,9 @@
     ],
     "imports": [
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/auth-session-state.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/agent/agent-prompt-loader.ts": {
@@ -78,10 +78,10 @@
       "src/agent/agent-prompt-loader.ts",
       "src/agent/aio-capture.ts",
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
-      "src/store/programs/ai-opt-in-gate.ts"
+      "src/store/programs/ai-opt-in-gate.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/agent/aio-capture.ts": {
@@ -98,8 +98,9 @@
       "src/agent/runner/harness/pi/task.ts",
       "src/agent/runner/harness/pi/tasks.ts",
       "src/agent/runner/harness/pi/tools.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
-      "src/store/agent-protocol/agent-signals.ts"
+      "src/store/agent-protocol/agent-signals.ts",
+      "src/store/auth-session-state.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/agent/runner/harness/pi/mcp.ts": {
@@ -144,8 +145,9 @@
       "src/agent/runner/harness/pi/security.ts",
       "src/agent/runner/harness/pi/tools.ts",
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
-      "src/store/agent-protocol/agent-signals.ts"
+      "src/store/agent-protocol/agent-signals.ts",
+      "src/store/auth-session-state.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/agent/runner/harness/pi/tasks.ts": {
@@ -160,8 +162,9 @@
     ],
     "imports": [
       "src/agent/aio-capture.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/agent-protocol/agent-signals.ts",
+      "src/store/auth-session-state.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/agent/runner/sequence/orchestrator/queue-tools.ts": {
@@ -216,10 +219,11 @@
       "src/cli/commands/basic-integration/non-interactive.ts",
       "src/cli/commands/basic-integration/playground.ts",
       "src/cli/control-hooks.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
-      "src/tui/App.tsx"
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts",
+      "src/tui/App.tsx",
+      "src/tui/console/headless-ui.ts"
     ]
   },
   "src/cli/commands/basic-integration/ci-install.ts": {
@@ -229,7 +233,8 @@
     "imports": [
       "src/cli/control-hooks.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/auth-session-state.ts",
+      "src/tui/console/headless-ui.ts"
     ]
   },
   "src/cli/commands/basic-integration/interactive.ts": {
@@ -268,49 +273,13 @@
     ],
     "imports": [
       "src/agent/agent-prompt.ts",
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
       "src/store/control/actions.ts",
       "src/store/programs/ai-opt-in-gate.ts",
-      "src/tui/App.tsx"
-    ]
-  },
-  "src/store/agent-protocol/agent-env-isolation.ts": {
-    "sources": [
-      "src/store/agent-protocol/agent-env-isolation.ts",
-      "src/store/agent-protocol/agent-phase.ts",
-      "src/store/agent-protocol/mcp-prompt.ts",
-      "src/store/agent-protocol/token-pricing.ts",
-      "src/store/file-watcher.ts",
-      "src/store/mcp-project-profile.ts",
-      "src/store/mcp-role-prompts.copy.json",
-      "src/store/mcp-role-prompts.ts",
-      "src/store/mcp-seed-events.ts",
-      "src/store/safe-tools.ts",
-      "src/store/services/claude-settings.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/browser-client.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/login-client.ts",
-      "src/store/session/secret-vault.ts",
-      "src/store/shared/clipboard.ts",
-      "src/store/shared/custom-headers.ts",
-      "src/store/shared/env-api-key.ts",
-      "src/store/shared/environment.ts",
-      "src/store/shared/terminal-bell.ts",
-      "src/store/state/store.ts",
-      "src/store/task-stream/audit-areas.ts",
-      "src/store/task-stream/destinations/file.ts",
-      "src/store/task-stream/destinations/posthog.ts",
-      "src/store/task-stream/event-plan-watcher.ts",
-      "src/store/task-stream/task-stream-push.ts",
-      "src/store/tools/handoff.ts",
-      "src/store/ui/store-ui.ts",
-      "src/store/ui/wizard-ui.ts",
-      "src/store/wizard-spellbook.ts"
-    ],
-    "imports": [
-      "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts",
+      "src/tui/App.tsx",
+      "src/tui/console/headless-ui.ts"
     ]
   },
   "src/store/agent-protocol/agent-signals.ts": {
@@ -501,9 +470,9 @@
       "src/store/programs/run-config.ts"
     ],
     "imports": [
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/auth-session-state.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
   },
   "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts": {
@@ -718,11 +687,19 @@
       "src/tui/ui-store.ts"
     ],
     "imports": [
-      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
       "src/store/programs/ai-opt-in-gate.ts",
       "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
+  },
+  "src/tui/console/headless-ui.ts": {
+    "sources": [
+      "src/tui/console/headless-ui.ts",
+      "src/tui/console/logging-ui.ts"
+    ],
+    "imports": [
+      "src/store/auth-session-state.ts"
+    ]
   }
 }
diff --git a/scripts/__fixtures__/chunk-manifest.prod.json b/scripts/__fixtures__/chunk-manifest.prod.json
index 3e48dd1ac..262963df6 100644
--- a/scripts/__fixtures__/chunk-manifest.prod.json
+++ b/scripts/__fixtures__/chunk-manifest.prod.json
@@ -23,9 +23,9 @@
     ],
     "imports": [
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/auth-session-state.ts"
     ]
   },
   "src/agent/agent-prompt-loader.ts": {
@@ -78,10 +78,10 @@
       "src/agent/agent-prompt-loader.ts",
       "src/agent/aio-capture.ts",
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
-      "src/store/programs/ai-opt-in-gate.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/programs/ai-opt-in-gate.ts"
     ]
   },
   "src/agent/aio-capture.ts": {
@@ -98,9 +98,8 @@
       "src/agent/runner/harness/pi/task.ts",
       "src/agent/runner/harness/pi/tasks.ts",
       "src/agent/runner/harness/pi/tools.ts",
-      "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/agent-protocol/agent-env-isolation.ts",
+      "src/store/agent-protocol/agent-signals.ts"
     ]
   },
   "src/agent/runner/harness/pi/mcp.ts": {
@@ -145,9 +144,8 @@
       "src/agent/runner/harness/pi/security.ts",
       "src/agent/runner/harness/pi/tools.ts",
       "src/agent/runner/sequence/orchestrator/queue-tools.ts",
-      "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/agent-protocol/agent-env-isolation.ts",
+      "src/store/agent-protocol/agent-signals.ts"
     ]
   },
   "src/agent/runner/harness/pi/tasks.ts": {
@@ -162,9 +160,8 @@
     ],
     "imports": [
       "src/agent/aio-capture.ts",
-      "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/agent-protocol/agent-env-isolation.ts",
+      "src/store/auth-session-state.ts"
     ]
   },
   "src/agent/runner/sequence/orchestrator/queue-tools.ts": {
@@ -219,10 +216,11 @@
       "src/cli/commands/basic-integration/non-interactive.ts",
       "src/cli/commands/basic-integration/playground.ts",
       "src/cli/control-hooks.ts",
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts",
-      "src/tui/App.tsx"
+      "src/tui/App.tsx",
+      "src/tui/console/headless-ui.ts"
     ]
   },
   "src/cli/commands/basic-integration/ci-install.ts": {
@@ -232,7 +230,8 @@
     "imports": [
       "src/cli/control-hooks.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts"
+      "src/store/auth-session-state.ts",
+      "src/tui/console/headless-ui.ts"
     ]
   },
   "src/cli/commands/basic-integration/interactive.ts": {
@@ -271,12 +270,50 @@
     ],
     "imports": [
       "src/agent/agent-prompt.ts",
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
       "src/store/control/actions.ts",
       "src/store/programs/ai-opt-in-gate.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts",
-      "src/tui/App.tsx"
+      "src/tui/App.tsx",
+      "src/tui/console/headless-ui.ts"
+    ]
+  },
+  "src/store/agent-protocol/agent-env-isolation.ts": {
+    "sources": [
+      "src/store/agent-protocol/agent-env-isolation.ts",
+      "src/store/agent-protocol/agent-phase.ts",
+      "src/store/agent-protocol/mcp-prompt.ts",
+      "src/store/agent-protocol/token-pricing.ts",
+      "src/store/file-watcher.ts",
+      "src/store/mcp-project-profile.ts",
+      "src/store/mcp-role-prompts.copy.json",
+      "src/store/mcp-role-prompts.ts",
+      "src/store/mcp-seed-events.ts",
+      "src/store/safe-tools.ts",
+      "src/store/services/claude-settings.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/browser-client.ts",
+      "src/store/services/steps/add-mcp-server-to-clients/login-client.ts",
+      "src/store/session/secret-vault.ts",
+      "src/store/shared/clipboard.ts",
+      "src/store/shared/custom-headers.ts",
+      "src/store/shared/env-api-key.ts",
+      "src/store/shared/environment.ts",
+      "src/store/shared/terminal-bell.ts",
+      "src/store/state/store.ts",
+      "src/store/task-stream/audit-areas.ts",
+      "src/store/task-stream/destinations/file.ts",
+      "src/store/task-stream/destinations/posthog.ts",
+      "src/store/task-stream/event-plan-watcher.ts",
+      "src/store/task-stream/task-stream-push.ts",
+      "src/store/tools/handoff.ts",
+      "src/store/ui/store-ui.ts",
+      "src/store/ui/wizard-ui.ts",
+      "src/store/wizard-spellbook.ts"
+    ],
+    "imports": [
+      "src/store/agent-protocol/agent-signals.ts",
+      "src/store/auth-session-state.ts"
     ]
   },
   "src/store/agent-protocol/agent-signals.ts": {
@@ -467,9 +504,9 @@
       "src/store/programs/run-config.ts"
     ],
     "imports": [
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
-      "src/store/auth-session-state.ts",
-      "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
+      "src/store/auth-session-state.ts"
     ]
   },
   "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts": {
@@ -684,10 +721,20 @@
       "src/tui/ui-store.ts"
     ],
     "imports": [
+      "src/store/agent-protocol/agent-env-isolation.ts",
       "src/store/agent-protocol/agent-signals.ts",
       "src/store/auth-session-state.ts",
       "src/store/programs/ai-opt-in-gate.ts",
       "src/store/services/steps/add-mcp-server-to-clients/MCPClient.ts"
     ]
+  },
+  "src/tui/console/headless-ui.ts": {
+    "sources": [
+      "src/tui/console/headless-ui.ts",
+      "src/tui/console/logging-ui.ts"
+    ],
+    "imports": [
+      "src/store/auth-session-state.ts"
+    ]
   }
 }