diff --git a/.mex/ROUTER.md b/.mex/ROUTER.md
index 7fc233d1..a8fc275d 100644
--- a/.mex/ROUTER.md
+++ b/.mex/ROUTER.md
@@ -18,7 +18,7 @@ edges:
     condition: when refreshing the release README, badges, community links, or architecture illustrations
   - target: patterns/hub-first-run-onboarding.md
     condition: when adding or changing the Hub first-run tour or its checkout-local completion state
-last_updated: 2026-10-11
+last_updated: 2026-10-13
 ---
 
 # Session Bootstrap
@@ -30,7 +30,52 @@ Then read this file fully before doing anything else in this session.
 ## Current Project State
 
 **Working:**
-- PR #250 review fixes are implemented on `fix/206-nested-dependency-manifests`:
+- Release preparation for 0.8.4 is on `codex/release-0.8.4`, based on main
+  `54f7d7a`, and includes the terminal setup overhaul and default-routing work.
+  Current package metadata, capability fixtures, README installation examples,
+  release notes, and upgrade guidance target 0.8.4. Historical release records
+  retain their versions. Teams must upgrade together before sharing new `mh2:`
+  groundings; older clients cannot read them. Preparation and PR creation are
+  authorized; publication is still pending. Verification and known follow-ups
+  are tracked in `docs/design/0.8.4-release-plan.md`.
+- PR #271 review fixes add final stdin shutdown, bounded terminal warning history,
+  a clean copyable Hub link, width-aware control labels, explicit paused outcomes,
+  and a final browser-commit readiness check. The Wiki grounding bridge now
+  accepts exact evidence from fully parsed files when the only graph shortfall
+  is an unrelated incomplete parse; partial-file and missing-target evidence
+  remains unverified, and source/configuration drift still refuses. Windows
+  packed CLI discovery compares canonical paths. Release performance limits
+  remain unchanged; the final exact-head CI run is still required.
+- The Windows follow-up waits for Enter after the manual prompt and Hub link
+  view in a short-lived child process. A parent console read between HUD mounts
+  left the next HUD without input on Windows. `mex check` now checks groundings
+  when the graph's only faults are incomplete parses (and/or changed source).
+  Partial-file and missing targets are unverified with the files named, and
+  configuration drift still skips grounding. Main's #250/#251 checker fixes are
+  merged into the release branch.
+- Local terminal setup is the default for `mex setup` and bare `mex` in
+  incomplete projects, with the lowercase ASCII `mex` banner in cyan.
+  `setup --browser` explicitly opens browser setup; `--cli` remains supported.
+  Bare `mex` still opens the Hub for established code projects, preserving
+  missing-index recovery. The HUD replaces the old prompts with
+  integration selection before writes, native Claude/Codex terminal handoff,
+  and explicit complete/paused/failed/cancelled outcomes. Enter selects the
+  highlighted tool and starts; Space optionally toggles extra integrations,
+  and a separate Continue row supports the current selection or no agent.
+  It reuses the shared
+  setup engine and opens the setup-enabled Hub after validation for commit
+  review and optional completion details. Scripts and CI remain plain and
+  never launch an interactive agent or long-lived Hub. Long graph steps now
+  forward actual phase/file counts into an animated HUD with phase/quiet timers;
+  failures retain bounded local worker diagnostics and authored recovery advice.
+  This is working-tree
+  implementation, not a published release.
+- Local setup error-reporting work preserves authored recovery instructions
+  for expected config, ignore-protection, integration, Graph, grounding, and
+  Wiki failures in the browser. Raw diagnostics remain terminal-only, and
+  unexpected exceptions retain the generic fallback. This working-tree change
+  leaves the setup completion rules and private response schema unchanged.
+- PR #250's nested dependency-manifest fixes are merged into main:
   recursive manifest discovery preserves root precedence, skips symlinks, and
   abstains when bounded discovery or reads cannot complete. These changes are
   validated by 137 focused tests and typecheck after main integration; see [dependency-manifest-discovery.md](patterns/dependency-manifest-discovery.md) for regression guidance.
@@ -54,7 +99,7 @@ Then read this file fully before doing anything else in this session.
   approving review before normal merge. The maintainer will publish after merge.
   Verification and remaining publication steps are tracked in
   `docs/design/0.8.3-release-plan.md`.
-- 0.8.2 setup work on `codex/0.8.2-hub-setup` makes `mex setup` and bare
+- 0.8.2 setup work on `codex/0.8.2-hub-setup` originally made `mex setup` and bare
   `mex` browser entry points; `setup --cli` retains terminal setup and
   `setup --dry-run` remains a read-only terminal preview. Setup commits now
   lead to a completion guide with explicit **Open Hub**, version-pinned optional
@@ -70,7 +115,8 @@ Then read this file fully before doing anything else in this session.
   frozen. The release plan records the deterministic calibration and CI evidence.
   This is branch implementation, not a published release; verification
   and outstanding release gates are in `docs/design/0.8.2-release-plan.md`.
-- Incomplete checkouts open a Hub setup wizard from `mex`, `mex setup`, or `mex hub` instead of the
+- Incomplete checkouts can open a Hub setup wizard explicitly with
+  `mex setup --browser` or `mex hub` instead of the
   full dashboard. Setup begins on a welcome screen, then runs the same ordered
   `mex setup` steps through a headless engine, pauses at population with a
   copyable prompt when no selected CLI is available. Claude/Codex population
@@ -379,6 +425,16 @@ Then read this file fully before doing anything else in this session.
 - Public package-root exports for the provisional team contracts.
 
 **Known Issues:**
+- A disposable MEX copy with installed dependencies reproduced Node heap
+  exhaustion during graph construction (924 sources, last event 865/924,
+  about 101 seconds, explicit V8 heap-limit stderr). The source-only copy
+  completed; a tiny fresh repository also passes. A compiler-only probe also
+  exhausted the heap during signature rendering, before graph persistence;
+  this does not establish a persistent leak or one uniquely causal declaration.
+  Setup now exposes that cause,
+  but the underlying compiler memory pressure is not fixed by HUD animation
+  or process isolation. Investigate it without changing canonical signatures
+  or increasing production heap/resource budgets merely to pass the example.
 - Graph construction still rebuilds the full eligible corpus after source
   changes and has no peak-memory quota. The branch's actual Hub probe peaked at
   about 1,963 MiB combined RSS and retained multi-second pauses around initial
diff --git a/.mex/context/setup.md b/.mex/context/setup.md
index c5f65212..79fcead4 100644
--- a/.mex/context/setup.md
+++ b/.mex/context/setup.md
@@ -20,7 +20,7 @@ edges:
 # Ground only setup behavior implemented by specific code symbols.
 # Entry shape: { node: "function:<tier-1-id>", fingerprint: "mh2:64:<base64url>" }
 grounds_to: []
-last_updated: "2026-10-08"
+last_updated: "2026-10-09"
 mex:
   id: mx_01M1M0CJGBPPFPWHY980PMTS2T
   type: guide
@@ -77,9 +77,9 @@ relations:
 2. `npm run typecheck`
 3. `npm test`
 4. `npm run build`
-5. For exact-checkout browser setup, run `node dist/cli.js setup`. Use `node dist/cli.js setup --cli` for terminal dogfooding; rerun that terminal command after manual population to finalize grounding and Wiki readiness.
+5. For exact-checkout terminal setup, run `node dist/cli.js setup` (`--cli` remains supported). The HUD hands the terminal to a selected native Claude/Codex session, restores it, checks population, then finalizes grounding and Wiki. Manual population offers Check populated files or a resumable exit. Use `node dist/cli.js setup --browser` for browser setup or to reopen its commit/completion page. `--yes`, pipes, and CI use plain output with no agent or Hub launch; exit 2 means population is still required.
 6. Review the canonical scaffold and selected agent files in setup, then explicitly commit them through the Hub action or your Git client. Keep generated databases and `.mex/local/` ignored. The completion guide precedes **Open Hub** and offers optional version-pinned global install and contact details.
-7. Bare `node dist/cli.js` opens the Hub or setup; `node dist/cli.js hub` remains supported. Verify any installed global CLI matches the checkout. `mex tui` retains the terminal dashboard.
+7. Bare `node dist/cli.js` opens the Hub for established code projects, including missing-index recovery, and terminal setup otherwise. `node dist/cli.js hub` explicitly opens the browser. Verify any installed global CLI matches the checkout. `mex tui` retains the terminal dashboard.
 
 <!-- mex:entity
 id: mx_01M1M0CJE778KMAJA005V2RWWN
@@ -135,6 +135,7 @@ relations:
 
 - **`node:sqlite` is unavailable:** confirm `node --version` is at least 22.5; older Node releases cannot run MEX 0.8.x.
 - **Graph reports migration/rebuild required after an upgrade:** run the exact checkout CLI with `node dist/cli.js graph rebuild`, or rerun setup; do not edit SQLite files manually.
+- **Graph setup appears idle:** the terminal HUD shows real worker phases/file counts, phase elapsed time, and time since the last event. Its spinner shows the interface is active, not that the worker has reported more progress. Press `d` for details; worker failures retain bounded terminal diagnostics, including confirmed Node heap exhaustion.
 - **Wiki reports migration required:** finish scaffold population and continue browser setup or rerun `node dist/cli.js setup --cli` so migration, index rebuild, and validation happen in the supported order.
 - **Tests become flaky while a build runs:** do not run the full test suite concurrently with tsup/Vite cleanup of generated output.
 - **Graph status is degraded:** inspect parse health and narrow graph queries; partial structural parsing is usable evidence, not permission to invent missing facts.
diff --git a/.mex/patterns/dogfood-mex-setup.md b/.mex/patterns/dogfood-mex-setup.md
index 02bca748..12be4bb7 100644
--- a/.mex/patterns/dogfood-mex-setup.md
+++ b/.mex/patterns/dogfood-mex-setup.md
@@ -13,12 +13,12 @@ edges:
     condition: "when distinguishing canonical artifacts from local projections"
   - target: "patterns/release-performance-gate.md"
     condition: "when the change also affects packed-install or release gates"
-last_updated: 2026-09-13
+last_updated: 2026-10-10
 mex:
   id: mx_01M1M0CJJD2AQZ6XKHV4VKYTGJ
   type: pattern
   status: promoted
-  revision: 5
+  revision: 7
   title: dogfood-mex-setup
   grounds_to:
     - node: function:9055347f917caf8721a2f6d4e18bcc9a
@@ -64,13 +64,81 @@ global `mex`.
 
 ## Gotchas
 
-- From 0.8.2, unflagged `setup` opens the browser. Terminal drivers and scripts
-  must pass `--cli`; `--dry-run` remains a read-only terminal preview.
+- Unflagged `setup` now opens terminal setup; `--cli` remains a compatibility
+  alias. Browser drivers must pass `setup --browser` or use `hub` explicitly.
+  Bare `mex` uses terminal setup for incomplete/agent-memory projects and the
+  Hub for code projects with a Router and committed identity, even when indexes
+  are missing. Keep that entry decision read-only and independent of source
+  scanning, CLI discovery, or database-presence completion claims.
+  `--dry-run` remains a read-only terminal preview. Reject `--browser` combined
+  with `--cli`, `--dry-run`, `--tool`, or `--yes` before launching either flow.
+- Read-only entry tests snapshot Git bytes as well as project files. Disable
+  automatic Git maintenance in fixture-writing commands before taking those
+  snapshots; a background maintenance lock disappearing after a fixture commit
+  is unrelated to entry discovery. Keep the full snapshot assertion intact.
+- Interactive terminal setup uses the shared ordered engine through a HUD.
+  Enter on a tool selects it and starts setup atomically; that focused tool
+  precedes other checked tools when selecting a native agent. Space optionally
+  toggles extra integrations. A separate Continue row preserves the checked
+  choices, including the deliberate no-agent path. Test fresh setup without
+  injected `--tool` flags so highlighted-but-unchecked choices are exercised.
+  Suspend and completely unmount the HUD before inherited-stdio population,
+  then restore it and inspect the files. Agent exit zero alone is not readiness.
+  Keep signals and descendant cleanup separate from headless process groups:
+  native agents share MEX's foreground terminal and must not be detached.
+  Ink unmount restores cooked mode and unrefs stdin but does not pause its
+  underlying reader: explicitly pause stdin before handing it to the child,
+  and ref it before remounting Ink or opening the manual readline question.
+  Otherwise the parent can consume the child's input or exit while awaiting
+  a manual answer. On final close, pause and unref stdin even after a readline
+  round trip; otherwise a Windows console read can keep the process alive.
+  Manual prompt/link questions use the cooked terminal without readline's
+  keypress decoder. Readline also pauses the stream on close: resume reads only
+  after the remounted HUD installs its input handler, retaining the first key.
+  Real PTY tests cover both readline round trips. Verify Windows portability
+  and native console shutdown separately; POSIX PTYs do not cover that boundary.
+- Forward graph maintenance updates separately from ordered setup phases:
+  repeated parse events must not mark the graph complete or restart its timer.
+  Show real phase/count updates, animate only during active work, and distinguish
+  elapsed time from time since the last worker event. Stop animation on unmount
+  so the native agent retains the terminal without stray HUD redraws.
+- Preserve bounded worker stderr locally; discarded stderr hides Node heap
+  exhaustion behind a generic worker failure. Retain exit/signal, elapsed time,
+  and last progress; project only authored recovery text to Hub. A signal alone
+  is not evidence of memory exhaustion. Fresh tiny fixtures verify the path but
+  do not represent MEX with its installed dependency graph.
+  A self-killed worker reports a nonzero exit code and no signal on Windows;
+  POSIX reports `SIGKILL` and no exit code. Assert the platform's real diagnostic
+  while preserving process-death, workspace-cleanup, and live-index checks.
+  Distinguish a signal sent by MEX to clean up an already diagnosed failure
+  from the worker's original cause. Preserve both in local diagnostic metadata,
+  but do not describe supervisor cleanup as the cause of failure.
+  Give malformed-protocol tests the normal worker-start allowance; reserve the
+  deliberately tiny startup deadline for the startup-timeout case itself.
+- Keep bounded process-local setup history under `d`, including earlier
+  migration warnings. Open details at the current diagnostic and allow scrolling
+  back; replacing only the latest message loses earlier actionable notices.
+  Choose footer labels by the actual available width. On the finishing Hub
+  screen, `l` suspends the HUD to print its entire URL without frame characters.
+- After terminal validation, start the setup-enabled Hub in the foreground for
+  commit review and completion. `--no-open` suppresses browser launch only.
+  Scripted/CI/`--yes` runs never start an agent or long-lived Hub; exit 2 is the
+  resumable population checkpoint, 1 failure, and 130/143 cancellation.
+  Choosing Finish later clears a prior agent-launch failure for this explicit
+  paused outcome. After the Hub stops, recheck the browser's commit result before
+  choosing the completion message; committed projects reopen with `mex hub`,
+  while the remaining commit page reopens with `mex setup --browser`.
 - Test completion without a real global installation or contact submission.
   Isolate `MEX_HOME` in disposable fixtures and inject the npm/form transport.
   Successful contact delivery stores only a submitted marker; skipping stores
   only a skipped marker. Neither contains contact data or analytics identifiers.
 - Build before browser testing, and do not rebuild a running Hub's asset tree.
+  The same applies to a running setup CLI, including time spent in its native
+  agent session: tsup cleans old hashed chunks, and the late Hub import can
+  fail when that session returns. Exit the old process completely before
+  rebuilding. If this happened after finalization, start the current CLI with
+  `setup --browser` to open the finishing page; Retry in the old HUD
+  cannot replace its cached module imports.
   `test/cli.test.ts` also builds production assets in its setup hook; run the
   packaged browser scenarios after that suite so manifests cannot outlive files.
 
@@ -78,13 +146,20 @@ global `mex`.
   use the built checkout when validating uncommitted setup changes.
 - Setup copies missing scaffold files but does not overwrite substantive files.
   Population prompts must merge at section granularity and preserve managed blocks.
-- A non-interactive run without Claude Code or Codex may pause after printing the
-  population prompt. That is a resumable checkpoint, not a failed setup.
+- A non-interactive run pauses after printing the population prompt when
+  placeholders remain, even if an agent CLI is installed. It never waits on an
+  interactive session. Test the shipped interactive CLI with the POSIX PTY
+  harness and fake agents; the Python harness is skipped on Windows.
 - Drift staleness uses committed Git history. Correct uncommitted content can
   remain stale until the canonical scaffold is committed.
-- A Graph with partial parses can support scoped evidence while exact reads
-  abstain. Do not weaken freshness or provenance checks to force an answer.
-- MEX does not stage, commit, pull, or push repository changes.
+- An unrelated incomplete parse does not invalidate exact Wiki grounding from
+  a fully parsed file. Only the grounding bridge admits parse-only degradation;
+  source/configuration drift still refuses, partial-file facts remain unverified,
+  and missing targets are not reconciled across an incomplete corpus. Name the
+  incomplete files and remedy rather than claiming a concurrent graph change.
+- Terminal setup does not stage or commit. The setup Hub may create a local
+  commit only after exact diff review and explicit user action, preserving
+  unrelated staged work. MEX never pulls or pushes.
 
 ## Verify
 
diff --git a/.mex/patterns/safe-graph-snapshot-evolution.md b/.mex/patterns/safe-graph-snapshot-evolution.md
index c95faafb..d0a343dd 100644
--- a/.mex/patterns/safe-graph-snapshot-evolution.md
+++ b/.mex/patterns/safe-graph-snapshot-evolution.md
@@ -12,12 +12,12 @@ edges:
     condition: "when changing the graph data plane or its consumers"
   - target: "context/conventions.md"
     condition: "when verifying a graph implementation change"
-last_updated: 2026-09-09
+last_updated: 2026-10-10
 mex:
   id: mx_01M1M0CJP81C590FCKTSN5HA3Q
   type: pattern
   status: promoted
-  revision: 4
+  revision: 5
   title: safe-graph-snapshot-evolution
   grounds_to:
     - node: function:57e8797d70bfb28e3f0bb1d6e065a84b
@@ -157,6 +157,14 @@ only to explicit maintenance workflows.
   containment and verified source bytes survive a config change; anything
   reached by following an edge does not. Labelling everything is honest but
   wastes a trustworthy answer; labelling nothing is a lie.
+- Wiki grounding admits only parse-only degradation through its own snapshot
+  bridge. Exact nodes and fingerprints must come from files recorded as fully
+  parsed; source or configuration drift still refuses. Do not reconcile a
+  missing target against an incomplete corpus or infer that it is gone. Carry
+  the bounded incomplete-file reason through reads and rejected writes, and
+  retain the complete final snapshot/source revalidation before publication.
+  Test real Wiki apply for healthy and partial files plus source/config drift;
+  do not relax the general GraphPort gate to make grounding work.
 - Commit output under the class it was labelled with. If the store changes class
   between opening and output, discard the response rather than relabelling it —
   the records were built under a claim they no longer earn.
diff --git a/.mex/patterns/secure-local-project-hub.md b/.mex/patterns/secure-local-project-hub.md
index b2f4412c..12cb5de4 100644
--- a/.mex/patterns/secure-local-project-hub.md
+++ b/.mex/patterns/secure-local-project-hub.md
@@ -11,12 +11,12 @@ edges:
     condition: "when persisting a Hub job or migrating team.db"
   - target: "context/architecture.md"
     condition: "when wiring a real Graph or Wiki adapter"
-last_updated: 2026-09-11
+last_updated: 2026-10-09
 mex:
   id: mx_01M1M0CJQ2BSV71G1C7TXZD9RH
   type: pattern
   status: promoted
-  revision: 10
+  revision: 11
   title: secure-local-project-hub
   grounds_to:
     - node: function:188820af31f0d74c6518f6926f559877
@@ -76,6 +76,13 @@ preview/apply services.
 
 ## Gotchas
 
+- Setup failures need a browser-safe explanation at the producer. Use the
+  internal `SetupError.userMessage` contract for expected failures; retain raw
+  filesystem, Git, worker, and database diagnostics in `message`/`cause` only.
+  Classify maintenance codes and use registry-owned Wiki remediation rather
+  than forwarding exception text. Keep both run error fields within 512
+  characters, preserve cancellation precedence, and test the real runner's
+  failure and retry path as well as mocked error projection.
 - WHATWG URL construction normalizes traversal and backslashes; native request
   targets need their own pre-normalization gate.
 - A HEAD request may be routed through a GET handler. Reject it before reserving
@@ -154,6 +161,12 @@ preview/apply services.
   carry no output backlog. Never put the transcript into repeated run snapshots.
   Browser retention is independently bounded, with a limited text/row window,
   literal selectable text, stable scrollback, and explicit Follow latest.
+- Allocate a setup transcript identity only after the first retained agent
+  output, then announce it on the run snapshot. Starting or checking setup can
+  skip the agent entirely; commit checks, manual population, and finalization
+  must not fabricate an empty session. Show real startup activity until output
+  arrives, and retain actual session history through finalization and commit
+  review. Verify both the absent-session path and replay after a page refresh.
 - Cap individual provider records, tool correlation, and SSE cadence; discard
   malformed/oversized records and require recognized terminal success. Claude
   partial/final text, Codex cumulative assistant text, and tool lifecycle
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e4cde68f..a73ae1df 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,14 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.8.4] - 2026-10-09
+
+Unpublished release preparation. The date records preparation; merge, tagging,
+and publication remain separate release steps.
+
 ### Added
+- `mex wiki link-sections` previews missing `refines` relationships between existing section entities and their enclosing knowledge; `--apply` writes the structural links without changing facts or grounding baselines. The bounded Hub graph keeps a limited number of linked parents visible.
+- `mex wiki upgrade` previews a bounded review of broad code-linked knowledge for one fact per entity. `--apply` uses the sync agent chooser, with an optional `--tool` override and a manual prompt when no CLI is available. It requires a fresh graph, refuses flagged candidate groundings, preserves existing ids as overviews, and does not rerun setup. `mex wiki reground <id>` previews re-recording a reviewed entity's code links and requires `--apply` to write them.
 - `mex graph compact-fingerprints` re-encodes every committed `mh:` fingerprint as `mh2:` in one explicit pass, for a team that wants the smaller scaffold now rather than file by file. `--dry-run` reports the files and byte savings without writing, and `--json` returns the result. It needs no code graph, rewrites only the fingerprint values in root, `mex:` and section-entity `grounds_to` lists with their quoting kept, checks that every grounding decodes to the same fingerprint before publishing a file, skips Team records, and leaves a file edited during the pass untouched. On five populated scaffolds it re-encoded all 121 fingerprints, changing one line per fingerprint and nothing else, and a second run found nothing to do (#233).
 
 - A knowledge file can declare its Wiki entity type with a root `type` key in its frontmatter, and `mex wiki migrate` adopts it as one file-level entity of that type, moving the value to `mex.type`. This is the explicit type an unknown `context/*.md` file needs; its location alone still types nothing. A value that is not a Wiki type, names a Spec-family type (created through `mex inbox`), or disagrees with the rule that already types the file is reported and the file left unchanged. Setup's population prompts now ask for `type` on every domain-specific context file they create, so population output is indexed with its groundings (#227).
@@ -12,31 +19,47 @@ All notable changes to this project will be documented in this file.
 - `mex pattern add` adds the new pattern to the Wiki when the scaffold already uses it, through the same locked, audited migration `mex wiki migrate` runs, so its template edge also becomes a relation. A scaffold with no Wiki entity, or a path `wiki.exclude` hides, keeps the plain template, and a failure leaves the file in place and names `mex wiki migrate` (#227).
 
 ### Changed
+- `mex setup` now defaults to a keyboard-driven terminal HUD with an ASCII banner, tool selection before writes, real graph phase/file counts, and elapsed/quiet timers. Enter selects the highlighted tool and starts; Space selects additional integrations. Bare `mex` opens terminal setup for an incomplete project and keeps established code projects on Hub. Use `mex setup --browser` for browser setup, `mex hub` for Hub, and `mex tui` for the terminal dashboard; `--cli` remains a supported alias for the default setup route.
+- Interactive terminal population hands the real terminal to an available selected Claude Code or Codex CLI, then resumes MEX after that session exits. Incomplete work offers retry, a copyable manual prompt, file checks, or Finish later. Setup reports complete, paused, failed, and cancelled outcomes. `--yes`, piped input/output, and CI remain plain and never launch an agent or a long-lived Hub; repeatable `--tool` flags or `--tool none` select integrations without interaction. `--dry-run` stays read-only.
+- `mex check`, Wiki queries, and Hub views share one fact-aware code-link verdict. Comment-only and formatting-only edits remain fresh; changes proved away from the named fact report `changed-nearby`; missing or ambiguous links remain flagged. Setup/GROW guidance asks for one code-linked claim per entity, grounded to every dependency. `mex sync` reviews flagged Wiki facts in the same agent session, re-records only reviewed links, rebuilds the Wiki index, and checks again. `mex wiki validate` checks structure; use `mex check` for code-link health.
 - `context/stack.md`, which setup writes for every project, is adopted by `mex wiki migrate` as one file-level `architecture` entity, its lists left as prose. It was the one template file no migration rule covered, so it and every edge pointing at it stayed outside the Wiki. On a populated Hono scaffold, declaring the two domain files' types and migrating created three entities, converted 16 edges to relations and moved 12 groundings under entities; `wiki query` and `wiki for-code` then returned the routing knowledge (#227).
 - `mex graph refresh` is faster on large repositories, with the same graph. An edit that leaves a file's declaration signature unchanged (its emitted `.d.ts`, comments excluded and union members in one order) no longer re-extracts the files that import it: each capture records the signature of every file it imports as its own compiler project saw it, importers are captured again only in a project that now sees a different signature, and their stored locations in the edited file are moved to where the same nodes are now declared. Compiler projects share module and library resolution, file-existence answers and reads of installed dependencies, so a repository with many `tsconfig` files resolves each import once. Within one refresh or rebuild each unchanged source file is read once, each corpus walk runs once while every directory it listed keeps its identity, the database is hashed once per identity, and staged sources stay in memory up to 64 MB instead of being copied to disk; any file, directory or database whose device, inode, size, modification or change time moved is read again. A refresh with nothing to publish now also returns early on a graph whose only fault is partially parsed files, and records the audit its inspection ran. The fingerprint and LSH audit of a delta publication checks the rewritten files' fingerprints bucket by bucket and the store's bucket total, since the rest of the copy is the audited store's bytes; every other invariant is still checked across the whole store. On a Windows benchmark of 11 repositories a one-file edit refreshed 2–3× faster (Hono 35 → 12 s, Django 65 → 32 s, NestJS 81 → 33 s) and a no-change refresh up to 5× faster (Django 47 → 9 s), while every incremental replay (16 single commits, 80 commits, one 80-commit jump) still matched a clean build exactly and clean builds were byte-identical to before. The extraction cache format changes, so the first refresh after upgrading re-extracts the corpus once. The accepted costs: a full build emits a declaration file for each file's dependencies, and a refresh holds up to 64 MB of source text in memory (#209).
 - Grounding fingerprints committed to Markdown are about 3.5× shorter. They were written as `mh:64:<hex>`, the hex of their JSON, and took a quarter to two fifths of a populated scaffold's bytes, which every agent reading a grounded file paid for in tokens. They are now written as `mh2:64:<base64url>`: the token count, the 64 MinHash values and each neighbour id as bytes. The encoding is lossless, so reconciliation compares exactly what it did before. Across 121 fingerprints in five populated scaffolds the average fell from 1,751 to 497 characters; re-encoding a populated Hono scaffold shrank it from 137 KB to 102 KB, with fingerprints going from 35% to 13% of it, while `mex check`, `wiki validate` and rename reconciliation on a clean rebuild reported exactly what they did before. Committed `mh:` fingerprints keep working and are compared by value, so upgrading does not make any grounding read as changed, require a review, or rewrite a file; an entry is re-encoded only when its file's groundings are being rewritten anyway (#233).
 - `mex graph scope` is up to 21× faster on codebases with large type signatures, with byte-identical output. Matching a query against a node re-split its name, qualified name, signature and docstring into identifiers once per query term and once per concept, and a TypeScript signature is the checker's full type text, which on a generic-heavy codebase runs to hundreds of kilobytes. Each node's identifiers are now computed once and reused while its text is unchanged, and identifiers repeated across signatures are split once. On Hono the six evaluation Scope queries went from a 79 s median (35–87 s) to 3.7 s (3.4–4.5 s); on mex the eleven went from 4.7 s to 4.0 s. Every response matched the previous one byte for byte (#234).
-- A grounded function edited only in its comments no longer raises `GROUNDING_DRIFT`. `bodyHash` still decides whether a body changed; a new optional `codeHash`, committed beside it, hashes the node's code tokens with comments set aside, read by the file's own tree-sitter grammar for every supported language. When the body changed but its code did not, `mex check` reports the unscored info notice `GROUNDING_COMMENT_DRIFT`, and `mex sync` offers the explicit grounding review — old and new code, default no — instead of an AI session; accepting renews both hashes. Whitespace-only reformatting was already not drift. String contents and Python docstrings are code, so editing them is still drift. Anything uncertain keeps the warning: a parse error inside the node, a language without a grammar, or a baseline whose comment-free hash is unknown. A grounding committed before `codeHash` falls back to the graph's cached old body when that cache holds the committed baseline. Capture writes `codeHash` only while `bodyHash` describes the current code, bound to it as `ch1:<first 12 hex of bodyHash>:<hash>`; a code hash left beside a `bodyHash` it was not captured with, as an older version's accepted review or a hand edit leaves it, is ignored. The first capture after upgrading adds `codeHash` to every grounding that is not drifted (#236).
+- Groundings can carry an optional `codeHash` bound to their committed `bodyHash`, so comment-only changes can be distinguished from code changes without silently accepting a new baseline. The shared Wiki verdict treats proven comment-only and formatting-only changes as fresh; `mex check` can still report an unscored informational notice when the recorded body differs. Uncertain comparisons remain flagged, and accepting a new baseline still requires explicit review. String contents and Python docstrings remain code (#236).
 - `STALE_FILE` no longer counts every repository commit. Its commit signal now counts only commits made since the file last changed that touched a path the file references: its path claims, and the files of the code it grounds (committed `file`, else the node's file in the graph, plus inline `mex://` anchors). A scaffold file that references no paths is judged by its age and `last_updated` alone. Paths that are scaffold knowledge, URLs, and anything that would match the whole repository are not counted. `SETUP.md`, `SYNC.md`, `patterns/README.md` and `patterns/INDEX.md` are text mex ships, kept current by `mex pattern add` and the index-sync check, so they are no longer reported. On mex's own scaffold, `STALE_FILE` findings fell from 16 to 1. The previous counts ran from 50 to 289 commits, and the same files now count 0 to 6 commits to their referenced paths. The day and commit thresholds are unchanged (#237).
 
 ### Fixed
-- The Wiki commands now use the code graph. `mex wiki validate` always reported `codeGraphAvailable: false` and resolved no grounding, `mex wiki rebuild-index` stored no grounding health, so `--health changed` matched nothing, `mex wiki migrate` never backfilled a `bodyHash`, and `mex wiki apply` could not ground. All of this happened silently, even in a checkout with a fresh `graph.db`. `validate`, `rebuild-index`, `migrate`, `apply` and `regenerate-views` now reach the graph the way the Project Hub does: through one read-only snapshot per command, proved fresh again before anything derived from it is reported. `rebuild-index` publishes its health only after that proof. A graph that is stale, incompatible, corrupt or changing during the pass is not used; the command does its work without it and adds the info notice `CODE_GRAPH_UNAVAILABLE`, which says why and names `mex graph`. A checkout with no graph stays as quiet as before. Three resolution faults that the missing graph had hidden are fixed with it:
-  - Migration's backfill now writes the body hash the grounding was made against: the baseline `mex ground` cached when its fingerprint is the committed one, otherwise the current body only while the fingerprint still matches, otherwise none. It no longer adopts code that may have drifted.
-  - A grounding whose node is reached through a re-minted id (#240), or rebound after a move, is fresh when its body is byte-identical.
-  - A grounding with no `bodyHash` is judged by its code tokens, not by the ids of its callers and callees.
-
-  On a populated Hono scaffold, `wiki validate` and the index went from resolving nothing to the same verdicts as `mex check`: 7 groundings fresh, and both groundings of an edited method changed. Without the last two fixes, 2 entities there and 3 on a second scaffold built before #240 read changed with their code unchanged (#232).
+- Returning from terminal setup's manual prompt or Hub link view no longer hangs on Windows. A short-lived child process now waits for Enter on the inherited terminal, as the native agent handoff does, so MEX never reads the console between HUD mounts. Before, Enter left the HUD without input, and neither Ctrl+C nor another Enter released the process.
+- `mex check` now checks groundings when the graph's only fault is an incompletely parsed file. Before, one unparseable fixture skipped every grounding and still scored 100. Links in fully parsed files now get the same verdicts as on a fresh graph. A link into a partially parsed file, or to a node the graph lacks, is `GROUNDING_UNVERIFIED` and names the files to fix or exclude. Nothing is reconciled across the parse gap, and configuration drift still skips grounding.
+- `mex check` discovers `package.json` and `pyproject.toml` manifests at any depth, ignoring `node_modules` and `.git`, and the root manifest keeps precedence (#250). Yarn and pnpm built-in commands are no longer reported as `DEAD_COMMAND`, and `patterns/INDEX.md` frontmatter edges count toward index synchronization (#203, #251).
+- Terminal setup releases stdin when the HUD closes, including after showing a copyable Hub link. Finish later reports a paused outcome after an agent failure; the final message reflects a commit completed in the browser. Earlier migration warnings remain in bounded scrollable details, narrow footers retain their controls, and graph diagnostics distinguish worker failures from MEX's cleanup signal.
+- Wiki grounding can verify exact nodes in fully parsed files when an unrelated file has an incomplete parse. Facts from partial files remain unverified with named remediation, missing targets are not reconciled against incomplete evidence, and source/configuration drift still blocks grounding. A stable incomplete graph no longer produces a false concurrent-change error.
+- Expected setup failures retain authored recovery instructions for configuration, ignore protection, integrations, Graph, grounding, and Wiki. Graph worker failures distinguish startup/build deadlines, exit status, signals, and proven Node heap exhaustion, retaining bounded terminal diagnostics while the browser receives safe messages. Unexpected exceptions keep the generic browser fallback.
+- Native terminal handoff restores input ownership and terminal modes on return, separates incomplete/failed/cancelled agent exits, and cleans up owned child processes and private prompts. Setup cancellation and non-interactive runs have explicit exit outcomes instead of silently appearing successful.
+- Checking or completing setup without retained population output no longer creates a phantom background session or empty transcript panel. Terminal-finalized projects can proceed through browser commit review and completion without starting an agent.
+- CLI discovery verifies MEX's identity instead of trusting an unrelated executable named `mex` on PATH (#223, #262).
+- Hub groups repeated Wiki diagnostics with expandable details, reports unchecked query health honestly, and uses the same relevance ordering and live fact-aware grounding verdicts as CLI queries.
+- Graph class properties and fields now receive body hashes and fingerprints for grounding. Fact anchors are stricter so a nearby-change verdict does not hide a change to the fact's own dependencies; graph grammars are loaded before grounding publication as well as ordinary construction.
+- Wiki maintenance commands that need code evidence (`rebuild-index`, `migrate`, `apply`, `reground`, and `regenerate-views`) use a fresh read-only graph snapshot and revalidate it before reporting or publishing derived results. Stale, incompatible, corrupt, or changing graphs are not used; commands that can proceed without them report `CODE_GRAPH_UNAVAILABLE`. Migration backfills the recorded grounding baseline rather than accepting drifted current code; byte-identical rebound bodies stay fresh, and links without `bodyHash` are judged by code tokens rather than caller/callee ids. `wiki validate` is now explicitly structure-only; grounding checks belong to `mex check` (#232).
 - `mex wiki query` now answers natural-language questions. It ANDed every word of the query, stop words included, so "Why does Hono avoid runtime dependencies?" required `why`, `does` and `avoid` and found nothing, although an entity titled *Zero runtime dependencies, Web Standards only* exists. Stop words and question words are now dropped before the every-term search, which otherwise works as before. The rest of the page is filled with entities matching some of the terms, ranked by how much of the query they cover (each term's inverse document frequency, weighted by title, summary or body) and found through a conservative stem, so `dependencies` meets `dependency`. Such an entity needs at least two distinctive terms, and a term found in most of the wiki, usually the project's own name, does not count as one. Within a field, hits are now ordered by relevance (FTS5 `bm25`) after lifecycle and health rather than by title, so the entity most about the words comes first; title still breaks ties. Each hit carries `match` (`all_terms` or `some_terms`) and, for a broader hit, `matchedTerms`; the result carries `terms`, `ignoredTerms` and `unmatchedTerms`. A broader answer adds the info notice `WIKI_QUERY_PARTIAL_MATCH`, and an empty one adds `WIKI_QUERY_NO_MATCH`, which names the terms nothing mentions and suggests keywords, `ROUTER.md` or `mex graph scope` instead of leaving a bare empty list; neither changes the exit code. Hub search uses the same plan and order, with every all-terms hit ahead of the broader ones. On the two evaluation scaffolds, with their unindexed knowledge adopted (#227), natural-language hit@5 went from 0.00 to 0.92 (Hono) and 0.77 (mex), keyword hit@5 to 1.00 on both, keyword hit@1 from 0.50 to 0.75 and from 0.69 to 0.85, exact titles stayed at 1.00, and all six off-topic evaluation queries still return nothing. Of 24 further off-topic questions, 6 return broader hits, each labelled with the terms it matched and the terms nothing does (#235).
 - A refresh that must extract every TypeScript and JavaScript file in full no longer mis-indexes files outside every `tsconfig`. When such a change reached the program built for them (for example a new plain script, whose declarations the other files can see), the signal to extract in full was taken for a crashed program, and every one of those files was indexed by the fallback parser with different node ids and edges until the next rebuild. On FastAPI, a jump over 80 commits that added one documentation script left 48 nodes and 78 edges different from a clean build; it now matches exactly (#209).
 - `mex check` no longer reports two false positives seen on clean scaffolds. A brace-expanded script name such as `bun run test:{node,workerd}` is expanded and each script it names is checked against `package.json`; a name that still holds braces after expansion is a placeholder and is skipped, as is one naming more than 64 scripts. A command written in code inside a dependency entry, such as `` **`bun test` / `deno test`** ``, is no longer claimed as a dependency, since a package name never contains whitespace (#231).
 
 ### Compatibility
 
-- `CODE_GRAPH_UNAVAILABLE` is a new Wiki diagnostic code, at info severity. `wiki validate` can now report `GROUNDING_STALE`, `GROUNDING_MISSING` and `GROUNDING_UNRESOLVED` on scaffolds where it reported none, all at warning severity, so its exit status is unchanged. The index and graph schemas are unchanged; run `mex wiki rebuild-index` once to record health in an existing index (#232).
+- `CODE_GRAPH_UNAVAILABLE` is an informational Wiki diagnostic for commands that require graph evidence; `wiki validate` no longer serves as a code-link health gate. Use `mex check` for that purpose, and run `mex wiki rebuild-index` after refreshing the graph to update existing indexed health. Graph schema remains v4; Wiki and canonical Relay artifact versions remain unchanged.
 - Earlier MEX versions cannot read `mh2:` fingerprints. On a Hono scaffold re-encoded to `mh2:`, 0.8.3 reported 10 groundings it could not reconcile as `GROUNDING_GONE`, and its Wiki rejected 11 groundings as malformed and 5 entities as unparseable, breaking 3 relations; capture also treats such a grounding as changed and asks for a review. Upgrade everyone who shares a scaffold before anyone commits new groundings. Graph and Wiki index schemas are unchanged (#233).
 - A root `type` key is optional and additive. Earlier versions ignore it and leave the file outside the Wiki as before; once migrated it is an ordinary `mex.type`. Adoption may now remove a root `type` key, alongside `grounds_to` and `topics`. `KNOWLEDGE_NOT_ADOPTED` and `KNOWLEDGE_UNTYPED` are new `IssueCode` values and new Wiki diagnostic codes. Graph and Wiki index schemas are unchanged (#227).
 - `codeHash` is an optional, additive `grounds_to` field; graph and Wiki index schemas are unchanged. Earlier versions read scaffolds that carry it, ignore it, and report every changed body as `GROUNDING_DRIFT` as before. `GROUNDING_COMMENT_DRIFT` is a new `IssueCode` value (#236).
 
+- Public `DriftIssue` adds optional `entity` and `verdict` fields. `IssueCode` adds `GROUNDING_COMMENT_DRIFT`, `GROUNDING_NEARBY_DRIFT`, `GROUNDING_NO_BASELINE`, `GROUNDING_MOVED`, `KNOWLEDGE_NOT_ADOPTED`, and `KNOWLEDGE_UNTYPED`. No package-root export or required argument is removed. The maintainer-selected 0.8.4 release is a scoped exception to the usual minor-version rule for additive public fields; see [Compatibility](COMPATIBILITY.md#upgrading-to-084).
+
+### Known limitations
+
+- Dependency-rich TypeScript/JavaScript graph builds can still exhaust Node's heap. A disposable MEX copy reproduced this with installed dependencies, and compiler-only extraction reproduced it before database writes. Better progress, diagnostics, and process isolation do not fix the underlying memory pressure.
+- Browser completion readiness still relies on limited placeholder/index-presence checks after restart; a failed final validation can be followed by a commit-ready screen. Oversized population prompts can also exceed the Hub run-response contract. These remain follow-up work; this release does not establish that every setup path completes reliably.
+
 ## [0.8.3] - 2026-09-28
 
 ### Added
diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md
index 61768bb8..81b36b2f 100644
--- a/COMPATIBILITY.md
+++ b/COMPATIBILITY.md
@@ -52,6 +52,104 @@ shipping new versions.
 If you only use the `mex` CLI, most of this still applies, but CLI flags
 themselves are best-effort (see [CLI surface](#cli-surface) below).
 
+## Upgrading to 0.8.4
+
+Release preparation is dated October 9, 2026; 0.8.4 remains unpublished until
+merge, tagging, and publication. The commands below apply once it is available.
+
+**Upgrade everyone sharing a scaffold before committing new groundings.**
+0.8.4 writes lossless `mh2:` fingerprints; 0.8.3 and earlier cannot read them and
+can report false missing or malformed grounding. Existing `mh:` fingerprints
+remain supported, compare by value, and are not rewritten by ordinary reads.
+`mex graph compact-fingerprints --dry-run` previews an optional explicit
+conversion; apply it only after the team's clients have been upgraded. Graph
+schema remains v4; Wiki and canonical Relay artifact versions are unchanged.
+
+Install `mex-agent@0.8.4`, preserve the existing graph, then run:
+
+```bash
+mex graph refresh
+mex check
+mex sync
+mex wiki rebuild-index
+```
+
+The internal extraction-cache format changes, so the first refresh re-extracts
+the corpus once. Later refreshes can reuse unchanged captures and avoid
+re-extracting importers whose dependency declaration signatures did not change.
+Do not delete or rebuild a working old graph as the first upgrade step. Projects
+upgrading from before 0.8.3 must also retain that graph for the TypeScript node-ID
+transition described [below](#upgrading-to-083). A fresh clone without it relies
+on committed fingerprint reconciliation and may require manual re-grounding.
+For an incompatible or damaged store, follow `mex graph status`'s explicit
+recovery action.
+
+`mex check` now supplies the code-link verdicts shared with Wiki queries and Hub.
+`mex wiki validate` checks structure and is not a replacement code-link health
+gate. Proven comment-only and formatting-only changes remain fresh; changes
+away from the named fact can report `changed-nearby`. Missing, ambiguous, or
+unverified links still require attention. Review sync's decisions and the
+scaffold diff before committing through Git. `mex wiki reground <id>` previews
+re-recording a reviewed entity's links; `--apply` authorizes that write.
+Ordinary reads never accept a new grounding baseline.
+
+Graph-aware Wiki maintenance uses a fresh snapshot and revalidates it before
+publishing derived results. Where a command can continue without graph evidence,
+it reports `CODE_GRAPH_UNAVAILABLE`; that is not a successful code-link check.
+Rebuild the local Wiki index after graph/scaffold maintenance to refresh its
+stored health. Use `mex wiki migrate --dry-run` to review newly adoptable
+`context/stack.md`, patterns, and explicitly typed domain files before running
+`mex wiki migrate`. Untyped unknown context files stay outside the Wiki and are
+reported for review. No update or ordinary Hub read migrates those files for you.
+
+For managed integrations, run `mex skills sync --dry-run`, resolve conflicts,
+then `mex skills sync` and start a new agent session. Do not overlay standalone
+skill installs on MEX-managed integrations. An already completed setup does not
+need setup again solely to upgrade.
+
+### Setup entry-point change
+
+`mex setup` opens the terminal HUD by default; `--cli` remains supported.
+`mex setup --browser` explicitly selects browser setup and cannot be combined
+with terminal-only `--cli`, `--tool`, `--yes`, or `--dry-run`. Bare `mex` chooses
+terminal setup for an incomplete project and Hub for an established code
+project. `mex hub` explicitly opens the browser; `mex tui` retains the terminal
+dashboard. `--port` and `--no-open` also control the finishing Hub launched by
+interactive terminal setup.
+
+Use `--yes` and repeatable `--tool` flags (or `--tool none`) for automation.
+Piped input/output and CI also use plain output and never start an agent or a
+long-lived Hub. Exit codes are `0` for completed preparation/successful dry run,
+`2` for pending population, `1` for failure, and `130`/`143` for interruption.
+Scripts needing browser setup must select `--browser` explicitly.
+
+### Additive API changes in 0.8.4
+
+No package-root export or required argument is removed. `DriftIssue` adds the
+optional `entity` (`id`, `title`) and `verdict` fields. `IssueCode` adds
+`GROUNDING_COMMENT_DRIFT`, `GROUNDING_NEARBY_DRIFT`, `GROUNDING_NO_BASELINE`,
+`GROUNDING_MOVED`, `KNOWLEDGE_NOT_ADOPTED`, and `KNOWLEDGE_UNTYPED`. Consumers
+that handle codes exhaustively should add these cases. Frontmatter grounding
+entries can carry optional `codeHash` alongside `bodyHash`; old clients ignore
+that field, but still cannot read the new `mh2:` fingerprint encoding.
+
+The maintainer explicitly selected 0.8.4 for these changes. As with 0.8.3, this
+is a scoped exception to the usual minor-version rule for additive public fields;
+the general versioning policy below is unchanged.
+
+### Remaining setup and graph limits
+
+Dependency-rich TypeScript/JavaScript graph builds can still exhaust Node's
+heap during compiler extraction. File count alone does not bound resolved type
+complexity. Worker isolation and diagnostics do not lower the required peak
+memory or guarantee a successful build.
+
+Browser completion readiness still relies on limited placeholder/index-presence
+checks after restart; a failed final validation can subsequently appear
+commit-ready. Oversized population prompts can exceed the Hub run-response
+contract. Neither issue is resolved by the terminal redesign. Review the actual
+scaffold and run code-link/structure checks before treating setup as verified.
+
 ## Upgrading to 0.8.3
 
 Install `mex-agent@0.8.3`. In a project with an existing code graph, keep that
@@ -218,9 +316,9 @@ grounds_to:
     fingerprint: "mh2:64:AXbN..."
 ```
 
-Fingerprints are written as `mh2:64:<base64url>`. Scaffolds committed before #233 hold `mh:64:<hex>`; both are read and compared by value, and an older entry is re-encoded only when its file's groundings are rewritten. `mex graph compact-fingerprints` re-encodes them all in one explicit pass (`--dry-run` writes nothing). Versions before #233 cannot read `mh2:`, so everyone sharing a scaffold should upgrade before new groundings are committed.
+Fingerprints are written as `mh2:64:<base64url>`. Scaffolds committed before #233 hold `mh:64:<hex>`; both are read and compared by value, and an older entry is re-encoded only when its file's groundings are rewritten. `mex graph compact-fingerprints` re-encodes them all in one explicit pass (`--dry-run` writes nothing). MEX 0.8.3 and earlier cannot read `mh2:`, so everyone sharing a scaffold should upgrade to 0.8.4 before new groundings are committed.
 
-An entry may also carry `bodyHash`, the hash of the node's body when it was grounded, and `codeHash`, the hash of that body's code with comments set aside, bound to the `bodyHash` it was captured with (#236). Capture writes both; neither is hand-written. When only `bodyHash` differs from the current code, `mex check` reports the info notice `GROUNDING_COMMENT_DRIFT` instead of `GROUNDING_DRIFT`.
+An entry may also carry `bodyHash`, the hash of the node's body when it was grounded, and `codeHash`, the hash of that body's code with comments set aside, bound to the `bodyHash` it was captured with (#236). Capture writes both; neither is hand-written. When the recorded body differs but its bound code hash proves the code unchanged, the shared verdict remains fresh and `mex check` can report the informational `GROUNDING_COMMENT_DRIFT` notice. Uncertain comparisons remain flagged; reads never renew the baseline.
 
 Files without `grounds_to` retain their previous behavior. The graph database and grounding baselines under `.mex/` are internal mex data and should not be edited directly.
 
diff --git a/README.es.md b/README.es.md
index f33f3283..951f6d1d 100644
--- a/README.es.md
+++ b/README.es.md
@@ -15,10 +15,10 @@ MEX mantiene la arquitectura, las decisiones, los requisitos y los traspasos de
 [![Estrellas en GitHub](https://img.shields.io/github/stars/mex-memory/mex?style=flat)](https://github.com/mex-memory/mex/stargazers)
 [![Sitio web](https://img.shields.io/badge/website-mexmemory.com-4f7cff)](https://mexmemory.com)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FEdNsQ4Qt4)
-[![Licencia: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.0/LICENSE)
+[![Licencia: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.4/LICENSE)
 [![CI](https://github.com/mex-memory/mex/actions/workflows/ci.yml/badge.svg)](https://github.com/mex-memory/mex/actions/workflows/ci.yml)
-[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
+[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
 [![Memoria para agentes](https://img.shields.io/badge/agent%20memory-compatible-6f8cff)](#agent-memory-mode)
 [![MCP: solo código fuente](https://img.shields.io/badge/MCP-source%20only-6f8cff)](#mcp-server)
 
@@ -26,7 +26,7 @@ MEX mantiene la arquitectura, las decisiones, los requisitos y los traspasos de
 
 </div>
 
-> La descripción principal de esta traducción sigue correspondiendo a 0.8.0. Los comandos de instalación y las indicaciones de actualización se han ajustado para 0.8.3; los cambios de producto se documentan en el [README en inglés](README.md) y en las [notas de la versión 0.8.3](RELEASE_NOTES.md).
+> La descripción principal de esta traducción sigue correspondiendo a 0.8.0. La configuración, los comandos de instalación y las indicaciones de actualización se han ajustado para 0.8.4; los demás cambios de producto se documentan en el [README en inglés](README.md) y en las [notas de la versión 0.8.4](RELEASE_NOTES.md).
 
 ---
 
@@ -35,7 +35,7 @@ Una persona del equipo sabe por qué existe una restricción. Otra conoce el his
 **Lo que un ingeniero y su agente aprenden debería convertirse en contexto que el siguiente compañero pueda aprovechar.** MEX le da a ese conocimiento un lugar duradero en el repositorio: Markdown legible, explicaciones vinculadas al código, propuestas de Spec revisadas y traspasos estructurados. Las personas lo exploran y revisan en un Hub local; los agentes lo recuperan y ayudan a mantenerlo mediante las instrucciones del proyecto y la CLI.
 
 > [!IMPORTANT]
-> **[MEX 0.8](https://github.com/mex-memory/mex/releases/tag/v0.8.0) amplía la memoria de los agentes para convertirla en memoria del equipo:** un Project Hub local, una Wiki estructurada y flujos de trabajo de equipo, Specs con aprobación explícita, Members, Workstreams, Relays, Activity y habilidades (skills) oficiales para Claude Code/Codex, todo conectado con el sistema existente de Code Graph, vinculación al código y detección de divergencias.
+> **[MEX 0.8.4](RELEASE_NOTES.md) inicia la configuración en un nuevo HUD de terminal**, cede la terminal a tu agente y termina con la revisión en Hub. Los errores de configuración conservan las instrucciones para recuperarse. También acelera las consultas y la actualización del Graph y reduce las huellas de grounding; [actualiza a todo el equipo antes de compartir el nuevo formato](#upgrade-and-compatibility).
 
 💬 **Únete a la comunidad de MEX en Discord** — conversa sobre ideas, pide ayuda, comparte tus comentarios y muestra lo que estás creando.
 
@@ -102,14 +102,18 @@ MEX requiere **Node.js 22.5 o posterior** y un repositorio Git. El flujo habitua
 Ejecuta lo siguiente desde la raíz del repositorio:
 
 ```bash
-npx mex-agent@0.8.3 setup
+npx mex-agent@0.8.4 setup
 ```
 
-El comando abre la configuración en el navegador local. Elige las herramientas de IA, crea el scaffold y los índices y deja que una CLI disponible de Claude Code o Codex complete la memoria. Si el agente no está disponible o falla, copia el prompt y continúa después de completarlo manualmente. Las instrucciones existentes se conservan; las indicaciones de integración manual no bloquean la configuración.
+El comando abre un HUD de terminal con un nuevo banner ASCII `mex` en cian. Usa las flechas para resaltar una herramienta y Enter para seleccionarla y comenzar; Espacio permite marcar integraciones adicionales. La fila Continue inicia con las opciones marcadas o sin agente. Las tareas largas muestran actividad animada, tiempo transcurrido y el trabajo más reciente; el análisis del Graph muestra recuentos reales de archivos. Si está disponible una CLI seleccionada de Claude Code o Codex, su sesión interactiva toma la terminal; sal de esa sesión para volver a MEX. MEX comprueba el scaffold antes de continuar y ofrece reintentar, completar manualmente o dejarlo para después si falta contenido. Se conservan las instrucciones existentes.
 
-Revisa el diff exacto en el Hub y elige **Commit setup** para crear un commit local; también puedes usar el punto de control manual de Git. La pantalla final explica cómo abrir una sesión nueva y verificar la memoria. Ofrece instalar globalmente la versión que está ejecutándose y, de forma opcional, dejar un correo y un nombre opcional. Web3Forms recibe estos datos en el formulario integrado; no entran en el repositorio ni en la telemetría. El equipo solo guarda si enviaste u omitiste la invitación. Elige **Open Hub** para abrir el Hub completo y su recorrido inicial.
+Tras la validación, se abre Hub para terminar. Revisa el diff exacto y elige **Commit setup** para crear un commit local; también puedes usar el punto de control manual de Git. MEX conserva los cambios ajenos ya preparados y nunca hace push ni pull. La pantalla final explica cómo abrir una sesión nueva y verificar la memoria. Ofrece instalar globalmente la versión que está ejecutándose y, de forma opcional, dejar un correo y un nombre opcional. Web3Forms recibe estos datos en el formulario integrado; no entran en el repositorio ni en la telemetría. El equipo solo guarda si enviaste u omitiste la invitación. Elige **Open Hub** para abrir el Hub completo y su recorrido inicial.
 
-Para usar la terminal o SSH: `npx mex-agent@0.8.3 setup --cli`. `setup --dry-run` sigue siendo una vista previa de terminal sin cambios; `--no-open` imprime el enlace y `--port <n>` elige el puerto local. Tras instalar, `mex` abre Hub o la configuración y `mex tui` abre el panel de terminal. Los agentes tienen sus propios requisitos de instalación, cuenta y red.
+Mantén la terminal abierta mientras usas Hub; `q` o Ctrl+C lo detienen. `--no-open` muestra el enlace final sin abrir el navegador y `--port <n>` elige el puerto local. Pulsa `d` para ver más detalles del estado o del error. Los errores previstos incluyen instrucciones concretas de recuperación, por ejemplo para corregir una configuración mal formada o una regla de Git que oculta el scaffold. Los agentes tienen sus propios requisitos de instalación, cuenta y red.
+
+Para configurar desde el navegador, usa `npx mex-agent@0.8.4 setup --browser`; ejecuta el mismo motor con un agente en segundo plano y la alternativa de completar la memoria manualmente. `--browser --no-open` imprime el enlace sin abrirlo. `--cli` sigue siendo un alias del flujo de terminal predeterminado.
+
+Para scripts, usa `--yes` y `--tool <name>` (repetible), o `--tool none`. CI y la entrada o salida redirigida también usan texto sin interacción: reutilizan las opciones guardadas, no seleccionan integraciones si no hay ninguna guardada y no inician agentes ni navegadores. Los códigos de salida son `0` para preparación o vista previa completada, `2` si falta completar la memoria, `1` para errores y `130`/`143` para interrupciones. `mex setup --dry-run` no modifica archivos. Tras instalar, `mex` abre Hub en un proyecto de código establecido o la configuración de terminal en uno incompleto; `mex hub` abre el navegador explícitamente y `mex tui` abre el panel de terminal.
 
 ![Tres pasos para dejar listo el proyecto: ejecutar la configuración, poblar la memoria y después revisar y guardar el punto de control con un commit antes de abrir Hub.](docs/diagrams/readme/setup.svg)
 
@@ -125,9 +129,9 @@ Comparte el commit de configuración revisado mediante un push siguiendo el fluj
 Clona el repositorio y la rama del equipo, o actualízalos con un pull de Git. Si la configuración de 0.8 está completa y guardada en un commit, construye los índices derivados en tu propia copia de trabajo y abre Hub:
 
 ```bash
-npx mex-agent@0.8.3 graph rebuild
-npx mex-agent@0.8.3 wiki rebuild-index
-npx mex-agent@0.8.3 hub
+npx mex-agent@0.8.4 graph rebuild
+npx mex-agent@0.8.4 wiki rebuild-index
+npx mex-agent@0.8.4 hub
 ```
 
 Reutiliza la memoria compartida del proyecto; no la regeneres solo para incorporarte. En Team/Members, comprueba la identidad efectiva y, si hace falta, selecciona tu registro de Member existente para establecerla localmente. Si aún no tienes un registro, créalo explícitamente mediante el flujo con revisión y comparte sus archivos canónicos. Members sirve para atribuir contribuciones, no es un sistema de inicio de sesión ni de permisos.
@@ -140,7 +144,7 @@ Para configuraciones antiguas o incompletas, sigue primero las instrucciones de
 <summary><strong>¿Prefieres una instalación global?</strong></summary>
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex setup
 ```
 
@@ -155,14 +159,14 @@ La instalación global opcional, tanto en Hub como en la terminal, fija la versi
 <summary><strong>¿Usas MEX para un agente operativo persistente?</strong></summary>
 
 ```bash
-npx mex-agent@0.8.3 setup --mode agent-memory
+npx mex-agent@0.8.4 setup --mode agent-memory
 ```
 
 Esta plantilla independiente aplica el modelo de enrutamiento y mantenimiento de MEX a laboratorios domésticos, infraestructura y espacios de trabajo de agentes de larga duración. Añade un contrato `HEARTBEAT.md` y convenciones de limpieza; el flujo de Code Graph, Wiki y Hub de equipo descrito en este README corresponde al modo predeterminado `code-repo`.
 
 </details>
 
-Los ejemplos usan `mex` para facilitar la lectura. Instálalo globalmente como se indica arriba o sustitúyelo por `npx mex-agent@0.8.3`.
+Los ejemplos usan `mex` para facilitar la lectura. Instálalo globalmente como se indica arriba o sustitúyelo por `npx mex-agent@0.8.4`.
 
 <a id="how-mex-works"></a>
 
@@ -264,7 +268,7 @@ El flujo de Inbox sujeto a aprobación se aplica a propuestas de la familia Spec
 <details>
 <summary><strong>Servidor MCP — solo código fuente</strong></summary>
 
-El repositorio incluye un [workspace MCP](https://github.com/mex-memory/mex/tree/v0.8.0/packages/mex-mcp) para desarrollo local. No se publica con MEX 0.8; la interfaz publicada para agentes es la CLI `mex-agent`, junto con sus instrucciones de proyecto y skills.
+El repositorio incluye un [workspace MCP](https://github.com/mex-memory/mex/tree/v0.8.4/packages/mex-mcp) para desarrollo local. No se publica con MEX 0.8; la interfaz publicada para agentes es la CLI `mex-agent`, junto con sus instrucciones de proyecto y skills.
 
 </details>
 
@@ -350,14 +354,19 @@ Usa `mex capabilities --json` para descubrir las capacidades en un formato legib
 Para una instalación global, actualiza la CLI y las copias de las skills seleccionadas de Claude Code/Codex:
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex skills sync --dry-run
 mex skills sync
 ```
 
-Si ya completaste la configuración con 0.8.0, estos comandos actualizan las skills y las instrucciones administradas del agente; no hace falta volver a ejecutar setup solo por actualizar el paquete. Revisa los conflictos que se indiquen con instrucciones editadas localmente y después inicia una nueva sesión del agente.
+Si ya completaste la configuración con 0.8.0–0.8.3, estos comandos actualizan las skills y las instrucciones administradas del agente; no hace falta volver a ejecutar setup solo por actualizar el paquete. Revisa los conflictos que se indiquen con instrucciones editadas localmente y después inicia una nueva sesión del agente.
+
+> [!WARNING]
+> **Actualiza a todos los que comparten el scaffold a 0.8.4 antes de hacer commit de groundings nuevos o modificados.** Las huellas compactas `mh2:` no pueden leerse en versiones anteriores, incluida 0.8.3. Las huellas `mh:` existentes siguen siendo válidas; actualizar el paquete no reescribe archivos ni cambia su significado.
+
+Los esquemas de los índices Graph y Wiki no cambian. La primera ejecución de `mex graph refresh` vuelve a extraer el código una vez para la nueva caché. Para convertir las huellas existentes de una vez, revisa `mex graph compact-fingerprints --dry-run`, ejecuta `mex graph compact-fingerprints` y revisa el diff antes de hacer commit. Consulta [cómo actualizar a 0.8.4](COMPATIBILITY.md#upgrading-to-084).
 
-**Al actualizar a 0.8.3, conserva el Graph existente.** Ejecuta `mex graph refresh` y después `mex sync`: la primera actualización realiza una extracción completa y puede cambiar los identificadores de TypeScript. Revisa los casos ambiguos o ausentes y confirma los cambios del scaffold mediante Git. Si cambia el scaffold, actualiza el índice Wiki con `mex wiki rebuild-index`. Un clon nuevo o una reconstrucción sin el Graph anterior depende de las huellas guardadas y puede requerir volver a vincular código manualmente. Consulta la [guía de compatibilidad](COMPATIBILITY.md#upgrading-to-083).
+**Si vienes de 0.8.2 o una versión anterior, conserva el Graph existente.** Los cambios de identidad de TypeScript introducidos en 0.8.3 pueden cambiar los identificadores. Ejecuta `mex graph refresh` y después `mex sync` para conservar la correspondencia con los antiguos. Revisa los casos ambiguos o ausentes y confirma los cambios del scaffold mediante Git. Si cambia el scaffold, actualiza el índice Wiki con `mex wiki rebuild-index`. Un clon nuevo o una reconstrucción sin el Graph anterior depende de las huellas guardadas y puede requerir volver a vincular código manualmente. Consulta los [pasos de migración de 0.8.3](COMPATIBILITY.md#upgrading-to-083).
 
 Actualizar el paquete y las skills no basta para que un repositorio antiguo o incompleto esté listo para Hub. Para esos repositorios, evalúa setup con una ejecución de prueba antes de aplicarlo; setup conserva los archivos existentes y sigue requiriendo la revisión de sus cambios:
 
@@ -417,10 +426,10 @@ MEX mantiene la memoria del equipo en archivos del repositorio y proporciona flu
 
 ## Más información
 
-- Lee las [notas de la versión MEX 0.8](https://github.com/mex-memory/mex/releases/tag/v0.8.0).
-- Consulta la [guía de entorno de ejecución y compatibilidad](https://github.com/mex-memory/mex/blob/v0.8.0/COMPATIBILITY.md) y la [política de seguridad](https://github.com/mex-memory/mex/blob/v0.8.0/SECURITY.md).
-- Revisa la [matriz de compatibilidad del Code Graph](https://github.com/mex-memory/mex/blob/v0.8.0/docs/code-graph-support.md).
-- Consulta el [modelo de extractores y las relaciones compatibles](https://github.com/mex-memory/mex/blob/v0.8.0/docs/extractors.md).
-- Lee los [resultados del benchmark de recuperación del Code Graph](https://github.com/mex-memory/mex/blob/v0.8.0/evaluate/RESULTS.md), incluida la comparación evaluada a ciegas frente a una búsqueda de archivos convencional.
+- Lee las [notas de la versión MEX 0.8.4](RELEASE_NOTES.md).
+- Consulta la [guía de entorno de ejecución y compatibilidad](https://github.com/mex-memory/mex/blob/v0.8.4/COMPATIBILITY.md) y la [política de seguridad](https://github.com/mex-memory/mex/blob/v0.8.4/SECURITY.md).
+- Revisa la [matriz de compatibilidad del Code Graph](https://github.com/mex-memory/mex/blob/v0.8.4/docs/code-graph-support.md).
+- Consulta el [modelo de extractores y las relaciones compatibles](https://github.com/mex-memory/mex/blob/v0.8.4/docs/extractors.md).
+- Lee los [resultados del benchmark de recuperación del Code Graph](https://github.com/mex-memory/mex/blob/v0.8.4/evaluate/RESULTS.md), incluida la comparación evaluada a ciegas frente a una búsqueda de archivos convencional.
 - Inspecciona la CLI localmente con `mex capabilities --json` y `mex commands`.
 - Únete a la [comunidad de MEX en Discord](https://discord.gg/FEdNsQ4Qt4) o visita [mexmemory.com](https://mexmemory.com).
diff --git a/README.md b/README.md
index 82031eca..53843f1c 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@
 **Shared project memory for engineers and their coding agents.**
 
 ```bash
-npx mex-agent@0.8.3 setup
+npx mex-agent@0.8.4 setup
 ```
 
 Setup includes the official Inbox and Relay skills for your selected Claude Code or Codex integration. [Standalone skill installation](#standalone-skill-installation) is an alternative for existing MEX projects.
@@ -20,10 +20,10 @@ MEX keeps your team's architecture, decisions, requirements, and handoffs alongs
 [![GitHub stars](https://img.shields.io/github/stars/mex-memory/mex?style=flat)](https://github.com/mex-memory/mex/stargazers)
 [![Website](https://img.shields.io/badge/website-mexmemory.com-4f7cff)](https://mexmemory.com)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FEdNsQ4Qt4)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.3/LICENSE)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.4/LICENSE)
 [![CI](https://github.com/mex-memory/mex/actions/workflows/ci.yml/badge.svg)](https://github.com/mex-memory/mex/actions/workflows/ci.yml)
-[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.3/package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.3/package.json)
+[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
 [![Agent memory](https://img.shields.io/badge/agent%20memory-compatible-6f8cff)](#agent-memory-mode)
 [![MCP: source only](https://img.shields.io/badge/MCP-source%20only-6f8cff)](#mcp-server)
 
@@ -38,7 +38,7 @@ One engineer knows why a constraint exists. Another has the debugging history. A
 **What one engineer and their agent learn should become context the next teammate can use.** MEX gives that knowledge a durable home in the repository: readable Markdown, code-linked explanations, reviewed knowledge contributions, and structured handoffs. People explore and review it in a local Hub; agents retrieve and help maintain it through project instructions and the CLI.
 
 > [!IMPORTANT]
-> **[MEX 0.8.3](RELEASE_NOTES.md) makes graph refresh incremental and grounding more reliable**, adds FastAPI, Flask, and NestJS routes, and brings scaffold export and Markdown timelines. Existing projects should follow the [graph upgrade steps](#upgrade-and-compatibility) to preserve TypeScript grounding links.
+> **[MEX 0.8.4](RELEASE_NOTES.md) starts setup in a new terminal HUD**, hands the terminal to your agent, and finishes with review in the Hub. Setup errors now keep their recovery guidance. The release also speeds up graph refresh and retrieval and writes smaller grounding fingerprints; [upgrade the whole team before sharing the new format](#upgrade-and-compatibility).
 
 💬 **Join the MEX community on Discord** — discuss ideas, get help, share feedback, and show what you're building.
 
@@ -96,24 +96,30 @@ MEX requires **Node.js 22.5 or newer**, SQLite FTS5 support in that Node build,
 Run from the repository root:
 
 ```bash
-npx mex-agent@0.8.3 setup
+npx mex-agent@0.8.4 setup
 ```
 
-This opens setup in your local browser Hub. Choose your AI tools, watch the scaffold and indexes build, and let an available selected Claude Code or Codex CLI populate project memory. If the agent is unavailable or fails, copy the population prompt into your agent, then continue. Existing instructions are preserved; any manual integration pointers appear as advisory guidance.
+This opens a keyboard-driven terminal HUD with a cyan ASCII `mex` banner. Highlight a tool with the arrow keys and press Enter to select it and begin. Space optionally selects additional integrations; the Continue row starts with your checked choices or without an agent. Long steps show an animated activity indicator, elapsed time, and the latest reported work; graph parsing also shows real file counts. When a selected Claude Code or Codex CLI is available, its normal interactive session takes over the terminal; exit that session to return to MEX. MEX checks the scaffold before continuing. Incomplete work can be reopened, populated manually, or left for later. Existing instructions are preserved.
 
-Review the exact setup-file diff in the Hub and choose **Commit setup** to create a local commit. A manual Git checkpoint remains available. MEX preserves unrelated staged work and never pushes or pulls.
+After validation, setup opens the Hub for completion. Review the exact setup-file diff and choose **Commit setup** to create a local commit. A manual Git checkpoint remains available. MEX preserves unrelated staged work and never pushes or pulls.
 
 The completion screen explains how to start a fresh agent session and verify that it reads your project memory. It also offers two optional steps: install the `mex` command globally at the version running setup, and leave an email (plus an optional name) for follow-up about MEX. Contact details are sent through the embedded Web3Forms service and stay out of the repository and usage telemetry. Only a submitted/skipped preference is remembered on this computer. Choose **Open Hub** when ready; the Hub's introductory tour starts there.
 
-Connected agents have their own installation, account, and network requirements. To print the local browser link without opening it, use `npx mex-agent@0.8.3 setup --no-open`; add `--port <n>` to choose a loopback port.
+Connected agents have their own installation, account, and network requirements. Keep the setup terminal running while using the finishing Hub; press `q` or Ctrl+C to stop it. Use `npx mex-agent@0.8.4 setup --no-open` to show the finishing link without opening a browser; add `--port <n>` to choose a loopback port. Press `d` in the HUD to read longer status or error details.
 
-Prefer terminal setup or working over SSH?
+Expected setup errors include specific recovery instructions, such as correcting malformed configuration or an ignore rule that hides the scaffold. An incomplete agent session returns to recovery choices; a successful agent exit alone does not mark setup complete.
+
+Prefer browser setup?
 
 ```bash
-npx mex-agent@0.8.3 setup --cli
+npx mex-agent@0.8.4 setup --browser
 ```
 
-`mex setup --dry-run` remains a terminal preview without changes. Once installed, bare `mex` opens the Hub (or setup for an incomplete project), while `mex tui` opens the terminal dashboard.
+The browser runs the same setup engine with a background Claude Code or Codex session and manual population fallback. `--browser --no-open` prints its link without launching a browser. The existing `--cli` flag remains an alias for the default terminal flow.
+
+For scripts, use `--yes` with repeatable `--tool <name>` flags (or `--tool none`). Piped input/output and CI also use plain output. These runs reuse saved choices, default to no integrations when none are saved, and never launch an agent or browser or wait for input. Exit codes are `0` for completed preparation or a successful dry run, `2` when population is still required, `1` for failure, and `130`/`143` for interruption. After a population checkpoint, rerun `mex setup` to continue. Once preparation is complete, `mex setup --browser` opens the commit and completion page.
+
+`mex setup --dry-run` remains a terminal preview without changes. Once installed, bare `mex` opens the Hub for an established code project or terminal setup for an incomplete project. `mex hub` explicitly opens the browser, while `mex tui` opens the terminal dashboard.
 
 ![Three steps to a ready project: run setup, populate memory, then review and commit the checkpoint before opening Hub.](docs/diagrams/readme/setup.svg)
 
@@ -127,9 +133,9 @@ Push the reviewed setup commit through your team's normal Git workflow so teamma
 Clone or pull the team's repository and branch through Git. For a completed, committed 0.8 setup, build the derived indexes in your own checkout and open Hub:
 
 ```bash
-npx mex-agent@0.8.3 graph rebuild
-npx mex-agent@0.8.3 wiki rebuild-index
-npx mex-agent@0.8.3 hub
+npx mex-agent@0.8.4 graph rebuild
+npx mex-agent@0.8.4 wiki rebuild-index
+npx mex-agent@0.8.4 hub
 ```
 
 Reuse the shared project memory; do not regenerate it just to join. In Team/Members, check the effective identity and, if needed, choose your existing Member record as a local override. If you do not have a record yet, explicitly create one through the reviewed workflow and share its canonical files. Members are attribution, not a sign-in or permission system.
@@ -142,13 +148,13 @@ Older or incomplete setups should follow [upgrade and compatibility](#upgrade-an
 <summary><strong>Prefer a global installation?</strong></summary>
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex setup
 ```
 
 The npm package is named `mex-agent`; the installed command is `mex`. Complete the review and commit checkpoint above before running `mex hub`.
 
-Both the Hub and terminal completion flows offer an optional global installation pinned to the running MEX version. If it fails, setup remains complete and you can retry the command above. Open a new terminal afterward and run `mex --version`.
+The Hub completion page, also opened after interactive terminal setup, offers an optional global installation pinned to the running MEX version. If it fails, setup remains complete and you can retry the command above. Open a new terminal afterward and run `mex --version`.
 
 </details>
 
@@ -157,14 +163,14 @@ Both the Hub and terminal completion flows offer an optional global installation
 <summary><strong>Using MEX for a persistent operational agent?</strong></summary>
 
 ```bash
-npx mex-agent@0.8.3 setup --mode agent-memory
+npx mex-agent@0.8.4 setup --mode agent-memory
 ```
 
 This separate template applies MEX's routing and maintenance model to homelab, infrastructure, and long-running agent workspaces. It adds a `HEARTBEAT.md` contract and cleanup conventions; the Code Graph, Wiki, and team-Hub flow described in this README is the default `code-repo` mode.
 
 </details>
 
-Examples use `mex` for readability. Install it globally as above or replace it with `npx mex-agent@0.8.3`.
+Examples use `mex` for readability. Install it globally as above or replace it with `npx mex-agent@0.8.4`.
 
 ## How MEX works
 
@@ -275,7 +281,7 @@ Choose one installer for each agent integration. If `mex setup` or `mex skills s
 <details>
 <summary><strong>MCP server — source only</strong></summary>
 
-The repository includes an [MCP workspace](https://github.com/mex-memory/mex/tree/v0.8.3/packages/mex-mcp) for local development. It is not published with MEX 0.8; the released agent interface is the `mex-agent` CLI and its project instructions and skills.
+The repository includes an [MCP workspace](https://github.com/mex-memory/mex/tree/v0.8.4/packages/mex-mcp) for local development. It is not published with MEX 0.8; the released agent interface is the `mex-agent` CLI and its project instructions and skills.
 
 </details>
 
@@ -350,7 +356,7 @@ Run `mex <command> --help` for the complete interface.
 
 | Goal | Commands |
 | --- | --- |
-| Set up or inspect compatibility | `mex setup`, `mex setup --cli`, `mex capabilities`, `mex skills sync` |
+| Set up or inspect compatibility | `mex setup`, `mex setup --browser`, `mex capabilities`, `mex skills sync` |
 | Use persistent-agent mode | `mex setup --mode agent-memory`, `mex heartbeat` |
 | Open a local interface | `mex hub`, `mex tui` |
 | Build and retrieve code context | `mex graph status`, `mex graph refresh`, `mex graph rebuild`, `mex graph scope <task>`, `mex graph query <relation> <target>`, `mex graph get <node-id>`, `mex impact <target>` |
@@ -381,14 +387,19 @@ Use `mex capabilities --json` for machine-readable capability discovery and `mex
 For a global installation, upgrade the CLI and refresh the selected Claude Code/Codex skill copies:
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex skills sync --dry-run
 mex skills sync
 ```
 
-For an already completed 0.8.0–0.8.2 setup, this refreshes the managed skills and agent guidance; setup does not need to run again just for the package upgrade. Review any reported conflicts with locally edited instructions, then start a new agent session.
+For an already completed 0.8.0–0.8.3 setup, this refreshes the managed skills and agent guidance; setup does not need to run again just for the package upgrade. Review any reported conflicts with locally edited instructions, then start a new agent session.
+
+> [!WARNING]
+> **Upgrade everyone sharing the scaffold to 0.8.4 before committing new or updated groundings.** This release writes compact `mh2:` fingerprints, which earlier versions—including 0.8.3—cannot read. Existing `mh:` fingerprints remain readable; upgrading alone neither rewrites files nor changes their grounding meaning.
+
+The Graph and Wiki index schemas are unchanged. The first graph refresh after upgrading re-extracts the corpus once for the new extraction cache. To convert existing fingerprints together, preview `mex graph compact-fingerprints --dry-run`, then run `mex graph compact-fingerprints` and review the diff before committing. See [Upgrading to 0.8.4](COMPATIBILITY.md#upgrading-to-084) for the full sequence.
 
-**Keep your existing graph for the 0.8.3 upgrade.** The first refresh performs a full extraction and can change TypeScript node IDs. Refresh before syncing so MEX can map the old IDs to their replacements:
+**Keep your existing graph when upgrading from 0.8.2 or earlier.** The TypeScript identity changes introduced in 0.8.3 can change node IDs. Refresh before syncing so MEX can map the old IDs to their replacements:
 
 ```bash
 mex graph refresh
@@ -449,10 +460,10 @@ MEX keeps team memory in repository files and provides local retrieval and revie
 
 ## Explore further
 
-- Read the [MEX 0.8.3 release notes](RELEASE_NOTES.md).
-- Check the [runtime and compatibility guide](https://github.com/mex-memory/mex/blob/v0.8.3/COMPATIBILITY.md) and [security policy](https://github.com/mex-memory/mex/blob/v0.8.3/SECURITY.md).
-- Review the [Code Graph support matrix](https://github.com/mex-memory/mex/blob/v0.8.3/docs/code-graph-support.md).
-- See the [extractor model and supported relationships](https://github.com/mex-memory/mex/blob/v0.8.3/docs/extractors.md).
-- Read the [graph retrieval benchmark results](https://github.com/mex-memory/mex/blob/v0.8.3/evaluate/RESULTS.md), including the blind-graded comparison against an ordinary file-search baseline.
+- Read the [MEX 0.8.4 release notes](RELEASE_NOTES.md).
+- Check the [runtime and compatibility guide](https://github.com/mex-memory/mex/blob/v0.8.4/COMPATIBILITY.md) and [security policy](https://github.com/mex-memory/mex/blob/v0.8.4/SECURITY.md).
+- Review the [Code Graph support matrix](https://github.com/mex-memory/mex/blob/v0.8.4/docs/code-graph-support.md).
+- See the [extractor model and supported relationships](https://github.com/mex-memory/mex/blob/v0.8.4/docs/extractors.md).
+- Read the [graph retrieval benchmark results](https://github.com/mex-memory/mex/blob/v0.8.4/evaluate/RESULTS.md), including the blind-graded comparison against an ordinary file-search baseline.
 - Inspect the CLI locally with `mex capabilities --json` and `mex commands`.
 - Join the [MEX community on Discord](https://discord.gg/FEdNsQ4Qt4) or visit [mexmemory.com](https://mexmemory.com).
diff --git a/README.pt-BR.md b/README.pt-BR.md
index 7b332607..128bc913 100644
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -15,10 +15,10 @@ O MEX mantém a arquitetura, as decisões, os requisitos e as passagens de conte
 [![Estrelas no GitHub](https://img.shields.io/github/stars/mex-memory/mex?style=flat)](https://github.com/mex-memory/mex/stargazers)
 [![Site](https://img.shields.io/badge/website-mexmemory.com-4f7cff)](https://mexmemory.com)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FEdNsQ4Qt4)
-[![Licença: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.0/LICENSE)
+[![Licença: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.4/LICENSE)
 [![CI](https://github.com/mex-memory/mex/actions/workflows/ci.yml/badge.svg)](https://github.com/mex-memory/mex/actions/workflows/ci.yml)
-[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
+[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
 [![Memória para agentes](https://img.shields.io/badge/agent%20memory-compatible-6f8cff)](#agent-memory-mode)
 [![MCP: somente código-fonte](https://img.shields.io/badge/MCP-source%20only-6f8cff)](#mcp-server)
 
@@ -26,7 +26,7 @@ O MEX mantém a arquitetura, as decisões, os requisitos e as passagens de conte
 
 </div>
 
-> A descrição principal desta tradução ainda corresponde à versão 0.8.0. Os comandos de instalação e as orientações de atualização foram ajustados para 0.8.3; as mudanças do produto estão documentadas no [README em inglês](README.md) e nas [notas de lançamento da versão 0.8.3](RELEASE_NOTES.md).
+> A descrição principal desta tradução ainda corresponde à versão 0.8.0. A configuração, os comandos de instalação e as orientações de atualização foram ajustados para 0.8.4; as demais mudanças do produto estão documentadas no [README em inglês](README.md) e nas [notas de lançamento da versão 0.8.4](RELEASE_NOTES.md).
 
 ---
 
@@ -35,7 +35,7 @@ Uma pessoa sabe por que uma restrição existe. Outra conhece o histórico de de
 **O que um engenheiro e seu agente aprendem deve se tornar contexto que o próximo colega possa usar.** O MEX dá a esse conhecimento um lugar duradouro no repositório: Markdown legível, explicações vinculadas ao código, propostas de Spec revisadas e passagens de contexto estruturadas. As pessoas exploram e revisam esse conhecimento em um Hub local; os agentes o consultam e ajudam a mantê-lo por meio das instruções do projeto e da CLI.
 
 > [!IMPORTANT]
-> **O [MEX 0.8](https://github.com/mex-memory/mex/releases/tag/v0.8.0) amplia a memória de agentes para a memória da equipe:** um Project Hub local, Wiki estruturada e fluxos de trabalho de equipe, Specs com aprovação explícita, Members, Workstreams, Relays, Activity e skills oficiais para Claude Code/Codex — tudo conectado ao Code Graph e ao sistema de grounding e detecção de divergências já existentes.
+> **O [MEX 0.8.4](RELEASE_NOTES.md) inicia a configuração em um novo HUD de terminal**, entrega o terminal ao agente e termina com a revisão no Hub. Os erros de configuração preservam as orientações de recuperação. A versão também acelera as consultas e a atualização do Graph e reduz as impressões digitais de grounding; [atualize toda a equipe antes de compartilhar o novo formato](#upgrade-and-compatibility).
 
 💬 **Entre na comunidade do MEX no Discord** — discuta ideias, peça ajuda, compartilhe feedback e mostre o que está construindo.
 
@@ -102,14 +102,18 @@ O MEX requer **Node.js 22.5 ou mais recente** e um repositório Git. O fluxo nor
 Execute na raiz do repositório:
 
 ```bash
-npx mex-agent@0.8.3 setup
+npx mex-agent@0.8.4 setup
 ```
 
-O comando abre a configuração no navegador local. Escolha as ferramentas de IA, crie o scaffold e os índices e use uma CLI disponível do Claude Code ou Codex para preencher a memória. Se o agente estiver indisponível ou falhar, copie o prompt e continue após o preenchimento manual. As instruções existentes são preservadas; orientações de integração manual não bloqueiam a configuração.
+O comando abre um HUD de terminal com um novo banner ASCII `mex` em ciano. Use as setas para destacar uma ferramenta e Enter para selecioná-la e começar; Espaço permite marcar integrações adicionais. A linha Continue inicia com as opções marcadas ou sem agente. Etapas longas mostram atividade animada, tempo decorrido e o trabalho mais recente; a análise do Graph mostra contagens reais de arquivos. Se uma CLI selecionada do Claude Code ou Codex estiver disponível, sua sessão interativa assume o terminal; saia dessa sessão para voltar ao MEX. O MEX verifica o scaffold antes de continuar e oferece tentar novamente, preencher manualmente ou deixar para depois se faltar conteúdo. As instruções existentes são preservadas.
 
-Revise o diff exato no Hub e escolha **Commit setup** para criar um commit local; o ponto de verificação manual do Git continua disponível. A tela final explica como iniciar uma nova sessão e verificar a memória. Ela oferece instalar globalmente a versão em execução e, opcionalmente, deixar um e-mail e um nome opcional. O formulário integrado envia esses dados ao Web3Forms; eles não entram no repositório nem na telemetria. O computador guarda apenas se você enviou ou pulou o convite. Escolha **Open Hub** para abrir o Hub completo e o tour inicial.
+Após a validação, o Hub abre para concluir a configuração. Revise o diff exato e escolha **Commit setup** para criar um commit local; o ponto de verificação manual do Git continua disponível. O MEX preserva alterações não relacionadas já preparadas e nunca faz push nem pull. A tela final explica como iniciar uma nova sessão e verificar a memória. Ela oferece instalar globalmente a versão em execução e, opcionalmente, deixar um e-mail e um nome opcional. O formulário integrado envia esses dados ao Web3Forms; eles não entram no repositório nem na telemetria. O computador guarda apenas se você enviou ou pulou o convite. Escolha **Open Hub** para abrir o Hub completo e o tour inicial.
 
-Para usar o terminal ou SSH: `npx mex-agent@0.8.3 setup --cli`. `setup --dry-run` continua sendo uma prévia de terminal sem alterações; `--no-open` imprime o link e `--port <n>` escolhe a porta local. Após instalar, `mex` abre o Hub ou a configuração e `mex tui` abre o painel de terminal. Os agentes têm seus próprios requisitos de instalação, conta e rede.
+Mantenha o terminal aberto enquanto usa o Hub; `q` ou Ctrl+C o encerram. `--no-open` mostra o link final sem abrir o navegador e `--port <n>` escolhe a porta local. Pressione `d` para ver mais detalhes do estado ou do erro. Os erros previstos incluem orientações específicas de recuperação, como corrigir uma configuração malformada ou uma regra do Git que oculta o scaffold. Os agentes têm seus próprios requisitos de instalação, conta e rede.
+
+Para configurar pelo navegador, use `npx mex-agent@0.8.4 setup --browser`; ele usa o mesmo motor com um agente em segundo plano e a opção de preencher a memória manualmente. `--browser --no-open` imprime o link sem abri-lo. `--cli` continua sendo um alias do fluxo de terminal padrão.
+
+Para scripts, use `--yes` e `--tool <name>` (repetível), ou `--tool none`. CI e entrada ou saída redirecionada também usam texto sem interação: reutilizam as opções salvas, não selecionam integrações se nenhuma estiver salva e não iniciam agentes nem navegadores. Os códigos de saída são `0` para preparação ou prévia concluída, `2` se faltar preencher a memória, `1` para erros e `130`/`143` para interrupções. `mex setup --dry-run` não altera arquivos. Após instalar, `mex` abre o Hub em um projeto de código estabelecido ou a configuração de terminal em um projeto incompleto; `mex hub` abre o navegador explicitamente e `mex tui` abre o painel de terminal.
 
 ![Três etapas para preparar o projeto: executar a configuração, preencher a memória e revisar e fazer commit do ponto de verificação antes de abrir o Hub.](docs/diagrams/readme/setup.svg)
 
@@ -125,9 +129,9 @@ Faça push do commit de configuração revisado pelo fluxo Git normal da equipe
 Clone o repositório da equipe ou faça pull da branch pelo Git. Se a configuração da versão 0.8 estiver concluída e incluída em um commit, construa os índices derivados no seu próprio checkout e abra o Hub:
 
 ```bash
-npx mex-agent@0.8.3 graph rebuild
-npx mex-agent@0.8.3 wiki rebuild-index
-npx mex-agent@0.8.3 hub
+npx mex-agent@0.8.4 graph rebuild
+npx mex-agent@0.8.4 wiki rebuild-index
+npx mex-agent@0.8.4 hub
 ```
 
 Reutilize a memória compartilhada do projeto; não a gere novamente só para entrar na equipe. Em Team/Members, confira a identidade efetiva e, se necessário, selecione seu registro de Member existente para defini-lo localmente. Se você ainda não tiver um registro, crie um explicitamente pelo fluxo com revisão e compartilhe seus arquivos canônicos. Members servem para atribuição, não para login ou controle de permissões.
@@ -140,7 +144,7 @@ Configurações antigas ou incompletas devem seguir primeiro a seção de [atual
 <summary><strong>Prefere uma instalação global?</strong></summary>
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex setup
 ```
 
@@ -155,14 +159,14 @@ A instalação global opcional, no Hub e no terminal, fixa a versão de MEX em e
 <summary><strong>Vai usar o MEX com um agente operacional persistente?</strong></summary>
 
 ```bash
-npx mex-agent@0.8.3 setup --mode agent-memory
+npx mex-agent@0.8.4 setup --mode agent-memory
 ```
 
 Esse template separado aplica o modelo de roteamento e manutenção do MEX a ambientes de homelab, infraestrutura e agentes de longa duração. Ele adiciona um contrato `HEARTBEAT.md` e convenções de limpeza; o fluxo de Code Graph, Wiki e Hub de equipe descrito neste README corresponde ao modo padrão `code-repo`.
 
 </details>
 
-Os exemplos usam `mex` para facilitar a leitura. Instale-o globalmente como indicado acima ou substitua-o por `npx mex-agent@0.8.3`.
+Os exemplos usam `mex` para facilitar a leitura. Instale-o globalmente como indicado acima ou substitua-o por `npx mex-agent@0.8.4`.
 
 <a id="how-mex-works"></a>
 
@@ -264,7 +268,7 @@ O fluxo governado do Inbox se aplica a propostas da família Spec. Atualizaçõe
 <details>
 <summary><strong>Servidor MCP — somente código-fonte</strong></summary>
 
-O repositório inclui um [workspace MCP](https://github.com/mex-memory/mex/tree/v0.8.0/packages/mex-mcp) para desenvolvimento local. Ele não é publicado com o MEX 0.8; a interface lançada para agentes é a CLI `mex-agent` com suas instruções de projeto e skills.
+O repositório inclui um [workspace MCP](https://github.com/mex-memory/mex/tree/v0.8.4/packages/mex-mcp) para desenvolvimento local. Ele não é publicado com o MEX 0.8; a interface lançada para agentes é a CLI `mex-agent` com suas instruções de projeto e skills.
 
 </details>
 
@@ -350,14 +354,19 @@ Use `mex capabilities --json` para descobrir capacidades em formato legível por
 Para uma instalação global, atualize a CLI e as cópias das skills selecionadas do Claude Code/Codex:
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex skills sync --dry-run
 mex skills sync
 ```
 
-Se a configuração com a versão 0.8.0 já foi concluída, esses comandos atualizam as skills e as instruções gerenciadas do agente; não é necessário executar setup novamente só para atualizar o pacote. Revise os conflitos apontados com instruções editadas localmente e depois inicie uma nova sessão do agente.
+Se a configuração com uma versão de 0.8.0 a 0.8.3 já foi concluída, esses comandos atualizam as skills e as instruções gerenciadas do agente; não é necessário executar setup novamente só para atualizar o pacote. Revise os conflitos apontados com instruções editadas localmente e depois inicie uma nova sessão do agente.
+
+> [!WARNING]
+> **Atualize todos que compartilham o scaffold para 0.8.4 antes de fazer commit de groundings novos ou alterados.** As impressões digitais compactas `mh2:` não podem ser lidas por versões anteriores, incluindo a 0.8.3. As impressões `mh:` existentes continuam válidas; atualizar o pacote não reescreve arquivos nem altera seu significado.
+
+Os esquemas dos índices Graph e Wiki não mudam. A primeira execução de `mex graph refresh` extrai o código novamente uma vez para o novo cache. Para converter as impressões digitais existentes de uma vez, confira `mex graph compact-fingerprints --dry-run`, execute `mex graph compact-fingerprints` e revise o diff antes de fazer commit. Consulte [como atualizar para 0.8.4](COMPATIBILITY.md#upgrading-to-084).
 
-**Ao atualizar para 0.8.3, preserve o Graph existente.** Execute `mex graph refresh` e depois `mex sync`: a primeira atualização faz uma extração completa e pode mudar os identificadores TypeScript. Revise os casos ambíguos ou ausentes e faça commit das alterações do scaffold pelo Git. Se o scaffold mudar, atualize o índice Wiki com `mex wiki rebuild-index`. Um clone novo ou uma reconstrução sem o Graph anterior depende das impressões digitais salvas e pode exigir vincular o código novamente de forma manual. Consulte o [guia de compatibilidade](COMPATIBILITY.md#upgrading-to-083).
+**Se estiver vindo de 0.8.2 ou de uma versão anterior, preserve o Graph existente.** As mudanças de identidade do TypeScript introduzidas em 0.8.3 podem mudar os identificadores. Execute `mex graph refresh` e depois `mex sync` para manter a correspondência com os antigos. Revise os casos ambíguos ou ausentes e faça commit das alterações do scaffold pelo Git. Se o scaffold mudar, atualize o índice Wiki com `mex wiki rebuild-index`. Um clone novo ou uma reconstrução sem o Graph anterior depende das impressões digitais salvas e pode exigir vincular o código novamente de forma manual. Consulte os [passos de migração da versão 0.8.3](COMPATIBILITY.md#upgrading-to-083).
 
 Atualizar apenas o pacote e as skills não deixa um repositório antigo ou incompleto pronto para o Hub. Para esses repositórios, avalie setup com uma simulação antes de aplicá-lo; setup preserva os arquivos existentes e suas alterações ainda precisam ser revisadas:
 
@@ -417,10 +426,10 @@ O MEX mantém a memória da equipe em arquivos do repositório e oferece fluxos
 
 ## Saiba mais
 
-- Leia as [notas de lançamento do MEX 0.8](https://github.com/mex-memory/mex/releases/tag/v0.8.0).
-- Consulte o [guia de ambiente de execução e compatibilidade](https://github.com/mex-memory/mex/blob/v0.8.0/COMPATIBILITY.md) e a [política de segurança](https://github.com/mex-memory/mex/blob/v0.8.0/SECURITY.md).
-- Veja a [matriz de suporte do Code Graph](https://github.com/mex-memory/mex/blob/v0.8.0/docs/code-graph-support.md).
-- Consulte o [modelo dos extratores e as relações suportadas](https://github.com/mex-memory/mex/blob/v0.8.0/docs/extractors.md).
-- Leia os [resultados do benchmark de recuperação do Code Graph](https://github.com/mex-memory/mex/blob/v0.8.0/evaluate/RESULTS.md), incluindo a comparação avaliada às cegas com uma busca de arquivos comum.
+- Leia as [notas de lançamento do MEX 0.8.4](RELEASE_NOTES.md).
+- Consulte o [guia de ambiente de execução e compatibilidade](https://github.com/mex-memory/mex/blob/v0.8.4/COMPATIBILITY.md) e a [política de segurança](https://github.com/mex-memory/mex/blob/v0.8.4/SECURITY.md).
+- Veja a [matriz de suporte do Code Graph](https://github.com/mex-memory/mex/blob/v0.8.4/docs/code-graph-support.md).
+- Consulte o [modelo dos extratores e as relações suportadas](https://github.com/mex-memory/mex/blob/v0.8.4/docs/extractors.md).
+- Leia os [resultados do benchmark de recuperação do Code Graph](https://github.com/mex-memory/mex/blob/v0.8.4/evaluate/RESULTS.md), incluindo a comparação avaliada às cegas com uma busca de arquivos comum.
 - Examine a CLI localmente com `mex capabilities --json` e `mex commands`.
 - Entre na [comunidade do MEX no Discord](https://discord.gg/FEdNsQ4Qt4) ou visite [mexmemory.com](https://mexmemory.com).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 50e26380..cf0caf85 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -15,10 +15,10 @@ MEX 将团队的架构、决策、需求和交接信息与代码放在一起。
 [![GitHub 星标](https://img.shields.io/github/stars/mex-memory/mex?style=flat)](https://github.com/mex-memory/mex/stargazers)
 [![网站](https://img.shields.io/badge/website-mexmemory.com-4f7cff)](https://mexmemory.com)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/FEdNsQ4Qt4)
-[![许可证：MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.0/LICENSE)
+[![许可证：MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mex-memory/mex/blob/v0.8.4/LICENSE)
 [![CI](https://github.com/mex-memory/mex/actions/workflows/ci.yml/badge.svg)](https://github.com/mex-memory/mex/actions/workflows/ci.yml)
-[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.0/package.json)
+[![Node.js >=22.5](https://img.shields.io/badge/Node.js-%3E%3D22.5-339933?logo=node.js&logoColor=white)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178c6)](https://github.com/mex-memory/mex/blob/v0.8.4/package.json)
 [![智能体记忆](https://img.shields.io/badge/agent%20memory-compatible-6f8cff)](#agent-memory-mode)
 [![MCP：仅提供源码](https://img.shields.io/badge/MCP-source%20only-6f8cff)](#mcp-server)
 
@@ -26,7 +26,7 @@ MEX 将团队的架构、决策、需求和交接信息与代码放在一起。
 
 </div>
 
-> 此译文的主要产品介绍仍对应 0.8.0。安装命令和升级指引已调整为 0.8.3；产品变更请参阅[英文 README](README.md)和 [0.8.3 发行说明](RELEASE_NOTES.md)。
+> 此译文的主要产品介绍仍对应 0.8.0。设置流程、安装命令和升级指引已调整为 0.8.4；其他产品变更请参阅[英文 README](README.md)和 [0.8.4 发行说明](RELEASE_NOTES.md)。
 
 ---
 
@@ -35,7 +35,7 @@ MEX 将团队的架构、决策、需求和交接信息与代码放在一起。
 **一位工程师及其智能体获得的认识，应该成为下一位队友能用上的上下文。** MEX 在仓库中为这些知识提供持久的归宿：可读的 Markdown、关联代码的说明、经过审阅的 Spec 提案，以及结构化交接。人通过本地 Hub 浏览和审阅；智能体通过项目指令和 CLI 检索并协助维护。
 
 > [!IMPORTANT]
-> **[MEX 0.8](https://github.com/mex-memory/mex/releases/tag/v0.8.0) 将智能体记忆扩展为团队记忆：** 本地 Project Hub、结构化 Wiki 与团队工作流、受审批流程管控的 Specs、Members、Workstreams、Relays、Activity，以及官方 Claude Code/Codex 技能——全部与已有的 Code Graph、代码关联和漂移检测系统相连接。
+> **[MEX 0.8.4](RELEASE_NOTES.md) 默认在全新的终端 HUD 中开始设置**，将终端交给智能体，再回到 Hub 中完成审阅。设置错误会保留具体的恢复指引。本版本还加快 Graph 刷新和检索，并缩短代码关联指纹；[共享新格式前，请先升级整个团队](#upgrade-and-compatibility)。
 
 💬 **加入 Discord 上的 MEX 社区**——讨论想法、寻求帮助、分享反馈，展示你正在构建的项目。
 
@@ -102,14 +102,18 @@ MEX 需要 **Node.js 22.5 或更高版本**，以及一个 Git 仓库。标准 n
 在仓库根目录运行：
 
 ```bash
-npx mex-agent@0.8.3 setup
+npx mex-agent@0.8.4 setup
 ```
 
-此命令会在本地浏览器中打开设置向导。选择 AI 工具，构建脚手架和索引，并让可用的 Claude Code 或 Codex CLI 填充项目记忆。若智能体不可用或运行失败，可复制提示词，手动完成后继续。现有指令会保留；需要手动补充的集成指引不会阻止设置。
+此命令会打开终端 HUD，并显示全新的青色 ASCII `mex` 标识。使用方向键高亮工具，按 Enter 选中并开始；也可用空格键勾选其他集成。Continue 行会按已勾选的选项继续，也可不使用智能体。耗时步骤会显示活动动画、已用时间和最近的工作状态；Graph 解析还会显示实际文件数量。若所选的 Claude Code 或 Codex CLI 可用，其原生交互会话会接管终端；退出该会话即可返回 MEX。MEX 会先检查脚手架；若内容尚未完成，可重试、手动填充或稍后继续。现有指令会保留。
 
-在 Hub 中审阅确切的设置文件差异，点击 **Commit setup** 创建本地提交，也可以使用手动 Git 检查点。完成页面会说明如何开启新会话并验证项目记忆，还可选择安装当前版本的全局命令，或留下电子邮箱和可选姓名。联系信息通过内嵌 Web3Forms 服务发送，不写入仓库或使用遥测；本机只记录已提交或已跳过。点击 **Open Hub** 后进入完整 Hub 和首次使用导览。
+验证后，设置会打开 Hub 进入收尾步骤。审阅确切的设置文件差异，点击 **Commit setup** 创建本地提交，也可以使用手动 Git 检查点。MEX 会保留无关的暂存变更，且不会自动 push 或 pull。完成页面会说明如何开启新会话并验证项目记忆，还可选择安装当前版本的全局命令，或留下电子邮箱和可选姓名。联系信息通过内嵌 Web3Forms 服务发送，不写入仓库或使用遥测；本机只记录已提交或已跳过。点击 **Open Hub** 后进入完整 Hub 和首次使用导览。
 
-若偏好终端或通过 SSH 操作，请运行 `npx mex-agent@0.8.3 setup --cli`。`setup --dry-run` 仍是只读终端预览；`--no-open` 只打印浏览器链接，`--port <n>` 指定本地端口。安装后，`mex` 打开 Hub 或设置，`mex tui` 打开终端面板。智能体仍需自行安装并满足账户和网络要求。
+使用 Hub 时请保持设置终端运行；按 `q` 或 Ctrl+C 可停止它。`--no-open` 显示收尾页面的链接而不打开浏览器，`--port <n>` 指定本地端口。按 `d` 可查看完整的状态或错误详情。预期的设置错误会附带具体恢复指引，例如修正格式错误的配置或隐藏脚手架的 Git 忽略规则。智能体仍需自行安装并满足账户和网络要求。
+
+如需从浏览器进行设置，运行 `npx mex-agent@0.8.4 setup --browser`；它使用相同的设置引擎，在后台运行智能体，并提供手动填充选项。`--browser --no-open` 只打印链接而不打开浏览器。`--cli` 仍是默认终端流程的兼容别名。
+
+脚本可使用 `--yes` 和可重复的 `--tool <name>`，或 `--tool none`。CI 及重定向输入或输出的环境也使用无交互文本输出：复用已保存的选项，没有保存的选项时不选择任何集成，也不会启动智能体或浏览器。退出码 `0` 表示准备或预览成功，`2` 表示仍需填充记忆，`1` 表示失败，`130`/`143` 表示中断。`mex setup --dry-run` 不修改文件。安装后，`mex` 会为已建立的代码项目打开 Hub，为未完成的项目打开终端设置；`mex hub` 显式打开浏览器，`mex tui` 打开终端面板。
 
 ![准备好项目的三个步骤：运行设置、填充记忆，然后审阅并提交检查点，再打开 Hub。](docs/diagrams/readme/setup.svg)
 
@@ -125,9 +129,9 @@ npx mex-agent@0.8.3 setup
 通过 Git 克隆或拉取团队的仓库和分支。如果 0.8 设置已完成并提交，在自己的检出目录中构建派生索引，然后打开 Hub：
 
 ```bash
-npx mex-agent@0.8.3 graph rebuild
-npx mex-agent@0.8.3 wiki rebuild-index
-npx mex-agent@0.8.3 hub
+npx mex-agent@0.8.4 graph rebuild
+npx mex-agent@0.8.4 wiki rebuild-index
+npx mex-agent@0.8.4 hub
 ```
 
 复用共享的项目记忆，不要仅为加入项目而重新生成。在 Team/Members 中检查实际生效的身份，并按需选择你已有的 Member 记录作为本地覆盖设置。如果尚无记录，请通过经过审阅的工作流明确创建一条，并共享其权威记录文件。Members 用于标明归属，不是登录或权限系统。
@@ -140,7 +144,7 @@ npx mex-agent@0.8.3 hub
 <summary><strong>更喜欢全局安装？</strong></summary>
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex setup
 ```
 
@@ -155,14 +159,14 @@ npm 包名为 `mex-agent`，安装后的命令为 `mex`。运行 `mex hub` 前
 <summary><strong>想将 MEX 用于长期运行的运维智能体？</strong></summary>
 
 ```bash
-npx mex-agent@0.8.3 setup --mode agent-memory
+npx mex-agent@0.8.4 setup --mode agent-memory
 ```
 
 这个独立模板将 MEX 的路由与维护模型应用于家庭实验室、基础设施，以及长期运行的智能体工作空间。它增加了 `HEARTBEAT.md` 约定和清理规范；本 README 描述的 Code Graph、Wiki 和团队 Hub 流程属于默认的 `code-repo` 模式。
 
 </details>
 
-为便于阅读，示例使用 `mex`。你可以按上述方式全局安装，或将其替换为 `npx mex-agent@0.8.3`。
+为便于阅读，示例使用 `mex`。你可以按上述方式全局安装，或将其替换为 `npx mex-agent@0.8.4`。
 
 <a id="how-mex-works"></a>
 
@@ -264,7 +268,7 @@ Claude Code 使用 `--tool claude`。审阅生成的指令和技能文件；如
 <details>
 <summary><strong>MCP 服务器——仅提供源码</strong></summary>
 
-仓库包含用于本地开发的 [MCP 工作区](https://github.com/mex-memory/mex/tree/v0.8.0/packages/mex-mcp)。它未随 MEX 0.8 发布；已发布的智能体接口是 `mex-agent` CLI 及其项目指令和技能。
+仓库包含用于本地开发的 [MCP 工作区](https://github.com/mex-memory/mex/tree/v0.8.4/packages/mex-mcp)。它未随 MEX 0.8 发布；已发布的智能体接口是 `mex-agent` CLI 及其项目指令和技能。
 
 </details>
 
@@ -350,14 +354,19 @@ Relay 是持久交接记录，不是聊天、实时通知、任务分配，也
 如果使用全局安装，请升级 CLI 并刷新所选 Claude Code/Codex 技能副本：
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex skills sync --dry-run
 mex skills sync
 ```
 
-如果已完成 0.8.0 的设置，上述命令会更新受管理的技能和智能体指引；无需仅为升级软件包而重新运行 setup。请检查与本地修改的指引之间报告的冲突，然后开启新的智能体会话。
+如果已完成 0.8.0–0.8.3 的设置，上述命令会更新受管理的技能和智能体指引；无需仅为升级软件包而重新运行 setup。请检查与本地修改的指引之间报告的冲突，然后开启新的智能体会话。
+
+> [!WARNING]
+> **提交新增或修改的代码关联前，请让所有共享脚手架的成员升级到 0.8.4。** 早期版本（包括 0.8.3）无法读取紧凑的 `mh2:` 指纹。现有 `mh:` 指纹仍受支持；仅升级软件包不会重写文件或改变代码关联的含义。
+
+Graph 和 Wiki 索引的 schema 不变。升级后首次运行 `mex graph refresh` 会为新的提取缓存重新提取一次代码。如需一次性转换现有指纹，先预览 `mex graph compact-fingerprints --dry-run`，再运行 `mex graph compact-fingerprints`，审阅差异后提交。完整步骤见[升级到 0.8.4](COMPATIBILITY.md#upgrading-to-084)。
 
-**升级到 0.8.3 时，请保留现有 Graph。** 先运行 `mex graph refresh`，再运行 `mex sync`：首次刷新会完整提取代码，并可能更改 TypeScript 节点 ID。请检查有歧义或缺失的 grounding，通过 Git 提交 scaffold 变更。若 scaffold 已变更，请运行 `mex wiki rebuild-index` 刷新 Wiki 索引。新克隆或未保留旧 Graph 的重建只能依靠已提交的指纹进行匹配，可能需要手动重新关联代码。详见[兼容性指南](COMPATIBILITY.md#upgrading-to-083)。
+**如果从 0.8.2 或更早版本升级，请保留现有 Graph。** 0.8.3 引入的 TypeScript 标识变更可能改变节点 ID。先运行 `mex graph refresh`，再运行 `mex sync`，以保留新旧 ID 的映射。请检查有歧义或缺失的 grounding，通过 Git 提交 scaffold 变更。若 scaffold 已变更，请运行 `mex wiki rebuild-index` 刷新 Wiki 索引。新克隆或未保留旧 Graph 的重建只能依靠已提交的指纹进行匹配，可能需要手动重新关联代码。详见 [0.8.3 迁移步骤](COMPATIBILITY.md#upgrading-to-083)。
 
 仅升级软件包和技能，并不能让旧仓库或尚未完成设置的仓库立即满足 Hub 的运行条件。对于这些仓库，请先通过 dry run 检查 setup 的变更，再实际应用；setup 会保留现有编写的文件，其变更仍需审阅：
 
@@ -417,10 +426,10 @@ MEX 将团队记忆保存在仓库文件中，并提供本地检索和审阅工
 
 ## 继续了解
 
-- 阅读 [MEX 0.8 发行说明](https://github.com/mex-memory/mex/releases/tag/v0.8.0)。
-- 查看[运行时与兼容性指南](https://github.com/mex-memory/mex/blob/v0.8.0/COMPATIBILITY.md)和[安全政策](https://github.com/mex-memory/mex/blob/v0.8.0/SECURITY.md)。
-- 查阅 [Code Graph 支持矩阵](https://github.com/mex-memory/mex/blob/v0.8.0/docs/code-graph-support.md)。
-- 了解[提取器模型和支持的关系](https://github.com/mex-memory/mex/blob/v0.8.0/docs/extractors.md)。
-- 阅读 [Code Graph 检索基准结果](https://github.com/mex-memory/mex/blob/v0.8.0/evaluate/RESULTS.md)，其中包含与普通文件搜索基线的盲评对比。
+- 阅读 [MEX 0.8.4 发行说明](RELEASE_NOTES.md)。
+- 查看[运行时与兼容性指南](https://github.com/mex-memory/mex/blob/v0.8.4/COMPATIBILITY.md)和[安全政策](https://github.com/mex-memory/mex/blob/v0.8.4/SECURITY.md)。
+- 查阅 [Code Graph 支持矩阵](https://github.com/mex-memory/mex/blob/v0.8.4/docs/code-graph-support.md)。
+- 了解[提取器模型和支持的关系](https://github.com/mex-memory/mex/blob/v0.8.4/docs/extractors.md)。
+- 阅读 [Code Graph 检索基准结果](https://github.com/mex-memory/mex/blob/v0.8.4/evaluate/RESULTS.md)，其中包含与普通文件搜索基线的盲评对比。
 - 在本地使用 `mex capabilities --json` 和 `mex commands` 检查 CLI。
 - 加入 [Discord 上的 MEX 社区](https://discord.gg/FEdNsQ4Qt4)，或访问 [mexmemory.com](https://mexmemory.com)。
diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md
index 86128bcf..4341581f 100644
--- a/RELEASE_NOTES.md
+++ b/RELEASE_NOTES.md
@@ -1,106 +1,140 @@
-# mex 0.8.3 — Faster graphs, more reliable grounding
-
-MEX 0.8.3 makes graph refresh incremental, preserves more knowledge links across
-clones and code changes, and expands route and dependency coverage. It also adds
-scaffold export and Markdown timelines.
-
-## Faster graph maintenance and reads
-
-- Refresh reuses unchanged file extractions and rewrites only changed graph
-  rows. TypeScript and JavaScript dependents are re-extracted when needed;
-  broad compiler or configuration changes fall back to full extraction.
-  Resolution still runs over the whole corpus.
-- A refresh with nothing to publish leaves `graph.db` untouched. JSON output
-  reports the refresh mode, fallback reason, and work performed. The extraction
-  cache adds to local database size.
-- Targeted reads reuse a validated publication audit, and CLI code splitting
-  avoids loading the compiler and terminal UI for lightweight commands.
-
-## Grounding that survives everyday work
-
-- TypeScript node IDs no longer depend on the checkout directory. Type signatures
-  use canonical ordering so incremental and full extraction agree.
-- `mex impact` reads knowledge links from the committed scaffold, so they work
-  on fresh clones. Grounding records take priority over transitive callers when
-  the output budget is tight; `graph get` keeps node metadata when source does
-  not fit. Inline anchors alone are not returned as impact grounding records.
-- `mex check` reads groundings at both the root and under `mex:`. Writers
-  consolidate compatible root entries under `mex.grounds_to`; conflicting
-  entries stay visible for review.
-- Source edits no longer disable all grounding checks. Unchanged files can use
-  the prior snapshot; edited tree-sitter files can be re-extracted locally.
-  Edited TypeScript/JavaScript groundings report `GROUNDING_UNVERIFIED` until
-  refresh rather than appearing clean. Other freshness failures still block
-  checks that cannot be trusted.
-- Small-function renames can reconcile from callers and callees, with an
-  explicit `GROUNDING_MOVED_BY_NEIGHBORS` notice. Equally good candidates remain
-  ambiguous, and inline anchors can use committed fingerprints after rebuilds.
-
-## More project coverage and useful outputs
-
-- New bounded **FastAPI, Flask, and NestJS route resolvers** join Express and
-  Next.js App Router. Static paths and unambiguous same-file handlers are
-  supported; this is not general runtime routing analysis.
-- Dependency checking reads Python `pyproject.toml`, including common optional
-  and grouped dependencies. Architectural labels produce fewer package warnings.
-- Graph commands and doctor report recognized source files with no registered
-  extractor, and status distinguishes uninspected fields from real zero counts.
-- `mex export` bundles scaffold Markdown into one document; use `--out <path>`
-  for a file. `mex timeline --format md` produces a Markdown table for reports.
-- Heartbeat explains when missing `last_updated` fields leave staleness checks
-  inactive, accepts zero-day thresholds, and deduplicates symlinked files.
-- Official Inbox and Relay skills are discoverable through standalone skill
-  installers and Claude Code marketplace metadata. Standalone installation is
-  an alternative to MEX-managed skills; it still requires the CLI and a project.
+# mex 0.8.4 — Terminal setup and clearer knowledge checks
+
+Prepared October 9, 2026. This release is unpublished until the reviewed changes
+are merged, tagged, and published.
+
+MEX 0.8.4 makes terminal setup the default, adds a native interactive agent
+handoff, and reports setup progress and failures more clearly. It also includes
+the graph, Wiki search, and grounding improvements merged since 0.8.3.
+
+## Terminal setup by default
+
+Run `mex setup` to open the keyboard-driven HUD and ASCII banner. Choose a tool
+with the arrow keys and Enter; Space selects additional integrations. Selection
+happens before setup writes. An available selected Claude Code or Codex CLI
+receives the real terminal, including normal keyboard interaction. Exit the
+agent to return to MEX; incomplete population offers retry, a manual prompt,
+file checks, or Finish later.
+
+Graph work shows actual phase/file counts and elapsed time. Setup distinguishes
+complete, paused, failed, and cancelled outcomes. Expected failures carry
+recovery instructions; bounded worker diagnostics remain available in the
+terminal, while browser errors expose only safe messages. Completing or checking
+setup without agent output no longer creates an empty background-session panel.
+Press `d` to review retained setup notices and diagnostics; `l` on the finishing
+screen shows a clean copyable Hub link, including in a narrow terminal. Finish
+later remains a paused outcome after an agent failure, and the final message
+reflects a setup commit completed in the browser. On Windows, returning from
+the manual prompt or the Hub link view no longer leaves the HUD without input.
+
+After interactive preparation, the browser handles setup-file review, the
+explicit local commit checkpoint, and completion. MEX never pushes. Use
+`mex setup --browser` to select browser setup directly; `--cli` remains an alias
+for terminal setup. Bare `mex` opens terminal setup for an incomplete project
+and Hub for an established code project. `mex hub` and `mex tui` remain explicit
+browser and terminal-dashboard entry points.
+
+For scripts, use `mex setup --yes --tool <name>` or `--tool none`. Piped input/output
+and CI also use plain output, reuse saved choices where available, and never
+launch an agent or long-lived Hub. Exit codes are `0` for completed preparation
+or a successful dry run, `2` for pending population, `1` for failure, and
+`130`/`143` for interruption. `--dry-run` remains read-only.
+
+## Faster graphs, smaller fingerprints
+
+- Refresh avoids re-extracting importers whose dependency declaration signatures
+  did not change and shares compiler resolution work across projects. The first
+  refresh after upgrading re-extracts the corpus once for the new internal cache
+  format; subsequent work can reuse it. The inferred-program fallback now agrees
+  with a clean build after changes outside every `tsconfig`.
+- Scope tokenizes each node once per query, avoiding repeated work on large type
+  signatures while preserving the output.
+- New grounding fingerprints use lossless `mh2:` encoding, substantially reducing
+  committed Markdown size. Existing `mh:` values remain readable and are not
+  rewritten by reads. `mex graph compact-fingerprints --dry-run` previews an
+  optional explicit conversion; omit `--dry-run` to apply it.
+
+**Upgrade every collaborator before committing `mh2:` groundings. MEX 0.8.3 and
+earlier cannot read that encoding.**
+
+## Knowledge checks and Wiki maintenance
+
+- `mex check`, Wiki queries, and Hub views share fact-aware grounding verdicts.
+  Proven comment-only and formatting-only edits stay fresh; changes away from
+  everything a fact names are distinguished from changes that may invalidate it.
+  Missing or ambiguous links remain flagged. Class properties and fields now
+  receive body hashes and fingerprints too.
+- `mex sync` reviews flagged Wiki facts in the same agent session. After review,
+  `mex wiki reground <id> --apply` can re-record a still-valid fact's links;
+  changed text or uncertain links require the corresponding review. Index
+  rebuild and another check follow. Baselines are not silently accepted.
+- `mex wiki validate` checks structure. Use `mex check` for code-link health.
+  Graph-aware Wiki maintenance uses a revalidated snapshot. An unrelated
+  incomplete parse permits exact grounding from fully parsed files; targets
+  in incomplete files remain unverified with named remediation. Source or
+  configuration drift still blocks grounding, and missing targets are not
+  reconciled against an incomplete corpus. `mex check` applies the same rule:
+  one unparseable file no longer skips every grounding check.
+- Natural-language Wiki queries ignore question/stop words, rank exact-term
+  answers ahead of broader matches, and explain partial or empty results. Hub
+  search uses the same ranking and identifies unchecked health.
+- Migration adopts `context/stack.md` and knowledge files with an explicit usable
+  entity type. Check and validate name eligible or untyped files left outside
+  the Wiki; pattern creation joins an existing Wiki through migration.
+- `mex wiki link-sections` previews missing section-to-parent relationships;
+  `--apply` records them. `mex wiki upgrade` previews a bounded review of broad
+  code-linked facts, with an agent or manual prompt for explicit application.
+  It requires a fresh graph and refuses flagged candidate links.
+- Staleness counts commits affecting referenced paths, and script/dependency
+  checks avoid brace-expansion and command-prose false positives. Dependency
+  checks find nested `package.json` and `pyproject.toml` manifests, and Yarn or
+  pnpm built-in commands are no longer reported as dead scripts. CLI discovery
+  verifies MEX rather than trusting an executable's name. Hub groups repeated
+  Wiki diagnostics with expandable detail.
 
 ## Upgrade an existing project
 
-**Keep the old graph for the first refresh.** TypeScript signature fixes can
-change node IDs, and the old index lets refresh retain aliases for those IDs.
+After publication, install the pinned release and preserve your existing graph:
 
 ```bash
-npm install -g mex-agent@0.8.3
+npm install -g mex-agent@0.8.4
 mex graph refresh
+mex check
 mex sync
+mex wiki rebuild-index
 ```
 
-The first refresh performs a full extraction with `typescript-5.9-v5`.
-Review the scaffold diff and any ambiguous or missing groundings before
-committing through Git. If the scaffold changed, run `mex wiki rebuild-index`
-to update its local index. A fresh clone or rebuild without the old graph uses
-committed fingerprints and may require manual re-grounding. For an incompatible
-or damaged index, follow the explicit recovery action from `mex graph status`.
-
-For integrations managed by MEX:
-
-```bash
-mex skills sync --dry-run
-mex skills sync
-```
-
-Review conflicts and start a fresh agent session. Do not install standalone
-skills over a MEX-managed integration. Completed 0.8.0–0.8.2 setups do not need
-setup again solely to upgrade. New projects can start with
-`npx mex-agent@0.8.3 setup`; terminal setup remains `setup --cli`.
-
-Node.js 22.5 or newer with SQLite FTS5 remains required. Graph schema stays v4
-with an internal extraction cache; canonical Wiki and Relay artifact versions
-are unchanged. Public API additions include the optional
-`HeartbeatResult.filesWithoutLastUpdated` field and three grounding issue codes;
-exhaustive consumers should review [the compatibility guide](COMPATIBILITY.md#additive-api-changes-in-083).
-
-## Contributors
-
-Thanks to everyone who contributed code, tests, documentation, and integration
-work since 0.8.2:
-
-- @theyashasvipandey — incremental refresh and grounding, identity, and path fixes ([#247](https://github.com/mex-memory/mex/pull/247), [#246](https://github.com/mex-memory/mex/pull/246), [#244](https://github.com/mex-memory/mex/pull/244), [#243](https://github.com/mex-memory/mex/pull/243), [#242](https://github.com/mex-memory/mex/pull/242), [#241](https://github.com/mex-memory/mex/pull/241), [#200](https://github.com/mex-memory/mex/pull/200)).
-- @abhinav-phi — Flask/NestJS routes, Python dependencies, claim filtering, coverage, export, timeline, heartbeat, CLI smoke tests, and changelog history ([#177](https://github.com/mex-memory/mex/pull/177), [#102](https://github.com/mex-memory/mex/pull/102), [#185](https://github.com/mex-memory/mex/pull/185), [#186](https://github.com/mex-memory/mex/pull/186), [#175](https://github.com/mex-memory/mex/pull/175), [#183](https://github.com/mex-memory/mex/pull/183), [#182](https://github.com/mex-memory/mex/pull/182), [#181](https://github.com/mex-memory/mex/pull/181), [#178](https://github.com/mex-memory/mex/pull/178), [#184](https://github.com/mex-memory/mex/pull/184)).
-- @sidsri14 — FastAPI routes ([#113](https://github.com/mex-memory/mex/pull/113)).
-- @Kaustubh1235 — targeted-read performance ([#196](https://github.com/mex-memory/mex/pull/196)).
-- @chiliec — impact output priority and honest status fields ([#238](https://github.com/mex-memory/mex/pull/238), [#215](https://github.com/mex-memory/mex/pull/215)).
-- @iveteamorim — graph-get output budgeting ([#239](https://github.com/mex-memory/mex/pull/239)).
-- @architdhamija — skill discoverability ([#245](https://github.com/mex-memory/mex/pull/245)).
-- @theDakshJaitly — skill discovery validation and installer separation, export FIFO safety tests, historical compatibility corrections, README upkeep, and release integration ([skills fixes](https://github.com/mex-memory/mex/commit/e6fa172), [export tests](https://github.com/mex-memory/mex/commit/a0c1a92), [changelog corrections](https://github.com/mex-memory/mex/commit/81d83d2), [README update](https://github.com/mex-memory/mex/commit/5b6e02c)).
-
-**Full changelog:** [v0.8.2…v0.8.3](https://github.com/mex-memory/mex/compare/v0.8.2...v0.8.3).
+Review grounding decisions and scaffold changes before committing through Git.
+Do not delete a working graph as the first upgrade step. For a damaged or
+incompatible store, follow `mex graph status`'s explicit recovery action. Projects
+skipping 0.8.3 must also follow its one-time TypeScript identity guidance in the
+[compatibility guide](COMPATIBILITY.md#upgrading-to-084).
+
+Use `mex wiki migrate --dry-run` to preview newly adoptable knowledge, review
+its proposed changes, and run `mex wiki migrate` when ready to apply them.
+For MEX-managed integrations, preview with `mex skills sync --dry-run`, resolve
+conflicts, then run `mex skills sync` and start a new agent session. Standalone
+skills are an alternative installer; do not overlay them on managed copies.
+A completed setup does not need to run again solely for this package upgrade.
+
+Node.js 22.5 or newer with SQLite FTS5 remains required. Graph schema stays v4;
+Wiki and canonical Relay artifact versions are unchanged. Public `DriftIssue`
+adds optional fields and `IssueCode` adds cases; exhaustive consumers should
+review [the API compatibility notes](COMPATIBILITY.md#additive-api-changes-in-084).
+
+## Known limitations
+
+Dependency-rich TypeScript/JavaScript builds can still exhaust Node's heap. A
+924-source disposable MEX copy with installed dependencies failed, and a
+compiler-only probe reproduced exhaustion during signature rendering before
+persistence. Progress, diagnostics, and process isolation contain and explain
+that failure; they do not fix its memory requirement.
+
+The browser's completion readiness still uses limited placeholder and
+index-presence checks after restart, so a failed final validation can later
+appear commit-ready. Oversized population prompts can exceed the Hub run-response
+contract. These are separate follow-ups; this release does not claim every
+setup or completion path is reliable.
+
+**Full changelog:** [v0.8.3…v0.8.4](https://github.com/mex-memory/mex/compare/v0.8.3...v0.8.4).
+The comparison becomes available when the release tag is published.
diff --git a/docs/code-graph-support.md b/docs/code-graph-support.md
index 67f9dbcc..829ed86e 100644
--- a/docs/code-graph-support.md
+++ b/docs/code-graph-support.md
@@ -1,6 +1,6 @@
 # Code graph support
 
-This page documents the fixture-backed code-graph support included in mex 0.8.3.
+This page documents the fixture-backed code-graph support included in mex 0.8.4.
 
 This page distinguishes three evidence levels:
 
diff --git a/docs/design/0.8.4-release-plan.md b/docs/design/0.8.4-release-plan.md
new file mode 100644
index 00000000..a82e9d37
--- /dev/null
+++ b/docs/design/0.8.4-release-plan.md
@@ -0,0 +1,246 @@
+# MEX 0.8.4 release preparation
+
+Release branch: `codex/release-0.8.4`, based on main
+`54f7d7a538bd0c77abf21484893bee74f4c0bb68`, with the terminal setup work in
+`5a9035eed696d5e282004a892e8aaef3e026eb48` and the default-routing follow-up.
+Preparation started October 9, 2026. The maintainer selected 0.8.4 and authorized
+release preparation and a PR. This is an unpublished release; merge, tagging,
+npm publication, and a GitHub release are separate actions.
+
+## Scope
+
+The previous release is [v0.8.3](https://github.com/mex-memory/mex/releases/tag/v0.8.3),
+at `8a1e39b1e52e92b40b203da411b54cc955a256aa`. Its GitHub publication timestamp is
+September 27, 2026 UTC (September 28 in the maintainer's timezone).
+
+0.8.4 includes the changes since that tag, including the Graph/Wiki performance,
+grounding, search, and knowledge-adoption changes already on main. The PR adds
+terminal setup as the default, the spaced lowercase cyan banner, native agent
+handoff, real graph activity, resumable outcomes, authored setup errors, and
+the release metadata and documentation. The packaged smoke follows the new
+noninteractive setup contract instead of answering removed numeric prompts.
+
+Current package versions, capability fixtures, installation examples, and
+release links move to 0.8.4. Historical changelog and design records retain
+their original versions. Private workspace versions, dependency versions, and
+installed-skill provenance are independent of the published CLI version.
+Unrelated managed-skill edits, local `.mex/config.json`, and Discord artwork
+remain outside the PR.
+
+## Compatibility and remaining work
+
+Upgrade every collaborator before committing new `mh2:` groundings: 0.8.3 and
+earlier clients cannot read that encoding. Preserve the existing graph for the
+first refresh, review changes through `mex check` and `mex sync`, and rebuild
+the Wiki index when needed. See [COMPATIBILITY.md](../../COMPATIBILITY.md) for
+the exact upgrade sequence and additive public API changes already on main.
+The maintainer's explicit 0.8.4 selection is a release-specific exception to
+the usual minor-version policy for additive public fields.
+
+The setup presentation and diagnostics do not fix large-repository compiler
+heap exhaustion. Browser setup's existing readiness shortcut can also offer
+completion after a failed finalization if its placeholder/index-presence checks
+pass; oversized population prompts can exceed the private run-response limit.
+Those remain follow-ups and must not be represented as solved by this release.
+Fresh-project interview changes remain outside this work.
+
+## Verification
+
+Release validation uses isolated temporary copies. Rebuilding a running
+setup/Hub's original `dist/` can remove chunks that process still needs, so the
+developer checkout's active build must stay intact during those checks.
+
+1. **Public API — pass.** This PR leaves `src/index.ts` unchanged. The built
+   public declarations are byte-identical to the previous build. Public API
+   changes already on main since 0.8.3 are documented in the compatibility guide.
+2. **Read/write authority — pass.** Entry discovery has real-fixture non-mutation
+   coverage. Setup preserves its existing write and explicit-commit boundaries;
+   the architecture inventory now pins the bounded worker diagnostic sink to
+   stderr only.
+3. **Bounded work — pass.** Inputs, retained diagnostics, output, and rendering
+   bounds remain covered; no resource budget is widened. Packed setup subprocess
+   checks use a 120-second timeout and a 4 MiB output limit.
+4. **Tests and types — pass with reruns recorded.** The broad root run, excluding
+   the build-owning CLI file to prevent concurrent build replacement, completed
+   with 4,708 passing tests, eight failures, and two skips on Node 24.4.1/macOS.
+   Four failures came from omitted Git/tracked scaffold metadata in the temporary
+   copy, one from the new stderr writer missing in the architecture inventory,
+   and two from Node 24.4.1 `rmSync` rejecting directory-symlink fixture cleanup.
+   The cleanup now explicitly unlinks a confirmed symlink, preserving the
+   containment assertions. The remaining Hub Wiki-read failure did not reproduce
+   in either its isolated case or the full file; no runtime retry was added.
+   All affected files passed their reruns: 91 tests on Node 22.17.1 plus 52 on
+   Node 24.4.1. Version/capability/install tests passed (26); the separately run
+   CLI suite passed (33). Root and Hub workspace typechecks passed.
+5. **Build, packaging, and acceptance — pass.** The CLI suite's standard
+   production build passed on Node 22.17.1. The built CLI reports 0.8.4; all 16
+   real-PTY setup cases, seven built CLI smoke cases, and three setup-completion
+   browser cases passed. Fresh packed-install Hub and official-skills smoke
+   passed with an isolated MEX home and npm cache. Graph evaluator tests passed
+   (39), and comparison evaluator tests passed (47). Their first temporary-copy
+   attempts needed the live log moved outside the repository's identity hash
+   and a fixture Git HEAD; no evaluator code or limits changed.
+6. **Diff hygiene — pass.** Whitespace, local document links, version pins, and
+   historical release preservation checks passed. Non-version lockfile fields
+   are unchanged. Generated state and unrelated files remain unstaged.
+7. **Protocols — pass.** Graph/Wiki schemas, extraction, identity, and candidate
+   IPC shapes are unchanged by the setup/release PR. Progress uses the existing
+   maintenance events; bounded worker diagnostics remain terminal-only.
+
+Pending: exact-head CI and maintainer review before merge/publication.
+
+### PR #271 CI follow-up
+
+The [first PR run](https://github.com/mex-memory/mex/actions/runs/37973046420)
+at `8fc1449` passed Node 24, macOS portability, browser, and release-performance
+checks. Two test assumptions failed:
+
+- Node 22 passed 4,746 tests but failed an entry-discovery non-mutation snapshot
+  because `.git/objects/maintenance.lock` disappeared. Fixture commits could
+  leave automatic Git maintenance running after the commit returned. The test
+  helper now passes command-scoped `maintenance.auto=false`; the full project
+  and Git-byte snapshots remain intact. A local Git trace confirmed the default
+  fixture commit launched detached maintenance and the override prevented it.
+- Windows portability passed 545 tests but the abrupt graph-worker death case
+  expected POSIX `SIGKILL`. The test now requires a nonzero numeric exit code
+  with a null signal on Windows, and `SIGKILL` with a null exit code on POSIX.
+  It also checks that the worker is dead, retaining workspace/sidecar cleanup
+  and unchanged-live-graph assertions.
+
+The fix changes tests and documentation only. Focused local tests passed on
+Node 22.17.1/macOS (eight entry cases and 20 candidate-process cases), followed
+by the root and both Hub workspace typechecks. Exact Windows and Linux/Git
+runner verification remains a gate in the next PR run; production behavior,
+protocols, resource limits, and build outputs are unchanged.
+
+### PR #271 review fixes
+
+The Windows review identified a pending stdin read after native handoff, a
+short-path/case mismatch in packed CLI discovery, an unrealistically short
+malformed-worker startup deadline, and Wiki grounding refusing a stable graph
+solely because an unrelated file parsed incompletely. Follow-up findings covered
+stale completion text after a browser commit, vanished migration notices,
+Finish later reporting failure, narrow footer/link usability, and a cleanup
+signal presented as the worker failure's cause.
+
+Terminal close now pauses and unrefs stdin. A real-PTY copy-link round trip
+also exposed readline's paused input stream after returning to the HUD. Manual
+prompt/link questions keep the cooked terminal without its keypress decoder;
+the remounted HUD resumes reads after installing its input handler.
+`l` prints the full Hub URL outside the frame; footer variants fit the available
+width. Details retain at most 64 events, 1,024 characters each, and 16,384 total,
+open at the current diagnostic, and permit scrolling back. Finish later clears
+the prior population failure for its explicit paused outcome, and stopping the
+Hub rechecks the commit readiness before selecting the final message. Worker
+diagnostics retain the actual signal and mark supervisor cleanup separately.
+
+Only the Wiki grounding bridge admits parse-only graph degradation. It filters
+nodes, symbols, fingerprints, and source evidence to fully parsed files, abstains
+from missing-target reconciliation, and names the incomplete files. Source and
+configuration drift still refuse; final snapshot/source revalidation still
+discards a prepared publication on change. General GraphPort reads keep their
+existing stricter gate. Public exports and protocol/index schemas are unchanged.
+
+The [second PR run](https://github.com/mex-memory/mex/actions/runs/37975590426)
+at `10aca78` passed Node 22/24, macOS, and browser checks. Windows failed at the
+packed PATH guard now corrected to compare canonical filesystem paths. The
+release-performance gate confirmed four Wiki wall-time breaches on both fresh
+runners: small refresh/rebuild, medium rebuild, and large rebuild. Retained
+reports match the earlier passing run's environment, configuration, production
+asset measurements, and fixture sizes; the intervening commit changed tests and
+documentation only. This establishes comparable runs, not the cause of the
+timing difference. No budget or confirmation rule was widened. A fresh passing
+performance run on the final commit remains mandatory before merge.
+
+Local review-fix verification on Node 22.17.1/macOS:
+
+1. **Public API — pass.** `src/index.ts` is unchanged; final `index.d.ts` is
+   byte-identical to a declaration build of the previous PR head.
+2. **Read/write authority — pass.** Real Wiki apply accepts exact healthy-file
+   groundings, rejects partial-file groundings without canonical changes, blocks
+   source/config drift, and discards prepared publication after a source change.
+3. **Bounds — pass.** History, per-event text, rendered diagnostics, incomplete
+   path reporting, and existing Graph/Wiki request limits remain bounded.
+4. **Tests/types — pass after isolated reruns.** The broad suite excluding the
+   separately built CLI/PTY files passed 4,708 tests and skipped two; seven tests
+   in two Git-heavy files hit their existing deadlines. Both entire files passed
+   their single-worker rerun (90 tests), without increasing a deadline. Focused
+   review tests passed (233), followed by 69 final boundary tests after input
+   cleanup changes and three grounding cases with additional projection/missing
+   target assertions. Root and both Hub workspace typechecks passed.
+5. **Build/acceptance — pass.** Final production build, the separate CLI suite
+   (33), built smoke (seven), real PTY setup (18), setup commit/completion browser
+   cases (three), fresh packed-install Hub/skills smoke, and evaluator suites
+   (39 Graph, 47 comparison) passed. Intermediate temporary copies needed their
+   mascot/dependency assets included; no product workaround was added.
+6. **Diff hygiene — pass.** `git diff --check` passes. Generated indexes, local
+   state, build outputs, managed-skill edits, config, and Discord work stay out
+   of the review-fix commit.
+7. **Contracts — pass.** Stable codes, ordering, cursors, snapshot revocation,
+   non-mutation, and failed-publication coverage pass. No protocol or schema
+   version changes are introduced.
+
+Final exact-head CI remains pending. Native Windows console behavior still
+needs the reviewer's rerun; the POSIX PTY harness does not claim Windows coverage.
+
+### Windows return and parse-degraded check follow-up
+
+A Windows 11 ConPTY rerun of `a86f9b6` (Node 24.11) drove the HUD with real
+keystrokes and a stand-in interactive agent. Native handoff then `q` exited 0,
+confirming the stdin shutdown fix. Returning from the manual prompt (2 of 2) or
+the Hub link view (1 of 1) did not: after Enter the HUD never resumed input, and
+neither Ctrl+C nor Enter released the process. `10aca78` returned correctly from
+the same prompt script.
+
+A standalone Ink probe isolated the cause. After any parent read of the console
+between mounts (readline in either terminal mode, or a raw `data` listener), the
+next Ink renderer received no keys while the event loop kept running. A child
+process reading the inherited console, as the native handoff does, left the
+next renderer working. Both Enter waits now use a short-lived Node child: exit 0
+on Enter, non-zero at end of input or on a signal. Ctrl+C reaches MEX as SIGINT
+and cancels as before. The link view also started inside Ink's input handler,
+where unmounting let Ink's read loop begin a cooked read that consumed the
+Enter, so it now starts after the handler returns. Closing the HUD releases a
+pending link wait.
+
+`mex check` published grounding findings only for a fresh graph or one stale
+solely by changed source. A graph degraded only by an incompletely parsed file
+therefore skipped every grounding and scored 100, even for a link to a node id
+that does not exist. The read-only grounding runtime now binds snapshots whose
+only shortfalls are changed source and/or incomplete parses. Nodes in fully
+parsed files receive the same verdicts as on a fresh graph. Nodes in partial or
+failed files, and nodes the snapshot lacks, are `GROUNDING_UNVERIFIED` with the
+files named. Nothing is reconciled, findings are discarded if the graph changes
+mid-check, and configuration drift still skips grounding.
+
+The `headless-population` launch-failure test used cross-spawn for a missing
+file. On Windows that starts `cmd.exe`, so the activity callback fired before
+the expected launch error. The test now uses Node's `spawn`, which fails before
+starting on every platform; production code is unchanged.
+
+Verification on Windows 11, Node 24.11:
+
+1. **ConPTY acceptance — pass.** Prompt → Enter → Up/Enter on Finish later exits
+   2; prompt → Enter → Ctrl+C exits 130; Hub link → Enter → `d` opens details and
+   `q` or Ctrl+C stops the Hub with exit 0; native handoff → `q` exits 0. Each
+   scenario passed twice on the final build.
+2. **Grounding — pass.** On a repository with an unparseable fixture, setup
+   `--yes` finalizes and captures the healthy grounding. `mex check` reports
+   body drift in a healthy file, and an unverified link for a partial-file or
+   missing target with the file named. A fresh graph gives the same verdicts
+   for healthy files. The new parse-gap tests fail without the fix.
+3. **Tests/types — pass.** Root and Hub typechecks pass. New tests: Enter-wait
+   child (6), parse-degraded check (2). Across drift, setup, Wiki, grounding,
+   and check suites, 2,371 tests passed. Nine failed in five files: Wiki
+   migration/adapter timeouts, an index concurrency race, two graph freshness
+   swap cases, and a `wiki-sweep` module load. The same nine fail at the
+   pre-fix merge commit in this Windows environment, so they are not
+   regressions.
+
+## Publication checklist
+
+- Review the PR and require its applicable CI, including Node 22/24, portability,
+  browser, packaging, and pinned performance jobs.
+- Confirm the changelog date matches publication day.
+- Merge, tag, publish npm, and create the GitHub release only through separately
+  authorized release actions. Preparing this PR does not perform them.
diff --git a/package-lock.json b/package-lock.json
index fc1666c8..ba4c37f8 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "mex-agent",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "mex-agent",
-      "version": "0.8.3",
+      "version": "0.8.4",
       "license": "MIT",
       "workspaces": [
         "packages/*"
diff --git a/package.json b/package.json
index 67bdbcda..097e7f8b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mex-agent",
-  "version": "0.8.3",
+  "version": "0.8.4",
   "description": "Persistent project memory and deterministic local code graphs for AI coding agents",
   "type": "module",
   "main": "./dist/index.js",
diff --git a/packages/hub-web/src/app/setup-page.test.tsx b/packages/hub-web/src/app/setup-page.test.tsx
index c1d976bc..5b8da333 100644
--- a/packages/hub-web/src/app/setup-page.test.tsx
+++ b/packages/hub-web/src/app/setup-page.test.tsx
@@ -280,6 +280,47 @@ describe("Hub setup wizard", () => {
     expect(screen.getByRole("button", { name: "Resume setup" })).toBeEnabled();
   });
 
+  it("switches from startup activity to the first real transcript and keeps it through the commit checkpoint and refresh", async () => {
+    const at = new Date().toISOString();
+    const transcriptId = "a944e8d9-7e02-4d04-9a62-d8b347b8e7dc";
+    const harness = setupHarness({ hasScaffold: true }, {
+      status: "running", populationTool: "codex", selectedTools: ["codex"],
+      progress: { step: "population", label: "Populating MEX" },
+      populationActivity: { tool: "codex", startedAt: at, lastActivityAt: null, totalEvents: 1,
+        events: [{ id: 1, at, kind: "starting", state: "running" }] },
+    });
+    const view = renderSetup(harness.api);
+    expect(await screen.findByRole("list", { name: "Recent agent activity" })).toHaveTextContent("Starting the background session");
+    expect(screen.queryByRole("region", { name: "Background session output" })).toBeNull();
+    expect(harness.api.subscribeToSetupTranscript).not.toHaveBeenCalled();
+    await waitForSubscription(harness, 1);
+
+    act(() => harness.snapshot({ transcriptId }));
+    await waitFor(() => expect(harness.api.subscribeToSetupTranscript).toHaveBeenCalledOnce());
+    const batch: SetupTranscriptBatch = {
+      runId: transcriptId, cursor: 1, firstId: 1, truncated: false, done: false,
+      entries: [{ id: 1, at, kind: "assistant", text: "I have updated the project memory.", truncated: false }],
+    };
+    act(() => harness.sendTranscript(batch));
+    expect(screen.getByText("I have updated the project memory.")).toBeVisible();
+    expect(screen.queryByRole("list", { name: "Recent agent activity" })).toBeNull();
+
+    act(() => harness.snapshot({ progress: { step: "finalize", label: "Finalize MEX" } }));
+    await waitFor(() => expect(screen.getByText("I have updated the project memory.")).toBeVisible());
+    act(() => harness.sendTranscript({ ...batch, done: true }));
+    act(() => harness.complete({ status: "paused", stage: "needs_commit", populated: true, commitCommands }, {
+      stage: "needs_commit", populated: true, commitCommands,
+    }));
+    expect(await screen.findByRole("button", { name: "Check commit and continue" })).toBeVisible();
+    expect(screen.getByText("I have updated the project memory.")).toBeVisible();
+    expect(screen.getByText("Session ended")).toBeVisible();
+
+    view.unmount();
+    renderSetup(harness.api);
+    await waitFor(() => expect(screen.getByText("I have updated the project memory.")).toBeVisible());
+    expect(screen.queryByText("This session produced no output.")).toBeNull();
+  });
+
   it.each(["claude", "codex"] as const)("restores %s population activity on refresh and accepts real SSE updates without a percentage", async (tool) => {
     // Keep async bootstrap/render duration out of the elapsed-time assertion.
     vi.spyOn(Date, "now").mockReturnValue(Date.now());
diff --git a/scripts/hub-pack-smoke.mjs b/scripts/hub-pack-smoke.mjs
index e9b31149..4b07fff5 100644
--- a/scripts/hub-pack-smoke.mjs
+++ b/scripts/hub-pack-smoke.mjs
@@ -7,6 +7,7 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  realpathSync,
   readdirSync,
   rmSync,
   statSync,
@@ -183,7 +184,7 @@ try {
   }
 
   const beforeSetupHead = run("git", ["rev-parse", "HEAD"], project).trim();
-  const setupOutput = await runInteractiveAgentSetup(cli, project, work);
+  const setupOutput = runNoninteractiveAgentSetup(cli, project, work);
   verifyPackedSetupOutput(setupOutput);
   verifySetupConfig(project);
   verifySetupIgnoreProtection(project);
@@ -1046,15 +1047,16 @@ async function verifyFreshCodeRepoSetup(tarball, workRoot, cache, version) {
   const cli = join(installed, "dist", "cli.js");
   const agentBin = join(workRoot, "fresh-setup-agent-bin");
   mkdirSync(agentBin, { recursive: true });
-  installFakeCodex(agentBin, workRoot);
+  const agentInvocation = installSetupAgentGuards(agentBin, workRoot);
 
   const beforeHead = run("git", ["rev-parse", "HEAD"], project).trim();
-  const output = await runFreshCodeRepoSetup(cli, project, agentBin);
+  const output = runFreshCodeRepoSetup(cli, project, agentBin, agentInvocation);
   const normalized = output.replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "");
   for (const expected of [
-    "Codex finished the population session",
+    "Setup paused: scaffold population is still required.",
+    "Population prompt:",
     "Wiki migration and index are ready.",
-    "Graph and Wiki are ready. Setup is ready to commit.",
+    "Graph and Wiki are ready. Review and commit the canonical MEX setup.",
   ]) {
     if (!normalized.includes(expected)) {
       throw new Error(`Packed fresh setup omitted: ${expected}\n${normalized}`);
@@ -1082,7 +1084,7 @@ async function verifyFreshCodeRepoSetup(tarball, workRoot, cache, version) {
   ]) {
     const content = readFileSync(join(project, ".mex", file), "utf8");
     if (content.includes("[Project Name]") || content.includes("[YYYY-MM-DD]")) {
-      throw new Error(`Fake Codex population left a required placeholder in ${file}.`);
+      throw new Error(`Manual fixture population left a required placeholder in ${file}.`);
     }
   }
   for (const database of ["graph.db", "wiki.db"]) {
@@ -1115,171 +1117,148 @@ async function verifyFreshCodeRepoSetup(tarball, workRoot, cache, version) {
   }
 }
 
-function installFakeCodex(directory, workRoot) {
-  const script = join(workRoot, "fake-codex-populate.mjs");
+function installSetupAgentGuards(directory, workRoot) {
+  const invocation = join(workRoot, "unexpected-setup-agent.json");
+  const script = join(workRoot, "unexpected-setup-agent.mjs");
   writeFileSync(script, [
-    'import { readFileSync, readdirSync, writeFileSync } from "node:fs";',
-    'import { join } from "node:path";',
-    'const root = join(process.cwd(), ".mex");',
-    'const visit = (directory) => {',
-    '  for (const entry of readdirSync(directory, { withFileTypes: true })) {',
-    '    const path = join(directory, entry.name);',
-    '    if (entry.isDirectory()) visit(path);',
-    '    else if (entry.isFile() && entry.name.endsWith(".md")) {',
-    '      const content = readFileSync(path, "utf8")',
-    '        .replaceAll("[Project Name]", "Packed First Run")',
-    '        .replaceAll("[YYYY-MM-DD]", "2026-09-02");',
-    '      writeFileSync(path, content, "utf8");',
-    '    }',
-    '  }',
-    '};',
-    'visit(root);',
-    'process.stdout.write("fake Codex populated the scaffold\\n");',
+    'import { writeFileSync } from "node:fs";',
+    `writeFileSync(${JSON.stringify(invocation)}, JSON.stringify(process.argv));`,
+    'process.stderr.write("Noninteractive setup must not launch an agent.\\n");',
+    'process.exitCode = 99;',
     '',
   ].join("\n"), "utf8");
-  if (process.platform === "win32") {
-    writeFileSync(join(directory, "codex.cmd"), `@"${process.execPath}" "${script}" %*\r\n`, "utf8");
-  } else {
-    const command = join(directory, "codex");
-    writeFileSync(command, `#!/bin/sh\nexec "${process.execPath}" "${script}" "$@"\n`, "utf8");
-    chmodSync(command, 0o755);
+  for (const command of ["claude", "codex"]) {
+    if (process.platform === "win32") {
+      writeFileSync(join(directory, `${command}.cmd`), `@"${process.execPath}" "${script}" %*\r\n`, "utf8");
+    } else {
+      const executable = join(directory, command);
+      writeFileSync(executable, `#!/bin/sh\nexec "${process.execPath}" "${script}" "$@"\n`, "utf8");
+      chmodSync(executable, 0o755);
+    }
   }
+  return invocation;
 }
 
-function runFreshCodeRepoSetup(cli, project, agentBin) {
-  const env = {
-    ...process.env,
-    MEX_TELEMETRY: "0",
-    NO_COLOR: "1",
-    PATH: `${agentBin}${delimiter}${process.env.PATH ?? ""}`,
-  };
-  return new Promise((resolveOutput, reject) => {
-    const setup = spawn(process.execPath, [cli, "setup", "--cli"], {
-      cwd: project,
-      env,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    let selected = false;
-    let settled = false;
-    const finish = (error, output) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (error) reject(error);
-      else resolveOutput(output);
-    };
-    const timer = setTimeout(() => {
-      if (setup.exitCode === null) setup.kill("SIGKILL");
-      finish(new Error(`Timed out running packed fresh setup.\n${stdout}\n${stderr}`));
-    }, 120_000);
-    setup.stdout.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
-      if (!selected && stdout.includes("Choice [1-8] (default: 1):")) {
-        selected = true;
-        setup.stdin.end("6\n");
-      }
-    });
-    setup.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
-    setup.on("error", (error) => finish(error));
-    setup.on("close", (code, signal) => {
-      if (code !== 0 || signal !== null || !selected) {
-        finish(new Error(
-          `Packed fresh setup failed (exit ${String(code)}, signal ${String(signal)}).\n${stdout}\n${stderr}`,
-        ));
-        return;
+function populateSetupFixture(project) {
+  // Stand in for an explicit user/agent edit after the plain CLI pauses. The
+  // setup command itself must never invoke the available fake agent above.
+  const visit = (directory) => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) visit(path);
+      else if (entry.isFile() && entry.name.endsWith(".md")) {
+        const before = readFileSync(path, "utf8");
+        const after = before
+          .replaceAll("[Project Name]", "Setup Fixture")
+          .replaceAll("[YYYY-MM-DD]", "2026-09-02");
+        if (after !== before) writeFileSync(path, after, "utf8");
       }
-      finish(null, stdout);
-    });
-  });
+    }
+  };
+  visit(join(project, ".mex"));
 }
 
-function runInteractiveAgentSetup(cli, project, workRoot) {
+function runFreshCodeRepoSetup(cli, project, agentBin, agentInvocation) {
+  const env = { ...process.env, MEX_TELEMETRY: "0", NO_COLOR: "1" };
+  // Replace every spelling of PATH, including Path on Windows, so the sentinel
+  // agents always win over any developer-machine installation.
+  const originalPath = Object.entries(env).find(([key]) => key.toLowerCase() === "path")?.[1] ?? "";
+  for (const key of Object.keys(env)) {
+    if (key.toLowerCase() === "path") delete env[key];
+  }
+  env.PATH = `${agentBin}${delimiter}${originalPath}`;
+  const locatedAgent = spawnSync(
+    locateSmokeExecutable(process.platform === "win32" ? "where.exe" : "which"),
+    ["codex"],
+    { cwd: project, env, encoding: "utf8", timeout: 5_000, windowsHide: true },
+  );
+  const expectedAgent = join(agentBin, process.platform === "win32" ? "codex.cmd" : "codex");
+  // where.exe expands Windows short paths and normalizes their case.
+  const canonical = (path) => {
+    const real = realpathSync.native(path);
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  };
+  const locatedPath = locatedAgent.stdout?.split(/\r?\n/u)[0].trim();
+  if (locatedAgent.error || locatedAgent.status !== 0
+    || !locatedPath || canonical(locatedPath) !== canonical(expectedAgent)) {
+    throw new Error("The packed fresh setup smoke did not expose its guarded Codex CLI first on PATH.");
+  }
+  const assertNoAgent = () => {
+    if (existsSync(agentInvocation)) {
+      throw new Error("Packed noninteractive setup launched an agent instead of pausing for manual population.");
+    }
+  };
+  return runManualPopulationSetup(cli, project, env, ["codex"], { assertNoAgent });
+}
+
+function runNoninteractiveAgentSetup(cli, project, workRoot) {
   const emptyPath = join(workRoot, "empty-agent-path");
   mkdirSync(emptyPath, { recursive: true });
 
-  // This fixture exercises the code Hub after setup, so persist code-repo intent.
-  // Keep the packed smoke independent from developer-machine agent installs.
-  // Launch Node by absolute path and restrict PATH to Git, then prove the
-  // selected agent CLIs are absent before exercising manual population.
+  // Also exercise selected integrations when no corresponding agent CLI is
+  // installed. Keep Node absolute and prove the restricted PATH still has Git.
   const env = { ...process.env, MEX_TELEMETRY: "0", NO_COLOR: "1" };
   for (const key of Object.keys(env)) {
     if (key.toLowerCase() === "path") delete env[key];
   }
   env.PATH = installGitOnlyPath(emptyPath);
   verifyManualSetupEnvironment(project, env);
+  return runManualPopulationSetup(cli, project, env, ["claude", "codex"], { legacyCli: true });
+}
 
-  return new Promise((resolveOutput, reject) => {
-    const setup = spawn(process.execPath, [cli, "setup", "--cli", "--mode", "code-repo"], {
-      cwd: project,
-      env,
-      stdio: ["pipe", "pipe", "pipe"],
-    });
-    let stdout = "";
-    let stderr = "";
-    let choseMultiple = false;
-    let choseClients = false;
-    let settled = false;
+function runManualPopulationSetup(cli, project, env, tools, {
+  legacyCli = false,
+  assertNoAgent = () => {},
+} = {}) {
+  const entryOptions = legacyCli ? ["--cli"] : [];
+  const paused = runPlainSetup(cli, project, env, [
+    ...entryOptions, "--mode", "code-repo", ...tools.flatMap((tool) => ["--tool", tool]),
+  ], 2);
+  assertNoAgent();
+  for (const expected of ["Setup paused: scaffold population is still required.", "Population prompt:"]) {
+    if (!paused.includes(expected)) {
+      throw new Error(`Packed setup omitted its manual population checkpoint: ${expected}\n${paused}`);
+    }
+  }
 
-    const fail = (error) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (setup.exitCode === null) setup.kill("SIGKILL");
-      reject(error);
-    };
-    const answer = (value) => {
-      if (setup.stdin.destroyed || !setup.stdin.writable) {
-        fail(new Error(`The packed setup closed stdin before all prompts were answered.\n${stderr}`));
-        return;
-      }
-      setup.stdin.write(`${value}\n`);
-    };
-    const drivePrompts = () => {
-      if (!choseMultiple && stdout.includes("Choice [1-8] (default: 1):")) {
-        choseMultiple = true;
-        answer("7");
-      }
-      if (!choseClients && stdout.includes("Enter tool numbers separated by spaces")) {
-        choseClients = true;
-        answer("1 6");
-        setup.stdin.end();
-      }
-    };
-    const timer = setTimeout(() => {
-      fail(new Error(`Timed out driving the packed interactive setup.\n${stdout}\n${stderr}`));
-    }, 60_000);
+  populateSetupFixture(project);
+  // Omitting mode and tools on resume must retain the user's persisted choices.
+  const completed = runPlainSetup(cli, project, env, entryOptions, 0);
+  assertNoAgent();
+  for (const expected of [
+    "Wiki migration and index are ready.",
+    "Graph and Wiki are ready. Review and commit the canonical MEX setup.",
+    "Run `mex setup --browser` to open the setup completion page.",
+  ]) {
+    if (!completed.includes(expected)) {
+      throw new Error(`Packed setup did not finish preparation after manual population: ${expected}\n${completed}`);
+    }
+  }
+  return `${paused}\n${completed}`;
+}
 
-    setup.stdout.on("data", (chunk) => {
-      stdout += chunk.toString("utf8");
-      drivePrompts();
-    });
-    setup.stderr.on("data", (chunk) => { stderr += chunk.toString("utf8"); });
-    setup.on("error", (error) => {
-      fail(new Error(`The packed interactive setup could not start: ${error.message}`, {
-        cause: error,
-      }));
-    });
-    setup.on("close", (code, signal) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      if (
-        code !== 0
-        || signal !== null
-        || !choseMultiple
-        || !choseClients
-      ) {
-        reject(new Error(
-          `The packed interactive setup did not complete all expected prompts `
-          + `(exit ${String(code)}, signal ${String(signal)}).\n${stdout}\n${stderr}`,
-        ));
-        return;
-      }
-      resolveOutput(stdout);
-    });
+function runPlainSetup(cli, project, env, options, expectedExit) {
+  const args = [cli, "setup", "--yes", "--no-open", ...options];
+  const result = spawnSync(process.execPath, args, {
+    cwd: project,
+    env,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: 120_000,
+    maxBuffer: 4 * 1024 * 1024,
+    windowsHide: true,
   });
+  if (result.error || result.status !== expectedExit || result.signal !== null) {
+    throw new Error(
+      `Packed plain setup expected exit ${expectedExit}, got ${String(result.status)}`
+      + ` (signal ${String(result.signal)}).\n${result.stdout}\n${result.stderr}`,
+      { cause: result.error },
+    );
+  }
+  if (result.stdout.includes("\u001b[?1049h") || /Choice \[1-8\]|Enter tool numbers/u.test(result.stdout)) {
+    throw new Error("Packed noninteractive setup rendered an interactive tool picker.");
+  }
+  return result.stdout;
 }
 
 function installGitOnlyPath(directory) {
@@ -1330,22 +1309,18 @@ function verifyManualSetupEnvironment(project, env) {
 
 function verifyPackedSetupOutput(output) {
   const normalized = output.replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "");
-  const expectedActions = [
-    "Install the packaged mex-inbox skill at .claude/skills/mex-inbox.",
-    "Install the packaged mex-relay skill at .claude/skills/mex-relay.",
-    "Append the MEX-managed instruction block to CLAUDE.md without changing its existing bytes.",
-    "Install the packaged mex-inbox skill at .agents/skills/mex-inbox.",
-    "Install the packaged mex-relay skill at .agents/skills/mex-relay.",
-    "Append the MEX-managed instruction block to AGENTS.md without changing its existing bytes.",
+  const expectedMessages = [
+    "Link AI tool instructions",
+    "Install official MEX agent skills",
+    "Setup paused: scaffold population is still required.",
+    "Population prompt:",
+    "Wiki migration and index are ready.",
+    "Graph and Wiki are ready. Review and commit the canonical MEX setup.",
   ];
-  const sessionGuarantee = "Start a new Claude Code and Codex session to guarantee the new skills and project instructions are loaded.";
-  if (
-    !normalized.includes("Choice [1-8] (default: 1):")
-    || !normalized.includes("Enter tool numbers separated by spaces")
-    || !expectedActions.every((message) => normalized.includes(message))
-    || !normalized.includes(sessionGuarantee)
-  ) {
-    throw new Error("The packed interactive setup omitted its two-client install actions or new-session guarantee.");
+  // Installation itself is checked against the exact packaged trees, managed
+  // instructions and both clients' idempotent sync reports below.
+  if (!expectedMessages.every((message) => normalized.includes(message))) {
+    throw new Error("The packed plain setup omitted its install, manual population, or completion status.");
   }
 }
 
@@ -1361,7 +1336,7 @@ function verifySetupConfig(project) {
       readOnly: ["context/read-only/**"],
     })
   ) {
-    throw new Error("The packed interactive setup did not persist code-repo intent and both clients while preserving existing config.");
+    throw new Error("The packed plain setup did not preserve code-repo intent, both clients, and existing config on resume.");
   }
 }
 
diff --git a/src/cli.ts b/src/cli.ts
index c71e235b..1a396e16 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -1,5 +1,5 @@
 import chalk from "chalk";
-import { Command, InvalidArgumentError } from "commander";
+import { Command, InvalidArgumentError, Option } from "commander";
 import { realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -175,6 +175,36 @@ async function runBrowserCommand(options: { port?: number; open: boolean; mode?:
   await launchHub({ port: options.port, openBrowser: options.open, mode: options.mode, setup: options.setup });
 }
 
+async function reportSetupCommandError(error: unknown): Promise<void> {
+  const { SetupError } = await import("./setup/errors.js");
+  console.error(error instanceof SetupError ? error.userMessage : error instanceof Error ? error.message : String(error));
+  if (error instanceof SetupError && error.message !== error.userMessage) console.error(`Diagnostics: ${error.message}`);
+  process.exitCode = 1;
+}
+
+async function runSetupCommand(options: {
+  browser?: boolean; dryRun?: boolean; mode?: string; port?: number; open: boolean; tool?: string[]; yes?: boolean;
+}): Promise<void> {
+  try {
+    if (options.browser) {
+      await runBrowserCommand({ ...options, setup: true });
+      return;
+    }
+    const setup = await import("./setup/index.js");
+    const result = await setup.runSetup({
+      dryRun: options.dryRun,
+      mode: options.mode,
+      port: options.port,
+      openBrowser: options.open,
+      ...(options.tool === undefined ? {} : { tools: setup.parseSetupTools(options.tool) }),
+      ...(options.yes ? { yes: true } : {}),
+    });
+    process.exitCode = result.exitCode;
+  } catch (error) {
+    await reportSetupCommandError(error);
+  }
+}
+
 // ── Telemetry hooks ──
 
 const cliTelemetry = createCliTelemetry(captureEvent, flush, undefined, (command) => {
@@ -192,7 +222,13 @@ program
   .option("--port <n>", "Bind a specific loopback port", parsePortArg)
   .option("--no-open", "Print the Hub link without opening a browser")
   .action(async (opts: { port?: number; open: boolean }) => {
-    await runBrowserCommand(opts);
+    try {
+      const { resolveDefaultEntry } = await import("./setup/entry.js");
+      if (await resolveDefaultEntry() === "hub") await runBrowserCommand(opts);
+      else await runSetupCommand(opts);
+    } catch (error) {
+      await reportSetupCommandError(error);
+    }
   });
 
 program
@@ -301,37 +337,20 @@ program.addCommand(buildSpecCommand({
   io: processTeamCommandIo(),
 }));
 
-// ── Setup (browser by default; explicit terminal and read-only paths) ──
+// ── Setup (terminal by default; explicit browser and read-only paths) ──
 program
   .command("setup")
-  .description("Set up MEX in the local Hub; use --cli for terminal setup")
-  .option("--cli", "Run setup in the terminal")
+  .description("Set up MEX in the terminal; use --browser for browser setup")
+  .option("--cli", "Run setup in the terminal (the default)")
+  .addOption(new Option("--browser", "Run setup in the local browser Hub").conflicts(["cli", "dryRun", "tool", "yes"]))
   .option("--mode <mode>", "Template mode: code-repo or agent-memory (preserves saved mode)")
   .option("--dry-run", "Show what would happen without making changes")
   .option("--port <n>", "Bind a specific loopback port", parsePortArg)
-  .option("--no-open", "Print the setup link without opening a browser")
-  .option("--tool <tool>", "Terminal setup: use this AI tool instead of asking (repeatable; none for no tool)", (value: string, previous: string[] = []) => [...previous, value])
+  .option("--no-open", "Show the Hub link without opening a browser")
+  .option("--tool <tool>", "Terminal setup: preselect an AI tool (repeatable; none for no tool; --yes skips review)", (value: string, previous: string[] = []) => [...previous, value])
   .option("--yes", "Terminal setup: never wait on a question (for scripts and CI)")
   .action(async (_opts, command: Command) => {
-    const opts = command.optsWithGlobals<{ cli?: boolean; dryRun?: boolean; mode?: string; port?: number; open: boolean; tool?: string[]; yes?: boolean }>();
-    try {
-      if (opts.cli || opts.dryRun || opts.tool !== undefined || opts.yes) {
-        if (opts.port !== undefined || opts.open === false) throw new Error("--port and --no-open apply to browser setup. Omit them with --cli or --dry-run.");
-        const setup = await import("./setup/index.js");
-        await setup.runSetup({
-          dryRun: opts.dryRun,
-          mode: opts.mode,
-          ...(opts.tool === undefined ? {} : { tools: setup.parseSetupTools(opts.tool) }),
-          ...(opts.yes ? { yes: true } : {}),
-        });
-      } else {
-        await runBrowserCommand({ ...opts, setup: true });
-      }
-    } catch (err) {
-      console.error((err as Error).message);
-      process.exitCode = 1;
-      return;
-    }
+    await runSetupCommand(command.optsWithGlobals());
   });
 
 // ── Official agent skills ──
@@ -1307,9 +1326,9 @@ program
   .description("List all available commands and scripts")
   .action(() => {
     console.log(chalk.bold("\nCLI Commands") + chalk.dim("  (run from project root)\n"));
-    console.log("  mex                    Open the local Hub (or setup for a new project)");
-    console.log("  mex setup              Set up MEX in the local browser Hub");
-    console.log("  mex setup --cli        Use the terminal setup flow");
+    console.log("  mex                    Open the Hub, or terminal setup for a new project");
+    console.log("  mex setup              Set up MEX in the terminal HUD");
+    console.log("  mex setup --browser    Use the browser setup flow");
     console.log("  mex setup --dry-run    Preview setup without making changes");
     console.log("  mex skills sync        Install/update official skills for configured agents");
     console.log("  mex skills sync --dry-run --json  Preview skill and instruction changes as JSON");
diff --git a/src/drift/checkers/grounding.ts b/src/drift/checkers/grounding.ts
index 6f0c931d..dcdebeb0 100644
--- a/src/drift/checkers/grounding.ts
+++ b/src/drift/checkers/grounding.ts
@@ -34,14 +34,15 @@ export function movedByNeighborsMessage(oldId: string, newId: string, anchor = f
   return `${anchor ? "Inline anchor" : "Grounded node"} matched by callers and callees, not body: ${oldId} → ${newId}`;
 }
 
-/** What a snapshot stale only by changed source can still say about one node (#228). */
+/** What a snapshot stale by changed source (#228) or incomplete parses can still say about one node. */
 export type SourceDriftResolution =
   /** The node's body as a refresh would record it: from the snapshot when its
    *  file is unchanged, or re-derived exactly from the edited file. `codeHash`
    *  computes that body's comment-free hash on demand (#236). */
   | { kind: "current"; bodyHash: string | undefined; codeHash?: () => string | null }
-  /** Only a refresh can settle this node; `reason` says why. */
-  | { kind: "unverified"; reason: string };
+  /** Only a refresh can settle this node; `reason` says why. A parse gap is not
+   *  settled by a refresh, so it names its own condition in `until`. */
+  | { kind: "unverified"; reason: string; until?: string };
 
 /**
  * Grounding against a graph whose only fault is that source files changed.
@@ -120,7 +121,7 @@ export function makeGroundingChecker(
         const resolution = sourceDrift.resolve(grounding.node);
         if (resolution.kind === "unverified") {
           issues.push(withEntity(issue("GROUNDING_UNVERIFIED", "warning", source,
-            `Grounded node cannot be verified until \`mex graph refresh\`: ${grounding.node} (${resolution.reason})`), entity));
+            `Grounded node cannot be verified ${resolution.until ?? "until `mex graph refresh`"}: ${grounding.node} (${resolution.reason})`), entity));
           continue;
         }
         target = sourceDriftLinkGraph(shared, grounding.node, resolution, codeHashing);
@@ -154,7 +155,7 @@ export function makeGroundingChecker(
         const resolution = sourceDrift.resolve(anchor.nodeId);
         if (resolution.kind === "unverified") {
           issues.push(issue("GROUNDING_UNVERIFIED", "warning", source,
-            `Inline anchor cannot be verified until \`mex graph refresh\`: ${anchor.nodeId} (${resolution.reason})`));
+            `Inline anchor cannot be verified ${resolution.until ?? "until `mex graph refresh`"}: ${anchor.nodeId} (${resolution.reason})`));
         }
         continue;
       }
diff --git a/src/drift/index.ts b/src/drift/index.ts
index 329d9c36..958b280d 100644
--- a/src/drift/index.ts
+++ b/src/drift/index.ts
@@ -136,8 +136,11 @@ export async function runDriftCheckWithGraphStatus(
   // refresh, so the score could not move for the very edit it exists to catch.
   // The runtime now checks unchanged files against the snapshot, re-derives
   // nodes in edited files exactly or reports them GROUNDING_UNVERIFIED, and
-  // never reconciles. Every other non-fresh reason still skips grounding.
+  // never reconciles. A snapshot with incompletely parsed files is checked the
+  // same way: groundings in fully parsed files are exact, the rest unverified.
+  // Every other non-fresh reason still skips grounding.
   let sourceDriftGrounding = false;
+  let parseDegradedGrounding = false;
   try {
     try {
       const loadRuntime = opts.groundingRuntimeLoader ? false : groundingRelevant;
@@ -149,7 +152,8 @@ export async function runDriftCheckWithGraphStatus(
       sourceDriftGrounding = !usesInjectedGroundingRuntime
         && groundingRuntime !== null
         && loaded.sourceDrift === true
-        && graphStatus.status === "stale";
+        && (graphStatus.status === "stale" || graphStatus.status === "degraded");
+      parseDegradedGrounding = sourceDriftGrounding && loaded.parseDegraded === true;
 
       if (usesInjectedGroundingRuntime) {
         // Preserve the historical injection seam while still inspecting graph
@@ -173,7 +177,7 @@ export async function runDriftCheckWithGraphStatus(
 
       if (!usesInjectedGroundingRuntime && groundingRelevant && graphStatus.status !== "fresh") {
         warnGraph(
-          graphFreshnessWarning(graphStatus, groundingRelevant, needsGroundingMigration, sourceDriftGrounding),
+          graphFreshnessWarning(graphStatus, groundingRelevant, needsGroundingMigration, sourceDriftGrounding, parseDegradedGrounding),
         );
       } else if (groundingRelevant && !groundingRuntime && !graphUpgradeNudgeShown) {
         graphUpgradeNudgeShown = true;
@@ -266,11 +270,12 @@ export async function runDriftCheckWithGraphStatus(
       }
     }
 
-    // A guard that saw the graph change mid-check marks the status degraded,
-    // so a source-drift batch is published only while it is still `stale`.
+    // A guard that saw the graph change mid-check records that diagnostic, so a
+    // partial batch is published only while the bound snapshot stayed valid.
     if (usesInjectedGroundingRuntime
       || graphStatus?.status === "fresh"
-      || (sourceDriftGrounding && graphStatus?.status === "stale")) {
+      || (sourceDriftGrounding
+        && !graphStatus?.diagnostics.some((entry) => entry.code === "GRAPH_INDEX_READER_DATABASE_CHANGED"))) {
       allIssues.push(...pendingGroundingIssues);
       checkerIssueCounts.push(...pendingGroundingIssueCounts);
     }
@@ -371,12 +376,17 @@ function graphFreshnessWarning(
   groundingRelevant: boolean,
   needsGroundingMigration: boolean,
   sourceDriftGrounding = false,
+  parseDegradedGrounding = false,
 ): string {
   const groundingNote = !groundingRelevant
     ? ""
-    : sourceDriftGrounding
-      ? "; groundings in changed source files were re-read or marked unverified"
-      : "; grounding checks skipped";
+    : !sourceDriftGrounding
+      ? "; grounding checks skipped"
+      : !parseDegradedGrounding
+        ? "; groundings in changed source files were re-read or marked unverified"
+        : status.changes.total > 0
+          ? "; groundings in changed or incompletely parsed source files were re-read or marked unverified"
+          : "; groundings in incompletely parsed source files were marked unverified";
   const command = graphRemediationCommand(status);
   const primary = status.diagnostics.find((entry) =>
     entry.code === "GRAPH_INDEX_READER_DATABASE_CHANGED"
diff --git a/src/graph/__tests__/candidate-process.test.ts b/src/graph/__tests__/candidate-process.test.ts
index 5125182a..1e603230 100644
--- a/src/graph/__tests__/candidate-process.test.ts
+++ b/src/graph/__tests__/candidate-process.test.ts
@@ -8,7 +8,7 @@ import { build } from "esbuild";
 import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";
 import { boundedCandidateMessage } from "../candidate-protocol.js";
 import { createGraphCandidateProgressSender } from "../candidate-progress.js";
-import { runGraphCandidateProcess } from "../candidate-process.js";
+import { GRAPH_CANDIDATE_DIAGNOSTIC_BYTES, GraphCandidateProcessError, runGraphCandidateProcess } from "../candidate-process.js";
 import { GRAPH_CORPUS_LIMITS } from "../corpus-policy.js";
 import { createGraphEngine } from "../engine-impl.js";
 import { rebuildGraph, refreshGraph, type GraphMaintenanceExecutionOptions } from "../maintenance.js";
@@ -24,6 +24,12 @@ let crashEntry: string;
 let lateEntry: string;
 let disconnectedEntry: string;
 let parentEntry: string;
+let startupCrashEntry: string;
+let noReadyEntry: string;
+let malformedEntry: string;
+let diagnosticEntry: string;
+let heapLimitEntry: string;
+let reportedHeapTextEntry: string;
 
 function root(): string {
   const path = mkdtempSync(join(tmpdir(), "mex-candidate-process-test-"));
@@ -93,6 +99,25 @@ beforeAll(async () => {
       __internal: { entrypoint: process.argv[4], onSpawn: (pid, workspace) => process.send({ type: "spawned", pid, workspace }) },
     });
   `);
+  startupCrashEntry = await bundle("startup-crash", `
+    process.stderr.write("Error: missing private runtime dependency\\n");
+    process.exit(7);
+  `);
+  noReadyEntry = await bundle("no-ready", 'setInterval(() => {}, 1000);');
+  malformedEntry = await bundle("malformed", 'process.send({ type: "progress", progress: { phase: "parse", source: "private" } }); setInterval(() => {}, 1000);');
+  diagnosticEntry = await bundle("diagnostic", prefix + `
+    process.send({ type: "progress", progress: { phase: "parse", completed: 1, total: 2 } });
+    process.stderr.write("\\x1b[31mPRIVATE_START\\x1b[0m\\x1b]0;INJECTED_TITLE\\x07\\n" + "x".repeat(256 * 1024) + "\\nPRIVATE_END\\n", () => {
+      process.send({ type: "failed", category: "failed" });
+    });
+  ` + suffix);
+  heapLimitEntry = await bundle("heap-limit", prefix + `
+    process.send({ type: "progress", progress: { phase: "parse", completed: 1, total: 2 } });
+    process.stderr.write("x".repeat(10 * 1024) + "\\nFATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\\n" + "y".repeat(10 * 1024), () => process.exit(134));
+  ` + suffix);
+  reportedHeapTextEntry = await bundle("reported-heap-text", prefix + `
+    process.stderr.write("FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\\n", () => process.send({ type: "failed", category: "failed" }));
+  ` + suffix);
 }, 30_000);
 
 afterEach(() => {
@@ -219,10 +244,19 @@ describe("isolated graph candidate construction", () => {
     const database = await baseline(path);
     pendingChange(path);
     const before = hash(database);
+    let pid = 0;
     let workspace = "";
-    await expect(refreshGraph(path, isolated(crashEntry, {
-      onSpawn: (_pid: number, directory: string) => { workspace = directory; },
-    }))).rejects.toMatchObject({ category: "failed" });
+    const error = await refreshGraph(path, isolated(crashEntry, {
+      onSpawn: (childPid: number, directory: string) => { pid = childPid; workspace = directory; },
+    })).catch((error: unknown) => error) as GraphCandidateProcessError;
+    expect(error).toBeInstanceOf(GraphCandidateProcessError);
+    // Windows reports forced termination as an exit code, without a POSIX signal.
+    const exit = process.platform === "win32"
+      ? { exitCode: expect.any(Number), signal: null }
+      : { exitCode: null, signal: "SIGKILL" };
+    expect(error).toMatchObject({ category: "failed", diagnostic: { reason: "exit", ...exit } });
+    if (process.platform === "win32") expect(error.diagnostic!.exitCode).not.toBe(0);
+    expect(processAlive(pid)).toBe(false);
     expect(existsSync(workspace)).toBe(false);
     expect(hash(database)).toBe(before);
     expect(artifacts(path)).toEqual([]);
@@ -303,7 +337,7 @@ describe("isolated graph candidate construction", () => {
     await expect(runGraphCandidateProcess({
       projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"b".repeat(48)}`), operation: "rebuild",
       __internal: { entrypoint: busyEntry, buildTimeoutMs: 500, onSpawn: (value) => { pid = value; } },
-    })).rejects.toMatchObject({ category: "failed" });
+    })).rejects.toMatchObject({ category: "failed", diagnostic: { reason: "build-timeout" } });
     expect(processAlive(pid)).toBe(false);
   });
 
@@ -345,6 +379,80 @@ describe("isolated graph candidate construction", () => {
     expect(boundedCandidateMessage({ type: "failed", category: "x".repeat(1024 * 1024) })).toBeNull();
   });
 
+  it("reports a worker startup crash with its exit code and bounded local stderr", async () => {
+    const path = root();
+    const error = await runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"d".repeat(48)}`), operation: "rebuild",
+      __internal: { entrypoint: startupCrashEntry },
+    }).catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(GraphCandidateProcessError);
+    expect(error).toMatchObject({ category: "failed", diagnostic: { reason: "exit", exitCode: 7, signal: null,
+      elapsedMs: expect.any(Number), stderr: "Error: missing private runtime dependency" } });
+    expect((error as Error).message).toContain("exit code 7");
+    expect((error as Error).message).toContain("missing private runtime dependency");
+  });
+
+  it.each([
+    ["startup deadline", () => noReadyEntry, "startup-timeout"],
+    ["invalid protocol", () => malformedEntry, "protocol"],
+  ] as const)("distinguishes a %s from graph build failure", async (_label, entrypoint, reason) => {
+    const path = root();
+    await expect(runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"d".repeat(48)}`), operation: "rebuild",
+      __internal: { entrypoint: entrypoint(), ...(reason === "startup-timeout" ? { startupTimeoutMs: 100 } : {}) },
+    })).rejects.toMatchObject({ category: "failed", diagnostic: { reason } });
+  }, 20_000);
+
+  it("drains excessive worker diagnostics, keeps useful head/tail, strips terminal controls, and reports last progress", async () => {
+    const path = root();
+    const error = await runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"d".repeat(48)}`), operation: "rebuild",
+      __internal: { entrypoint: diagnosticEntry },
+    }).catch((error: unknown) => error) as GraphCandidateProcessError;
+    expect(error.diagnostic).toMatchObject({ reason: "worker-error", progress: { phase: "parse", completed: 1, total: 2 } });
+    expect(error.diagnostic!.stderr).toContain("PRIVATE_START");
+    expect(error.diagnostic!.stderr).toContain("PRIVATE_END");
+    expect(error.diagnostic!.stderr).toContain("truncated");
+    expect(error.diagnostic!.stderr).not.toMatch(/\u001b|\u0007|INJECTED_TITLE/u);
+    expect(Buffer.byteLength(error.diagnostic!.stderr!)).toBeLessThanOrEqual(GRAPH_CANDIDATE_DIAGNOSTIC_BYTES);
+    expect(error.message).toContain("last progress: parse 1/2 files");
+    expect(error.message).not.toContain("signal SIGTERM");
+    expect(error.message).not.toContain("signal SIGKILL");
+    expect(error.diagnostic!.resourceFailure).toBeUndefined();
+  });
+
+  it("identifies a heap limit only from Node's explicit fatal runtime diagnostic", async () => {
+    const path = root();
+    const error = await runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"d".repeat(48)}`), operation: "rebuild",
+      __internal: { entrypoint: heapLimitEntry },
+    }).catch((error: unknown) => error) as GraphCandidateProcessError;
+    expect(error.diagnostic).toMatchObject({ reason: "exit", exitCode: 134, resourceFailure: "heap-limit" });
+    expect(error.message).toContain("reached Node's JavaScript heap limit");
+    expect(error.diagnostic!.stderr).not.toContain("FATAL ERROR");
+  });
+
+  it("does not treat a caught worker error containing the heap marker as a fatal runtime crash", async () => {
+    const path = root();
+    const error = await runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", `graph.db.candidate-${"d".repeat(48)}`), operation: "rebuild",
+      __internal: { entrypoint: reportedHeapTextEntry },
+    }).catch((error: unknown) => error) as GraphCandidateProcessError;
+    expect(error.diagnostic!.reason).toBe("worker-error");
+    expect(error.diagnostic!.resourceFailure).toBeUndefined();
+  });
+
+  it("preserves an actual worker exception on stderr without widening the failure IPC schema", async () => {
+    const path = root();
+    const error = await runGraphCandidateProcess({
+      projectRoot: path, candidatePath: join(path, ".mex", "invalid-candidate-name"), operation: "rebuild",
+      __internal: { entrypoint: realEntry },
+    }).catch((error: unknown) => error) as GraphCandidateProcessError;
+    expect(error.diagnostic).toMatchObject({ reason: "worker-error", stderr: "Error: Invalid candidate path." });
+    expect(error.message).not.toContain("signal SIGTERM");
+    expect(boundedCandidateMessage({ type: "failed", category: "failed", errorMessage: "private" })).toBeNull();
+  });
+
   it("sends throttled counts during synchronous work without requiring completion callbacks to run", () => {
     let now = 0;
     let blocked = false;
diff --git a/src/graph/application-adapter.ts b/src/graph/application-adapter.ts
index 2660e7a3..94e7e66e 100644
--- a/src/graph/application-adapter.ts
+++ b/src/graph/application-adapter.ts
@@ -156,6 +156,8 @@ export interface RepositoryGraphGroundedNode {
 export interface RepositoryGraphGroundingSnapshot {
   /** Exact immutable graph snapshot revision, for composite Wiki cursors. */
   readonly revision: string;
+  /** Missing targets cannot be reconciled conclusively across a parse gap. */
+  readonly incompleteReason?: string;
   getNode(nodeId: string): RepositoryGraphGroundedNode | null;
   /** Up to 50 direct symbols, in request order without duplicates or source bodies. */
   getSymbols(nodeIds: readonly string[]): readonly CodeSymbol[];
@@ -363,7 +365,7 @@ export class RepositoryGraphPort implements GraphPort {
         } finally {
           snapshot.revoke();
         }
-      });
+      }, undefined, true);
       return read.value;
     } catch (error) {
       if (error instanceof GroundingSnapshotCallbackError) throw error.cause;
@@ -399,7 +401,7 @@ export class RepositoryGraphPort implements GraphPort {
       }, async (publication) => {
         commitStarted = true;
         committed = await publication.commit();
-      });
+      }, true);
       return committed!;
     } catch (error) {
       if (prepared !== undefined && !commitStarted) {
@@ -421,9 +423,20 @@ export class RepositoryGraphPort implements GraphPort {
   } {
       const store = new FingerprintStore(context.session.db);
       const reconciler = new MinHashReconciler(store);
+      const incomplete = context.session.degradations.includes("parse-degraded");
+      const files = incomplete ? context.session.graph.getIndexedFiles?.() ?? [] : [];
+      const healthyFiles = new Set(files.filter(file => file.parseStatus === "ok").map(file => file.path));
+      const gaps = files.filter(file => file.parseStatus !== "ok").map(file => file.path).sort();
+      const incompleteReason = incomplete
+        ? `The code graph has incomplete parses${gaps.length ? ` in ${gaps.slice(0, 8).join(", ").slice(0, 1_024)}${gaps.length > 8 ? ", …" : ""}` : ""}. This target cannot be verified. Fix those files or explicitly exclude intentional fixtures, then run \`mex graph\`.`
+        : undefined;
+      const getVerifiedNode = (nodeId: string) => {
+        const node = context.session.graph.getNode(nodeId);
+        return node && (!incomplete || healthyFiles.has(node.filePath)) ? node : null;
+      };
       const evidence = createGroundingEvidence({
         projectRoot: this.#projectRoot,
-        getNode: (nodeId) => context.session.graph.getNode(nodeId),
+        getNode: getVerifiedNode,
       });
       let active = true;
       const assertActive = (): void => {
@@ -433,6 +446,7 @@ export class RepositoryGraphPort implements GraphPort {
       };
       const snapshot: RepositoryGraphGroundingSnapshot = {
         revision: context.revision,
+        ...(incompleteReason ? { incompleteReason } : {}),
         getSymbols(nodeIds) {
           assertActive();
           if (!Array.isArray(nodeIds) || nodeIds.length > MAX_GROUNDING_SYMBOLS) {
@@ -441,7 +455,7 @@ export class RepositoryGraphPort implements GraphPort {
           const ids = [...new Set(Array.from(nodeIds, validateSymbolId))];
           try {
             return ids.flatMap((id) => {
-              const node = context.session.graph.getNode(id);
+              const node = getVerifiedNode(id);
               // Graph point reads also follow aliases. Only the requested
               // declaration belongs in this direct-symbol projection.
               return node?.id === id ? [projectNode(node)] : [];
@@ -453,7 +467,7 @@ export class RepositoryGraphPort implements GraphPort {
         getNode(nodeId) {
           assertActive();
           try {
-            const node = context.session.graph.getNode(nodeId);
+            const node = getVerifiedNode(nodeId);
             return node === null ? null : {
               id: node.id,
               bodyHash: node.bodyHash ?? null,
@@ -468,6 +482,7 @@ export class RepositoryGraphPort implements GraphPort {
         getFingerprint(nodeId) {
           assertActive();
           try {
+            if (incomplete && !getVerifiedNode(nodeId)) return null;
             const fingerprint = store.get(nodeId);
             return fingerprint === null ? null : serializeFingerprint(fingerprint);
           } catch {
@@ -477,6 +492,7 @@ export class RepositoryGraphPort implements GraphPort {
         reconcile(nodeId, committedFingerprint, bodyHash) {
           assertActive();
           try {
+            if (incomplete) return null;
             const fingerprint = deserializeFingerprint(committedFingerprint);
             return fingerprint === null ? null : reconciler.reconcile(nodeId, fingerprint, bodyHash);
           } catch {
@@ -527,6 +543,7 @@ export class RepositoryGraphPort implements GraphPort {
   async #withFresh<T>(
     build: (context: FreshContext) => T | Promise<T>,
     afterValidation?: (value: T) => void | Promise<void>,
+    allowParseDegraded = false,
   ): Promise<{
     revision: string;
     status: GraphStatus;
@@ -537,6 +554,7 @@ export class RepositoryGraphPort implements GraphPort {
       loaded = await this.#deps.loadFresh(this.#projectRoot, {
         dbPath: this.#dbPath,
         loadSession: true,
+        ...(allowParseDegraded ? { allowDegradedReads: true } : {}),
       });
     } catch {
       throw interruptedRead("The graph changed or became unavailable before the read began.");
@@ -544,6 +562,11 @@ export class RepositoryGraphPort implements GraphPort {
     const session = loaded.session;
     if (!session) throw errorForStatus(loaded.graphStatus);
     try {
+      if (session.degradations.length && (!allowParseDegraded
+        || session.degradations.some(degradation => degradation !== "parse-degraded"))) {
+        throw portError("INDEX_STALE", 409, "Graph inputs changed",
+          "The graph's source or configuration changed. Refresh it before verifying groundings.");
+      }
       const revision = readSnapshotRevision(session.db);
       const context: FreshContext = {
         session,
diff --git a/src/graph/candidate-entry.ts b/src/graph/candidate-entry.ts
index 4622976c..34537e4c 100644
--- a/src/graph/candidate-entry.ts
+++ b/src/graph/candidate-entry.ts
@@ -1,4 +1,4 @@
-import { existsSync, lstatSync, realpathSync } from "node:fs";
+import { existsSync, lstatSync, realpathSync, writeSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative } from "node:path";
 import { createGraphEngine, GraphSourceStagingError } from "./engine-impl.js";
 import type { GraphEngine } from "./engine.js";
@@ -58,6 +58,18 @@ function failureCategory(error: unknown): "compatibility" | "staging" | "failed"
   return "failed";
 }
 
+/** Local stderr only. The private IPC schema and GraphPort keep fixed categories. */
+function writeFailureDiagnostic(error: unknown): void {
+  const name = error instanceof Error ? error.name : "Error";
+  const code = typeof error === "object" && error !== null && "code" in error ? String(error.code) : "";
+  const message = error instanceof Error ? error.message : String(error);
+  const failures = error instanceof GraphSourceStagingError
+    ? error.failures.slice(0, 3).map((failure) => `${failure.operation} ${failure.filePath.slice(0, 512)}: ${failure.message.slice(0, 1024)}`).join("\n")
+    : "";
+  const summary = Buffer.from(`${name.slice(0, 128)}${code ? ` (${code.slice(0, 128)})` : ""}: ${message.slice(0, 2048)}\n${failures}`.slice(0, 4096)).subarray(0, 4096);
+  try { writeSync(2, summary); } catch { /* Diagnostics cannot replace the original failure. */ }
+}
+
 async function main(): Promise<void> {
   if (!process.send || !process.connected) throw new Error("Candidate construction requires its private parent channel.");
   const stopWatchdog = await startGraphCandidateWatchdog();
@@ -87,6 +99,7 @@ async function main(): Promise<void> {
       outcome = { type: "complete", result };
       if (!boundedCandidateMessage(outcome)) throw new Error("Graph result exceeded its private message bound.");
     } catch (error) {
+      writeFailureDiagnostic(error);
       try { engine?.close(); } catch { /* The supervisor removes the unpublished candidate after close. */ }
       outcome = { type: "failed", category: failureCategory(error) };
     }
@@ -95,11 +108,12 @@ async function main(): Promise<void> {
       await stopWatchdog();
       process.exitCode = outcome.type === "complete" ? 0 : 1;
       process.disconnect();
-    } catch {
+    } catch (error) {
+      writeFailureDiagnostic(error);
       process.exit(1);
     }
   });
   await send({ type: "ready" });
 }
 
-main().catch(() => process.exit(1));
+main().catch((error) => { writeFailureDiagnostic(error); process.exit(1); });
diff --git a/src/graph/candidate-process.ts b/src/graph/candidate-process.ts
index a83c7a0c..1048fcb6 100644
--- a/src/graph/candidate-process.ts
+++ b/src/graph/candidate-process.ts
@@ -15,11 +15,31 @@ const STARTUP_TIMEOUT_MS = 15_000;
 const TERMINATE_GRACE_MS = 500;
 // A hang guard, not a resource/performance promise for a particular repository.
 const BUILD_TIMEOUT_MS = 30 * 60 * 1000;
+export const GRAPH_CANDIDATE_DIAGNOSTIC_BYTES = 8 * 1024;
+const NODE_HEAP_FAILURE = /^FATAL ERROR: (?:Reached heap limit|Ineffective mark-compacts near heap limit) Allocation failed - JavaScript heap out of memory\s*$/mu;
+
+export interface GraphCandidateProcessDiagnostic {
+  readonly reason: "entrypoint-missing" | "spawn" | "startup-timeout" | "build-timeout"
+    | "protocol" | "ipc-disconnected" | "worker-error" | "exit" | "observer" | "cancelled";
+  readonly exitCode?: number | null;
+  readonly signal?: NodeJS.Signals | null;
+  /** Signal requested by MEX after an already diagnosed worker failure. */
+  readonly supervisorSignal?: NodeJS.Signals;
+  readonly elapsedMs?: number;
+  readonly progress?: GraphCandidateProgress;
+  /** Only set when Node prints its explicit fatal JavaScript heap-limit marker. */
+  readonly resourceFailure?: "heap-limit";
+  /** Bounded local terminal diagnostics. Never project this field into GraphPort/Hub responses. */
+  readonly stderr?: string;
+}
 
 export class GraphCandidateProcessError extends Error {
   override readonly name = "GraphCandidateProcessError";
-  constructor(readonly category: "cancelled" | "compatibility" | "staging" | "failed" | "unsafe") {
-    super(category === "cancelled"
+  constructor(
+    readonly category: "cancelled" | "compatibility" | "staging" | "failed" | "unsafe",
+    readonly diagnostic?: GraphCandidateProcessDiagnostic,
+  ) {
+    super(diagnostic ? diagnosticMessage(diagnostic) : category === "cancelled"
       ? "Graph candidate construction was cancelled."
       : "The isolated graph candidate could not be completed safely.");
   }
@@ -36,6 +56,7 @@ export interface GraphCandidateProcessOptions {
     entrypoint?: string;
     onSpawn?: (pid: number, workspace: string) => void;
     buildTimeoutMs?: number;
+    startupTimeoutMs?: number;
   };
 }
 
@@ -59,7 +80,7 @@ function candidateEntrypoint(): string {
   // use the installed build; no TypeScript loader or public CLI is spawned.
   const candidates = [join(HERE, "graph-candidate.js"), join(HERE, "../../dist/graph-candidate.js")];
   const entrypoint = candidates.find((path) => existsSync(path));
-  if (!entrypoint) throw new GraphCandidateProcessError("failed");
+  if (!entrypoint) throw new GraphCandidateProcessError("failed", { reason: "entrypoint-missing" });
   return entrypoint;
 }
 
@@ -90,6 +111,8 @@ export async function runGraphCandidateProcess(options: GraphCandidateProcessOpt
 
 function superviseCandidate(options: GraphCandidateProcessOptions, request: GraphCandidateRequest): Promise<BuildResult> {
   return new Promise((resolve, reject) => {
+    const startedAt = performance.now();
+    const stderr = boundedWorkerDiagnostic();
     let child: ChildProcess;
     try {
       child = spawn(process.execPath, [options.__internal?.entrypoint ?? candidateEntrypoint()], {
@@ -99,64 +122,78 @@ function superviseCandidate(options: GraphCandidateProcessOptions, request: Grap
         // its main thread is inside synchronous TypeScript or SQLite work.
         // Overlapped enables asynchronous reads on the inherited Windows
         // lifeline handle; it is identical to `pipe` on Unix.
-        stdio: ["ignore", "ignore", "ignore", "ipc", "overlapped"],
+        stdio: ["ignore", "ignore", "pipe", "ipc", "overlapped"],
         serialization: "json",
         windowsHide: true,
       });
-    } catch {
-      reject(new GraphCandidateProcessError("failed"));
+    } catch (error) {
+      reject(error instanceof GraphCandidateProcessError ? error : new GraphCandidateProcessError("failed", {
+        reason: "spawn", stderr: boundedDiagnosticText(error instanceof Error ? error.message : String(error)),
+      }));
       return;
     }
     let ready = false;
     let result: BuildResult | undefined;
     let failure: GraphCandidateProcessError | undefined;
+    let lastProgress: GraphCandidateProgress | undefined;
+    const sentSignals = new Set<NodeJS.Signals>();
+    child.stderr?.on("data", (chunk: Buffer) => stderr.append(chunk));
+    const fail = (reason: GraphCandidateProcessDiagnostic["reason"], category: GraphCandidateProcessError["category"] = "failed") =>
+      new GraphCandidateProcessError(category, { reason });
+    const kill = (signal: NodeJS.Signals) => {
+      if (child.kill(signal)) sentSignals.add(signal);
+    };
     let terminateTimer: ReturnType<typeof setTimeout> | undefined;
     const stop = (error: GraphCandidateProcessError) => {
       if (failure) return;
       failure = error;
-      child.kill("SIGTERM");
-      terminateTimer = setTimeout(() => child.kill("SIGKILL"), TERMINATE_GRACE_MS);
+      kill("SIGTERM");
+      terminateTimer = setTimeout(() => kill("SIGKILL"), TERMINATE_GRACE_MS);
       terminateTimer.unref();
     };
-    const cancelled = () => stop(new GraphCandidateProcessError("cancelled"));
+    const cancelled = () => stop(fail("cancelled", "cancelled"));
     const parentExit = () => child.kill("SIGKILL");
-    const startupTimer = setTimeout(() => stop(new GraphCandidateProcessError("failed")), STARTUP_TIMEOUT_MS);
+    const startupTimer = setTimeout(() => stop(fail("startup-timeout")), options.__internal?.startupTimeoutMs ?? STARTUP_TIMEOUT_MS);
     const buildTimer = setTimeout(
-      () => stop(new GraphCandidateProcessError("failed")),
+      () => stop(fail("build-timeout")),
       options.__internal?.buildTimeoutMs ?? BUILD_TIMEOUT_MS,
     );
     startupTimer.unref();
     buildTimer.unref();
     process.once("exit", parentExit);
     options.signal?.addEventListener("abort", cancelled, { once: true });
-    child.on("error", () => stop(new GraphCandidateProcessError("failed")));
+    child.on("error", (error) => {
+      stderr.append(Buffer.from(`${error.name}: ${error.message}\n`));
+      stop(fail("spawn"));
+    });
     child.on("disconnect", () => {
       // A live parent keeps FD4 open, so the parent-death watchdog cannot help
       // when only IPC is lost. A disconnected writer without a terminal result
       // must be stopped promptly instead of holding the lease until timeout.
-      if (!result && !failure) stop(new GraphCandidateProcessError("failed"));
+      if (!result && !failure) stop(fail("ipc-disconnected"));
     });
     child.on("message", (raw: unknown) => {
       if (failure) return;
       const message = boundedCandidateMessage(raw);
-      if (!message || result) return stop(new GraphCandidateProcessError("failed"));
+      if (!message || result) return stop(fail("protocol"));
       if (message.type === "ready") {
-        if (ready) return stop(new GraphCandidateProcessError("failed"));
+        if (ready) return stop(fail("protocol"));
         ready = true;
         clearTimeout(startupTimer);
-        child.send(request, (error) => { if (error) stop(new GraphCandidateProcessError("failed")); });
+        child.send(request, (error) => { if (error) stop(fail("ipc-disconnected")); });
       } else if (!ready) {
-        stop(new GraphCandidateProcessError("failed"));
+        stop(fail("protocol"));
       } else if (message.type === "progress") {
+        lastProgress = message.progress;
         try {
           options.onProgress?.(message.progress);
         } catch {
-          stop(new GraphCandidateProcessError("failed"));
+          stop(fail("observer"));
         }
       } else if (message.type === "complete") {
         result = message.result;
       } else {
-        stop(new GraphCandidateProcessError(message.category));
+        stop(fail("worker-error", message.category));
       }
     });
     child.once("close", (code, signal) => {
@@ -166,16 +203,92 @@ function superviseCandidate(options: GraphCandidateProcessOptions, request: Grap
       process.removeListener("exit", parentExit);
       options.signal?.removeEventListener("abort", cancelled);
       child.stdio[4]?.destroy();
-      if (options.signal?.aborted) reject(new GraphCandidateProcessError("cancelled"));
-      else if (failure) reject(failure);
-      else if (code !== 0 || signal || !result) reject(new GraphCandidateProcessError("failed"));
-      else resolve(result);
+      if (options.signal?.aborted) failure = fail("cancelled", "cancelled");
+      if (failure || code !== 0 || signal || !result) {
+        let reason = failure?.diagnostic?.reason ?? "exit";
+        const diagnosticOutput = stderr.text();
+        // An exiting process also disconnects IPC. Preserve the actual crash or
+        // exit status instead of blaming a channel that closed as a consequence.
+        if (reason === "ipc-disconnected" && (code !== null || (signal && !sentSignals.has(signal)))) reason = "exit";
+        reject(new GraphCandidateProcessError(failure?.category ?? "failed", {
+          reason, exitCode: code, signal,
+          ...(reason !== "exit" && signal && sentSignals.has(signal) ? { supervisorSignal: signal } : {}),
+          elapsedMs: Math.max(0, Math.round(performance.now() - startedAt)),
+          ...(lastProgress ? { progress: lastProgress } : {}),
+          ...(reason === "exit" && stderr.heapLimit()
+            ? { resourceFailure: "heap-limit" as const } : {}),
+          ...(diagnosticOutput ? { stderr: diagnosticOutput } : {}),
+        }));
+      } else resolve(result);
     });
     try {
       if (child.pid) options.__internal?.onSpawn?.(child.pid, request.workspace);
       if (options.signal?.aborted) cancelled();
     } catch {
-      stop(new GraphCandidateProcessError("failed"));
+      stop(fail("observer"));
     }
   });
 }
+
+function boundedDiagnosticText(text: string): string {
+  const plain = text.slice(0, GRAPH_CANDIDATE_DIAGNOSTIC_BYTES * 4)
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/gu, "")
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/gu, "")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/gu, "");
+  return Buffer.from(plain).subarray(0, GRAPH_CANDIDATE_DIAGNOSTIC_BYTES).toString("utf8").replace(/\uFFFD$/u, "").trim();
+}
+
+/** Drain all stderr while retaining a bounded beginning and end, including fatal runtime output. */
+function boundedWorkerDiagnostic(): { append: (chunk: Buffer) => void; text: () => string; heapLimit: () => boolean } {
+  const marker = "\n[worker diagnostics truncated]\n";
+  const headLimit = 2048;
+  const tailLimit = GRAPH_CANDIDATE_DIAGNOSTIC_BYTES - headLimit - Buffer.byteLength(marker);
+  let head = Buffer.alloc(0);
+  let tail = Buffer.alloc(0);
+  let truncated = false;
+  let heapLimit = false;
+  let markerTail = "";
+  return {
+    append(chunk) {
+      // Keep the fixed fatal hint even if verbose startup/crash output pushes
+      // its line out of the retained head/tail. No raw content enters the hint.
+      const markerText = markerTail + chunk.toString("utf8");
+      heapLimit ||= NODE_HEAP_FAILURE.test(markerText);
+      markerTail = markerText.slice(-256);
+      const headBytes = Math.min(chunk.length, headLimit - head.length);
+      if (headBytes) head = Buffer.concat([head, chunk.subarray(0, headBytes)]);
+      const rest = chunk.subarray(headBytes);
+      if (tail.length + rest.length > tailLimit) truncated = true;
+      // Slice before concatenating: a single oversized write must not expand retained memory.
+      tail = Buffer.concat([tail, rest.subarray(Math.max(0, rest.length - tailLimit))]).subarray(-tailLimit);
+    },
+    text: () => boundedDiagnosticText(head.toString("utf8") + (truncated ? marker : "") + tail.toString("utf8")),
+    heapLimit: () => heapLimit,
+  };
+}
+
+function diagnosticMessage(diagnostic: GraphCandidateProcessDiagnostic): string {
+  const descriptions: Record<GraphCandidateProcessDiagnostic["reason"], string> = {
+    "entrypoint-missing": "The graph worker executable is missing from this MEX installation",
+    spawn: "The graph worker could not start",
+    "startup-timeout": "The graph worker did not become ready before its startup deadline",
+    "build-timeout": "The graph worker exceeded its graph construction deadline",
+    protocol: "The graph worker returned an invalid or out-of-order response",
+    "ipc-disconnected": "The graph worker lost its parent communication channel",
+    "worker-error": "The graph worker reported an error",
+    exit: "The graph worker exited without a valid completed result",
+    observer: "Graph worker supervision could not continue",
+    cancelled: "Graph candidate construction was cancelled",
+  };
+  const details: string[] = [];
+  if (diagnostic.exitCode !== undefined && diagnostic.exitCode !== null) details.push(`exit code ${diagnostic.exitCode}`);
+  if (diagnostic.signal && diagnostic.signal !== diagnostic.supervisorSignal) details.push(`signal ${diagnostic.signal}`);
+  if (diagnostic.elapsedMs !== undefined) details.push(`${(diagnostic.elapsedMs / 1000).toFixed(1)}s elapsed`);
+  if (diagnostic.progress) {
+    const { phase, completed, total } = diagnostic.progress;
+    details.push(`last progress: ${phase}${completed === undefined ? "" : ` ${completed}${total === undefined ? "" : `/${total}`} files`}`);
+  }
+  const description = diagnostic.resourceFailure === "heap-limit"
+    ? "The graph worker reached Node's JavaScript heap limit" : descriptions[diagnostic.reason];
+  return `${description}${details.length ? ` (${details.join("; ")})` : ""}.${diagnostic.stderr ? `\nWorker diagnostics:\n${boundedDiagnosticText(diagnostic.stderr)}` : ""}`;
+}
diff --git a/src/graph/runtime.ts b/src/graph/runtime.ts
index 8358c702..cb10cb86 100644
--- a/src/graph/runtime.ts
+++ b/src/graph/runtime.ts
@@ -90,11 +90,14 @@ export interface ReadOnlyGroundingRuntimeResult {
   graphStatus: GraphStatus;
   runtime: GroundingRuntime | null;
   /**
-   * True when `runtime` is bound to a stale snapshot whose only fault is
-   * changed source (#228). Its checker never reconciles and reports what it
-   * cannot settle as GROUNDING_UNVERIFIED. Only set under `allowSourceDrift`.
+   * True when `runtime` is bound to a snapshot whose only faults are changed
+   * source (#228) or incompletely parsed files. Its checker never reconciles
+   * and reports what it cannot settle as GROUNDING_UNVERIFIED. Only set under
+   * `allowSourceDrift`.
    */
   sourceDrift?: boolean;
+  /** Set with `sourceDrift` when incompletely parsed files are among those faults. */
+  parseDegraded?: boolean;
 }
 
 export interface LoadReadOnlyGroundingRuntimeOptions {
@@ -105,9 +108,10 @@ export interface LoadReadOnlyGroundingRuntimeOptions {
   /** Inspect status without opening graph readers when grounding is irrelevant. */
   loadRuntime?: boolean;
   /**
-   * Also bind a stale snapshot when changed source is its only shortfall, and
-   * check groundings against it (#228). Every other non-fresh store still
-   * returns no runtime. Opt-in, because the caller owns labelling the result.
+   * Also bind a snapshot whose only shortfalls are changed source (#228) or
+   * incompletely parsed files, and check groundings against it. Every other
+   * non-fresh store still returns no runtime. Opt-in, because the caller owns
+   * labelling the result.
    */
   allowSourceDrift?: boolean;
 }
@@ -141,6 +145,11 @@ type LoadReadOnlyGroundingRuntimeInternalOptions = LoadReadOnlyGroundingRuntimeO
  * an unchanged file; a node in an edited file is re-derived from that file by
  * the same extractor and body hash a refresh would use, or reported
  * unverified. Nothing about staleness is hidden: the status stays `stale`.
+ *
+ * A snapshot with incompletely parsed files is bound the same way. Every node
+ * in a fully parsed file is as exact as a fresh graph's; a node in a partial
+ * or failed file, or one the snapshot lacks, is unverified, because a parse
+ * gap can hide a definition. Nothing is reconciled across that gap.
  */
 export async function loadReadOnlyGroundingRuntime(
   config: MexConfig,
@@ -155,11 +164,11 @@ export async function loadReadOnlyGroundingRuntime(
         freshObservation: null,
       })
     : internal?.inspectObservation ?? inspectGraphStatusWithFreshObservation;
-  // The read-session loader would also adopt config drift and parse health.
-  // Grounding accepts neither, so hide every degraded observation except the
-  // one whose sole shortfall is changed source; the rest behave as before.
+  // The read-session loader would also adopt config drift. Grounding does not
+  // accept it, so hide every degraded observation except those whose only
+  // shortfalls are changed source or incomplete parses.
   const inspectObservation: typeof inspectGraphStatusWithFreshObservation = options.allowSourceDrift
-    ? async (inspectOptions) => onlySourceDrift(await inspectBase(inspectOptions))
+    ? async (inspectOptions) => onlyGroundableDegradation(await inspectBase(inspectOptions))
     : inspectBase;
   const loaded = await loadFreshGraphReadSession(config.projectRoot, {
     dbPath,
@@ -198,12 +207,16 @@ export async function loadReadOnlyGroundingRuntime(
         ];
       },
     };
+    const parseDegraded = session.degradations.includes("parse-degraded");
     const sourceDrift = session.degradations.length > 0
       ? await prepareSourceDriftGrounding(
           config.projectRoot,
           session.graph,
           session.driftedSources,
           loaded.graphStatus.changes.modified,
+          parseDegraded
+            ? (session.graph.getIndexedFiles?.() ?? []).filter((file) => file.parseStatus !== "ok").map((file) => file.path)
+            : [],
         )
       : undefined;
     await prepareGroundingCodeHashing();
@@ -225,6 +238,7 @@ export async function loadReadOnlyGroundingRuntime(
       // before candidate publication").
       runtime: { ...runtime, close: () => session.close() },
       ...(sourceDrift ? { sourceDrift: true } : {}),
+      ...(sourceDrift && parseDegraded ? { parseDegraded: true } : {}),
     };
   } catch {
     session.close();
@@ -563,14 +577,14 @@ function assembleGroundingRuntime(
   };
 }
 
-/** Keep a degraded observation only when changed source is the store's sole shortfall. */
-function onlySourceDrift(inspection: InternalGraphStatusInspection): InternalGraphStatusInspection {
+/** Keep a degraded observation only when changed source or incomplete parses are its sole shortfalls. */
+function onlyGroundableDegradation(inspection: InternalGraphStatusInspection): InternalGraphStatusInspection {
   const degraded = inspection.degradedObservation ?? null;
   if (!degraded) return inspection;
-  const sourceOnly = inspection.graphStatus.status === "stale"
-    && degraded.degradations.length === 1
-    && degraded.degradations[0] === "source-drift";
-  return sourceOnly ? inspection : { ...inspection, degradedObservation: null };
+  const groundable = (inspection.graphStatus.status === "stale" || inspection.graphStatus.status === "degraded")
+    && degraded.degradations.length > 0
+    && degraded.degradations.every((reason) => reason === "source-drift" || reason === "parse-degraded");
+  return groundable ? inspection : { ...inspection, degradedObservation: null };
 }
 
 /**
@@ -605,14 +619,21 @@ function isCompilerSourceLanguage(language: Language): boolean {
  *   node the extractor no longer emits under that id, a file that cannot be
  *   read within the corpus limits — is unverified. None of it is reported
  *   gone or moved: those need the whole refreshed corpus.
+ * - A node in a file that did not parse completely, or any node the snapshot
+ *   lacks while such a file exists, is unverified and names those files.
  */
 async function prepareSourceDriftGrounding(
   projectRoot: string,
   graph: GraphEngine,
   driftedSources: readonly string[],
   modifiedSources: readonly string[],
+  parseGaps: readonly string[] = [],
 ): Promise<SourceDriftGrounding> {
   const drifted = new Set(driftedSources);
+  const gaps = new Set(parseGaps);
+  const gapList = [...gaps].sort();
+  const gapNames = `${gapList.slice(0, 8).join(", ")}${gapList.length > 8 ? ", …" : ""}`.slice(0, 1_024);
+  const gapRemedy = "fix or exclude them, then run `mex graph`";
   const modified = new Set(modifiedSources.filter((path) => drifted.has(path)));
   const treeLanguages = [...new Set([...modified].map((path) => detectLanguage(path)))]
     .filter((language) => !isCompilerSourceLanguage(language));
@@ -645,10 +666,16 @@ async function prepareSourceDriftGrounding(
     return nodes;
   };
   const unverified = (reason: string): SourceDriftResolution => ({ kind: "unverified", reason });
+  const gap = (reason: string): SourceDriftResolution => ({ kind: "unverified", reason, until: "while the graph has incomplete parses" });
   return {
     resolve(nodeId) {
       const node = graph.getNode(nodeId);
-      if (!node) return unverified("not in the last graph snapshot");
+      if (!node) {
+        return gaps.size > 0
+          ? gap(`not in the graph, which could not fully parse ${gapNames}; ${gapRemedy}`)
+          : unverified("not in the last graph snapshot");
+      }
+      if (gaps.has(node.filePath)) return gap(`${node.filePath} did not parse completely; ${gapRemedy}`);
       if (!drifted.has(node.filePath)) {
         return { kind: "current", bodyHash: node.bodyHash, codeHash: () => currentNodeCodeHash(projectRoot, node) };
       }
diff --git a/src/hub/__tests__/setup-command.test.ts b/src/hub/__tests__/setup-command.test.ts
index 7589f15a..440470f3 100644
--- a/src/hub/__tests__/setup-command.test.ts
+++ b/src/hub/__tests__/setup-command.test.ts
@@ -16,6 +16,7 @@ const mocks = vi.hoisted(() => ({
   findConfig: vi.fn(),
   identity: vi.fn(),
   createTeam: vi.fn(),
+  openBrowser: vi.fn(),
   order: [] as string[],
 }));
 
@@ -30,6 +31,7 @@ vi.mock("../security/session.js", () => ({
 }));
 vi.mock("../app.js", () => ({ createHubApp: mocks.createApp }));
 vi.mock("../node-server.js", () => ({ startHubNodeServer: mocks.startServer }));
+vi.mock("../browser.js", () => ({ openHubBrowser: mocks.openBrowser }));
 vi.mock("../setup/services.js", () => ({ createSetupHubServices: mocks.createSetup }));
 vi.mock("../../setup/headless.js", () => ({ inspectSetupStatus: mocks.inspect }));
 vi.mock("../setup/readiness.js", () => ({ hasCommittedHubIdentity: mocks.committedIdentity }));
@@ -78,6 +80,96 @@ beforeEach(() => {
 afterEach(() => vi.restoreAllMocks());
 
 describe("Hub setup process", () => {
+  it("does not start resources when the finishing lane is already cancelled", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const onListening = vi.fn();
+    await runSetupHubCommand({ projectRoot: "/Users/private/project", openBrowser: true, signal: controller.signal, onListening });
+    expect(mocks.createSetup).not.toHaveBeenCalled();
+    expect(mocks.startServer).not.toHaveBeenCalled();
+    expect(mocks.startTelemetry).not.toHaveBeenCalled();
+    expect(mocks.openBrowser).not.toHaveBeenCalled();
+    expect(onListening).not.toHaveBeenCalled();
+    expect(process.stdout.write).not.toHaveBeenCalled();
+  });
+
+  it("closes a listener that finishes starting after cancellation", async () => {
+    let ready!: (server: { origin: string; close: typeof mocks.closeServer; replaceApp: () => void }) => void;
+    mocks.startServer.mockReturnValue(new Promise((resolve) => { ready = resolve; }));
+    const controller = new AbortController();
+    const onListening = vi.fn();
+    const running = runSetupHubCommand({ projectRoot: "/Users/private/project", openBrowser: true, signal: controller.signal, onListening });
+    await vi.waitFor(() => expect(mocks.startServer).toHaveBeenCalledOnce());
+    controller.abort();
+    ready({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp: vi.fn() });
+    await running;
+    expect(mocks.order).toEqual(["http", "setup"]);
+    expect(mocks.startTelemetry).not.toHaveBeenCalled();
+    expect(onListening).not.toHaveBeenCalled();
+    expect(mocks.openBrowser).not.toHaveBeenCalled();
+    expect(process.stdout.write).not.toHaveBeenCalled();
+  });
+
+  it("hands the bound finishing link to the HUD and removes shutdown listeners on abort", async () => {
+    const controller = new AbortController();
+    const onListening = vi.fn();
+    const removeAbortListener = vi.spyOn(controller.signal, "removeEventListener");
+    const priorInterrupt = process.listeners("SIGINT");
+    const priorTerminate = process.listeners("SIGTERM");
+    mocks.startServer.mockResolvedValue({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp: vi.fn() });
+    const running = runSetupHubCommand({
+      projectRoot: "/Users/private/project", openBrowser: true, port: 48123,
+      initialMode: "agent-memory", signal: controller.signal, onListening,
+    });
+    await vi.waitFor(() => expect(onListening).toHaveBeenCalledOnce());
+    expect(onListening).toHaveBeenCalledWith({ origin: "http://127.0.0.1:48123", bootstrapUrl: "http://127.0.0.1:48123/#token=private-bootstrap-token" });
+    expect(mocks.createSetup).toHaveBeenCalledWith("/Users/private/project", expect.objectContaining({ initialMode: "agent-memory" }));
+    expect(mocks.startServer).toHaveBeenCalledWith(expect.objectContaining({ port: 48123 }));
+    expect(mocks.openBrowser).toHaveBeenCalledWith("http://127.0.0.1:48123/#token=private-bootstrap-token");
+    expect(process.stdout.write).not.toHaveBeenCalled();
+    controller.abort();
+    await running;
+    expect(mocks.order).toEqual(["http", "setup", "telemetry"]);
+    expect(process.listeners("SIGINT")).toEqual(priorInterrupt);
+    expect(process.listeners("SIGTERM")).toEqual(priorTerminate);
+    expect(removeAbortListener).toHaveBeenCalledWith("abort", expect.any(Function));
+  });
+
+  it("handles cancellation from onListening before browser launch or shutdown wait", async () => {
+    const controller = new AbortController();
+    const priorInterrupt = process.listeners("SIGINT");
+    const priorTerminate = process.listeners("SIGTERM");
+    mocks.startServer.mockResolvedValue({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp: vi.fn() });
+    await runSetupHubCommand({
+      projectRoot: "/Users/private/project", openBrowser: true, signal: controller.signal,
+      onListening: () => controller.abort(),
+    });
+    expect(mocks.openBrowser).not.toHaveBeenCalled();
+    expect(process.stdout.write).not.toHaveBeenCalled();
+    expect(mocks.order).toEqual(["http", "setup", "telemetry"]);
+    expect(process.listeners("SIGINT")).toEqual(priorInterrupt);
+    expect(process.listeners("SIGTERM")).toEqual(priorTerminate);
+  });
+
+  it("routes startup output through onMessage when no listener callback is supplied", async () => {
+    const controller = new AbortController();
+    const onMessage = vi.fn(() => controller.abort());
+    mocks.startServer.mockResolvedValue({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp: vi.fn() });
+    await runSetupHubCommand({ projectRoot: "/Users/private/project", openBrowser: false, signal: controller.signal, onMessage });
+    expect(onMessage).toHaveBeenCalledWith(expect.stringContaining("http://127.0.0.1:48123/#token=private-bootstrap-token"));
+    expect(process.stdout.write).not.toHaveBeenCalled();
+    expect(mocks.order).toEqual(["http", "setup", "telemetry"]);
+  });
+
+  it("cleans up setup and reports a listener startup failure to its caller", async () => {
+    const onListening = vi.fn();
+    mocks.startServer.mockRejectedValue(new Error("Port is occupied."));
+    await expect(runSetupHubCommand({ projectRoot: "/Users/private/project", openBrowser: true, onListening })).rejects.toThrow("Port is occupied.");
+    expect(onListening).not.toHaveBeenCalled();
+    expect(mocks.openBrowser).not.toHaveBeenCalled();
+    expect(mocks.order).toEqual(["setup"]);
+  });
+
   it("starts the setup Hub without jobs when the checkout is not ready", async () => {
     let ready!: (server: { origin: string; close: typeof mocks.closeServer; replaceApp: () => void }) => void;
     mocks.startServer.mockReturnValue(new Promise((resolve) => { ready = resolve; }));
@@ -154,6 +246,47 @@ describe("Hub setup process", () => {
     expect(mocks.order).toEqual(["http", "jobs", "telemetry"]);
   });
 
+  it.each([{ setup: true }, { mode: "code-repo" }])("retains the setup finishing screen for explicit launch options %j", async (options) => {
+    mocks.inspect.mockReturnValue({ mode: "code-repo", hasScaffold: true, ready: true, stage: "ready" });
+    mocks.committedIdentity.mockResolvedValue(true);
+    mocks.startServer.mockResolvedValue({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp: vi.fn() });
+    const priorListeners = new Set(process.listeners("SIGTERM"));
+    const running = launchHub({ openBrowser: false, ...options });
+    await vi.waitFor(() => expect(mocks.events).toHaveBeenCalledOnce());
+    expect(mocks.createSetup).toHaveBeenCalledWith("/Users/private/project", expect.objectContaining({ initialMode: "mode" in options ? options.mode : undefined }));
+    expect(mocks.createTeam).not.toHaveBeenCalled();
+    stopHub(priorListeners);
+    await running;
+  });
+
+  it.each(["ready", "failed"])("routes a %s promotion notice through the HUD callback", async (outcome) => {
+    let onReady!: (signal: AbortSignal) => Promise<void>;
+    const replaceApp = vi.fn();
+    mocks.createSetup.mockImplementation((_root, options: { onReady: typeof onReady }) => {
+      onReady = options.onReady;
+      return { services: {}, setup: { shutdown: mocks.stopSetup } };
+    });
+    mocks.startServer.mockResolvedValue({ origin: "http://127.0.0.1:48123", close: mocks.closeServer, replaceApp });
+    const controller = new AbortController();
+    const onListening = vi.fn();
+    const onMessage = vi.fn();
+    const running = runSetupHubCommand({ projectRoot: "/Users/private/project", openBrowser: false, signal: controller.signal, onListening, onMessage });
+    await vi.waitFor(() => expect(onListening).toHaveBeenCalledOnce());
+    if (outcome === "ready") {
+      await onReady(new AbortController().signal);
+      expect(replaceApp).toHaveBeenCalledOnce();
+      expect(onMessage).toHaveBeenCalledWith("Project Hub is ready at http://127.0.0.1:48123");
+    } else {
+      mocks.findConfig.mockImplementation(() => { throw new Error("Config could not be read."); });
+      await expect(onReady(new AbortController().signal)).rejects.toThrow("Config could not be read.");
+      expect(replaceApp).not.toHaveBeenCalled();
+      expect(onMessage).toHaveBeenCalledWith("Project Hub could not open after setup: Config could not be read.");
+    }
+    expect(process.stdout.write).not.toHaveBeenCalled();
+    controller.abort();
+    await running;
+  });
+
   it("cleans up pending composition after cancellation without replacing the setup app", async () => {
     const replaceApp = vi.fn();
     let onReady!: (signal: AbortSignal) => Promise<void>;
diff --git a/src/hub/command.ts b/src/hub/command.ts
index e42ec69e..590ce70e 100644
--- a/src/hub/command.ts
+++ b/src/hub/command.ts
@@ -44,6 +44,9 @@ export interface RunSetupHubCommandOptions {
   readonly port?: number;
   readonly openBrowser: boolean;
   readonly initialMode?: SetupMode;
+  readonly signal?: AbortSignal;
+  readonly onListening?: (listener: { origin: string; bootstrapUrl: string }) => void;
+  readonly onMessage?: (message: string) => void;
 }
 
 /**
@@ -135,6 +138,7 @@ export async function runHubCommand(options: RunHubCommandOptions): Promise<void
 
 /** Setup-only Hub: same session/assets/server, no Team/Graph/Wiki jobs until ready. */
 export async function runSetupHubCommand(options: RunSetupHubCommandOptions): Promise<void> {
+  if (options.signal?.aborted) return;
   const captureEvent = createProjectTelemetryCapture(options.projectRoot);
   let server: Awaited<ReturnType<typeof startHubNodeServer>> | undefined;
   let stopTelemetry: (() => Promise<void>) | undefined;
@@ -143,9 +147,13 @@ export async function runSetupHubCommand(options: RunSetupHubCommandOptions): Pr
   let assets: HubAssetManifest | undefined;
   let promoting = false;
   let closing = false;
+  const reportMessage = (message: string): void => {
+    if (options.onMessage) options.onMessage(message);
+    else if (!options.onListening) process.stdout.write(`\n${message}\n`);
+  };
 
   const promoteToProjectHub = async (signal: AbortSignal): Promise<void> => {
-    if (signal.aborted) throw new Error("Setup was cancelled.");
+    if (signal.aborted || options.signal?.aborted) throw new Error("Setup was cancelled.");
     const listener = server;
     const session = security;
     const manifest = assets;
@@ -167,18 +175,16 @@ export async function runSetupHubCommand(options: RunSetupHubCommandOptions): Pr
         ...(config.wiki?.exclude === undefined ? {} : { wikiExclude: config.wiki.exclude }),
         ...(config.wiki?.readOnly === undefined ? {} : { wikiReadOnly: config.wiki.readOnly }),
       });
-      if (closing || signal.aborted) {
+      if (closing || signal.aborted || options.signal?.aborted) {
         await composed.jobs.shutdown();
-        throw new Error(signal.aborted ? "Setup was cancelled." : "The Hub listener is stopping.");
+        throw new Error(signal.aborted || options.signal?.aborted ? "Setup was cancelled." : "The Hub listener is stopping.");
       }
       jobs = composed.jobs;
       listener.replaceApp(composed.app);
-      process.stdout.write(`\nProject Hub is ready at ${listener.origin}\n`);
+      reportMessage(`Project Hub is ready at ${listener.origin}`);
     } catch (error) {
       const detail = error instanceof Error ? error.message : String(error);
-      process.stdout.write(
-        `\nProject Hub could not open after setup: ${detail}\n`,
-      );
+      reportMessage(`Project Hub could not open after setup: ${detail}`);
       throw error;
     } finally {
       promoting = false;
@@ -206,16 +212,18 @@ export async function runSetupHubCommand(options: RunSetupHubCommandOptions): Pr
     });
 
     server = await startHubNodeServer({ app, port: options.port });
+    if (options.signal?.aborted) return;
     expectedOrigin = server.origin;
     stopTelemetry = startHubTelemetry();
     emitHubTelemetry(captureEvent, "hub.session_started", {});
     const bootstrapUrl = `${server.origin}/#token=${encodeURIComponent(bootstrapToken)}`;
 
-    process.stdout.write(`\nProject Hub setup wizard running at ${server.origin}\n`);
-    process.stdout.write(`One-time bootstrap link (valid for 5 minutes):\n${bootstrapUrl}\n`);
-    process.stdout.write("Press Ctrl+C to stop.\n\n");
-    if (options.openBrowser) openHubBrowser(bootstrapUrl);
-    await waitForShutdownSignal();
+    options.onListening?.({ origin: server.origin, bootstrapUrl });
+    if (!options.onListening) {
+      reportMessage(`Project Hub setup wizard running at ${server.origin}\nOne-time bootstrap link (valid for 5 minutes):\n${bootstrapUrl}\nPress Ctrl+C to stop.\n`);
+    }
+    if (options.openBrowser && !options.signal?.aborted) openHubBrowser(bootstrapUrl);
+    await waitForShutdownSignal(options.signal);
   } finally {
     closing = true;
     try {
@@ -302,14 +310,17 @@ async function composeProductionHub(
   }
 }
 
-function waitForShutdownSignal(): Promise<void> {
+function waitForShutdownSignal(signal?: AbortSignal): Promise<void> {
   return new Promise((resolve) => {
+    if (signal?.aborted) { resolve(); return; }
     const complete = () => {
       process.off("SIGINT", complete);
       process.off("SIGTERM", complete);
+      signal?.removeEventListener("abort", complete);
       resolve();
     };
     process.once("SIGINT", complete);
     process.once("SIGTERM", complete);
+    signal?.addEventListener("abort", complete, { once: true });
   });
 }
diff --git a/src/hub/setup/__tests__/expected-errors.test.ts b/src/hub/setup/__tests__/expected-errors.test.ts
new file mode 100644
index 00000000..afbe1c16
--- /dev/null
+++ b/src/hub/setup/__tests__/expected-errors.test.ts
@@ -0,0 +1,102 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SetupRunSchema, type SetupRun } from "@mex/hub-contracts/setup";
+import { HubSetupRunner } from "../runner.js";
+
+const roots: string[] = [];
+const runners: HubSetupRunner[] = [];
+
+afterEach(async () => {
+  for (const runner of runners.splice(0)) await runner.shutdown();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-expected-error-"));
+  roots.push(root);
+  return root;
+}
+
+function observeRunner(root: string) {
+  const runner = new HubSetupRunner({ projectRoot: root });
+  runners.push(runner);
+  const observed: SetupRun[] = [];
+  runner.subscribe((run) => observed.push(run));
+  return { runner, observed };
+}
+
+async function expectSafeFailure(
+  runner: HubSetupRunner,
+  observed: readonly SetupRun[],
+  root: string,
+  message: string,
+): Promise<void> {
+  await vi.waitFor(() => expect(runner.snapshot().status).toBe("failed"));
+  const snapshot = SetupRunSchema.parse(runner.snapshot());
+  expect(snapshot).toMatchObject({
+    status: "failed", ready: false, error: message, message,
+    progress: { step: "scaffold" },
+  });
+  expect(observed.at(-1)).toEqual(snapshot);
+  for (const run of observed) expect(SetupRunSchema.safeParse(run).success).toBe(true);
+  const reconnect = vi.fn();
+  const unsubscribe = runner.subscribe(reconnect);
+  expect(reconnect).toHaveBeenCalledExactlyOnceWith(snapshot);
+  expect(SetupRunSchema.parse(reconnect.mock.calls[0]![0])).toEqual(snapshot);
+  unsubscribe();
+  const payload = JSON.stringify(observed);
+  expect(payload).not.toContain(root);
+  expect(payload).not.toContain("private-config-token");
+  expect(payload).not.toContain("Run mex setup --cli in this project for details");
+}
+
+describe("expected setup failures through the real Hub runner", () => {
+  it("reports malformed config and accepts a corrected-config retry on the same runner", async () => {
+    const root = fixture();
+    mkdirSync(join(root, ".mex"));
+    const configPath = join(root, ".mex", "config.json");
+    const malformed = '{"private-config-token":';
+    writeFileSync(configPath, malformed);
+    const { runner, observed } = observeRunner(root);
+
+    runner.start({ mode: "agent-memory", tools: [] });
+    await expectSafeFailure(runner, observed, root,
+      "Existing .mex/config.json is not a valid JSON object. Fix it before rerunning setup.");
+    expect(readFileSync(configPath, "utf8")).toBe(malformed);
+
+    writeFileSync(configPath, "{}\n");
+    const retry = runner.start({ mode: "agent-memory", tools: [] });
+    expect(retry).toMatchObject({ status: "running", error: null });
+    await vi.waitFor(() => expect(runner.snapshot().status).toBe("paused"), { timeout: 10_000 });
+    const resumed = SetupRunSchema.parse(runner.snapshot());
+    expect(resumed).toMatchObject({
+      mode: "agent-memory", status: "paused", stage: "needs_population",
+      ready: false, error: null, selectedTools: [], populationTool: null,
+    });
+    expect(resumed.prompt?.length).toBeGreaterThan(100);
+    expect(resumed.message).not.toContain("not a valid JSON");
+    for (const run of observed) expect(SetupRunSchema.safeParse(run).success).toBe(true);
+    expect(existsSync(join(root, ".mex", "graph.db"))).toBe(false);
+    expect(existsSync(join(root, ".mex", "wiki.db"))).toBe(false);
+  });
+
+  it("reports the broad Git ignore rule before graph construction or agent population", async () => {
+    const root = fixture();
+    execFileSync("git", ["init"], { cwd: root, stdio: "ignore" });
+    writeFileSync(join(root, ".gitignore"), ".mex/\n");
+    const { runner, observed } = observeRunner(root);
+
+    runner.start({ mode: "code-repo", tools: [] });
+    await expectSafeFailure(runner, observed, root,
+      "A Git ignore rule hides .mex/config.json. Remove the broad .mex ignore so canonical MEX files can be committed.");
+    expect(readFileSync(join(root, ".gitignore"), "utf8")).toBe(".mex/\n");
+    expect(existsSync(join(root, ".mex", "config.json"))).toBe(false);
+    expect(existsSync(join(root, ".mex", "graph.db"))).toBe(false);
+    expect(existsSync(join(root, ".mex", "wiki.db"))).toBe(false);
+    expect(runner.snapshot().populationTool).toBeNull();
+    expect(runner.snapshot().prompt).toBeNull();
+  });
+});
diff --git a/src/hub/setup/__tests__/runner.test.ts b/src/hub/setup/__tests__/runner.test.ts
index 9c300c0d..acf66b28 100644
--- a/src/hub/setup/__tests__/runner.test.ts
+++ b/src/hub/setup/__tests__/runner.test.ts
@@ -1,8 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { SetupRunSchema } from "@mex/hub-contracts/setup";
+import { SetupRunSchema, SetupTranscriptBatchSchema } from "@mex/hub-contracts/setup";
 import type { HeadlessSetupOptions } from "../../../setup/headless.js";
 import { SetupPopulationError } from "../../../setup/population.js";
+import { createPopulationTranscriptDecoder, type PopulationTranscriptSignal } from "../../../setup/population-transcript.js";
 import { SetupFinalizationError } from "../../../setup/index.js";
+import { SetupError } from "../../../setup/errors.js";
 
 const mocks = vi.hoisted(() => ({ inspect: vi.fn(), execute: vi.fn(), status: vi.fn(), initial: vi.fn() }));
 vi.mock("../../../setup/headless.js", () => ({ inspectSetupStatus: mocks.inspect, runHeadlessSetup: mocks.execute }));
@@ -63,37 +65,115 @@ describe("setup run lifecycle", () => {
       return new Promise((resolve) => { finish = () => resolve(result); });
     });
     const runner = new HubSetupRunner({ projectRoot: "/test" });
-    const run = runner.start({ mode: "code-repo", tools: ["codex"] });
+    const announcedPages: string[][] = [];
+    const setupListener = vi.fn((snapshot: ReturnType<HubSetupRunner["snapshot"]>) => {
+      if (snapshot.transcriptId) announcedPages.push(runner.readTranscript(snapshot.transcriptId, 0).entries.map(entry => entry.text));
+    });
+    runner.subscribe(setupListener);
+    expect(runner.start({ mode: "code-repo", tools: ["codex"] }).transcriptId).toBeUndefined();
     await Promise.resolve();
     const listener = vi.fn();
     const unsubscribe = runner.subscribeTranscript(listener);
-    for (let i = 0; i < 50; i++) report({ tool: "codex", kind: "assistant", text: `Session message ${i}\n` });
-    expect(listener).toHaveBeenCalledTimes(1);
+    const emissionsBeforeOutput = setupListener.mock.calls.length;
+    report({ tool: "codex", kind: "assistant", text: "Session message 0\n" });
+    const first = SetupRunSchema.parse(runner.snapshot());
+    expect(first.transcriptId).toBeDefined();
+    const firstId = first.transcriptId!;
+    expect(setupListener).toHaveBeenCalledTimes(emissionsBeforeOutput + 1);
+    expect(setupListener).toHaveBeenLastCalledWith(first);
+    expect(announcedPages[0]).toEqual(["Session message 0\n"]);
+    expect(SetupTranscriptBatchSchema.parse(runner.readTranscript(firstId, 0))).toMatchObject({
+      entries: [{ text: "Session message 0\n" }], cursor: 1, done: false,
+    });
+    for (let i = 1; i < 50; i++) report({ tool: "codex", kind: "assistant", text: `Session message ${i}\n` });
+    expect(setupListener).toHaveBeenCalledTimes(emissionsBeforeOutput + 1);
+    expect(listener).toHaveBeenCalledTimes(2);
     expect(JSON.stringify(runner.snapshot())).not.toContain("Session message");
-    expect(runner.readTranscript(run.transcriptId!, 0)).toMatchObject({ cursor: 32, done: false });
+    expect(runner.readTranscript(firstId, 0)).toMatchObject({ cursor: 32, done: false });
     await vi.advanceTimersByTimeAsync(200);
-    expect(listener).toHaveBeenCalledTimes(2);
+    expect(listener).toHaveBeenCalledTimes(3);
     runner.cancel();
     const cancelledReport = report;
     cancelledReport({ tool: "codex", kind: "assistant", text: "Late private output" });
     finish();
     await vi.waitFor(() => expect(runner.snapshot().status).toBe("cancelled"));
-    expect(runner.readTranscript(run.transcriptId!, 32)).toMatchObject({ cursor: 50, done: true });
+    expect(runner.readTranscript(firstId, 32)).toMatchObject({ cursor: 50, done: true });
     const next = runner.start({ mode: "code-repo", tools: ["claude"] });
     await Promise.resolve();
-    expect(next.transcriptId).not.toBe(run.transcriptId);
-    expect(() => runner.readTranscript(run.transcriptId!, 0)).toThrow("Reconnect");
+    expect(next.transcriptId).toBeUndefined();
+    expect(() => runner.readTranscript(firstId, 0)).toThrow("Reconnect");
     cancelledReport({ tool: "codex", kind: "assistant", text: "Prior session" });
-    expect(runner.readTranscript(next.transcriptId!, 0).entries).toEqual([]);
+    expect(runner.snapshot().transcriptId).toBeUndefined();
+    expect(vi.getTimerCount()).toBe(0);
     report({ tool: "claude", kind: "command", text: "Ran a command" });
-    runner.cancel();
+    const nextId = runner.snapshot().transcriptId!;
+    expect(nextId).toBeDefined();
+    expect(nextId).not.toBe(firstId);
+    expect(() => runner.readTranscript(firstId, 0)).toThrow("Reconnect");
     finish();
+    await vi.waitFor(() => expect(runner.snapshot().status).toBe("paused"));
+    report({ tool: "claude", kind: "assistant", text: "Late completed output" });
     await runner.shutdown();
-    expect(runner.readTranscript(next.transcriptId!, 0).entries.map((entry) => entry.text)).toEqual(["Ran a command"]);
+    expect(runner.readTranscript(nextId, 0)).toMatchObject({ done: true, entries: [{ text: "Ran a command" }] });
     expect(vi.getTimerCount()).toBe(0);
     unsubscribe();
   });
 
+  it.each([
+    { name: "manual population", stage: "needs_population", populated: false },
+    { name: "already populated commit checkpoint", stage: "needs_commit", populated: true },
+    { name: "finalization only", stage: "needs_finalize", populated: true },
+  ])("does not create a transcript for $name without agent output", async ({ stage, populated }) => {
+    mocks.inspect.mockReturnValue({ ...status, stage, populated });
+    mocks.status.mockResolvedValue({ ...status, stage: populated ? "needs_commit" : "needs_population", populated });
+    mocks.execute.mockImplementation(async (options: HeadlessSetupOptions) => {
+      options.onProgress?.({ step: populated ? "finalize" : "population", label: "Check existing setup" });
+      return { ...result, ready: false, populated, populationTool: null, populationCompleted: false };
+    });
+    const runner = new HubSetupRunner({ projectRoot: "/test" });
+    expect(runner.snapshot().transcriptId).toBeUndefined();
+    expect(runner.start({ mode: "code-repo", tools: [], confirmPopulation: true }).transcriptId).toBeUndefined();
+    await vi.waitFor(() => expect(runner.snapshot().status).toBe("paused"));
+    const snapshot = SetupRunSchema.parse(runner.snapshot());
+    expect(snapshot.transcriptId).toBeUndefined();
+    const reconnect = vi.fn();
+    runner.subscribe(reconnect);
+    expect(reconnect).toHaveBeenCalledExactlyOnceWith(snapshot);
+    await runner.shutdown();
+  });
+
+  it("keeps activity live without creating a transcript for empty or stripped output", async () => {
+    vi.useFakeTimers();
+    let options!: HeadlessSetupOptions;
+    let finish!: () => void;
+    mocks.execute.mockImplementation((input: HeadlessSetupOptions) => {
+      options = input;
+      return new Promise(resolve => { finish = () => resolve(result); });
+    });
+    const runner = new HubSetupRunner({ projectRoot: "/test" });
+    runner.start({ mode: "code-repo", tools: ["codex"] });
+    await Promise.resolve();
+    options.onPopulationActivity?.({ tool: "codex", kind: "starting", state: "running" });
+    options.onPopulationTranscript?.({ tool: "codex", kind: "assistant", text: "" });
+    const decoded = vi.fn((entry: PopulationTranscriptSignal) => options.onPopulationTranscript?.({ tool: "codex", ...entry }));
+    const decoder = createPopulationTranscriptDecoder("codex", decoded);
+    decoder.write(Buffer.from(JSON.stringify({ type: "item.completed", item: {
+      id: "control-only", type: "agent_message", text: "\u001b[31m\u0000\u0007\u001b[0m",
+    } }) + "\n"));
+    decoder.end();
+    expect(decoded).not.toHaveBeenCalled();
+    expect(runner.snapshot().populationActivity).toMatchObject({ tool: "codex", totalEvents: 1 });
+    expect(runner.snapshot().transcriptId).toBeUndefined();
+    expect(vi.getTimerCount()).toBe(0);
+    runner.cancel();
+    options.onPopulationTranscript?.({ tool: "codex", kind: "assistant", text: "Late first output" });
+    finish();
+    await runner.shutdown();
+    expect(SetupRunSchema.parse(runner.snapshot())).toMatchObject({ status: "cancelled" });
+    expect(runner.snapshot().transcriptId).toBeUndefined();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+
   it.each(["claude", "codex"] as const)("streams bounded %s activity before completion and preserves it for reconnects", async (tool) => {
     vi.useFakeTimers();
     vi.setSystemTime(new Date("2026-09-10T12:00:00.000Z"));
@@ -219,15 +299,82 @@ describe("setup run lifecycle", () => {
     await runner.shutdown();
   });
 
-  it("does not serialize an arbitrary internal failure into the browser", async () => {
-    mocks.execute.mockRejectedValue(new Error("secret token in /private/project/file.md"));
+  it("publishes only the authored setup message to current and reconnecting subscribers", async () => {
+    const userMessage = "Existing .mex/config.json is not a valid JSON object. Fix it before rerunning setup.";
+    mocks.execute.mockImplementation(async (options: HeadlessSetupOptions) => {
+      options.onProgress?.({ step: "scaffold", label: "Create .mex/ scaffold" });
+      throw new SetupError("Private failure in /private/project/config.json", {
+        userMessage,
+        cause: new Error("secret token in nested cause"),
+      });
+    });
+    const runner = new HubSetupRunner({ projectRoot: "/test" });
+    const listener = vi.fn();
+    runner.subscribe(listener);
+    runner.start({ mode: "code-repo", tools: [] });
+    await vi.waitFor(() => expect(runner.snapshot().status).toBe("failed"));
+
+    const snapshot = SetupRunSchema.parse(runner.snapshot());
+    expect(snapshot).toMatchObject({
+      status: "failed", ready: false, message: userMessage, error: userMessage,
+      progress: { step: "scaffold", label: "Create .mex/ scaffold" },
+    });
+    expect(snapshot.transcriptId).toBeUndefined();
+    expect(listener).toHaveBeenLastCalledWith(snapshot);
+    const reconnect = vi.fn();
+    runner.subscribe(reconnect);
+    expect(reconnect).toHaveBeenCalledExactlyOnceWith(snapshot);
+    expect(JSON.stringify([...listener.mock.calls, ...reconnect.mock.calls])).not.toMatch(/Private failure|\/private\/project|secret token|nested cause/);
+    await runner.shutdown();
+  });
+
+  it("keeps long authored setup failures inside the existing snapshot contract", async () => {
+    const userMessage = "Safe setup remediation. ".repeat(200);
+    mocks.execute.mockRejectedValue(new SetupError("Private exception detail", { userMessage }));
     const runner = new HubSetupRunner({ projectRoot: "/test" });
     runner.start({ mode: "code-repo", tools: [] });
     await vi.waitFor(() => expect(runner.snapshot().status).toBe("failed"));
-    expect(JSON.stringify(runner.snapshot())).not.toMatch(/secret token|\/private\/project/);
+    const snapshot = SetupRunSchema.parse(runner.snapshot());
+    expect(snapshot.message).toBe(userMessage.slice(0, 512));
+    expect(snapshot.error).toBe(snapshot.message);
+    expect(JSON.stringify(snapshot)).not.toContain("Private exception detail");
     await runner.shutdown();
   });
 
+  it.each([
+    new Error("secret token in /private/project/file.md", { cause: new Error("private nested cause") }),
+    { name: "SetupError", message: "secret token", userMessage: "untrusted claimed remediation" },
+  ])("does not serialize an arbitrary or lookalike failure into the browser", async (error) => {
+    mocks.execute.mockRejectedValue(error);
+    const runner = new HubSetupRunner({ projectRoot: "/test" });
+    runner.start({ mode: "code-repo", tools: [] });
+    await vi.waitFor(() => expect(runner.snapshot().status).toBe("failed"));
+    const snapshot = SetupRunSchema.parse(runner.snapshot());
+    expect(snapshot.message).toBe("Setup could not finish. Run mex setup --cli in this project for details, then retry.");
+    expect(snapshot.error).toBe(snapshot.message);
+    expect(JSON.stringify(snapshot)).not.toMatch(/secret token|\/private\/project|private nested cause|untrusted claimed remediation/);
+    await runner.shutdown();
+  });
+
+  it("keeps cancellation authoritative when execution rejects with an expected setup error", async () => {
+    let rejectExecution!: (error: unknown) => void;
+    mocks.execute.mockImplementation(() => new Promise((_resolve, reject) => { rejectExecution = reject; }));
+    const runner = new HubSetupRunner({ projectRoot: "/test" });
+    runner.start({ mode: "code-repo", tools: [] });
+    await vi.waitFor(() => expect(mocks.execute).toHaveBeenCalledOnce());
+    runner.cancel();
+    rejectExecution(new SetupError("Private cancellation detail", {
+      userMessage: "Expected setup failure that cancellation supersedes.",
+    }));
+    await runner.shutdown();
+    const snapshot = SetupRunSchema.parse(runner.snapshot());
+    expect(snapshot).toMatchObject({
+      status: "cancelled", ready: false, error: null,
+      message: "Setup was cancelled. You can resume it when ready.",
+    });
+    expect(JSON.stringify(snapshot)).not.toMatch(/Private cancellation detail|Expected setup failure/);
+  });
+
   it("stays at a commit checkpoint instead of attempting premature promotion", async () => {
     mocks.execute.mockResolvedValue(result);
     mocks.status.mockResolvedValue({ ...status, stage: "needs_commit", populated: true });
@@ -247,12 +394,14 @@ describe("setup run lifecycle", () => {
     const runner = new HubSetupRunner({ projectRoot: "/test", onReady });
     runner.start({ mode: "code-repo", tools: ["codex"], confirmPopulation: true });
     await vi.waitFor(() => expect(runner.snapshot().status).toBe("succeeded"));
+    expect(SetupRunSchema.parse(runner.snapshot()).transcriptId).toBeUndefined();
     expect(mocks.execute).not.toHaveBeenCalled();
     expect(onReady).not.toHaveBeenCalled();
     runner.start({ mode: "code-repo", tools: ["codex"], confirmPopulation: true, openHub: true });
     await vi.waitFor(() => expect(onReady).toHaveBeenCalledOnce());
     expect(mocks.execute).not.toHaveBeenCalled();
     await runner.shutdown();
+    expect(SetupRunSchema.parse(runner.snapshot()).transcriptId).toBeUndefined();
   });
 
   it("keeps completed Agent memory free of commit commands and Hub promotion", async () => {
diff --git a/src/hub/setup/runner.ts b/src/hub/setup/runner.ts
index 8246b518..1cf8087e 100644
--- a/src/hub/setup/runner.ts
+++ b/src/hub/setup/runner.ts
@@ -19,6 +19,7 @@ import {
 import { HubHttpError } from "../http/errors.js";
 import { setupCommitCheckpointCommands, SetupFinalizationError } from "../../setup/index.js";
 import { SetupPopulationError } from "../../setup/population.js";
+import { SetupError } from "../../setup/errors.js";
 import { initialSetupStatus, projectSetupStatus } from "./readiness.js";
 import { SetupTranscriptStore } from "./transcript.js";
 import { SetupCommitService } from "./commit.js";
@@ -235,8 +236,9 @@ export class HubSetupRunner {
     const startedAt = this.now().toISOString();
     const controller = new AbortController();
     this.controller = controller;
-    const transcriptId = randomUUID();
-    this.transcriptStore = new SetupTranscriptStore(transcriptId, this.now);
+    if (this.transcriptTimer !== null) clearTimeout(this.transcriptTimer);
+    this.transcriptTimer = null;
+    this.transcriptStore = null;
     this.run = {
       status: "running",
       mode: request.mode,
@@ -247,7 +249,6 @@ export class HubSetupRunner {
       prompt: null,
       populationTool: null,
       populationCompleted: false,
-      transcriptId,
       commitCommands: [],
       anchorNotes,
       message: "Starting MEX setup…",
@@ -310,7 +311,22 @@ export class HubSetupRunner {
         onAnchorNotes: (anchorNotes) => { this.run = { ...this.run, anchorNotes: [...anchorNotes] }; },
         onPopulationTranscript: (entry) => {
           if (signal.aborted || this.run.status !== "running" || this.controller?.signal !== signal) return;
-          this.transcriptStore?.append({ kind: entry.kind, text: entry.text });
+          if (entry.text.length === 0) return;
+          if (this.transcriptStore === null) {
+            // Population adapters already sanitize visible output. A setup
+            // check or an agent with no retained output has no transcript.
+            const transcriptId = randomUUID();
+            const store = new SetupTranscriptStore(transcriptId, this.now);
+            store.append({ kind: entry.kind, text: entry.text });
+            if (store.stats().retainedEntries === 0) return;
+            this.transcriptStore = store;
+            this.run = { ...this.run, transcriptId };
+            // Announce only after the first page is readable, even if no
+            // subsequent progress event arrives to wake setup subscribers.
+            this.emit();
+            return;
+          }
+          this.transcriptStore.append({ kind: entry.kind, text: entry.text });
           if (this.transcriptTimer === null) {
             this.transcriptTimer = setTimeout(() => this.notifyTranscript(), TRANSCRIPT_EMIT_INTERVAL_MS);
             this.transcriptTimer.unref();
@@ -366,15 +382,16 @@ export class HubSetupRunner {
       await this.finishFromResult(result, signal, request.openHub === true);
     } catch (error) {
       // Child output and arbitrary filesystem exceptions are never a browser payload.
-      const message = signal.aborted ? "Setup was cancelled. You can resume it when ready."
+      const message = (signal.aborted ? "Setup was cancelled. You can resume it when ready."
+        : error instanceof SetupError ? error.userMessage
         : error instanceof SetupPopulationError || error instanceof SetupFinalizationError || error instanceof HubHttpError ? error.message
-        : "Setup could not finish. Run mex setup --cli in this project for details, then retry.";
+        : "Setup could not finish. Run mex setup --cli in this project for details, then retry.").slice(0, 512);
       this.run = {
         ...this.run,
         status: signal.aborted ? "cancelled" : "failed",
         ready: false,
         message,
-        error: signal.aborted ? null : message.slice(0, 512),
+        error: signal.aborted ? null : message,
         finishedAt: this.now().toISOString(),
         progress: this.run.progress,
       };
diff --git a/src/setup/__tests__/agent-errors.test.ts b/src/setup/__tests__/agent-errors.test.ts
new file mode 100644
index 00000000..14edc51e
--- /dev/null
+++ b/src/setup/__tests__/agent-errors.test.ts
@@ -0,0 +1,145 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  AgentAssetsError,
+  applyAgentAssetsPlan,
+  planAgentAssets,
+  type AgentAssetsErrorCode,
+} from "../../agent-skills/installer.js";
+import { classifySetupAgentAssetsError } from "../agent-errors.js";
+import { SetupError } from "../errors.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("setup agent integration error classification", () => {
+  it.each([
+    ["INVALID_PACKAGED_SKILL", "Reinstall MEX"],
+    ["INVALID_OPTIONS", "Check the project directory"],
+    ["IGNORE_CHECK_FAILED", "run git status"],
+    ["CONCURRENT_MODIFICATION", "review the affected files"],
+    ["PATH_IDENTITY_CHANGED", "reconcile those backups before rerunning setup"],
+    ["REPLACEMENT_ACTIVE_BACKUP_RETAINED", "reconcile those backups before rerunning setup"],
+    ["APPLY_FAILED", "reconcile those backups before rerunning setup"],
+  ] satisfies Array<[AgentAssetsErrorCode, string]>)("classifies %s by code while retaining private diagnostics", (code, recovery) => {
+    const underlying = new Error("private child output and secret token");
+    const original = new AgentAssetsError(code, "failure at /private/project/secret-path", { cause: underlying });
+
+    const classified = classifySetupAgentAssetsError(original);
+
+    expect(classified).toBeInstanceOf(SetupError);
+    expect(classified?.message).toBe(original.message);
+    expect(classified?.cause).toBe(original);
+    expect(original.cause).toBe(underlying);
+    expect(classified?.userMessage).toContain(recovery);
+    expect(classified?.userMessage).not.toMatch(/private|secret|token/);
+    expect(classified?.userMessage.length).toBeLessThanOrEqual(512);
+    const differentText = new AgentAssetsError(code, "unrelated diagnostic");
+    expect(classifySetupAgentAssetsError(differentText)?.userMessage).toBe(classified?.userMessage);
+  });
+
+  it("preserves rollback diagnostics without recommending an unreviewed retry", () => {
+    const rollback = new AggregateError([
+      new Error("activation failed at /private/project"),
+      new Error("backup retained at /private/backup"),
+    ]);
+    const original = new AgentAssetsError("APPLY_FAILED", "Could not restore /private/backup", { cause: rollback });
+
+    const classified = classifySetupAgentAssetsError(original);
+
+    expect(classified?.cause).toBe(original);
+    expect(original.cause).toBe(rollback);
+    expect(classified?.userMessage).toContain("some files or backups may remain");
+    expect(classified?.userMessage).toContain("reconcile those backups before rerunning setup");
+    expect(classified?.userMessage).toContain(".mex-backup-");
+    expect(classified?.userMessage).toContain(".claude/skills or .agents/skills");
+    expect(classified?.userMessage).not.toContain("terminal diagnostics");
+    expect(classified?.userMessage).not.toContain("/private/");
+  });
+
+  it.each(["EACCES", "ENOSPC"])("delegates raw %s failures to the filesystem classifier", (code) => {
+    const original = Object.assign(new Error("private filesystem diagnostic"), { code });
+
+    const classified = classifySetupAgentAssetsError(original);
+
+    expect(classified?.message).toBe(original.message);
+    expect(classified?.cause).toBe(original);
+    expect(classified?.userMessage).toContain("Could not install the selected agent integrations");
+    expect(classified?.userMessage).toContain(code === "EACCES" ? "permissions" : "Storage is full");
+    expect(classified?.userMessage).not.toContain("private");
+  });
+
+  it.each([
+    new Error("INVALID_PACKAGED_SKILL: missing packaged skills"),
+    Object.assign(new Error("pretended installer failure"), { code: "INVALID_PACKAGED_SKILL" }),
+    { name: "AgentAssetsError", code: "APPLY_FAILED", message: "pretended installer failure" },
+    new AgentAssetsError("UNKNOWN_PLAN", "private internal diagnostic"),
+    new AgentAssetsError("DRY_RUN_PLAN", "private internal diagnostic"),
+    new AgentAssetsError("FUTURE_CODE" as AgentAssetsErrorCode, "private future diagnostic"),
+    null,
+  ])("leaves unrecognized failures for the generic fallback: %j", (error) => {
+    expect(classifySetupAgentAssetsError(error)).toBeNull();
+  });
+
+  it.each(["missing", "invalid"])("classifies a real %s packaged-skills failure", (kind) => {
+    const root = fixture();
+    const source = join(root, "packaged-skills");
+    if (kind === "invalid") {
+      mkdirSync(join(source, "mex-inbox"), { recursive: true });
+      writeFileSync(join(source, "mex-inbox", "README.md"), "No SKILL.md\n");
+    }
+    const original = captureInstallerError(() => planAgentAssets({
+      projectRoot: root, packagedSkillsRoot: source, packageVersion: "1.0.0",
+      clients: ["claude"], checkIgnored: false,
+    }));
+
+    const classified = classifySetupAgentAssetsError(original);
+
+    expect(original.code).toBe("INVALID_PACKAGED_SKILL");
+    expect(classified?.cause).toBe(original);
+    expect(classified?.userMessage).toContain("packaged MEX agent skills are missing or invalid");
+    expect(classified?.userMessage).not.toContain(root);
+  });
+
+  it("classifies a real change between installation preview and apply", () => {
+    const root = fixture();
+    const source = join(root, "packaged-skills");
+    for (const skill of ["mex-inbox", "mex-relay"]) {
+      mkdirSync(join(source, skill), { recursive: true });
+      writeFileSync(join(source, skill, "SKILL.md"), "Packaged skill\n");
+    }
+    const plan = planAgentAssets({
+      projectRoot: root, packagedSkillsRoot: source, packageVersion: "1.0.0",
+      clients: ["claude"], checkIgnored: false,
+    });
+    mkdirSync(join(root, ".claude/skills/mex-inbox"), { recursive: true });
+    writeFileSync(join(root, ".claude/skills/mex-inbox/SKILL.md"), "Concurrent authored skill\n");
+    const original = captureInstallerError(() => applyAgentAssetsPlan(plan));
+
+    const classified = classifySetupAgentAssetsError(original);
+
+    expect(original.code).toBe("CONCURRENT_MODIFICATION");
+    expect(classified?.userMessage).toContain("Finish or stop other edits");
+    expect(classified?.cause).toBe(original);
+  });
+});
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-agent-errors-"));
+  roots.push(root);
+  return root;
+}
+
+function captureInstallerError(run: () => unknown): AgentAssetsError {
+  try {
+    run();
+  } catch (error) {
+    expect(error).toBeInstanceOf(AgentAssetsError);
+    return error as AgentAssetsError;
+  }
+  throw new Error("Expected an agent installer failure.");
+}
diff --git a/src/setup/__tests__/contact.test.ts b/src/setup/__tests__/contact.test.ts
index 73f23005..a7b2dbd8 100644
--- a/src/setup/__tests__/contact.test.ts
+++ b/src/setup/__tests__/contact.test.ts
@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
@@ -62,7 +62,8 @@ describe("optional setup contact", () => {
     expect(readContactPreference()).toEqual({ status: "unavailable" });
     await expect(rememberContactPreference({ status: "skipped" })).rejects.toThrow();
     expect(readdirSync(outside)).toEqual([]);
-    rmSync(join(root, ".mex/setup")); mkdirSync(join(root, ".mex/setup"));
+    expect(lstatSync(join(root, ".mex/setup")).isSymbolicLink()).toBe(true);
+    unlinkSync(join(root, ".mex/setup")); mkdirSync(join(root, ".mex/setup"));
     writeFileSync(join(root, ".mex/setup/contact-submitted.json"), "broken");
     expect(readContactPreference()).toEqual({ status: "unavailable" });
     await expect(rememberContactPreference({ status: "submitted" })).rejects.toThrow();
diff --git a/src/setup/__tests__/entry.test.ts b/src/setup/__tests__/entry.test.ts
new file mode 100644
index 00000000..54c056fa
--- /dev/null
+++ b/src/setup/__tests__/entry.test.ts
@@ -0,0 +1,135 @@
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { findSetupProjectRoot, resolveDefaultEntry } from "../entry.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("default setup entry", () => {
+  it("keeps empty folders and missing paths read-only while choosing setup", async () => {
+    const root = fixture();
+    const missing = join(root, "not-created", "nested");
+    expect(findSetupProjectRoot(root)).toBe(root);
+    expect(findSetupProjectRoot(missing)).toBe(missing);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(await resolveDefaultEntry(missing)).toBe("setup");
+    expect(readdirSync(root)).toEqual([]);
+  });
+
+  it("chooses setup for a Git checkout before its scaffold exists", async () => {
+    const root = fixture(true);
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(snapshot(root)).toEqual(before);
+    expect(existsSync(join(root, ".mex"))).toBe(false);
+  });
+
+  it("chooses setup until the code project's identity is committed", async () => {
+    const root = fixture(true);
+    scaffold(root, "code-repo");
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("keeps Agent memory in setup even when its identity is committed", async () => {
+    const root = fixture(true);
+    scaffold(root, "agent-memory");
+    commitIdentity(root);
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("preserves Hub recovery for committed code projects without indexes or populated files", async () => {
+    const root = fixture(true);
+    scaffold(root, "code-repo");
+    commitIdentity(root);
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("hub");
+    expect(snapshot(root)).toEqual(before);
+    expect(existsSync(join(root, ".mex/graph.db"))).toBe(false);
+    expect(existsSync(join(root, ".mex/wiki.db"))).toBe(false);
+    expect(existsSync(join(root, ".mex/local"))).toBe(false);
+  });
+
+  it("does not route a committed identity without ROUTER.md to Hub", async () => {
+    const root = fixture(true);
+    scaffold(root, "code-repo");
+    rmSync(join(root, ".mex/ROUTER.md"));
+    commitIdentity(root);
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("returns to setup when the working identity differs from the committed identity", async () => {
+    const root = fixture(true);
+    scaffold(root, "code-repo");
+    commitIdentity(root);
+    scaffold(root, "code-repo");
+    const before = snapshot(root);
+    expect(await resolveDefaultEntry(root)).toBe("setup");
+    expect(snapshot(root)).toEqual(before);
+  });
+
+  it("discovers the same checkout from a nested working directory and preserves the old export", async () => {
+    const root = fixture(true);
+    scaffold(root, "code-repo");
+    commitIdentity(root);
+    const nested = join(root, "src", "nested");
+    mkdirSync(nested, { recursive: true });
+    vi.spyOn(process, "cwd").mockReturnValue(nested);
+    const before = snapshot(root);
+    expect(findSetupProjectRoot()).toBe(root);
+    expect(await resolveDefaultEntry()).toBe("hub");
+    const setup = await import("../index.js");
+    expect(setup.findSetupProjectRoot).toBe(findSetupProjectRoot);
+    expect(snapshot(root)).toEqual(before);
+  });
+});
+
+function fixture(withGit = false): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-entry-"));
+  roots.push(root);
+  if (withGit) git(root, "-c", "init.templateDir=", "init", "--quiet");
+  return root;
+}
+
+function scaffold(root: string, mode: "code-repo" | "agent-memory"): void {
+  mkdirSync(join(root, ".mex"), { recursive: true });
+  writeFileSync(join(root, ".mex/ROUTER.md"), "# [Project Name]\n");
+  writeFileSync(join(root, ".mex/config.json"), JSON.stringify({
+    scaffold_id: randomUUID(), scaffold_name: "Entry fixture", setupMode: mode, aiTools: [],
+  }));
+}
+
+function git(root: string, ...args: string[]): void {
+  // Fixture commits must not leave background maintenance racing the full .git snapshot.
+  execFileSync("git", ["-c", "maintenance.auto=false", ...args], { cwd: root, stdio: "pipe" });
+}
+
+function commitIdentity(root: string): void {
+  git(root, "add", ".mex/config.json");
+  git(root, "-c", "user.name=Setup entry test", "-c", "user.email=entry@example.invalid", "-c", "commit.gpgsign=false", "-c", "core.hooksPath=.git/hooks", "commit", "--quiet", "-m", "Fixture identity");
+}
+
+/** Small fixtures include Git bytes so discovery cannot silently initialize state. */
+function snapshot(root: string, prefix = ""): Record<string, string> {
+  const entries: Record<string, string> = {};
+  for (const entry of readdirSync(join(root, prefix), { withFileTypes: true })) {
+    const path = join(prefix, entry.name);
+    if (entry.isDirectory()) {
+      entries[`${path}/`] = "";
+      Object.assign(entries, snapshot(root, path));
+    } else entries[path] = readFileSync(join(root, path)).toString("base64");
+  }
+  return entries;
+}
diff --git a/src/setup/__tests__/finalization-errors.test.ts b/src/setup/__tests__/finalization-errors.test.ts
new file mode 100644
index 00000000..2f445ea9
--- /dev/null
+++ b/src/setup/__tests__/finalization-errors.test.ts
@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { SetupWikiFinalizationResult } from "../wiki-finalize.js";
+import { WikiMaintenanceLockedError } from "../../wiki/index/dbfile.js";
+import { SetupError } from "../errors.js";
+
+const mocks = vi.hoisted(() => ({ capture: vi.fn(), wiki: vi.fn() }));
+vi.mock("../../graph/runtime.js", async (original) => ({ ...await original(), captureGroundingBaselines: mocks.capture }));
+vi.mock("../wiki-finalize.js", () => ({ finalizeSetupWiki: mocks.wiki }));
+vi.mock("../../config.js", async (original) => ({ ...await original(), findConfig: () => ({ wiki: {} }) }));
+
+import { finalizeCodeRepoSetup, SetupFinalizationError } from "../index.js";
+
+beforeEach(() => {
+  vi.resetAllMocks();
+  vi.spyOn(console, "log").mockImplementation(() => undefined);
+  mocks.capture.mockResolvedValue({ captured: 0, skipped: 0 });
+});
+afterEach(() => vi.restoreAllMocks());
+
+describe("setup finalization expected failures", () => {
+  it("preserves a graph failure locally while reporting actionable grounding advice", async () => {
+    mocks.capture.mockRejectedValue(Object.assign(new Error("secret diagnostic /private/project"), { code: "GRAPH_MAINTENANCE_LOCKED" }));
+    const failure = await finalizeCodeRepoSetup("/project", "/project/.mex").catch(error => error);
+    expect(failure).toBeInstanceOf(SetupError);
+    expect(failure.message).toContain("secret diagnostic");
+    expect(failure.userMessage).toContain("Another graph operation is active");
+    expect(failure.userMessage).not.toContain("secret");
+    expect(mocks.wiki).not.toHaveBeenCalled();
+  });
+
+  it("keeps an unexpected grounding exception out of the browser allowlist", async () => {
+    mocks.capture.mockRejectedValue(new Error("secret unexpected exception"));
+    const failure = await finalizeCodeRepoSetup("/project", "/project/.mex").catch(error => error);
+    expect(failure).not.toBeInstanceOf(SetupError);
+    expect(failure.message).toContain("secret unexpected exception");
+  });
+
+  it("projects a thrown Wiki lock refusal", async () => {
+    mocks.wiki.mockRejectedValue(new WikiMaintenanceLockedError("/private/project/wiki.db.lock"));
+    const failure = await finalizeCodeRepoSetup("/project", "/project/.mex").catch(error => error);
+    expect(failure).toBeInstanceOf(SetupError);
+    expect(failure.userMessage).toContain("Another Wiki operation is active");
+    expect(failure.userMessage).not.toContain("/private");
+  });
+
+  it("retains the finalization error type and reports a Wiki diagnostic's authored fix", async () => {
+    mocks.wiki.mockResolvedValue({ ready: false, stage: "index", reason: "Wiki index rebuild failed validation.",
+      diagnostics: [{ code: "WIKI_INDEX_FTS5_UNAVAILABLE", severity: "error", message: "private database error", remediation: "private override" }],
+    } as SetupWikiFinalizationResult);
+    const failure = await finalizeCodeRepoSetup("/project", "/project/.mex").catch(error => error);
+    expect(failure).toBeInstanceOf(SetupFinalizationError);
+    expect(failure).toBeInstanceOf(SetupError);
+    expect(failure.message).toContain("WIKI_INDEX_FTS5_UNAVAILABLE");
+    expect(failure.userMessage).toContain("use a different Node build/version");
+    expect(failure.userMessage).toContain("Retry setup");
+    expect(failure.userMessage).not.toContain("private");
+    expect(failure.userMessage.length).toBeLessThanOrEqual(512);
+  });
+
+  it("preserves the existing grounding-remediation contract", async () => {
+    mocks.capture.mockImplementation(async (_config, options) => {
+      options.warn("Skipped grounding baseline for unavailable node <exact-node-id> in .mex/AGENTS.md.");
+      return { captured: 0, skipped: 1 };
+    });
+    const failure = await finalizeCodeRepoSetup("/project", "/project/.mex").catch(error => error);
+    expect(failure).toBeInstanceOf(SetupFinalizationError);
+    expect(failure.message).toContain("<exact-node-id> in .mex/AGENTS.md");
+    expect(failure.userMessage).toBe(failure.message);
+    expect(failure.message.length).toBeLessThanOrEqual(512);
+  });
+});
diff --git a/src/setup/__tests__/graph-progress-integration.test.ts b/src/setup/__tests__/graph-progress-integration.test.ts
new file mode 100644
index 00000000..f1e02b48
--- /dev/null
+++ b/src/setup/__tests__/graph-progress-integration.test.ts
@@ -0,0 +1,72 @@
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import type { GraphMaintenanceProgress } from "../../team/contracts/graph.js";
+import { runHeadlessSetup, type SetupProgressStep } from "../headless.js";
+
+const roots: string[] = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("real setup graph progress", () => {
+  it("forwards isolated worker phases and file counts while the parent remains responsive", async () => {
+    const root = fixture();
+    const setupSteps: SetupProgressStep[] = [];
+    const updates: GraphMaintenanceProgress[] = [];
+    let parsing = false;
+    let beatsDuringParsing = 0;
+    const heartbeat = setInterval(() => { if (parsing) beatsDuringParsing++; }, 5);
+    let result: Awaited<ReturnType<typeof runHeadlessSetup>>;
+    try {
+      result = await runHeadlessSetup({
+        projectRoot: root, mode: "code-repo", tools: [], confirmPopulation: true,
+        onProgress: ({ step }) => { setupSteps.push(step); },
+        onGraphProgress: (update) => {
+          expect(setupSteps.at(-1)).toBe("graph");
+          updates.push(update);
+          parsing = update.phase === "parse";
+        },
+      });
+    } finally {
+      clearInterval(heartbeat);
+    }
+    expect(result).toMatchObject({ mode: "code-repo", ready: false, stage: "needs_population" });
+    expect(setupSteps.filter(step => step === "graph")).toHaveLength(1);
+    expect(setupSteps.at(-1)).toBe("population");
+    expect(updates.map(update => update.phase)).toEqual(expect.arrayContaining(["discover", "stage", "parse", "resolve", "validate", "publish"]));
+    const parsed = updates.filter(update => update.phase === "parse");
+    expect(parsed[0]).toMatchObject({ completed: 0, total: 3 });
+    expect(parsed.at(-1)).toMatchObject({ completed: 3, total: 3 });
+    expect(parsed.every((update, index) => index === 0 || update.completed! >= parsed[index - 1].completed!)).toBe(true);
+    expect(beatsDuringParsing).toBeGreaterThan(0);
+    expect(JSON.stringify(updates)).not.toContain(root);
+    expect(JSON.stringify(updates)).not.toContain("private-calculation.ts");
+    expect(existsSync(join(root, ".mex/graph.db"))).toBe(true);
+    expect(existsSync(join(root, ".mex/wiki.db"))).toBe(false);
+    expect(readdirSync(join(root, ".mex")).filter(name => name.includes("candidate") || name.endsWith(".lock"))).toEqual([]);
+    expect(() => execFileSync("git", ["rev-parse", "HEAD"], { cwd: root, stdio: "ignore" })).toThrow();
+  });
+
+  it("does not report graph work for agent-memory setup", async () => {
+    const root = fixture();
+    const updates: GraphMaintenanceProgress[] = [];
+    await runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [], confirmPopulation: true,
+      onGraphProgress: update => updates.push(update) });
+    expect(updates).toEqual([]);
+    expect(existsSync(join(root, ".mex/graph.db"))).toBe(false);
+  });
+});
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-progress-"));
+  roots.push(root);
+  execFileSync("git", ["-c", "init.templateDir=", "init", "--quiet"], { cwd: root, stdio: "pipe" });
+  mkdirSync(join(root, "src"));
+  writeFileSync(join(root, "src/private-calculation.ts"), "export function double(value: number): number { return value * 2; }\n");
+  writeFileSync(join(root, "src/message.ts"), "export const prefix = 'Result';\n");
+  writeFileSync(join(root, "src/index.ts"), "import { double } from './private-calculation';\nimport { prefix } from './message';\nexport const message = `${prefix}: ${double(21)}`;\n");
+  return root;
+}
diff --git a/src/setup/__tests__/graph-progress.test.ts b/src/setup/__tests__/graph-progress.test.ts
new file mode 100644
index 00000000..3f40db25
--- /dev/null
+++ b/src/setup/__tests__/graph-progress.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { formatSetupGraphActivity, setupGraphActivity } from "../graph-progress.js";
+
+describe("setup graph activity", () => {
+  it("labels parsed file counts without making a whole-setup percentage claim", () => {
+    expect(setupGraphActivity({ phase: "parse", completed: 12, total: 40, message: "private source path" })).toEqual({
+      detail: "Parsing source files", progress: { completed: 12, total: 40, unit: "files parsed" },
+    });
+    expect(formatSetupGraphActivity({ phase: "parse", completed: 12, total: 40, message: "private source path" }))
+      .toBe("Parsing source files: 12 / 40 files parsed");
+  });
+
+  it("clears completed parse counts during resolve, validation, and publication", () => {
+    for (const phase of ["resolve", "validate", "publish"] as const) {
+      const activity = setupGraphActivity({ phase, completed: 40, total: 40, message: "private path or command" });
+      expect(activity.progress).toBeUndefined();
+      expect(activity.detail).not.toContain("private");
+    }
+  });
+
+  it("does not fabricate counts or a total and refuses invalid measurements", () => {
+    expect(setupGraphActivity({ phase: "parse", message: "raw" })).toEqual({ detail: "Parsing source files" });
+    expect(setupGraphActivity({ phase: "parse", completed: 0, message: "raw" }).progress).toEqual({ completed: 0, unit: "files parsed" });
+    for (const completed of [NaN, Infinity, -1, 1.5, Number.MAX_SAFE_INTEGER + 1]) {
+      expect(setupGraphActivity({ phase: "parse", completed, total: 3, message: "raw" }).progress).toBeUndefined();
+    }
+    expect(setupGraphActivity({ phase: "parse", completed: 10, total: 2, message: "raw" }).progress).toEqual({ completed: 10, unit: "files parsed" });
+  });
+});
diff --git a/src/setup/__tests__/headless-population.test.ts b/src/setup/__tests__/headless-population.test.ts
index e40931b7..320e6ec6 100644
--- a/src/setup/__tests__/headless-population.test.ts
+++ b/src/setup/__tests__/headless-population.test.ts
@@ -1,4 +1,5 @@
 import crossSpawn from "cross-spawn";
+import { spawn } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -319,8 +320,10 @@ describe("headless population process", () => {
   it("reports a launch failure instead of manual population", async () => {
     const fixture = agentFixture("");
     const onActivity = vi.fn();
+    // Node's own spawn fails before the child starts on every platform. On
+    // Windows cross-spawn runs a missing file through cmd.exe, which starts.
     const missingSpawn = ((_command: string, args: string[], options: object) =>
-      crossSpawn(join(fixture.root, "does-not-exist"), args, options)) as unknown as typeof crossSpawn;
+      spawn(join(fixture.root, "does-not-exist"), args, options)) as unknown as typeof crossSpawn;
     await expect(launchHeadlessSetupPopulation({
       ...fixture.options,
       onActivity,
diff --git a/src/setup/__tests__/headless.test.ts b/src/setup/__tests__/headless.test.ts
index 6553e202..d4887182 100644
--- a/src/setup/__tests__/headless.test.ts
+++ b/src/setup/__tests__/headless.test.ts
@@ -8,6 +8,8 @@ import * as population from "../headless-population.js";
 import { runSetup } from "../index.js";
 import { MEX_ANCHOR_START } from "../anchor.js";
 import { loadConfiguredAiTools, loadConfiguredSetupMode, hasConfiguredAiTools } from "../../config.js";
+import * as config from "../../config.js";
+import { SetupError } from "../errors.js";
 
 const roots: string[] = [];
 
@@ -60,6 +62,47 @@ describe("headless setup status", () => {
 });
 
 describe("headless setup run", () => {
+  it("returns an actionable expected error for malformed config without replacing it", async () => {
+    const root = fixture();
+    mkdirSync(join(root, ".mex"));
+    writeFileSync(join(root, ".mex/config.json"), "{broken");
+    await expect(runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [] })).rejects.toMatchObject({
+      userMessage: "Existing .mex/config.json is not a valid JSON object. Fix it before rerunning setup.",
+    });
+    expect(readFileSync(join(root, ".mex/config.json"), "utf8")).toBe("{broken");
+  });
+
+  it("identifies official skill conflicts without replacing user-owned files", async () => {
+    const root = fixture();
+    const skill = join(root, ".agents/skills/mex-inbox");
+    mkdirSync(skill, { recursive: true });
+    writeFileSync(join(skill, "SKILL.md"), "User-owned skill");
+    await expect(runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: ["codex"] })).rejects.toMatchObject({
+      userMessage: expect.stringContaining("Check .agents/skills/mex-inbox"),
+    });
+    expect(readFileSync(join(skill, "SKILL.md"), "utf8")).toBe("User-owned skill");
+  });
+
+  it("explains a config write failure without leaking raw filesystem diagnostics", async () => {
+    const root = fixture();
+    const cause = Object.assign(new Error("private path /secret/config"), { code: "ENOSPC" });
+    vi.spyOn(config, "saveAiTools").mockImplementation(() => { throw cause; });
+    const error = await runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [] }).catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(SetupError);
+    expect(error).toMatchObject({ cause, message: cause.message });
+    expect((error as SetupError).userMessage).toContain("Could not save the AI tool selection in .mex/config.json.");
+    expect((error as SetupError).userMessage).toContain("Free disk space");
+    expect((error as SetupError).userMessage).not.toMatch(/private|secret/);
+  });
+
+  it("preserves the existing persistence check as an expected error", async () => {
+    const root = fixture();
+    vi.spyOn(config, "readScaffoldId").mockReturnValue(undefined);
+    await expect(runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [] })).rejects.toMatchObject({
+      userMessage: "Could not persist .mex/config.json. Fix its permissions or contents and rerun setup.",
+    });
+  });
+
   it("delivers the real manual prompt and integration guidance before a population failure", async () => {
     const root = fixture();
     const authoredRules = `My existing agent rules.\n${MEX_ANCHOR_START}\n`;
diff --git a/src/setup/__tests__/ignore.test.ts b/src/setup/__tests__/ignore.test.ts
index c37a4dd0..5f8bff0e 100644
--- a/src/setup/__tests__/ignore.test.ts
+++ b/src/setup/__tests__/ignore.test.ts
@@ -1,5 +1,7 @@
 import {
+  appendFileSync,
   existsSync,
+  lstatSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -9,8 +11,9 @@ import {
 } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { execFileSync } from "node:child_process";
-import { afterEach, describe, expect, it } from "vitest";
+import { execFileSync, spawnSync } from "node:child_process";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { SetupError } from "../errors.js";
 import {
   ensureSetupIgnoreProtection,
   renderSetupIgnoreProtection,
@@ -18,9 +21,29 @@ import {
   verifySetupIgnoreProtection,
 } from "../ignore.js";
 
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    appendFileSync: vi.fn(actual.appendFileSync),
+    lstatSync: vi.fn(actual.lstatSync),
+    mkdirSync: vi.fn(actual.mkdirSync),
+    readFileSync: vi.fn(actual.readFileSync),
+    writeFileSync: vi.fn(actual.writeFileSync),
+  };
+});
+
+vi.mock("node:child_process", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:child_process")>();
+  return { ...actual, spawnSync: vi.fn(actual.spawnSync) };
+});
+
 const roots: string[] = [];
 
 afterEach(() => {
+  for (const mocked of [appendFileSync, lstatSync, mkdirSync, readFileSync, writeFileSync, spawnSync]) {
+    vi.mocked(mocked).mockReset();
+  }
   for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
 });
 
@@ -128,9 +151,11 @@ describe("setup local-data ignore protection", () => {
     writeFileSync(outside, "outside\n");
     symlinkSync(outside, join(root, ".mex/.gitignore"), "file");
 
-    expect(() => ensureSetupIgnoreProtection({ projectRoot: root })).toThrow(
-      SetupIgnoreProtectionError,
-    );
+    const error = ignoreError(() => ensureSetupIgnoreProtection({ projectRoot: root }));
+    expect(error.message).toContain(root);
+    expect(error.userMessage).toContain(".mex/.gitignore path must be a regular file");
+    expect(error.userMessage).not.toContain(root);
+    expect(error.userMessage).not.toContain(outside);
     expect(readFileSync(outside, "utf8")).toBe("outside\n");
   });
 
@@ -143,6 +168,72 @@ describe("setup local-data ignore protection", () => {
     );
   });
 
+  it.each(["file", "symlink"] as const)("explains an unsafe .mex %s without exposing its absolute path", (kind) => {
+    const root = fixture();
+    const outside = fixture();
+    if (kind === "file") writeFileSync(join(root, ".mex"), "existing file\n");
+    else symlinkSync(outside, join(root, ".mex"), process.platform === "win32" ? "junction" : "dir");
+
+    const error = ignoreError(() => ensureSetupIgnoreProtection({ projectRoot: root }));
+
+    expect(error.message).toContain(root);
+    expect(error.userMessage).toBe("The .mex path must be a regular directory, not a symlink. Fix that path, then rerun setup.");
+    expect(error.userMessage).not.toContain(outside);
+    expect(existsSync(join(outside, ".gitignore"))).toBe(false);
+  });
+
+  it("explains an invalid project root without exposing its absolute path", () => {
+    const root = join(fixture(), "not-a-directory");
+    writeFileSync(root, "existing file\n");
+
+    const error = ignoreError(() => ensureSetupIgnoreProtection({ projectRoot: root }));
+
+    expect(error.message).toContain(root);
+    expect(error.userMessage).toContain("Run setup from a valid project directory");
+    expect(error.userMessage).not.toContain(root);
+    expect(readFileSync(root, "utf8")).toBe("existing file\n");
+  });
+
+  it.each(["inspect", "read", "create", "append", "write"] as const)("keeps %s failure diagnostics private and retains their cause", (operation) => {
+    const root = operation === "read" || operation === "append" ? fixtureWithMex() : fixture();
+    if (operation === "read" || operation === "append") writeIgnore(root, "# unchanged\n");
+    const cause = Object.assign(new Error(`EACCES private details at ${root}`), { code: "EACCES" });
+    const fail = () => { throw cause; };
+    if (operation === "inspect") vi.mocked(lstatSync).mockImplementationOnce(fail);
+    if (operation === "read") vi.mocked(readFileSync).mockImplementationOnce(fail);
+    if (operation === "create") vi.mocked(mkdirSync).mockImplementationOnce(fail);
+    if (operation === "append") vi.mocked(appendFileSync).mockImplementationOnce(fail);
+    if (operation === "write") vi.mocked(writeFileSync).mockImplementationOnce(fail);
+
+    const error = ignoreError(() => ensureSetupIgnoreProtection({ projectRoot: root }));
+
+    expect(error.cause).toBe(cause);
+    expect(error.message).toContain(root);
+    if (operation === "read") expect(error.message).toBe(cause.message);
+    expect(error.userMessage).not.toContain(root);
+    expect(error.userMessage).not.toContain("private details");
+    expect(error.userMessage).toMatch(/permissions.*retry setup/u);
+    if (operation === "read" || operation === "append") expect(readIgnore(root)).toBe("# unchanged\n");
+  });
+
+  it.each([
+    ["ENOSPC", "Storage is full"],
+    ["EROFS", "filesystem is read-only"],
+  ])("uses the %s recovery guidance for ignore-file writes", (code, recovery) => {
+    const root = fixtureWithMex();
+    writeIgnore(root, "# unchanged\n");
+    const cause = Object.assign(new Error(`private filesystem failure at ${root}`), { code });
+    vi.mocked(appendFileSync).mockImplementationOnce(() => { throw cause; });
+
+    const error = ignoreError(() => ensureSetupIgnoreProtection({ projectRoot: root }));
+
+    expect(error.cause).toBe(cause);
+    expect(error.userMessage).toContain(recovery);
+    expect(error.userMessage).not.toContain("permissions");
+    expect(error.userMessage).not.toContain(root);
+    expect(readIgnore(root)).toBe("# unchanged\n");
+  });
+
   it("verifies derived files are ignored and canonical config remains trackable", () => {
     const root = fixture();
     initGit(root);
@@ -157,10 +248,69 @@ describe("setup local-data ignore protection", () => {
     ensureSetupIgnoreProtection({ projectRoot: root });
     writeFileSync(join(root, ".gitignore"), ".mex/\n", "utf8");
 
-    expect(() => verifySetupIgnoreProtection(root)).toThrow(/hides \.mex\/config\.json/u);
+    const error = ignoreError(() => verifySetupIgnoreProtection(root));
+    expect(error.message).toMatch(/hides \.mex\/config\.json/u);
+    expect(error.userMessage).toBe(error.message);
+    expect(error.userMessage).toContain("Remove the broad .mex ignore");
+    expect(error.userMessage).not.toContain(root);
+  });
+
+  it("explains how to repair a negation that exposes local MEX data", () => {
+    const root = fixture();
+    initGit(root);
+    ensureSetupIgnoreProtection({ projectRoot: root });
+    writeIgnore(root, "graph.db*\nwiki.db*\nlocal/\n!graph.db\n");
+
+    const error = ignoreError(() => verifySetupIgnoreProtection(root));
+
+    expect(error.message).toBe("Local MEX path is not ignored by Git: .mex/graph.db");
+    expect(error.userMessage).toContain("Check .mex/.gitignore and conflicting negation rules");
+    expect(error.userMessage).not.toContain(root);
+  });
+
+  it("reports a Git launch failure with remediation instead of its private cause", () => {
+    const root = fixture();
+    const cause = Object.assign(new Error(`spawn git ENOENT private ${root}`), { code: "ENOENT" });
+    vi.mocked(spawnSync).mockReturnValueOnce({
+      pid: 0, output: [], stdout: "", stderr: "", status: null, signal: null, error: cause,
+    });
+
+    const error = ignoreError(() => verifySetupIgnoreProtection(root));
+
+    expect(error.message).toBe("Could not run Git to verify local MEX data protection.");
+    expect(error.cause).toBe(cause);
+    expect(error.userMessage).toContain("Git is installed and available on PATH");
+    expect(error.userMessage).not.toContain(root);
+  });
+
+  it("preserves terminal Git stderr while exposing only authored browser guidance", () => {
+    const root = fixture();
+    const stderr = `fatal: private token and path ${root}\n`;
+    vi.mocked(spawnSync).mockReturnValueOnce({
+      pid: 123, output: [], stdout: "", stderr, status: 128, signal: null,
+    });
+
+    const error = ignoreError(() => verifySetupIgnoreProtection(root));
+
+    expect(error.message).toBe(`Git could not verify local MEX data protection: ${stderr.trim()}`);
+    expect(error.userMessage).toContain("valid Git repository");
+    expect(error.userMessage).toContain("git status");
+    expect(error.userMessage).not.toContain(root);
+    expect(error.userMessage).not.toContain("private token");
   });
 });
 
+function ignoreError(run: () => unknown): SetupIgnoreProtectionError {
+  try {
+    run();
+  } catch (error) {
+    expect(error).toBeInstanceOf(SetupIgnoreProtectionError);
+    expect(error).toBeInstanceOf(SetupError);
+    return error as SetupIgnoreProtectionError;
+  }
+  throw new Error("Expected an ignore-protection failure.");
+}
+
 function fixture(): string {
   const root = mkdtempSync(join(tmpdir(), "mex-setup-ignore-"));
   roots.push(root);
diff --git a/src/setup/__tests__/interactive-population.test.ts b/src/setup/__tests__/interactive-population.test.ts
new file mode 100644
index 00000000..5b863b71
--- /dev/null
+++ b/src/setup/__tests__/interactive-population.test.ts
@@ -0,0 +1,298 @@
+import crossSpawn from "cross-spawn";
+import { execFileSync, type ChildProcess } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { launchInteractiveSetupPopulation, type InteractivePopulationOptions } from "../interactive-population.js";
+
+const roots: string[] = [];
+const emergencyCleanup = new Set<number>();
+// The sandbox may explicitly disallow ps. Keep unit coverage there, and run this
+// real ancestry adapter scenario where the OS permits process enumeration.
+const canInspectProcesses = (() => {
+  if (process.platform === "win32") return false;
+  try { execFileSync("ps", ["-o", "pid=", "-p", String(process.pid)], { stdio: "ignore" }); return true; }
+  catch { return false; }
+})();
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  for (const pid of emergencyCleanup) { try { process.kill(pid, "SIGKILL"); } catch { /* Already gone. */ } }
+  emergencyCleanup.clear();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-native-population-"));
+  roots.push(root);
+  mkdirSync(join(root, ".mex"));
+  return root;
+}
+
+function fakeChild(pid = 912_345): ChildProcess {
+  return Object.assign(new EventEmitter(), { pid, kill: vi.fn(() => true) }) as unknown as ChildProcess;
+}
+
+function exited(child: ChildProcess, code: number | null, signal: NodeJS.Signals | null = null): void {
+  child.emit("exit", code, signal);
+  child.emit("close", code, signal);
+}
+
+function launchOptions(projectRoot: string, child: ChildProcess, afterSpawn?: (args: readonly string[]) => void): InteractivePopulationOptions {
+  return {
+    projectRoot, selectedTools: ["codex"], prompt: "Private project context",
+    __internal: {
+      isAvailable: async () => true,
+      snapshot: async () => [],
+      spawn: vi.fn((_command, args) => {
+        queueMicrotask(() => afterSpawn?.(args as string[]));
+        return child;
+      }) as unknown as typeof crossSpawn,
+    },
+  };
+}
+
+describe("native interactive setup population", () => {
+  it("inherits the foreground terminal and keeps the complete private prompt off argv", async () => {
+    const root = fixture();
+    const child = fakeChild();
+    const prompt = "Private context\n".repeat(4_096);
+    const options = launchOptions(root, child, (args) => {
+      expect(args).toHaveLength(1);
+      expect(args[0]!.length).toBeLessThan(256);
+      const pointer = /`([^`]+)`/u.exec(args[0]!)![1]!;
+      const file = join(root, pointer);
+      expect(readFileSync(file, "utf8")).toBe(prompt);
+      if (process.platform !== "win32") expect(statSync(file).mode & 0o777).toBe(0o600);
+      exited(child, 0);
+    });
+    const result = await launchInteractiveSetupPopulation({ ...options, prompt });
+    expect(result).toEqual({ tool: "codex", status: "exited", exitCode: 0, signal: null });
+    expect(options.__internal!.spawn).toHaveBeenCalledWith("codex", expect.any(Array), {
+      cwd: root, stdio: "inherit", detached: false,
+    });
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it("respects selection order and never launches unselected CLIs", async () => {
+    const root = fixture();
+    const child = fakeChild();
+    const available = vi.fn(async (command: string) => command === "claude");
+    const options = launchOptions(root, child, () => exited(child, 0));
+    const result = await launchInteractiveSetupPopulation({ ...options, selectedTools: ["cursor", "codex", "claude"],
+      __internal: { ...options.__internal, isAvailable: available } });
+    expect(available.mock.calls).toEqual([["codex"], ["claude"]]);
+    expect(result.tool).toBe("claude");
+    expect(options.__internal!.spawn).toHaveBeenCalledWith("claude", expect.any(Array), expect.any(Object));
+    expect(await launchInteractiveSetupPopulation({ ...options, selectedTools: ["cursor"] })).toMatchObject({ tool: null, status: "unavailable" });
+  });
+
+  it("does not create a prompt when no selected CLI is available", async () => {
+    const root = fixture();
+    const options = launchOptions(root, fakeChild());
+    expect(await launchInteractiveSetupPopulation({ ...options,
+      __internal: { ...options.__internal, isAvailable: async () => false } })).toMatchObject({ status: "unavailable", tool: null });
+    expect(options.__internal!.spawn).not.toHaveBeenCalled();
+    expect(readdirSync(join(root, ".mex"))).toEqual([]);
+  });
+
+  it("returns a safe actionable result if CLI discovery throws", async () => {
+    const root = fixture();
+    const options = launchOptions(root, fakeChild());
+    const result = await launchInteractiveSetupPopulation({ ...options, __internal: {
+      ...options.__internal, isAvailable: async () => { throw new Error("Private process diagnostics"); },
+    } });
+    expect(result).toMatchObject({ status: "failed", tool: null, message: expect.stringContaining("PATH") });
+    expect(result.message).not.toContain("Private");
+    expect(options.__internal!.spawn).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    { code: 7, signal: null, status: "failed" },
+    { code: null, signal: "SIGTERM", status: "failed" },
+    { code: null, signal: "SIGINT", status: "cancelled" },
+  ] as const)("classifies native exit $code / $signal as $status", async ({ code, signal, status }) => {
+    const root = fixture();
+    const child = fakeChild();
+    expect(await launchInteractiveSetupPopulation(launchOptions(root, child, () => exited(child, code, signal))))
+      .toMatchObject({ tool: "codex", status, exitCode: code, signal });
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it.each(["throw", "event"] as const)("settles a spawn %s and removes the prompt", async (failure) => {
+    const root = fixture();
+    const child = fakeChild();
+    const options = launchOptions(root, child, () => {
+      child.emit("error", new Error("Private diagnostic"));
+      exited(child, -2);
+    });
+    const result = await launchInteractiveSetupPopulation(failure === "throw" ? { ...options, __internal: {
+      ...options.__internal, spawn: vi.fn(() => { throw new Error("Private diagnostic"); }) as unknown as typeof crossSpawn,
+    } } : options);
+    expect(result).toMatchObject({ tool: "codex", status: "failed", message: expect.stringContaining("could not start") });
+    expect(result.message).not.toContain("Private diagnostic");
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it.each(["before discovery", "during discovery", "during spawn"] as const)("honors cancellation %s", async (timing) => {
+    const root = fixture();
+    const abort = new AbortController();
+    const child = fakeChild();
+    vi.mocked(child.kill).mockImplementation((signal) => { queueMicrotask(() => exited(child, null, signal as NodeJS.Signals)); return true; });
+    const options = launchOptions(root, child);
+    if (timing === "before discovery") abort.abort();
+    const result = await launchInteractiveSetupPopulation({ ...options, signal: abort.signal, __internal: {
+      ...options.__internal,
+      isAvailable: async () => { if (timing === "during discovery") abort.abort(); return true; },
+      spawn: ((_command, _args, _options) => { abort.abort(); return child; }) as typeof crossSpawn,
+    } });
+    expect(result.status).toBe("cancelled");
+    expect(existsSync(join(root, ".mex/local")) ? readdirSync(join(root, ".mex/local")) : []).toEqual([]);
+    if (timing !== "during spawn") expect(child.kill).not.toHaveBeenCalled();
+  });
+
+  it("returns an actionable failure when the private prompt cannot be prepared", async () => {
+    const root = fixture();
+    writeFileSync(join(root, ".mex/local"), "User-owned file");
+    const options = launchOptions(root, fakeChild());
+    expect(await launchInteractiveSetupPopulation(options)).toMatchObject({ status: "failed", message: expect.stringContaining("could not be prepared") });
+    expect(options.__internal!.spawn).not.toHaveBeenCalled();
+    expect(readFileSync(join(root, ".mex/local"), "utf8")).toBe("User-owned file");
+  });
+});
+
+describe.skipIf(process.platform === "win32")("interactive process ownership", () => {
+  it.each([false, true])("cleans observed helpers after a clean agent exit (signal failure: %s)", async (denied) => {
+    const root = fixture();
+    const child = fakeChild();
+    let processes = [
+      { pid: child.pid!, parentPid: process.pid, started: "root" },
+      { pid: child.pid! + 1, parentPid: child.pid!, started: "helper" },
+    ];
+    const snapshot = vi.fn(async () => processes);
+    const kill = vi.fn(() => {
+      if (denied) throw Object.assign(new Error("Private diagnostic"), { code: "EPERM" });
+      processes = [];
+    });
+    const options = launchOptions(root, child);
+    const resultPromise = launchInteractiveSetupPopulation({ ...options, __internal: { ...options.__internal, snapshot, kill } });
+    await vi.waitFor(() => expect(snapshot).toHaveBeenCalled());
+    processes = [{ ...processes[1]!, parentPid: 1 }];
+    exited(child, 0);
+    const result = await resultPromise;
+    expect(result.status).toBe(denied ? "failed" : "exited");
+    if (denied) expect(result.message).toContain("could not verify");
+    expect(kill).toHaveBeenCalledWith(child.pid! + 1, "SIGTERM");
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it("escalates only matching observed descendants and keeps the prompt until cleanup finishes", async () => {
+    const root = fixture();
+    const abort = new AbortController();
+    const child = fakeChild();
+    const rootProcess = { pid: child.pid!, parentPid: process.pid, started: "root-start" };
+    const descendant = { pid: child.pid! + 1, parentPid: child.pid!, started: "child-start" };
+    const grandchild = { pid: child.pid! + 2, parentPid: descendant.pid, started: "grandchild-start" };
+    const sibling = { pid: child.pid! + 3, parentPid: process.pid, started: "sibling-start" };
+    let processes = [rootProcess, descendant, grandchild, sibling];
+    const kill = vi.fn();
+    vi.mocked(child.kill).mockImplementation((signal) => {
+      expect(readdirSync(join(root, ".mex/local"))).toHaveLength(1);
+      if (signal === "SIGTERM") {
+        processes = [{ ...descendant, parentPid: 1, started: "reused-pid" }, { ...grandchild, parentPid: 1 }, sibling];
+        exited(child, null, "SIGTERM");
+      }
+      return true;
+    });
+    const options = launchOptions(root, child);
+    const resultPromise = launchInteractiveSetupPopulation({ ...options, signal: abort.signal, __internal: {
+      ...options.__internal, snapshot: async () => processes, kill,
+    } });
+    await vi.waitFor(() => expect(options.__internal!.spawn).toHaveBeenCalled());
+    abort.abort();
+    const result = await resultPromise;
+    expect(result.status).toBe("cancelled");
+    expect(kill.mock.calls).toEqual([[grandchild.pid, "SIGTERM"], [descendant.pid, "SIGTERM"], [grandchild.pid, "SIGKILL"]]);
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it("does not signal stale descendant identities if process enumeration fails", async () => {
+    const root = fixture();
+    const child = fakeChild();
+    const abort = new AbortController();
+    let enumerationFails = false;
+    const snapshot = vi.fn(async () => enumerationFails ? null : [
+      { pid: child.pid!, parentPid: process.pid, started: "root" },
+      { pid: child.pid! + 1, parentPid: child.pid!, started: "child" },
+    ]);
+    const kill = vi.fn();
+    vi.mocked(child.kill).mockImplementation((signal) => { exited(child, null, signal as NodeJS.Signals); return true; });
+    const options = launchOptions(root, child);
+    const resultPromise = launchInteractiveSetupPopulation({ ...options, signal: abort.signal,
+      __internal: { ...options.__internal, snapshot, kill } });
+    await vi.waitFor(() => expect(snapshot).toHaveBeenCalled());
+    enumerationFails = true;
+    abort.abort();
+    expect(await resultPromise).toMatchObject({ status: "cancelled", message: expect.stringContaining("could not verify") });
+    expect(kill).not.toHaveBeenCalled();
+    expect(child.kill).toHaveBeenCalledWith("SIGTERM");
+  });
+
+  it("does not report a clean agent exit when descendant cleanup cannot be verified", async () => {
+    const root = fixture();
+    const child = fakeChild();
+    const options = launchOptions(root, child, () => exited(child, 0));
+    expect(await launchInteractiveSetupPopulation({ ...options,
+      __internal: { ...options.__internal, snapshot: async () => { throw new Error("Private diagnostic"); } },
+    })).toMatchObject({ status: "failed", exitCode: 0, message: expect.stringContaining("could not verify") });
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+
+  it.skipIf(!canInspectProcesses)("stops a real resistant agent and its grandchild without signalling an unrelated sibling", async () => {
+    const root = fixture();
+    const abort = new AbortController();
+    const workerFile = join(root, "worker.cjs");
+    writeFileSync(workerFile, "process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);");
+    const agentFile = join(root, "agent.cjs");
+    const marker = join(root, "child-pid");
+    writeFileSync(agentFile, `const {spawn}=require('node:child_process'); const fs=require('node:fs');
+      process.on('SIGTERM', () => {});
+      const worker=spawn(process.execPath, [${JSON.stringify(workerFile)}], {stdio:'ignore'});
+      fs.writeFileSync(${JSON.stringify(marker)}, String(worker.pid)); setInterval(() => {}, 1000);`);
+    const sibling = crossSpawn(process.execPath, [workerFile], { stdio: "ignore" });
+    emergencyCleanup.add(sibling.pid!);
+    let agent: ChildProcess | undefined;
+    const kill = vi.fn((pid: number, signal: NodeJS.Signals) => { process.kill(pid, signal); });
+    const options: InteractivePopulationOptions = {
+      projectRoot: root, selectedTools: ["codex"], prompt: "Private setup", signal: abort.signal,
+      __internal: { isAvailable: async () => true, kill, spawn: ((_command, _args, spawnOptions) => {
+        agent = crossSpawn(process.execPath, [agentFile], spawnOptions);
+        emergencyCleanup.add(agent.pid!);
+        return agent;
+      }) as typeof crossSpawn },
+    };
+    const resultPromise = launchInteractiveSetupPopulation(options);
+    await vi.waitFor(() => expect(existsSync(marker)).toBe(true));
+    const workerPid = Number(readFileSync(marker, "utf8"));
+    emergencyCleanup.add(workerPid);
+    // Allow a heartbeat to observe the worker before cancellation reparents it.
+    await new Promise((resolve) => setTimeout(resolve, 200));
+    abort.abort();
+    expect(await resultPromise).toMatchObject({ status: "cancelled", signal: "SIGKILL" });
+    expect(agent!.exitCode).toBeNull();
+    expect(agent!.signalCode).toBe("SIGKILL");
+    expect(kill).toHaveBeenCalledWith(workerPid, "SIGTERM");
+    expect(kill).toHaveBeenCalledWith(workerPid, "SIGKILL");
+    // Some process supervisors defer reaping an orphaned zombie. It cannot run
+    // or write files, so distinguish it from a surviving worker.
+    await vi.waitFor(() => {
+      let status = "";
+      try { status = execFileSync("ps", ["-o", "stat=", "-p", String(workerPid)], { encoding: "utf8" }).trim(); } catch { /* Reaped. */ }
+      expect(status === "" || status.startsWith("Z")).toBe(true);
+    });
+    expect(() => process.kill(sibling.pid!, 0)).not.toThrow();
+    expect(readdirSync(join(root, ".mex/local"))).toEqual([]);
+  });
+});
diff --git a/src/setup/__tests__/maintenance-errors.test.ts b/src/setup/__tests__/maintenance-errors.test.ts
new file mode 100644
index 00000000..65bdfaab
--- /dev/null
+++ b/src/setup/__tests__/maintenance-errors.test.ts
@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+import { GraphCandidateProcessError } from "../../graph/candidate-process.js";
+import { IndexInUseError, IndexPathError, IndexPublishRecoveryError, WikiMaintenanceLockedError } from "../../wiki/index/dbfile.js";
+import { WikiCorpusLimitError } from "../../wiki/index/corpus-policy.js";
+import { WikiMaintenanceInterruptedError } from "../../wiki/index/maintenance.js";
+import type { WikiDiagnostic } from "../../wiki/model/diagnostic.js";
+import { SetupError } from "../errors.js";
+import { classifySetupMaintenanceError, setupWikiFailureMessage } from "../maintenance-errors.js";
+
+const PRIVATE = "private-token /private/project/secret.db";
+
+describe("safe setup maintenance failures", () => {
+  it.each([
+    ["GRAPH_MAINTENANCE_LOCKED", "Wait for it to finish"],
+    ["GRAPH_MAINTENANCE_GATE_STALE", "Verify no MEX process is running"],
+    ["GRAPH_MAINTENANCE_RACE", "Wait for other writers"],
+    ["GRAPH_PUBLICATION_FAILED", "recovery files"],
+    ["GRAPH_INDEX_NOT_REFRESHABLE", "mex graph rebuild"],
+    ["GRAPH_SOURCE_STAGING_FAILED", "read or parsed safely"],
+  ])("projects %s by code while preserving its local diagnostic", (code, advice) => {
+    const original = Object.assign(new Error(PRIVATE), { code, recoveryPath: PRIVATE, diagnostics: [{ message: PRIVATE }] });
+    const result = classifySetupMaintenanceError(original, "graph");
+    expect(result).toBeInstanceOf(SetupError);
+    expect(result?.message).toContain(PRIVATE);
+    expect(result?.cause).toBe(original);
+    expect(result?.userMessage).toContain(advice);
+    expect(result?.userMessage).not.toContain(PRIVATE);
+    expect(result!.userMessage.length).toBeLessThanOrEqual(512);
+  });
+
+  it.each(["compatibility", "staging", "failed", "unsafe", "cancelled"] as const)("explains a graph worker %s without its raw diagnostics", (category) => {
+    const error = new GraphCandidateProcessError(category);
+    error.message = PRIVATE;
+    const result = classifySetupMaintenanceError(error, "graph");
+    expect(result?.userMessage).toContain("Code graph setup could not finish.");
+    expect(result?.userMessage).toContain("setup");
+    expect(result?.userMessage).not.toContain(PRIVATE);
+    expect(result?.message).toContain(PRIVATE);
+  });
+
+  it.each([
+    ["entrypoint-missing", "Rebuild MEX"],
+    ["spawn", "execution permissions"],
+    ["startup-timeout", "startup deadline"],
+    ["build-timeout", "build time limit"],
+    ["protocol", "invalid response"],
+    ["ipc-disconnected", "lost communication"],
+    ["observer", "could not process"],
+    ["worker-error", "worker diagnostics"],
+  ] as const)("explains the worker lifecycle failure %s without exposing stderr", (reason, advice) => {
+    const result = classifySetupMaintenanceError(new GraphCandidateProcessError("failed", {
+      reason, stderr: PRIVATE,
+    }), "graph");
+    expect(result?.userMessage).toContain(advice);
+    expect(result?.userMessage).not.toContain(PRIVATE);
+    expect(result?.message).toContain(PRIVATE);
+    expect(result!.userMessage.length).toBeLessThanOrEqual(512);
+  });
+
+  it("explains confirmed heap exhaustion but does not infer it from a signal", () => {
+    const heap = classifySetupMaintenanceError(new GraphCandidateProcessError("failed", {
+      reason: "exit", signal: "SIGABRT", resourceFailure: "heap-limit", stderr: PRIVATE,
+    }), "graph");
+    expect(heap?.userMessage).toContain("JavaScript heap limit");
+    expect(heap?.userMessage).toContain("NODE_OPTIONS");
+    expect(heap?.userMessage).not.toContain(PRIVATE);
+    for (const signal of ["SIGABRT", "SIGKILL"] as const) {
+      const terminated = classifySetupMaintenanceError(new GraphCandidateProcessError("failed", {
+        reason: "exit", signal, stderr: PRIVATE,
+      }), "graph");
+      expect(terminated?.userMessage).toContain("terminated by a signal");
+      expect(terminated?.userMessage).not.toContain("heap");
+    }
+    expect(classifySetupMaintenanceError(new GraphCandidateProcessError("failed", {
+      reason: "exit", exitCode: 7,
+    }), "graph")?.userMessage).toContain("exited with status 7");
+  });
+
+  it.each([
+    [new WikiMaintenanceLockedError(PRIVATE), "Another Wiki operation"],
+    [new WikiCorpusLimitError("maxFileBytes"), "wiki.exclude"],
+    [new WikiMaintenanceInterruptedError("publish"), "Wait for other writers"],
+    [new IndexPublishRecoveryError(PRIVATE, PRIVATE, new Error(PRIVATE), new Error(PRIVATE)), "recovery files were retained"],
+    [new IndexInUseError(PRIVATE, new Error(PRIVATE)), "Close other processes"],
+    [new IndexPathError(PRIVATE), "redirected, or conflicting paths"],
+  ])("projects the expected Wiki failure %s", (error, advice) => {
+    const result = classifySetupMaintenanceError(error, "wiki");
+    expect(result?.userMessage).toContain(advice);
+    expect(result?.userMessage).not.toContain(PRIVATE);
+  });
+
+  it.each([
+    [{ code: "EACCES" }, "permissions"],
+    [{ code: "ENOSPC" }, "Free disk space"],
+    [{ code: "SQLITE_BUSY" }, "database is busy"],
+    [{ code: "ERR_SQLITE_ERROR", errcode: 262 }, "database is busy"],
+    [{ code: "ERR_SQLITE_ERROR", errcode: 13 }, "ran out of storage"],
+    [{ code: "ERR_SQLITE_ERROR", errcode: 8 }, "database is read-only"],
+  ])("projects filesystem/SQLite codes without inspecting their text: %j", (fields, advice) => {
+    const result = classifySetupMaintenanceError(Object.assign(new Error(PRIVATE), fields), "grounding");
+    expect(result?.userMessage).toContain(advice);
+    expect(result?.userMessage).not.toContain(PRIVATE);
+  });
+
+  it("keeps unrelated exceptions and SQLite failures unclassified", () => {
+    for (const error of [new Error(PRIVATE), Object.assign(new Error(PRIVATE), { code: "UNKNOWN" }),
+      Object.assign(new Error(PRIVATE), { code: "ERR_SQLITE_ERROR", errcode: 1 }),
+      { code: "GRAPH_MAINTENANCE_LOCKED", message: PRIVATE }]) {
+      expect(classifySetupMaintenanceError(error, "wiki")).toBeNull();
+    }
+  });
+});
+
+describe("Wiki setup remediation", () => {
+  it("uses the registry's blocking remediation and a safe relative location", () => {
+    const message = setupWikiFailureMessage("validation", [
+      { code: "ORPHANED_ENTITY", severity: "info", message: PRIVATE },
+      { code: "INVALID_ENTITY_ID", severity: "error", message: PRIVATE, remediation: PRIVATE, file: "context/setup.md" },
+    ]);
+    expect(message).toContain("INVALID_ENTITY_ID in .mex/context/setup.md");
+    expect(message).toContain("Do not hand-edit them");
+    expect(message).toContain("Retry setup");
+    expect(message).not.toContain(PRIVATE);
+  });
+
+  it("explains the runtime fix for missing FTS5 instead of prescribing a CLI setup rerun", () => {
+    const message = setupWikiFailureMessage("index", [{ code: "WIKI_INDEX_FTS5_UNAVAILABLE", severity: "error", message: PRIVATE }]);
+    expect(message).toContain("use a different Node build/version");
+    expect(message).toContain("Rebuilding cannot fix this");
+    expect(message).not.toContain("setup --cli");
+  });
+
+  it.each(["/private/project/secret.md", "../outside.md", "C:\\private\\secret.md", "context/secret\nname.md"])("omits unsafe location %s", (file) => {
+    const message = setupWikiFailureMessage("plan", [{ code: "WIKI_PARSE_ERROR", severity: "error", message: PRIVATE, file }]);
+    expect(message).not.toContain(file);
+    expect(message).not.toContain(" in ");
+  });
+
+  it("bounds long locations while retaining the retry action and avoids false no-write promises", () => {
+    const message = setupWikiFailureMessage("migration", [{ code: "WRITE_SCOPE_VIOLATION", severity: "error", message: PRIVATE,
+      file: `context/${"x".repeat(135)}.md` }]);
+    expect(message.length).toBeLessThanOrEqual(512);
+    expect(message).toContain("Retry setup");
+    expect(message).toContain("wiki.readOnly");
+    expect(message).not.toContain("Nothing was written");
+  });
+
+  it("does not echo unknown diagnostic codes or prose", () => {
+    const message = setupWikiFailureMessage("migration", [{ code: PRIVATE, severity: "error", message: PRIVATE } as unknown as WikiDiagnostic]);
+    expect(message).not.toContain(PRIVATE);
+    expect(message).toContain("retry setup");
+  });
+});
diff --git a/src/setup/__tests__/phases-errors.test.ts b/src/setup/__tests__/phases-errors.test.ts
new file mode 100644
index 00000000..cb6c9a55
--- /dev/null
+++ b/src/setup/__tests__/phases-errors.test.ts
@@ -0,0 +1,109 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { classifySetupFileSystemError, SetupError } from "../errors.js";
+import { buildSetupGraph, createSetupScaffold, verifyExistingSetupConfig } from "../phases.js";
+import { GraphMaintenanceError } from "../../graph/maintenance.js";
+import * as maintenance from "../../graph/maintenance.js";
+
+vi.mock("node:fs", async (importOriginal) => {
+  const original = await importOriginal<typeof import("node:fs")>();
+  return { ...original, readFileSync: vi.fn(original.readFileSync) };
+});
+
+const roots: string[] = [];
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.mocked(readFileSync).mockReset();
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-errors-"));
+  roots.push(root);
+  return root;
+}
+
+describe("expected setup preparation errors", () => {
+  it.each(["{broken", "[]", "null"])("explains invalid config %s without replacing it", async (contents) => {
+    const root = fixture();
+    writeFileSync(join(root, "config.json"), contents);
+    expect(() => verifyExistingSetupConfig(root)).toThrow(SetupError);
+    expect(() => verifyExistingSetupConfig(root)).toThrow("not a valid JSON object");
+    const fs = await vi.importActual<typeof import("node:fs")>("node:fs");
+    expect(fs.readFileSync(join(root, "config.json"), "utf8")).toBe(contents);
+  });
+
+  it("distinguishes an unreadable config from invalid JSON", () => {
+    const root = fixture();
+    writeFileSync(join(root, "config.json"), "{}");
+    const cause = Object.assign(new Error("EACCES /private/config.json secret"), { code: "EACCES" });
+    vi.mocked(readFileSync).mockImplementationOnce(() => { throw cause; });
+    try {
+      verifyExistingSetupConfig(root);
+      expect.fail("Expected unreadable config to fail");
+    } catch (error) {
+      expect(error).toBeInstanceOf(SetupError);
+      expect(error).toMatchObject({ cause, userMessage: expect.stringContaining("Could not read .mex/config.json. Access was denied") });
+      expect((error as SetupError).userMessage).not.toMatch(/private|secret|valid JSON/);
+    }
+  });
+
+  it("identifies a conflicting scaffold path and leaves it intact", () => {
+    const root = fixture();
+    mkdirSync(join(root, ".mex"));
+    writeFileSync(join(root, ".mex/context"), "keep me");
+    try {
+      createSetupScaffold({ projectRoot: root, mode: "agent-memory" });
+      expect.fail("Expected the path conflict to fail");
+    } catch (error) {
+      expect(error).toBeInstanceOf(SetupError);
+      expect((error as SetupError).userMessage).toContain("Could not create .mex/context/architecture.md.");
+      expect((error as SetupError).userMessage).toContain("conflicting file");
+      expect((error as SetupError).userMessage).not.toContain(root);
+    }
+  });
+
+  it.each([
+    ["EACCES", "permissions"], ["EPERM", "permissions"], ["EROFS", "read-only"],
+    ["ENOSPC", "Free disk space"], ["EDQUOT", "quota"], ["EBUSY", "busy"],
+    ["ENOENT", "missing"], ["EMFILE", "too many open files"],
+  ])("projects %s without copying exception text", (code, remedy) => {
+    const cause = Object.assign(new Error("private diagnostic /secret/path"), { code });
+    const error = classifySetupFileSystemError(cause, "Could not save .mex/config.json.");
+    expect(error).toMatchObject({ message: cause.message, cause });
+    expect(error?.userMessage).toContain(remedy);
+    expect(error?.userMessage).not.toMatch(/private|secret/);
+  });
+
+  it("does not classify unexpected exceptions by their message", () => {
+    expect(classifySetupFileSystemError(new Error("EACCES"), "Save config.")).toBeNull();
+    expect(classifySetupFileSystemError(Object.assign(new Error("secret"), { code: "UNKNOWN" }), "Save config.")).toBeNull();
+  });
+});
+
+describe("setup Graph error boundary", () => {
+  it("preserves a known maintenance failure's safe recovery instructions", async () => {
+    vi.spyOn(maintenance, "rebuildGraph").mockRejectedValue(new GraphMaintenanceError("GRAPH_MAINTENANCE_LOCKED", "private lock details"));
+    await expect(buildSetupGraph("/unused")).rejects.toMatchObject({
+      userMessage: expect.stringMatching(/another|running|progress/i),
+    });
+  });
+
+  it("keeps unknown graph failures outside the browser-safe contract", async () => {
+    vi.spyOn(maintenance, "rebuildGraph").mockRejectedValue(new Error("private compiler crash"));
+    const error = await buildSetupGraph("/unused").catch((error: unknown) => error);
+    expect(error).toBeInstanceOf(Error);
+    expect(error).not.toBeInstanceOf(SetupError);
+  });
+
+  it("checks cancellation before classifying a concurrent graph failure", async () => {
+    const controller = new AbortController();
+    vi.spyOn(maintenance, "rebuildGraph").mockImplementation(async () => {
+      controller.abort();
+      throw new GraphMaintenanceError("GRAPH_MAINTENANCE_LOCKED", "private lock details");
+    });
+    await expect(buildSetupGraph("/unused", { signal: controller.signal })).rejects.toThrow("Setup was cancelled");
+  });
+});
diff --git a/src/setup/__tests__/terminal-completion.test.ts b/src/setup/__tests__/terminal-completion.test.ts
new file mode 100644
index 00000000..de8093b3
--- /dev/null
+++ b/src/setup/__tests__/terminal-completion.test.ts
@@ -0,0 +1,54 @@
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { stdin, stdout } from "node:process";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { runTerminalSetup } from "../terminal.js";
+
+const state = vi.hoisted(() => ({ committed: false, inspectedAfterHub: false }));
+vi.mock("../terminal-ui.js", () => ({ createTerminalSetupUI: (_view: unknown, action: (value: unknown) => void) => {
+  setTimeout(() => action({ type: "start" }), 0);
+  return { update() {}, suspend: async () => {}, resume() {}, close: async () => {} };
+} }));
+vi.mock("../headless.js", () => ({ runHeadlessSetup: async () => ({ ready: true, mode: "code-repo", anchorNotes: [],
+  message: "Review and commit the canonical MEX setup." }) }));
+vi.mock("../../hub/command.js", () => ({ runSetupHubCommand: async (options: { onListening: (value: unknown) => void }) => {
+  options.onListening({ bootstrapUrl: "http://127.0.0.1:1234/#token=example" });
+  state.inspectedAfterHub = true;
+} }));
+vi.mock("../../hub/setup/readiness.js", () => ({ projectSetupStatus: async () => {
+  expect(state.inspectedAfterHub).toBe(true);
+  return { mode: "code-repo", ready: state.committed };
+} }));
+
+const roots: string[] = [];
+const inputTTY = Object.getOwnPropertyDescriptor(stdin, "isTTY");
+const outputTTY = Object.getOwnPropertyDescriptor(stdout, "isTTY");
+afterEach(() => {
+  vi.restoreAllMocks(); vi.unstubAllEnvs();
+  if (inputTTY) Object.defineProperty(stdin, "isTTY", inputTTY); else delete (stdin as { isTTY?: boolean }).isTTY;
+  if (outputTTY) Object.defineProperty(stdout, "isTTY", outputTTY); else delete (stdout as { isTTY?: boolean }).isTTY;
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("terminal completion after the finishing browser closes", () => {
+  it.each([true, false])("rechecks the browser's commit result (committed: %s)", async committed => {
+    state.committed = committed; state.inspectedAfterHub = false;
+    const root = mkdtempSync(join(tmpdir(), "mex-terminal-completion-")); roots.push(root);
+    vi.spyOn(process, "cwd").mockReturnValue(root);
+    vi.spyOn(console, "log").mockImplementation(() => {});
+    vi.stubEnv("CI", ""); vi.stubEnv("TERM", "xterm");
+    Object.defineProperty(stdin, "isTTY", { configurable: true, value: true });
+    Object.defineProperty(stdout, "isTTY", { configurable: true, value: true });
+    const result = await runTerminalSetup({ mode: "code-repo", tools: [], openBrowser: false });
+    expect(result).toMatchObject({ outcome: "complete", exitCode: 0 });
+    if (committed) {
+      expect(result.message).toContain("Setup complete");
+      expect(result.message).toContain("mex hub");
+      expect(result.message).not.toContain("Review and commit");
+    } else {
+      expect(result.message).toContain("Review and commit");
+      expect(result.message).toContain("mex setup --browser");
+    }
+  });
+});
diff --git a/src/setup/__tests__/terminal-return.test.ts b/src/setup/__tests__/terminal-return.test.ts
new file mode 100644
index 00000000..9282fa38
--- /dev/null
+++ b/src/setup/__tests__/terminal-return.test.ts
@@ -0,0 +1,67 @@
+import { EventEmitter } from "node:events";
+import type { ChildProcess } from "node:child_process";
+import { describe, expect, it, vi } from "vitest";
+import { waitForTerminalReturn } from "../terminal-return.js";
+
+function reader() {
+  const child = Object.assign(new EventEmitter(), { kill: vi.fn(() => true) }) as unknown as ChildProcess & { kill: ReturnType<typeof vi.fn> };
+  const spawn = vi.fn(() => child);
+  return { child, spawn };
+}
+
+describe("waiting for Enter while the HUD is suspended", () => {
+  it("reads the line in a child with the terminal inherited, never in this process", async () => {
+    const { child, spawn } = reader();
+    const waiting = waitForTerminalReturn(new AbortController().signal, { spawn });
+    expect(spawn).toHaveBeenCalledWith(process.execPath, ["-e", expect.any(String)],
+      { stdio: ["inherit", "ignore", "inherit"], windowsHide: true });
+    child.emit("exit", 0, null);
+    await expect(waiting).resolves.toBe("return");
+  });
+
+  it.each([["end of input", 3, null], ["an interrupt", null, "SIGINT"]])("cancels on %s", async (_name, code, signal) => {
+    const { child, spawn } = reader();
+    const waiting = waitForTerminalReturn(new AbortController().signal, { spawn });
+    child.emit("exit", code, signal);
+    await expect(waiting).resolves.toBe("cancel");
+  });
+
+  it("stops the reader when setup is cancelled or the wait is released", async () => {
+    const { child, spawn } = reader();
+    const controller = new AbortController();
+    const waiting = waitForTerminalReturn(controller.signal, { spawn });
+    controller.abort();
+    await expect(waiting).resolves.toBe("cancel");
+    expect(child.kill).toHaveBeenCalledOnce();
+    child.emit("exit", null, "SIGTERM");
+    await expect(waiting).resolves.toBe("cancel");
+  });
+
+  it("does not start a reader after cancellation and never strands the HUD on a launch failure", async () => {
+    const controller = new AbortController();
+    controller.abort();
+    const { spawn } = reader();
+    await expect(waitForTerminalReturn(controller.signal, { spawn })).resolves.toBe("cancel");
+    expect(spawn).not.toHaveBeenCalled();
+
+    await expect(waitForTerminalReturn(new AbortController().signal, { spawn: () => { throw new Error("EMFILE"); } }))
+      .resolves.toBe("return");
+    const failed = reader();
+    const waiting = waitForTerminalReturn(new AbortController().signal, { spawn: failed.spawn });
+    failed.child.emit("error", new Error("ENOENT"));
+    await expect(waiting).resolves.toBe("return");
+  });
+
+  it("returns on Enter and cancels at end of input with the real reader", async () => {
+    const { spawn } = await import("node:child_process");
+    const run = (input: string) => waitForTerminalReturn(new AbortController().signal, {
+      spawn: (command, args) => {
+        const child = spawn(command, args, { stdio: ["pipe", "ignore", "inherit"], windowsHide: true });
+        child.stdin!.end(input);
+        return child;
+      },
+    });
+    await expect(run("\n")).resolves.toBe("return");
+    await expect(run("")).resolves.toBe("cancel");
+  }, 20_000);
+});
diff --git a/src/setup/__tests__/terminal-ui-lifecycle.test.ts b/src/setup/__tests__/terminal-ui-lifecycle.test.ts
new file mode 100644
index 00000000..75fd2aec
--- /dev/null
+++ b/src/setup/__tests__/terminal-ui-lifecycle.test.ts
@@ -0,0 +1,82 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createTerminalSetupUI, type TerminalSetupView } from "../terminal-ui.js";
+import { stdin } from "node:process";
+
+const { render } = vi.hoisted(() => ({ render: vi.fn() }));
+vi.mock("ink", async importOriginal => ({ ...await importOriginal<typeof import("ink")>(), render }));
+
+const view: TerminalSetupView = {
+  projectName: "example", mode: "code-repo", screen: "progress", tools: [],
+  completedSteps: [], detail: "Preparing", startedAt: 0,
+};
+
+function renderer() {
+  let flush!: () => void;
+  let fail!: (error: Error) => void;
+  const exited = new Promise<void>((resolve, reject) => { flush = resolve; fail = reject; });
+  const instance = { rerender: vi.fn(), unmount: vi.fn(), waitUntilExit: vi.fn(() => exited), cleanup: vi.fn() };
+  return { instance, flush, fail };
+}
+
+beforeEach(() => { vi.restoreAllMocks(); render.mockReset(); });
+
+describe("terminal setup renderer ownership", () => {
+  it("waits for terminal restoration before handing control back and creates a fresh renderer on resume", async () => {
+    const first = renderer();
+    const second = renderer();
+    render.mockReturnValueOnce(first.instance).mockReturnValueOnce(second.instance);
+    const ui = createTerminalSetupUI(view, vi.fn());
+    expect(render.mock.calls[0][1]).toEqual({ alternateScreen: true, patchConsole: false, exitOnCtrlC: false });
+    let suspended = false;
+    const handoff = ui.suspend().then(() => { suspended = true; });
+    expect(first.instance.unmount).toHaveBeenCalledOnce();
+    await Promise.resolve();
+    expect(suspended).toBe(false);
+    expect(first.instance.cleanup).not.toHaveBeenCalled();
+    ui.update({ ...view, detail: "Native agent owns the terminal" });
+    expect(first.instance.rerender).not.toHaveBeenCalled();
+    first.flush();
+    await handoff;
+    expect(first.instance.cleanup).toHaveBeenCalledOnce();
+    ui.resume({ ...view, screen: "population", detail: "Welcome back" });
+    expect(render).toHaveBeenCalledTimes(2);
+    expect(render.mock.calls[1][0].props.view.detail).toBe("Welcome back");
+    const closing = ui.close();
+    second.flush();
+    await closing;
+    expect(second.instance.cleanup).toHaveBeenCalledOnce();
+    ui.resume(view);
+    expect(render).toHaveBeenCalledTimes(2);
+  });
+
+  it("coalesces repeated teardown and never mounts a queued resume after close", async () => {
+    const current = renderer();
+    const pause = vi.spyOn(stdin, "pause");
+    render.mockReturnValue(current.instance);
+    const ui = createTerminalSetupUI(view, vi.fn());
+    const first = ui.suspend();
+    const second = ui.suspend();
+    ui.resume(view);
+    const closing = ui.close();
+    current.flush();
+    await Promise.all([first, second, closing]);
+    expect(render).toHaveBeenCalledOnce();
+    expect(current.instance.cleanup).toHaveBeenCalledOnce();
+    await ui.close();
+    expect(current.instance.unmount).toHaveBeenCalledOnce();
+    expect(pause).toHaveBeenCalled();
+  });
+
+  it("still cleans up the Ink instance when its output flush fails", async () => {
+    const current = renderer();
+    const pause = vi.spyOn(stdin, "pause");
+    render.mockReturnValue(current.instance);
+    const ui = createTerminalSetupUI(view, vi.fn());
+    const closing = ui.close();
+    const error = new Error("Terminal output closed");
+    current.fail(error);
+    await expect(closing).rejects.toBe(error);
+    expect(current.instance.cleanup).toHaveBeenCalledOnce();
+    expect(pause).toHaveBeenCalledOnce();
+  });
+});
diff --git a/src/setup/__tests__/terminal-ui.test.ts b/src/setup/__tests__/terminal-ui.test.ts
new file mode 100644
index 00000000..4740a127
--- /dev/null
+++ b/src/setup/__tests__/terminal-ui.test.ts
@@ -0,0 +1,453 @@
+import React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, render } from "ink-testing-library";
+import { TerminalSetupHUD, type TerminalSetupView } from "../terminal-ui.js";
+import { appendTerminalSetupEvent } from "../terminal-events.js";
+
+const h = React.createElement;
+const settle = () => new Promise(resolve => setTimeout(resolve, 25));
+const initial: TerminalSetupView = {
+  projectName: "example-project", mode: "code-repo", screen: "configure",
+  tools: [
+    { id: "claude", name: "Claude Code", selected: true, cliAvailable: true },
+    { id: "codex", name: "Codex", selected: false, cliAvailable: true },
+    { id: "cursor", name: "Cursor", selected: false, cliAvailable: false },
+    { id: "windsurf", name: "Windsurf", selected: false, cliAvailable: false },
+    { id: "copilot", name: "Copilot", selected: false, cliAvailable: false },
+    { id: "opencode", name: "OpenCode", selected: false, cliAvailable: true },
+  ],
+  completedSteps: [], detail: "Choose the tools you use.", startedAt: Date.now(),
+};
+
+async function show(changes: Partial<TerminalSetupView> = {}, columns = 80, rows = 24) {
+  const onAction = vi.fn();
+  const view = { ...initial, ...changes };
+  const app = render(h(TerminalSetupHUD, { view, onAction }));
+  Object.defineProperty(app.stdout, "columns", { configurable: true, value: columns });
+  Object.defineProperty(app.stdout, "rows", { configurable: true, value: rows });
+  await settle();
+  app.stdout.emit("resize");
+  await settle();
+  return { ...app, view, onAction };
+}
+
+function expectFits(frame: string | undefined, columns: number, rows: number) {
+  const lines = (frame ?? "").split("\n");
+  expect(lines.length).toBeLessThanOrEqual(rows - 1);
+  for (const line of lines) expect(Array.from(line).length).toBeLessThanOrEqual(columns);
+}
+
+function expectAlignedBorders(frame: string | undefined, columns: number) {
+  const lines = (frame ?? "").split("\n").filter(line => line.includes("│"));
+  expect(lines.length).toBeGreaterThan(0);
+  for (const line of lines) {
+    const characters = Array.from(line);
+    expect(characters.indexOf("│")).toBe(1);
+    expect(characters.lastIndexOf("│")).toBe(columns - 2);
+  }
+}
+
+afterEach(() => { cleanup(); vi.useRealTimers(); });
+
+describe("terminal setup HUD", () => {
+  it.each([55, 57, 60, 64, 65, 66])("keeps selection and exit instructions complete at %s columns", async columns => {
+    const app = await show({}, columns, 16);
+    const footer = app.lastFrame()!.split("\n").at(-1)!;
+    expect(footer).toContain("Enter");
+    expect(footer).toContain("Space");
+    expect(footer).toMatch(/Ctrl\+C|\^C/);
+    expect(footer).not.toMatch(/…|\.\.\./);
+    expectFits(app.lastFrame(), columns, 16);
+  });
+
+  it("retains earlier finalize warnings in details after completion advances", async () => {
+    const events = ["AMBIGUOUS_MIGRATION: review architecture", "AMBIGUOUS_MIGRATION: review decisions", "Wiki validation finished"];
+    const app = await show({ screen: "hub", detail: "Continue in your browser", events });
+    app.stdin.write("d");
+    await settle();
+    expect(app.lastFrame()).toContain("review architecture");
+    expect(app.lastFrame()).toContain("review decisions");
+    expect(app.lastFrame()).toContain("Wiki validation finished");
+  });
+
+  it("bounds retained history and per-event text while preserving the latest messages", () => {
+    let events: readonly string[] = [];
+    for (let index = 0; index < 200; index++) events = appendTerminalSetupEvent(events, `${index}:` + "x".repeat(2_048));
+    expect(events.length).toBeLessThanOrEqual(64);
+    expect(events.reduce((sum, event) => sum + event.length, 0)).toBeLessThanOrEqual(16_384);
+    expect(events.every(event => event.length <= 1_024)).toBe(true);
+    expect(events.at(-1)).toMatch(/^199:/);
+    expect(events.some(event => event.startsWith("0:"))).toBe(false);
+  });
+
+  it("opens retained details at the current failure and lets users scroll back to earlier notices", async () => {
+    const events = Array.from({ length: 30 }, (_, index) => `Earlier setup event ${index}`);
+    const app = await show({ screen: "error", detail: "Current graph failure", events });
+    app.stdin.write("d");
+    await settle();
+    expect(app.lastFrame()).toContain("Current graph failure");
+    expect(app.lastFrame()).not.toContain("Earlier setup event 0");
+    for (let page = 0; page < 4; page++) { app.stdin.write("\u001b[5~"); await settle(); }
+    expect(app.lastFrame()).toContain("Earlier setup event 0");
+    expect(app.onAction).not.toHaveBeenCalled();
+  });
+
+  it("offers clean Hub link access in a narrow terminal", async () => {
+    const app = await show({ screen: "hub", hubUrl: "http://127.0.0.1:43123/#token=" + "a".repeat(48) }, 60, 16);
+    expect(app.lastFrame()).toContain("l copy link");
+    app.stdin.write("l");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "link" });
+  });
+  it("presents the ASCII identity and tool selection within 80 by 24", async () => {
+    const app = await show();
+    expectFits(app.lastFrame(), 80, 24);
+    expect(app.lastFrame()).toContain("88888b.d88b.   .d88b.  888  888");
+    expect(app.lastFrame()).toContain("888 \"888 \"88b d8P  Y8b `Y8bd8P'");
+    expect(app.lastFrame()).toContain("888  888  888 88888888   X88K");
+    expect(app.lastFrame()).toContain("888  888  888 Y8b.     .d8\"\"8b.");
+    expect(app.lastFrame()).toContain("888  888  888  \"Y8888  888  888");
+    expect(app.lastFrame()).toContain("A place for project knowledge.");
+    expect(app.lastFrame()).toContain("example-project  /  code-repo");
+    expect(app.lastFrame()).toContain("> [x] Claude Code  CLI ready");
+    expect(app.lastFrame()).toContain("[ ] Cursor");
+    expect(app.lastFrame()).toContain("Enter select/start");
+    expect(app.lastFrame()).toContain("Space multi-select");
+    expect(app.lastFrame()).toContain("Continue with selected tools");
+    expectAlignedBorders(app.lastFrame(), 80);
+  });
+
+  it("keeps the five-line banner and picker within 60 columns without clipping a side caption", async () => {
+    const app = await show({}, 60, 24);
+    expect(app.lastFrame()).toContain("88888b.d88b.   .d88b.  888  888");
+    expect(app.lastFrame()).toContain("888  888  888  \"Y8888  888  888");
+    expect(app.lastFrame()).not.toContain("A place for");
+    expect(app.lastFrame()).toContain("Continue with selected tools");
+    expect(app.lastFrame()).toContain("Enter select/start");
+    expectFits(app.lastFrame(), 60, 24);
+    expectAlignedBorders(app.lastFrame(), 60);
+  });
+
+  it("distinguishes a missing population CLI from tools that only receive an integration", async () => {
+    const app = await show({ tools: initial.tools.map(tool => ({ ...tool, cliAvailable: tool.id === "opencode" })) });
+    expect(app.lastFrame()).toContain("Claude Code  CLI not found");
+    expect(app.lastFrame()).toContain("Codex  CLI not found");
+    expect(app.lastFrame()).toContain("Cursor  integration only");
+    expect(app.lastFrame()).toContain("OpenCode  integration only");
+    expect(app.lastFrame()).not.toContain("CLI ready");
+    expectFits(app.lastFrame(), 80, 24);
+  });
+
+  it("selects the highlighted unchecked tool and starts with one atomic Enter action", async () => {
+    const app = await show({ tools: initial.tools.map(tool => ({ ...tool, selected: false })) });
+    expect(app.lastFrame()).toContain("> [ ] Claude Code");
+    expect(app.lastFrame()).toContain("Enter selects this tool");
+    expect(app.lastFrame()).toContain("and starts setup.");
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start", tool: "claude" }]]);
+    expect(app.view.tools.every(tool => !tool.selected)).toBe(true);
+  });
+
+  it("starts with a checked tool without toggling it off", async () => {
+    const app = await show();
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start", tool: "claude" }]]);
+    expect(app.view.tools[0].selected).toBe(true);
+  });
+
+  it("starts with the moved-to unchecked tool without requiring Space", async () => {
+    const app = await show({ tools: initial.tools.map(tool => ({ ...tool, selected: false })) });
+    app.stdin.write("\u001b[B");
+    await settle();
+    expect(app.lastFrame()).toContain("> [ ] Codex");
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start", tool: "codex" }]]);
+  });
+
+  it("uses the requested initial tool focus without reordering choices", async () => {
+    const app = await show({ initialTool: "codex" });
+    expect(app.lastFrame()).toContain("> [ ] Codex");
+    expect(app.lastFrame()!.indexOf("Claude Code")).toBeLessThan(app.lastFrame()!.indexOf("> [ ] Codex"));
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start", tool: "codex" }]]);
+  });
+
+  it.each([true, false])("continues with the current selection without adding a tool (selected: %s)", async hasSelectedTool => {
+    const app = await show({ initialTool: "continue", tools: initial.tools.map(tool => ({ ...tool, selected: hasSelectedTool && tool.id === "claude" })) });
+    expect(app.lastFrame()).toContain(hasSelectedTool ? "> Continue with selected tools" : "> Continue without an agent");
+    app.stdin.write(" ");
+    await settle();
+    expect(app.onAction).not.toHaveBeenCalled();
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start" }]]);
+    expect(app.view.tools.filter(tool => tool.selected).map(tool => tool.id)).toEqual(hasSelectedTool ? ["claude"] : []);
+    expectFits(app.lastFrame(), 80, 24);
+  });
+
+  it("moves tool focus, optionally toggles multiple tools with Space, and starts on Enter", async () => {
+    const app = await show();
+    app.stdin.write("\u001b[B");
+    await settle();
+    app.stdin.write(" ");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "toggle", tool: "codex" });
+    expect(app.lastFrame()).toContain("> [ ] Codex");
+    app.rerender(h(TerminalSetupHUD, {
+      view: { ...app.view, tools: app.view.tools.map(tool => ({ ...tool, selected: tool.id === "codex" || tool.selected })) },
+      onAction: app.onAction,
+    }));
+    await settle();
+    expect(app.lastFrame()).toContain("> [x] Codex");
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "toggle", tool: "codex" }], [{ type: "start", tool: "codex" }]]);
+  });
+
+  it("keeps a focused tool visible when a small terminal needs a scrolling list", async () => {
+    const app = await show({}, 32, 9);
+    app.stdin.write("\u001b[A");
+    await settle();
+    app.stdin.write("\u001b[A");
+    await settle();
+    expectFits(app.lastFrame(), 32, 9);
+    expect(app.lastFrame()).toContain("> [ ] OpenCode");
+    expect(app.lastFrame()).toContain("Enter");
+    app.stdin.write(" ");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "toggle", tool: "opencode" });
+  });
+
+  it.each([true, false])("keeps the focused Continue choice usable after resizing to 32 by 9 (selected: %s)", async hasSelectedTool => {
+    const app = await show({ tools: initial.tools.map(tool => ({ ...tool, selected: hasSelectedTool && tool.id === "claude" })) });
+    app.stdin.write("\u001b[A");
+    await settle();
+    expect(app.lastFrame()).toContain(hasSelectedTool ? "> Continue with selected tools" : "> Continue without an agent");
+    Object.defineProperties(app.stdout, { columns: { configurable: true, value: 32 }, rows: { configurable: true, value: 9 } });
+    app.stdout.emit("resize");
+    await settle();
+    const text = app.lastFrame()?.replace(/│/g, " ").replace(/\s+/g, " ");
+    expect(text).toContain(hasSelectedTool ? "> Continue with selected tools" : "> Continue without an agent");
+    expect(app.lastFrame()).toContain("Enter start Space multi");
+    expectFits(app.lastFrame(), 32, 9);
+    expectAlignedBorders(app.lastFrame(), 32);
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "start" }]]);
+  });
+
+  it("shows only reported completion and the active phase, without synthetic progress", async () => {
+    const app = await show({ screen: "progress", completedSteps: ["detect", "scaffold"], activeStep: "graph", detail: "Indexing local source files." });
+    expectFits(app.lastFrame(), 80, 24);
+    expect(app.lastFrame()).toContain("[done] Project");
+    expect(app.lastFrame()).toContain("[done] Scaffold");
+    expect(app.lastFrame()).toContain("[now ] Code graph");
+    expect(app.lastFrame()).toContain("[wait] Project knowledge");
+    expect(app.lastFrame()).not.toContain("%");
+    expect(app.lastFrame()).toContain("01 [done] Project");
+    expect(app.lastFrame()).toContain("WORKFLOW");
+    expect(app.lastFrame()).toContain("LATEST EVENT");
+    expect(app.lastFrame()).toContain("╭─ MEX / SETUP");
+  });
+
+  it("animates pending work and advances phase and quiet clocks without inventing progress", async () => {
+    vi.useFakeTimers({ toFake: ["Date", "setInterval", "clearInterval"] });
+    vi.setSystemTime(100_000);
+    const app = await show({ screen: "progress", activeStep: "graph", startedAt: 50_000, phaseStartedAt: 90_000, lastActivityAt: 95_000, detail: "Parsing source files" });
+    expect(app.lastFrame()).toContain("Phase 10s");
+    expect(app.lastFrame()).toContain("No new events for 5s");
+    expectAlignedBorders(app.lastFrame(), 80);
+    const first = app.lastFrame();
+    vi.advanceTimersByTime(120);
+    await settle();
+    expect(app.lastFrame()).not.toBe(first);
+    expect(app.lastFrame()).toMatch(/[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]  Code graph/);
+    expectAlignedBorders(app.lastFrame(), 80);
+    vi.advanceTimersByTime(5_880);
+    await settle();
+    expect(app.lastFrame()).toContain("Phase 16s");
+    expect(app.lastFrame()).toContain("No new events for 11s");
+    expect(app.lastFrame()).toContain("[now ] Code graph");
+    expect(app.lastFrame()).not.toContain("[done] Code graph");
+    expect(app.lastFrame()).not.toContain("%");
+    app.rerender(h(TerminalSetupHUD, { view: { ...app.view, lastActivityAt: 106_000, detail: "Writing graph candidate" }, onAction: app.onAction }));
+    await settle();
+    expect(app.lastFrame()).toContain("Phase 16s");
+    expect(app.lastFrame()).toContain("No new events for 0s");
+    app.unmount();
+    await settle();
+    const frames = app.frames.length;
+    vi.advanceTimersByTime(2_000);
+    await settle();
+    expect(app.frames).toHaveLength(frames);
+  });
+
+  it("does not animate configuration, manual choices, errors, Hub, or stopping work", async () => {
+    vi.useFakeTimers({ toFake: ["Date", "setInterval", "clearInterval"] });
+    vi.setSystemTime(100_000);
+    const app = await show({ startedAt: 50_000 });
+    for (const screen of ["configure", "population", "error", "hub", "progress"] as const) {
+      app.rerender(h(TerminalSetupHUD, { view: { ...app.view, screen, stopping: screen === "progress" }, onAction: app.onAction }));
+      await settle();
+      const frame = app.lastFrame();
+      vi.advanceTimersByTime(1_500);
+      await settle();
+      expect(app.lastFrame()).toBe(frame);
+      expect(app.lastFrame()).not.toMatch(/[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏]/);
+    }
+  });
+
+  it("shows only supplied finite counts and removes stale counts on the next view", async () => {
+    const app = await show({ screen: "progress", activeStep: "graph", detail: "Parsing source files", progress: { completed: 12, total: 200, unit: "files parsed" } });
+    expect(app.lastFrame()).toContain("12 / 200 files parsed");
+    expect(app.lastFrame()).not.toContain("%");
+    app.rerender(h(TerminalSetupHUD, { view: { ...app.view, progress: { completed: Infinity, total: 200, unit: "files parsed" } }, onAction: app.onAction }));
+    await settle();
+    expect(app.lastFrame()).not.toContain("files parsed");
+    app.rerender(h(TerminalSetupHUD, { view: { ...app.view, progress: undefined }, onAction: app.onAction }));
+    await settle();
+    expect(app.lastFrame()).not.toContain("files parsed");
+  });
+
+  it("prioritizes the real count and phase clocks in a 32 by 12 terminal", async () => {
+    const app = await show({ screen: "progress", activeStep: "graph", phaseStartedAt: Date.now() - 18_000, lastActivityAt: Date.now() - 3_000, detail: "Parsing source files with the TypeScript compiler.", progress: { completed: 324, total: 1000, unit: "files parsed" } }, 32, 12);
+    expect(app.lastFrame()).toContain("324 / 1,000 files parsed");
+    expect(app.lastFrame()).toContain("Phase 18s");
+    expect(app.lastFrame()).toContain("Quiet 3s");
+    expectFits(app.lastFrame(), 32, 12);
+    expectAlignedBorders(app.lastFrame(), 32);
+  });
+
+  it("omits phases that agent-memory mode and no selected integrations do not run", async () => {
+    const app = await show({ screen: "progress", mode: "agent-memory", tools: [], activeStep: "population" });
+    expect(app.lastFrame()).not.toContain("Code graph");
+    expect(app.lastFrame()).not.toContain("Codebase scan");
+    expect(app.lastFrame()).not.toContain("Grounding + Wiki");
+    expect(app.lastFrame()).not.toContain("Agent skills");
+    expect(app.lastFrame()).toContain("[now ] Project knowledge");
+  });
+
+  it("does not promise agent skills for an editor-only integration", async () => {
+    const app = await show({ screen: "progress", tools: initial.tools.map(tool => ({ ...tool, selected: tool.id === "cursor" })) });
+    expect(app.lastFrame()).not.toContain("Agent skills");
+  });
+
+  it.each([
+    ["population", "[wait] Project knowledge"],
+    ["error", "[fail] Project knowledge"],
+    ["hub", "[skip] Project knowledge"],
+  ] as const)("keeps %s status distinct from active work", async (screen, status) => {
+    const app = await show({ screen, activeStep: "population", completedSteps: ["scaffold"] });
+    expect(app.lastFrame()).toContain(status);
+    expect(app.lastFrame()).toContain("[done] Scaffold");
+    expect(app.lastFrame()).not.toContain("88888b.d88b.");
+  });
+
+  it.each(["configure", "progress", "population", "error", "hub"] as const)("cancels %s on Ctrl+C and raw-mode EOF", async screen => {
+    const app = await show({ screen });
+    app.stdin.write("\u0003");
+    await settle();
+    app.stdin.write("\u0004");
+    await settle();
+    expect(app.onAction.mock.calls).toEqual([[{ type: "cancel" }], [{ type: "cancel" }]]);
+  });
+
+  it("offers native agent handoff, prompt, check, and explicit pause separately", async () => {
+    const app = await show({ screen: "population", populationAgent: "Codex" });
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "agent" });
+    for (const type of ["prompt", "check", "exit"]) {
+      app.stdin.write("\u001b[B");
+      await settle();
+      app.stdin.write("\r");
+      await settle();
+      expect(app.onAction).toHaveBeenLastCalledWith({ type });
+    }
+  });
+
+  it("does not offer an unavailable agent and resets focus for an error screen", async () => {
+    const app = await show({ screen: "population", populationAgent: null });
+    expect(app.lastFrame()).not.toContain("Open Codex");
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "prompt" });
+    app.stdin.write("\u001b[B");
+    await settle();
+    app.rerender(h(TerminalSetupHUD, { view: { ...app.view, screen: "error", error: "Resolve the conflict, then retry." }, onAction: app.onAction }));
+    await settle();
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "retry" });
+    app.stdin.write("\u001b[B");
+    await settle();
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "exit" });
+  });
+
+  it("lets users scroll all bounded remediation without invoking menu actions", async () => {
+    const error = "Inspect retained files before retrying. ".repeat(35) + "FINAL REMEDIATION: reconcile the backup first.";
+    const app = await show({ screen: "error", error }, 40, 12);
+    expectFits(app.lastFrame(), 40, 12);
+    app.stdin.write("d");
+    await settle();
+    expect(app.lastFrame()).toContain("Details 1-");
+    for (let index = 0; index < 20; index++) { app.stdin.write("\u001b[6~"); await settle(); }
+    expect(app.lastFrame()?.replace(/│/g, "").replace(/\s+/g, " ")).toContain("backup first.");
+    expectFits(app.lastFrame(), 40, 12);
+    app.stdin.write("\r");
+    await settle();
+    expect(app.onAction).not.toHaveBeenCalled();
+    app.stdin.write("\u001b");
+    await settle();
+    expect(app.lastFrame()).toContain("Retry setup");
+  });
+
+  it("wraps the Hub link and retains the complete URL in scrollable details", async () => {
+    const hubUrl = "http://127.0.0.1:43123/setup#token=" + "abcdef0123456789".repeat(4);
+    const app = await show({ screen: "hub", detail: "Review setup in the browser.", hubUrl });
+    const frame = app.lastFrame() ?? "";
+    expect(frame).toContain("http://127.0.0.1:43123/");
+    expect(frame).not.toContain("...");
+    expectFits(frame, 80, 24);
+    app.stdin.write("q");
+    await settle();
+    expect(app.onAction).toHaveBeenLastCalledWith({ type: "cancel" });
+  });
+
+  it("keeps the end of a long Hub URL accessible after shrinking the terminal", async () => {
+    const hubUrl = "http://127.0.0.1:43123/setup#token=" + "abcdef0123456789".repeat(6) + "TOKENEND";
+    const app = await show({ screen: "hub", detail: "Review setup in your browser.", hubUrl }, 32, 10);
+    expectFits(app.lastFrame(), 32, 10);
+    app.stdin.write("d");
+    await settle();
+    for (let index = 0; index < 4; index++) { app.stdin.write("\u001b[6~"); await settle(); }
+    expect(app.lastFrame()).toContain("TOKENEND");
+    expectFits(app.lastFrame(), 32, 10);
+  });
+
+  it("bounds very large unsafe details and suppresses input while stopping", async () => {
+    const app = await show({ screen: "progress", detail: "\u001b[2J\u001b[31mBAD\n".repeat(10_000), stopping: true }, 40, 12);
+    expectFits(app.lastFrame(), 40, 12);
+    expect(app.lastFrame()).not.toContain("\u001b");
+    expect(app.lastFrame()).toContain("Stopping safely");
+    app.stdin.write("\u0003");
+    await settle();
+    expect(app.onAction).not.toHaveBeenCalled();
+  });
+
+  it("exposes a bounded error diagnostic preview and a discoverable expansion key", async () => {
+    const app = await show({ screen: "error", activeStep: "graph", error: "The graph worker exceeded its Node.js heap limit. Increase its memory allowance and retry setup.", detail: "Diagnostics: Worker stopped with SIGABRT while parsing 865 / 924 files. V8 heap allocation failed." });
+    expect(app.lastFrame()).toContain("DIAGNOSTICS  [d] expand");
+    expect(app.lastFrame()).toContain("SIGABRT");
+    expect(app.lastFrame()).toContain("865 / 924");
+    expect(app.lastFrame()).toContain("d diagnostics");
+    expect(app.lastFrame()).toContain("> Retry setup");
+    expectFits(app.lastFrame(), 80, 24);
+  });
+});
diff --git a/src/setup/__tests__/terminal.test.ts b/src/setup/__tests__/terminal.test.ts
new file mode 100644
index 00000000..0349962e
--- /dev/null
+++ b/src/setup/__tests__/terminal.test.ts
@@ -0,0 +1,70 @@
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { runSetup } from "../index.js";
+import * as population from "../headless-population.js";
+import { runHeadlessSetup } from "../headless.js";
+
+const roots: string[] = [];
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllEnvs(); for (const root of roots.splice(0)) rmSync(root, { force: true, recursive: true }); });
+function project() {
+  const root = mkdtempSync(join(tmpdir(), "mex-terminal-")); roots.push(root);
+  vi.spyOn(process, "cwd").mockReturnValue(root);
+  vi.spyOn(console, "log").mockImplementation(() => {});
+  return root;
+}
+function populate(root: string) {
+  for (const path of ["AGENTS.md", "ROUTER.md", "context/architecture.md", "context/stack.md", "context/conventions.md", "context/decisions.md", "context/setup.md"]) {
+    writeFileSync(join(root, ".mex", path), "# Authored knowledge\n\nRetain this work.\n");
+  }
+}
+
+describe("terminal setup outcomes", () => {
+  it("--yes never launches a headless agent and returns an explicit resumable pause", async () => {
+    const root = project();
+    const launch = vi.spyOn(population, "launchHeadlessSetupPopulation");
+    const result = await runSetup({ mode: "agent-memory", tools: ["codex"], yes: true });
+    expect(result).toMatchObject({ outcome: "paused", exitCode: 2 });
+    expect(launch).not.toHaveBeenCalled();
+    expect(readFileSync(join(root, ".mex/config.json"), "utf8")).toContain('"codex"');
+  });
+
+  it("CI uses empty default choices without waiting for input", async () => {
+    const root = project(); vi.stubEnv("CI", "1");
+    expect(await runSetup({ mode: "agent-memory" })).toMatchObject({ outcome: "paused", exitCode: 2 });
+    expect(JSON.parse(readFileSync(join(root, ".mex/config.json"), "utf8")).aiTools).toEqual([]);
+  });
+
+  it("plain completion preserves authored files and returns without a Hub server", async () => {
+    const root = project();
+    await runSetup({ mode: "agent-memory", tools: [], yes: true });
+    populate(root);
+    const before = readFileSync(join(root, ".mex/ROUTER.md"), "utf8");
+    expect(await runSetup({ yes: true, openBrowser: true })).toMatchObject({ outcome: "complete", exitCode: 0 });
+    expect(readFileSync(join(root, ".mex/ROUTER.md"), "utf8")).toBe(before);
+    expect(readdirSync(join(root, ".mex"))).not.toContain("graph.db");
+  });
+
+  it("fresh dry-run has no prompts, agent launch, config or local writes", async () => {
+    const root = project();
+    const launch = vi.spyOn(population, "launchHeadlessSetupPopulation");
+    expect(await runSetup({ mode: "agent-memory", tools: ["codex"], dryRun: true })).toMatchObject({ outcome: "dry-run", exitCode: 0 });
+    expect(readdirSync(root)).toEqual([]);
+    expect(launch).not.toHaveBeenCalled();
+  });
+
+  it("the shared engine checks files even when a presentation adapter claims completion", async () => {
+    const root = project();
+    const run = vi.fn(async () => ({ tool: "codex" as const, completed: true }));
+    expect(await runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [], populate: run })).toMatchObject({ ready: false, stage: "needs_population" });
+    expect(run).toHaveBeenCalledOnce();
+  });
+
+  it("the presentation callback can populate then continue through the shared engine", async () => {
+    const root = project();
+    expect(await runHeadlessSetup({ projectRoot: root, mode: "agent-memory", tools: [],
+      populate: async () => { populate(root); return { tool: null, completed: true }; },
+    })).toMatchObject({ ready: true, stage: "ready", mode: "agent-memory" });
+  });
+});
diff --git a/src/setup/__tests__/wiki-finalize.test.ts b/src/setup/__tests__/wiki-finalize.test.ts
index 951d8ebf..d4853819 100644
--- a/src/setup/__tests__/wiki-finalize.test.ts
+++ b/src/setup/__tests__/wiki-finalize.test.ts
@@ -24,6 +24,17 @@ afterEach(() => {
 });
 
 describe("setup Wiki finalization", () => {
+  it("stops at the migration boundary without changing canonical files or creating an index", async () => {
+    const { projectRoot, scaffoldRoot } = legacyScaffold(false);
+    const before = readFileSync(join(scaffoldRoot, "context/setup.md"), "utf8");
+    const abort = new AbortController();
+    await expect(finalizeSetupWiki({ projectRoot, scaffoldRoot, signal: abort.signal,
+      onProgress: message => { if (message === "Applying Wiki migration...") abort.abort(); },
+    })).rejects.toThrow("Setup was cancelled");
+    expect(readFileSync(join(scaffoldRoot, "context/setup.md"), "utf8")).toBe(before);
+    expect(existsSync(join(scaffoldRoot, "wiki.db"))).toBe(false);
+  });
+
   it("adopts files added since an earlier setup without telling the user to run migration (#227)", async () => {
     const projectRoot = fixture();
     const scaffoldRoot = join(projectRoot, ".mex");
diff --git a/src/setup/agent-errors.ts b/src/setup/agent-errors.ts
new file mode 100644
index 00000000..c242ade5
--- /dev/null
+++ b/src/setup/agent-errors.ts
@@ -0,0 +1,42 @@
+import { AgentAssetsError } from "../agent-skills/installer.js";
+import { classifySetupFileSystemError, SetupError } from "./errors.js";
+
+const BACKUP_REVIEW = "Look for hidden entries containing .mex-backup- beside CLAUDE.md or AGENTS.md and in .claude/skills or .agents/skills. Review and reconcile those backups before rerunning setup.";
+
+/** Translate known installer failures without exposing paths or child output. */
+export function classifySetupAgentAssetsError(error: unknown): SetupError | null {
+  if (!(error instanceof AgentAssetsError)) {
+    return classifySetupFileSystemError(error, "Could not install the selected agent integrations.");
+  }
+
+  let userMessage: string;
+  switch (error.code) {
+    case "INVALID_PACKAGED_SKILL":
+      userMessage = "The packaged MEX agent skills are missing or invalid. Reinstall MEX, then rerun setup.";
+      break;
+    case "INVALID_OPTIONS":
+      userMessage = "Agent integration setup could not validate the project or installation settings. Check the project directory and selected tools; reinstall MEX if its packaged settings are invalid.";
+      break;
+    case "IGNORE_CHECK_FAILED":
+      userMessage = "Git could not verify the agent integration paths. Make sure Git is available and run git status from the project root to diagnose the repository, then rerun setup.";
+      break;
+    case "CONCURRENT_MODIFICATION":
+      userMessage = "Agent integration files changed during setup. Finish or stop other edits, review the affected files, then rerun setup.";
+      break;
+    case "PATH_IDENTITY_CHANGED":
+      userMessage = `An agent integration path changed during setup. Stop other processes changing the project. ${BACKUP_REVIEW}`;
+      break;
+    case "REPLACEMENT_ACTIVE_BACKUP_RETAINED":
+      userMessage = `Updated agent files are active, but an original backup was retained. ${BACKUP_REVIEW}`;
+      break;
+    case "APPLY_FAILED":
+      // This code also covers failed rollback. Never imply retry alone is safe.
+      userMessage = `Agent integration could not finish, and some files or backups may remain. ${BACKUP_REVIEW}`;
+      break;
+    default:
+      // UNKNOWN_PLAN and DRY_RUN_PLAN indicate internal misuse, not a user fix.
+      return null;
+  }
+
+  return new SetupError(error.message, { cause: error, userMessage });
+}
diff --git a/src/setup/entry.ts b/src/setup/entry.ts
new file mode 100644
index 00000000..e9c16c41
--- /dev/null
+++ b/src/setup/entry.ts
@@ -0,0 +1,26 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { loadConfiguredSetupMode } from "../config.js";
+
+/** Locate the checkout without requiring or creating a MEX scaffold. */
+export function findSetupProjectRoot(startDir: string = process.cwd()): string {
+  let current = resolve(startDir);
+  while (true) {
+    if (existsSync(resolve(current, ".git"))) return current;
+    const parent = dirname(current);
+    if (parent === current) return resolve(startDir);
+    current = parent;
+  }
+}
+
+/** Keep established code projects on the Hub's existing recovery surfaces. */
+export async function resolveDefaultEntry(
+  projectRoot: string = findSetupProjectRoot(),
+): Promise<"setup" | "hub"> {
+  const scaffoldRoot = resolve(projectRoot, ".mex");
+  if (loadConfiguredSetupMode(scaffoldRoot) !== "code-repo"
+    || !existsSync(resolve(scaffoldRoot, "ROUTER.md"))) return "setup";
+  // New workspaces do not need to load the Hub or inspect Graph/Wiki state.
+  const { hasCommittedHubIdentity } = await import("../hub/setup/readiness.js");
+  return await hasCommittedHubIdentity(projectRoot) ? "hub" : "setup";
+}
diff --git a/src/setup/errors.ts b/src/setup/errors.ts
new file mode 100644
index 00000000..2db57254
--- /dev/null
+++ b/src/setup/errors.ts
@@ -0,0 +1,54 @@
+/**
+ * An expected setup failure with an explicitly safe browser explanation.
+ * Keep paths, child output, and underlying diagnostics in message/cause only;
+ * userMessage must be MEX-authored text and known relative setup paths.
+ */
+export class SetupError extends Error {
+  readonly userMessage: string;
+
+  constructor(message: string, options?: ErrorOptions & { userMessage?: string }) {
+    super(message, options);
+    this.name = "SetupError";
+    this.userMessage = options?.userMessage ?? message;
+  }
+}
+
+/** Classify known filesystem failures without inspecting or exposing their text.
+ * operation must be authored text, never a path or message from the exception.
+ */
+export function classifySetupFileSystemError(error: unknown, operation: string): SetupError | null {
+  if (!(error instanceof Error) || !("code" in error)) return null;
+  let recovery: string;
+  switch (error.code) {
+    case "EACCES":
+    case "EPERM":
+      recovery = "Access was denied. Check the file and directory permissions, then retry setup.";
+      break;
+    case "EROFS":
+      recovery = "The filesystem is read-only. Use a writable checkout, then retry setup.";
+      break;
+    case "ENOSPC":
+    case "EDQUOT":
+      recovery = "Storage is full or its quota was reached. Free disk space or increase the quota, then retry setup.";
+      break;
+    case "EBUSY":
+      recovery = "A required file is busy. Close the process using it, then retry setup.";
+      break;
+    case "EEXIST":
+    case "ENOTDIR":
+    case "EISDIR":
+    case "ELOOP":
+      recovery = "A required path has a conflicting file, directory, or symbolic link. Correct it, then retry setup.";
+      break;
+    case "ENOENT":
+      recovery = "A required file or directory is missing. Restore it, or reinstall MEX if its templates are missing, then retry setup.";
+      break;
+    case "EMFILE":
+    case "ENFILE":
+      recovery = "The system has too many open files. Close other processes, then retry setup.";
+      break;
+    default:
+      return null;
+  }
+  return new SetupError(error.message, { cause: error, userMessage: `${operation} ${recovery}` });
+}
diff --git a/src/setup/graph-progress.ts b/src/setup/graph-progress.ts
new file mode 100644
index 00000000..04a172cf
--- /dev/null
+++ b/src/setup/graph-progress.ts
@@ -0,0 +1,28 @@
+import type { GraphMaintenanceProgress } from "../team/contracts/graph.js";
+
+const LABELS: Record<GraphMaintenanceProgress["phase"], string> = {
+  discover: "Checking existing graph and project files",
+  stage: "Preparing an isolated graph build",
+  parse: "Parsing source files",
+  resolve: "Resolving code references",
+  validate: "Validating the rebuilt graph",
+  publish: "Saving the verified graph",
+};
+
+/** Keep maintenance text and arbitrary paths out of the presentation contract. */
+export function setupGraphActivity(update: GraphMaintenanceProgress): {
+  detail: string;
+  progress?: { completed: number; total?: number; unit: string };
+} {
+  const detail = LABELS[update.phase];
+  const completed = update.completed;
+  if (update.phase !== "parse" || completed === undefined || !Number.isSafeInteger(completed) || completed < 0) return { detail };
+  const total = update.total !== undefined && Number.isSafeInteger(update.total) && update.total > 0 && update.total >= completed
+    ? update.total : undefined;
+  return { detail, progress: { completed, ...(total === undefined ? {} : { total }), unit: "files parsed" } };
+}
+
+export function formatSetupGraphActivity(update: GraphMaintenanceProgress): string {
+  const { detail, progress } = setupGraphActivity(update);
+  return progress ? `${detail}: ${progress.completed}${progress.total === undefined ? "" : ` / ${progress.total}`} ${progress.unit}` : detail;
+}
diff --git a/src/setup/headless.ts b/src/setup/headless.ts
index c10366fd..d5d10b90 100644
--- a/src/setup/headless.ts
+++ b/src/setup/headless.ts
@@ -9,6 +9,10 @@ import {
   saveAiTools,
 } from "../config.js";
 import { AI_TOOLS, type AiTool } from "../types.js";
+import { AGENT_SKILL_TARGETS, OFFICIAL_MEX_SKILLS } from "../agent-skills/types.js";
+import { SetupError, classifySetupFileSystemError } from "./errors.js";
+import { classifySetupAgentAssetsError } from "./agent-errors.js";
+import type { GraphMaintenanceProgress } from "../team/contracts/graph.js";
 import { launchHeadlessSetupPopulation, type HeadlessPopulationActivity, type HeadlessPopulationTranscript } from "./headless-population.js";
 import {
   detectProjectState,
@@ -85,6 +89,16 @@ export interface HeadlessSetupOptions {
   readonly onPopulationTranscript?: (entry: HeadlessPopulationTranscript) => void;
   readonly onPopulationPrompt?: (prompt: string) => void;
   readonly onAnchorNotes?: (notes: readonly string[]) => void;
+  /** Presentation-owned population (the terminal temporarily yields to a native agent). */
+  readonly populate?: (input: {
+    selectedTools: readonly AiTool[];
+    prompt: string;
+    projectRoot: string;
+    signal?: AbortSignal;
+  }) => Promise<{ tool: "claude" | "codex" | null; completed: boolean }>;
+  readonly onMessage?: (message: string) => void;
+  /** Live maintenance updates, separate from the ordered setup phase transitions. */
+  readonly onGraphProgress?: (progress: GraphMaintenanceProgress) => void;
 }
 
 export interface HeadlessSetupProgress {
@@ -162,11 +176,12 @@ export function setupUnavailableReason(): string {
 }
 
 /**
- * Run the same ordered setup path as `mex setup`, without readline or a TTY.
+ * Run the shared ordered setup path, with presentation and input owned by callers.
  *
- * Tool choice arrives from the Hub form. Population uses a headless Claude or
- * Codex session when one is installed; otherwise the prompt is returned for
- * the user to paste. Finalize only runs after `isScaffoldPopulated`.
+ * The Hub defaults to a headless Claude/Codex session; the terminal supplies a
+ * native handoff callback. Scripts use confirmPopulation to inspect without an
+ * agent. Finalize only runs after checking the populated files, regardless of
+ * the population adapter's result.
  */
 export async function runHeadlessSetup(
   options: HeadlessSetupOptions,
@@ -186,7 +201,7 @@ export async function runHeadlessSetup(
   throwIfSetupAborted(options.signal);
 
   if (mode === "code-repo" && !existsSync(resolve(projectRoot, ".git"))) {
-    throw new Error("No Git repository found. Run `git init` first, then rerun setup.");
+    throw new SetupError("No Git repository found. Run `git init` first, then rerun setup.");
   }
 
   const scaffoldPopulatedAtStart = isScaffoldPopulated(mexDir);
@@ -199,28 +214,51 @@ export async function runHeadlessSetup(
   report("tools");
   const requestedTools = uniqueTools(options.tools ?? loadConfiguredAiTools(mexDir));
   const selectedTools = requestedTools;
-  const anchorNotes = ensureToolAnchors(projectRoot, templatesDir, selectedTools, false);
+  let anchorNotes: string[];
+  try {
+    anchorNotes = ensureToolAnchors(projectRoot, templatesDir, selectedTools, false, options.onMessage);
+  } catch (error) {
+    throw classifySetupFileSystemError(error, "Could not link the selected AI tool instruction files.") ?? error;
+  }
   options.onAnchorNotes?.(anchorNotes);
-  saveAiTools(mexDir, selectedTools);
+  try {
+    saveAiTools(mexDir, selectedTools);
+  } catch (error) {
+    throw classifySetupFileSystemError(error, "Could not save the AI tool selection in .mex/config.json.") ?? error;
+  }
 
   const selectedAgentClients = selectedTools.filter((tool) => tool === "claude" || tool === "codex");
   if (selectedAgentClients.length > 0) {
     report("skills");
-    const agentAssets = installSetupAgentAssets({
-      projectRoot,
-      selectedTools,
-      dryRun: false,
-      checkIgnored: mode === "code-repo",
-    });
+    let agentAssets: ReturnType<typeof installSetupAgentAssets>;
+    try {
+      agentAssets = installSetupAgentAssets({
+        projectRoot,
+        selectedTools,
+        dryRun: false,
+        checkIgnored: mode === "code-repo",
+      });
+    } catch (error) {
+      throw classifySetupAgentAssetsError(error) ?? error;
+    }
     if (agentAssets?.conflicted) {
-      throw new Error("Official MEX agent assets have conflicts. Resolve them and rerun setup or mex skills sync.");
+      // Only known install destinations can enter the browser explanation.
+      const destinations = new Set(Object.values(AGENT_SKILL_TARGETS).flatMap((target) => [
+        target.instructionsPath,
+        ...OFFICIAL_MEX_SKILLS.map((skill) => `${target.skillsDirectory}/${skill}`),
+      ]));
+      const conflicts = [...new Set(agentAssets.actions
+        .filter((action) => action.action === "conflict" && destinations.has(action.path))
+        .map((action) => action.path))].slice(0, 2);
+      const detail = conflicts.length ? ` Check ${conflicts.join(" and ")}.` : "";
+      throw new SetupError(`Official MEX agent assets have conflicts.${detail} Review them with mex skills sync --dry-run, resolve the conflicts, then retry setup.`);
     }
   }
 
   report("identity");
   const identity = ensureScaffoldIdentity(mexDir, projectRoot);
   if (readScaffoldId(mexDir) !== identity.scaffold_id) {
-    throw new Error("Could not persist .mex/config.json. Fix its permissions or contents and rerun setup.");
+    throw new SetupError("Could not persist .mex/config.json. Fix its permissions or contents and rerun setup.");
   }
 
   let scannerBrief: string | null = null;
@@ -231,7 +269,11 @@ export async function runHeadlessSetup(
 
   if (mode === "code-repo") {
     report("graph");
-    await buildSetupGraph(projectRoot, { background: true, signal: options.signal });
+    await buildSetupGraph(projectRoot, {
+      background: true,
+      signal: options.signal,
+      onProgress: options.onGraphProgress,
+    });
   }
 
   const prompt = await buildSetupPopulationPrompt(mode, state, scannerBrief);
@@ -244,7 +286,7 @@ export async function runHeadlessSetup(
 
   if (!populationFinished && options.confirmPopulation !== true) {
     throwIfSetupAborted(options.signal);
-    const launched = await launchHeadlessSetupPopulation({
+    const launched = await (options.populate ?? launchHeadlessSetupPopulation)({
       selectedTools,
       prompt,
       projectRoot,
@@ -288,7 +330,10 @@ export async function runHeadlessSetup(
   if (mode === "code-repo") {
     report("finalize");
     throwIfSetupAborted(options.signal);
-    await finalizeCodeRepoSetup(projectRoot, mexDir);
+    await finalizeCodeRepoSetup(projectRoot, mexDir, {
+      signal: options.signal,
+      onMessage: options.onMessage,
+    });
     throwIfSetupAborted(options.signal);
   }
 
diff --git a/src/setup/ignore.ts b/src/setup/ignore.ts
index 49026571..c093278e 100644
--- a/src/setup/ignore.ts
+++ b/src/setup/ignore.ts
@@ -7,6 +7,7 @@ import {
 } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { resolve } from "node:path";
+import { classifySetupFileSystemError, SetupError } from "./errors.js";
 
 export const SETUP_IGNORE_PATH = ".mex/.gitignore" as const;
 export const SETUP_IGNORE_RULES = ["graph.db*", "wiki.db*", "local/"] as const;
@@ -29,8 +30,8 @@ export interface SetupIgnoreProtectionResult {
   readonly addedRules: readonly string[];
 }
 
-export class SetupIgnoreProtectionError extends Error {
-  constructor(message: string, options?: ErrorOptions) {
+export class SetupIgnoreProtectionError extends SetupError {
+  constructor(message: string, options?: ErrorOptions & { userMessage?: string }) {
     super(message, options);
     this.name = "SetupIgnoreProtectionError";
   }
@@ -54,6 +55,7 @@ export function ensureSetupIgnoreProtection(
   if (mexStats && (mexStats.isSymbolicLink() || !mexStats.isDirectory())) {
     throw new SetupIgnoreProtectionError(
       `Cannot protect local MEX data: ${mexDirectory} is not a safe directory.`,
+      { userMessage: "The .mex path must be a regular directory, not a symlink. Fix that path, then rerun setup." },
     );
   }
 
@@ -61,10 +63,23 @@ export function ensureSetupIgnoreProtection(
   if (ignoreStats && (ignoreStats.isSymbolicLink() || !ignoreStats.isFile())) {
     throw new SetupIgnoreProtectionError(
       `Cannot protect local MEX data: ${ignorePath} is not a regular file.`,
+      { userMessage: "The .mex/.gitignore path must be a regular file, not a symlink. Fix that path, then rerun setup." },
     );
   }
 
-  const existing = ignoreStats ? readFileSync(ignorePath) : Buffer.alloc(0);
+  let existing: Buffer;
+  try {
+    existing = ignoreStats ? readFileSync(ignorePath) : Buffer.alloc(0);
+  } catch (error) {
+    throw new SetupIgnoreProtectionError(
+      error instanceof Error ? error.message : `Could not read local MEX ignore rules at ${ignorePath}.`,
+      {
+        cause: error,
+        userMessage: classifySetupFileSystemError(error, "Could not read .mex/.gitignore.")?.userMessage
+          ?? "Could not read .mex/.gitignore. Check its permissions, then rerun setup.",
+      },
+    );
+  }
   const content = existing.toString("utf8");
   const presentRules = new Set(splitLines(content));
   const addedRules = SETUP_IGNORE_RULES.filter((rule) => !presentRules.has(rule));
@@ -90,7 +105,11 @@ export function ensureSetupIgnoreProtection(
     } catch (error) {
       throw new SetupIgnoreProtectionError(
         `Could not create the MEX directory at ${mexDirectory}.`,
-        { cause: error },
+        {
+          cause: error,
+          userMessage: classifySetupFileSystemError(error, "Could not create .mex.")?.userMessage
+            ?? "Could not create .mex. Check write permissions for the project directory, then rerun setup.",
+        },
       );
     }
     requireSafeDirectory(mexDirectory, ".mex directory");
@@ -109,7 +128,11 @@ export function ensureSetupIgnoreProtection(
   } catch (error) {
     throw new SetupIgnoreProtectionError(
       `Could not write local MEX data protection to ${ignorePath}.`,
-      { cause: error },
+      {
+        cause: error,
+        userMessage: classifySetupFileSystemError(error, "Could not write .mex/.gitignore.")?.userMessage
+          ?? "Could not write .mex/.gitignore. Check write permissions for .mex and its ignore file, then rerun setup.",
+      },
     );
   }
 
@@ -168,7 +191,9 @@ export function verifySetupIgnoreProtection(projectRoot: string): void {
     ".mex/local/setup-state.json",
   ]) {
     if (!isIgnored(root, path)) {
-      throw new SetupIgnoreProtectionError(`Local MEX path is not ignored by Git: ${path}`);
+      throw new SetupIgnoreProtectionError(`Local MEX path is not ignored by Git: ${path}`, {
+        userMessage: "Local MEX data is not ignored by Git. Check .mex/.gitignore and conflicting negation rules, then retry setup.",
+      });
     }
   }
 }
@@ -192,6 +217,9 @@ function requireSafeDirectory(path: string, label: string): void {
   if (!stats || stats.isSymbolicLink() || !stats.isDirectory()) {
     throw new SetupIgnoreProtectionError(
       `Cannot protect local MEX data: ${label} at ${path} is not a safe directory.`,
+      { userMessage: label === "project root"
+        ? "The project root must be a regular directory, not a symlink. Run setup from a valid project directory."
+        : "The .mex path must be a regular directory, not a symlink. Fix that path, then rerun setup." },
     );
   }
 }
@@ -203,7 +231,11 @@ function lstatIfExists(path: string): ReturnType<typeof lstatSync> | null {
     if (isMissing(error)) return null;
     throw new SetupIgnoreProtectionError(
       `Could not inspect setup path ${path}.`,
-      { cause: error },
+      {
+        cause: error,
+        userMessage: classifySetupFileSystemError(error, "Could not inspect the setup paths.")?.userMessage
+          ?? "Could not inspect the setup paths. Check permissions for the project directory, .mex, and .mex/.gitignore, then rerun setup.",
+      },
     );
   }
 }
@@ -223,11 +255,13 @@ function isIgnored(projectRoot: string, path: string): boolean {
   if (checked.error) {
     throw new SetupIgnoreProtectionError("Could not run Git to verify local MEX data protection.", {
       cause: checked.error,
+      userMessage: "Could not run Git to verify ignore rules. Make sure Git is installed and available on PATH, then rerun setup.",
     });
   }
   if (checked.status === 0) return true;
   if (checked.status === 1) return false;
   throw new SetupIgnoreProtectionError(
     `Git could not verify local MEX data protection: ${checked.stderr.trim() || `exit ${checked.status}`}`,
+    { userMessage: "Git could not verify ignore rules. Check that this project is a valid Git repository and run git status to diagnose it, then rerun setup." },
   );
 }
diff --git a/src/setup/index.ts b/src/setup/index.ts
index 61bcc895..99620bc4 100644
--- a/src/setup/index.ts
+++ b/src/setup/index.ts
@@ -1,16 +1,9 @@
 import { existsSync, readFileSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { createInterface } from "node:readline/promises";
-import { stdin, stdout } from "node:process";
+import { resolve } from "node:path";
 import { globSync } from "glob";
 import chalk from "chalk";
 import {
-  saveAiTools,
-  ensureScaffoldIdentity,
   findConfig,
-  loadConfiguredAiTools,
-  hasConfiguredAiTools,
-  readScaffoldId,
 } from "../config.js";
 import {
   captureGroundingBaselines,
@@ -18,20 +11,13 @@ import {
 } from "../graph/runtime.js";
 import { VERSION } from "../version.js";
 import {
-  renderInstructionChangePreview,
   syncAgentAssets,
   type AgentAssetsReport,
   type AgentSkillClient,
 } from "../agent-skills/index.js";
-import { AI_TOOLS, type AiTool } from "../types.js";
-import { launchSetupPopulation } from "./population.js";
+import { type AiTool } from "../types.js";
 import {
-  buildSetupPopulationPrompt,
-  buildSetupGraph,
-  createSetupScaffold,
-  resolveSetupMode,
-  scanSetupCodebase,
-  setupTemplatesDirectory,
+  throwIfSetupAborted,
   type ProjectState,
 } from "./phases.js";
 export {
@@ -46,6 +32,9 @@ export {
   type SetupMode,
 } from "./phases.js";
 import { finalizeSetupWiki } from "./wiki-finalize.js";
+import { SetupError } from "./errors.js";
+import { classifySetupMaintenanceError, setupWikiFailureMessage } from "./maintenance-errors.js";
+export { findSetupProjectRoot } from "./entry.js";
 import {
   ensureMarkdownAnchor,
   ensureOpencodeAnchor,
@@ -102,6 +91,7 @@ export function ensureToolAnchors(
   templatesDir: string,
   tools: readonly AiTool[],
   dryRun: boolean,
+  onMessage?: (message: string) => void,
 ): string[] {
   const notes: string[] = [];
 
@@ -116,7 +106,7 @@ export function ensureToolAnchors(
     let result: AnchorWriteResult;
     if (dryRun) {
       if (!existsSync(dest)) {
-        ok(`(dry run) Would copy ${config.dest}`);
+        (onMessage ?? ok)(`(dry run) Would copy ${config.dest}`);
         continue;
       }
       result = isJson
@@ -128,7 +118,7 @@ export function ensureToolAnchors(
         : ensureMarkdownAnchor(projectRoot, config.dest, src);
     }
 
-    const note = reportAnchor(config.dest, result, dryRun);
+    const note = reportAnchor(config.dest, result, dryRun, onMessage);
     if (note) notes.push(note);
   }
 
@@ -136,27 +126,27 @@ export function ensureToolAnchors(
 }
 
 /** Print an anchor outcome; return a note for the ones the user must act on. */
-function reportAnchor(dest: string, result: AnchorWriteResult, dry: boolean): string | null {
+function reportAnchor(dest: string, result: AnchorWriteResult, dry: boolean, onMessage?: (message: string) => void): string | null {
   const prefix = dry ? "(dry run) Would " : "";
   switch (result.outcome) {
     case "created":
-      ok(`${prefix}${dry ? "copy" : "Copied"} ${dest}`);
+      (onMessage ?? ok)(`${prefix}${dry ? "copy" : "Copied"} ${dest}`);
       return null;
     case "appended":
-      ok(`${prefix}${dry ? "add" : "Added"} a MEX pointer to your existing ${dest}`);
+      (onMessage ?? ok)(`${prefix}${dry ? "add" : "Added"} a MEX pointer to your existing ${dest}`);
       return null;
     case "updated":
-      ok(`${prefix}${dry ? "refresh" : "Refreshed"} the MEX pointer in ${dest}`);
+      (onMessage ?? ok)(`${prefix}${dry ? "refresh" : "Refreshed"} the MEX pointer in ${dest}`);
       return null;
     case "already-linked":
-      info(`${dest} already points at .mex/ — left unchanged`);
+      (onMessage ?? info)(`${dest} already points at .mex/ — left unchanged`);
       return null;
     case "conflict": {
       const note =
         `${dest} was left untouched because ${result.reason}. `
         + "Add this line to it by hand so the scaffold is loaded: "
         + "`At the start of every session, read .mex/AGENTS.md and .mex/ROUTER.md.`";
-      warn(note);
+      (onMessage ?? warn)(note);
       return note;
     }
   }
@@ -167,41 +157,6 @@ function reportAnchor(dest: string, result: AnchorWriteResult, dry: boolean): st
 const ok = (msg: string) => console.log(`${chalk.green("✓")} ${msg}`);
 const info = (msg: string) => console.log(`${chalk.blue("→")} ${msg}`);
 const warn = (msg: string) => console.log(`${chalk.yellow("!")} ${msg}`);
-const header = (msg: string) => console.log(`\n${chalk.bold(msg)}`);
-
-export function findSetupProjectRoot(startDir: string = process.cwd()): string {
-  let current = resolve(startDir);
-  while (true) {
-    if (existsSync(resolve(current, ".git"))) return current;
-    const parent = dirname(current);
-    if (parent === current) return resolve(startDir);
-    current = parent;
-  }
-}
-
-function findProjectRoot(): string {
-  return findSetupProjectRoot();
-}
-
-function banner() {
-  const GRN = "\x1b[38;2;91;140;90m";
-  const DGR = "\x1b[38;2;74;122;73m";
-  const ORN = "\x1b[38;2;232;132;92m";
-  const DRK = "\x1b[38;2;61;61;61m";
-  const ROYAL = "\x1b[38;2;25;68;241m";
-  const NC = "\x1b[0m";
-  const BOLD = "\x1b[1m";
-
-  console.log();
-  console.log(`${GRN}     ████      ${ROYAL}███╗   ███╗███████╗██╗  ██╗${NC}`);
-  console.log(`${GRN}    █${DGR}█${GRN}██${DGR}█${GRN}█     ${ROYAL}████╗ ████║██╔════╝╚██╗██╔╝${NC}`);
-  console.log(`${ORN}  ██████████   ${ROYAL}██╔████╔██║█████╗   ╚███╔╝${NC}`);
-  console.log(`${ORN}█ ██${DRK}██${ORN}██${DRK}██${ORN}██ █ ${ROYAL}██║╚██╔╝██║██╔══╝   ██╔██╗${NC}`);
-  console.log(`${ORN}█ ██████████ █ ${ROYAL}██║ ╚═╝ ██║███████╗██╔╝ ██╗${NC}`);
-  console.log(`${ORN}   █ █  █ █    ${ROYAL}╚═╝     ╚═╝╚══════╝╚═╝  ╚═╝${NC}`);
-  console.log();
-  console.log(`               ${BOLD}universal ai context scaffold${NC}`);
-}
 
 // ── Main ──
 
@@ -225,229 +180,23 @@ export function setupCommitCheckpointCommands(selectedTools: readonly AiTool[]):
 export interface SetupRunOptions {
   dryRun?: boolean;
   mode?: string;
-  /** Use these AI tools instead of asking (`--tool`, repeatable). */
   tools?: AiTool[];
-  /**
-   * Never wait on a question (`--yes`): population counts as finished once the
-   * scaffold has no placeholders left, and the optional closing prompts are
-   * skipped. For scripts, CI and benchmarks.
-   */
+  /** Plain, noninteractive setup. Never starts an agent or a browser. */
   yes?: boolean;
+  port?: number;
+  openBrowser?: boolean;
 }
 
-export async function runSetup(opts: SetupRunOptions = {}): Promise<void> {
-  const { dryRun = false, yes = false } = opts;
-
-  banner();
-  console.log();
-
-  if (dryRun) {
-    warn("DRY RUN — no files will be created or modified");
-    console.log();
-  }
-
-  const templatesDir = setupTemplatesDirectory();
-  const projectRoot = findProjectRoot();
-  const mexDir = resolve(projectRoot, ".mex");
-  const mode = resolveSetupMode(mexDir, opts.mode);
-
-  if (mode === "code-repo" && !existsSync(resolve(projectRoot, ".git"))) {
-    throw new Error("No Git repository found. Run `git init` first, then rerun mex setup --cli.");
-  }
-
-  // ── Step 1: Detect project state ──
-
-  const scaffoldPopulatedAtStart = isScaffoldPopulated(mexDir);
-  const state = detectProjectState(projectRoot, mexDir);
-
-  if (mode === "agent-memory") {
-    info("Detected: agent-memory workspace");
-    info("Mode: persistent-agent operational memory");
-  } else {
-    switch (state) {
-      case "existing":
-        info("Detected: existing codebase with source files");
-        info("Mode: populate scaffold from code");
-        break;
-      case "fresh":
-        info("Detected: fresh project (no source files yet)");
-        info("Mode: populate scaffold from intent");
-        break;
-      case "partial":
-        info("Detected: existing codebase with a populated scaffold");
-        info("Mode: preserve authored files and finish setup readiness");
-        break;
-    }
-  }
-  console.log();
-
-  // ── Step 2: Create .mex/ scaffold ──
-
-  header("Creating .mex/ scaffold...");
-  console.log();
-
-  createSetupScaffold({
-    projectRoot,
-    mode,
-    dryRun,
-    onIgnore: (message, changed) => changed ? ok(message) : info(message),
-    onFile: (file, action) => {
-      if (action === "skip") info(`Skipped .mex/${file} (already exists)`);
-      else ok(`${dryRun ? "(dry run) Would copy" : "Copied"} .mex/${file}`);
-    },
-  });
-  console.log();
-
-  // ── Step 3: Tool config selection ──
-
-  let selectedTools: AiTool[] = [];
-  let anchorNotes: string[] = [];
-
-  // A persisted selection belongs to the scaffold even when population was
-  // interrupted or the templates gained new required slots. Reuse it instead
-  // of making a resumed setup ask the user the same question again.
-  const configuredTools = loadConfiguredAiTools(mexDir);
-  if (opts.tools !== undefined) {
-    selectedTools = [...new Set(opts.tools)];
-    anchorNotes = ensureToolAnchors(projectRoot, templatesDir, selectedTools, dryRun);
-    if (!dryRun) saveAiTools(mexDir, selectedTools);
-    info(`Using AI tools from --tool: ${selectedTools.map((tool) => AI_TOOLS[tool].name).join(", ") || "none"}`);
-  } else if (hasConfiguredAiTools(mexDir)) {
-    selectedTools = configuredTools;
-    // A scaffold orphaned by the old skip lands here, not in the menu
-    // branch: it is populated and its aiTools are saved. Link on this path
-    // too, or rerunning setup could never repair the installs that need it.
-    anchorNotes = ensureToolAnchors(projectRoot, templatesDir, selectedTools, dryRun);
-    info(`Using configured AI tools: ${selectedTools.map((tool) => AI_TOOLS[tool].name).join(", ") || "none"}`);
-  } else {
-    const rl = createInterface({ input: stdin, output: stdout });
-    try {
-      const selection = await selectToolConfig(rl, projectRoot, templatesDir, dryRun);
-      selectedTools = selection.tools;
-      anchorNotes = selection.anchorNotes;
-    } finally {
-      rl.close();
-    }
-  }
-  console.log();
-
-  const selectedAgentClients = selectedTools.filter(
-    (tool): tool is AgentSkillClient => tool === "claude" || tool === "codex",
-  );
-  if (selectedAgentClients.length > 0) {
-    header("Installing official MEX agent skills...");
-    console.log();
-    const agentAssets = installSetupAgentAssets({
-      projectRoot,
-      selectedTools,
-      dryRun,
-      checkIgnored: mode === "code-repo",
-    })!;
-    renderAgentAssetsReport(agentAssets);
-    console.log();
-    const sessionSummary = `a new ${formatAgentClientList(agentAssets.clients)} session `
-      + "to guarantee the new skills and project instructions are loaded.";
-    if (agentAssets.conflicted) {
-      throw new Error("Official MEX agent assets have conflicts. Resolve the warnings above and rerun setup or mex skills sync.");
-    } else if (dryRun) {
-      info(`After applying this setup, start ${sessionSummary}`);
-    } else {
-      info(`Start ${sessionSummary}`);
-    }
-    console.log();
-  }
-
-  // Mint a stable scaffold identity. Independent of tool selection so a setup
-  // that picks no AI tool still gets a scaffold_id written to config.json.
-  if (!dryRun) {
-    const identity = ensureScaffoldIdentity(mexDir, projectRoot);
-    if (readScaffoldId(mexDir) !== identity.scaffold_id) {
-      throw new Error("Could not persist .mex/config.json. Fix its permissions or contents and rerun setup.");
-    }
-  }
-
-  // ── Step 4: Run scanner (if not fresh) ──
-
-  let scannerBrief: string | null = null;
-
-  if (mode === "code-repo" && state !== "fresh") {
-    info("Scanning codebase...");
-    scannerBrief = await scanSetupCodebase(projectRoot, mexDir);
-    if (scannerBrief) ok("Pre-analysis complete — AI will reason from brief instead of exploring");
-    else warn("Scanner failed — AI will explore the filesystem directly");
-  }
-
-  if (mode === "code-repo" && !dryRun) {
-    info("Building code graph...");
-    await buildSetupGraph(projectRoot);
-    ok("Code graph ready");
-  }
-
-  const prompt = await buildSetupPopulationPrompt(mode, state, scannerBrief);
-
-  // ── Step 6: Run or print ──
-
-  if (dryRun) {
-    header("Would run population prompt (dry run — skipping)");
-    console.log();
-    ok("Done (dry run).");
-    return;
-  }
-
-  let populationFinished = scaffoldPopulatedAtStart;
-  if (populationFinished) {
-    header("Finishing setup from the existing populated scaffold...");
-    console.log();
-  } else {
-    header("Launching an agent to populate the scaffold...");
-    console.log();
-    info("The first selected available Claude Code or Codex CLI will run in the project root.");
-    console.log();
-    const launched = launchSetupPopulation(selectedTools, prompt, projectRoot);
-    if (launched.completed) {
-      ok(`${AI_TOOLS[launched.tool!].name} finished the population session`);
-      populationFinished = isScaffoldPopulated(mexDir);
-      if (!populationFinished) {
-        warn("The agent exited successfully, but required scaffold placeholders remain.");
-      }
-    } else if (launched.tool !== null) {
-      warn(`${AI_TOOLS[launched.tool].name} did not complete population.`);
-    }
-  }
-
-  if (!populationFinished) {
-    header("Almost done. One more step — populate the scaffold.");
-    console.log();
-    info("Paste the prompt below into your AI tool.");
-    info("The agent will read your codebase and fill every scaffold file.");
-    printPromptForManualPaste(prompt);
-    populationFinished = yes ? isScaffoldPopulated(mexDir) : await confirmPopulationFinished(mexDir);
-  }
-
-  if (!populationFinished || !isScaffoldPopulated(mexDir)) {
-    console.log();
-    info("Setup paused at population. After the agent finishes, rerun `mex setup --cli` to finalize Graph and Wiki readiness.");
-    // The anchors were written before population, so an unlinked one is just
-    // as true on this path -- and this is the last output the user sees.
-    printAnchorNotes(anchorNotes);
-    return;
-  }
-
-  if (mode === "code-repo") {
-    await finalizeCodeRepoSetup(projectRoot, mexDir);
-    console.log();
-    ok("Graph and Wiki are ready. Setup is ready to commit.");
-    printCommitCheckpoint(selectedTools);
-  } else {
-    console.log();
-    ok("Setup complete.");
-  }
+export interface SetupRunResult {
+  outcome: "complete" | "paused" | "cancelled" | "failed" | "dry-run";
+  message: string;
+  /** 2 is a resumable pause; 130/143 indicate cancellation. */
+  exitCode: number;
+}
 
-  printAnchorNotes(anchorNotes);
-  if (yes) return;
-  await promptGlobalInstall();
-  if (process.exitCode === 130 || process.exitCode === 143) return;
-  await promptSetupContact();
+export async function runSetup(opts: SetupRunOptions = {}): Promise<SetupRunResult> {
+  const { runTerminalSetup } = await import("./terminal.js");
+  return runTerminalSetup(opts);
 }
 
 /** Parse `--tool` values for a non-interactive setup; unknown names are an error. */
@@ -513,85 +262,6 @@ const TOOL_CHOICE_MAP: Record<string, AiTool> = {
   "6": "codex",
 };
 
-async function selectToolConfig(
-  rl: ReturnType<typeof createInterface>,
-  projectRoot: string,
-  templatesDir: string,
-  dryRun: boolean,
-): Promise<{ tools: AiTool[]; anchorNotes: string[] }> {
-  header("Which AI tool do you use?");
-  console.log();
-  console.log("  1) Claude Code");
-  console.log("  2) Cursor");
-  console.log("  3) Windsurf");
-  console.log("  4) GitHub Copilot");
-  console.log("  5) OpenCode");
-  console.log("  6) Codex (OpenAI)");
-  console.log("  7) Multiple (select next)");
-  console.log("  8) None / skip");
-  console.log();
-
-  const choice = (await rl.question("Choice [1-8] (default: 1): ")).trim() || "1";
-
-  const selectedTools: AiTool[] = [];
-
-  const copyConfig = (key: string) => {
-    const tool = TOOL_CHOICE_MAP[key];
-    if (!tool) return;
-    selectedTools.push(tool);
-  };
-
-  switch (choice) {
-    case "1":
-    case "2":
-    case "3":
-    case "4":
-    case "5":
-    case "6":
-      copyConfig(choice);
-      break;
-    case "7": {
-      const multi = (await rl.question("Enter tool numbers separated by spaces (e.g. 1 2 5): ")).trim();
-      for (const c of multi.split(/\s+/)) {
-        copyConfig(c);
-      }
-      break;
-    }
-    case "8":
-      info("Skipped tool config — AGENTS.md in .mex/ works with any tool that can read files");
-      break;
-    default:
-      warn("Unknown choice, skipping tool config");
-      break;
-  }
-
-  const anchorNotes = ensureToolAnchors(projectRoot, templatesDir, selectedTools, dryRun);
-
-  // Persist tool selection
-  if (!dryRun) {
-    const mexDir = resolve(projectRoot, ".mex");
-    saveAiTools(mexDir, selectedTools);
-  }
-
-  return { tools: [...new Set(selectedTools)], anchorNotes };
-}
-
-function renderAgentAssetsReport(report: AgentAssetsReport): void {
-  for (const action of report.actions) {
-    if (action.action === "conflict") continue;
-    if (action.action === "noop") info(action.message);
-    else ok(action.message);
-    if (report.dryRun) {
-      const preview = renderInstructionChangePreview(action);
-      if (preview !== null) console.log(preview);
-    }
-  }
-  for (const warning of report.warnings) {
-    warn(warning.message);
-    if (warning.resolution) info(warning.resolution);
-  }
-}
-
 export interface InstallSetupAgentAssetsOptions {
   projectRoot: string;
   selectedTools: readonly AiTool[];
@@ -624,51 +294,13 @@ export function installSetupAgentAssets(
   });
 }
 
-function formatAgentClientList(clients: readonly AgentSkillClient[]): string {
-  const labels = [...new Set(clients)].map((client) => (
-    client === "claude" ? "Claude Code" : "Codex"
-  ));
-  if (labels.length === 1) return labels[0]!;
-  return `${labels.slice(0, -1).join(", ")} and ${labels.at(-1)}`;
-}
-
-function printPromptForManualPaste(prompt: string): void {
-  console.log();
-  console.log("─────────────────── COPY BELOW THIS LINE ───────────────────");
-  console.log();
-  console.log(prompt);
-  console.log();
-  console.log("─────────────────── COPY ABOVE THIS LINE ───────────────────");
-  console.log();
-  ok("Paste the prompt above into your agent to populate the scaffold.");
-}
-
-async function confirmPopulationFinished(mexDir: string): Promise<boolean> {
-  if (!stdin.isTTY) return false;
-  const rl = createInterface({ input: stdin, output: stdout });
-  try {
-    console.log();
-    info("After the agent finishes populating, return here to finish setup.");
-    const answer = (await rl.question("  Has population finished? [y/N] ")).trim().toLowerCase();
-    if (answer !== "y" && answer !== "yes") return false;
-    if (!isScaffoldPopulated(mexDir)) {
-      warn("Required placeholders remain in the .mex scaffold files.");
-      return false;
-    }
-    return true;
-  } finally {
-    rl.close();
-  }
-}
-
 /**
- * A finalization failure whose message is composed here from MEX-authored text,
- * relative scaffold paths, and scaffold-authored node ids — never from arbitrary
- * exceptions — so the Hub may show it instead of a generic failure.
+ * Expected finalization failure. The Hub uses its authored userMessage;
+ * message may retain fuller terminal diagnostics without exposing them there.
  */
-export class SetupFinalizationError extends Error {
-  constructor(message: string) {
-    super(message);
+export class SetupFinalizationError extends SetupError {
+  constructor(message: string, options?: ErrorOptions & { userMessage?: string }) {
+    super(message, options);
     this.name = "SetupFinalizationError";
   }
 }
@@ -677,7 +309,14 @@ export class SetupFinalizationError extends Error {
 const FINALIZATION_DETAIL_LIMIT = 2;
 const FINALIZATION_DETAIL_CHARS = 140;
 
-export async function finalizeCodeRepoSetup(projectRoot: string, mexDir: string): Promise<void> {
+export async function finalizeCodeRepoSetup(projectRoot: string, mexDir: string, options: {
+  signal?: AbortSignal;
+  onMessage?: (message: string) => void;
+} = {}): Promise<void> {
+  const info = options.onMessage ?? ((message: string) => console.log(message));
+  const warn = info;
+  const ok = info;
+  throwIfSetupAborted(options.signal);
   info("Capturing grounding baselines...");
   const captureWarnings: string[] = [];
   let result: GroundingBaselineCaptureResult;
@@ -694,9 +333,12 @@ export async function finalizeCodeRepoSetup(projectRoot: string, mexDir: string)
       },
     );
   } catch (error) {
+    const expected = classifySetupMaintenanceError(error, "grounding");
+    if (expected) throw expected;
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Grounding finalization failed: ${message}. Rerun mex setup after fixing it.`);
   }
+  throwIfSetupAborted(options.signal);
   try {
     assertGroundingCaptureReady(result);
   } catch (error) {
@@ -710,18 +352,27 @@ export async function finalizeCodeRepoSetup(projectRoot: string, mexDir: string)
   else info("No authored grounding baselines needed capture");
 
   const config = findConfig(projectRoot);
-  const wiki = await finalizeSetupWiki({
-    projectRoot,
-    scaffoldRoot: mexDir,
-    exclude: config.wiki?.exclude,
-    readOnly: config.wiki?.readOnly,
-    onProgress: info,
-    onWarning: warn,
-  });
+  let wiki: Awaited<ReturnType<typeof finalizeSetupWiki>>;
+  try {
+    wiki = await finalizeSetupWiki({
+      projectRoot,
+      scaffoldRoot: mexDir,
+      exclude: config.wiki?.exclude,
+      readOnly: config.wiki?.readOnly,
+      signal: options.signal,
+      onProgress: info,
+      onWarning: warn,
+    });
+  } catch (error) {
+    throwIfSetupAborted(options.signal);
+    throw classifySetupMaintenanceError(error, "wiki") ?? error;
+  }
+  throwIfSetupAborted(options.signal);
   if (!wiki.ready) {
     const codes = [...new Set(wiki.diagnostics.map((entry) => entry.code))].join(", ");
     const suffix = codes.length === 0 ? "" : ` (${codes})`;
-    throw new SetupFinalizationError(`${wiki.reason ?? "Wiki setup did not finish."}${suffix} Fix the issue and rerun mex setup --cli.`);
+    const userMessage = setupWikiFailureMessage(wiki.stage, wiki.diagnostics);
+    throw new SetupFinalizationError(`${wiki.reason ?? "Wiki setup did not finish."}${suffix} ${userMessage}`, { userMessage });
   }
   ok(`Wiki ready with ${wiki.indexedEntities} indexed entit${wiki.indexedEntities === 1 ? "y" : "ies"}`);
 }
@@ -733,135 +384,3 @@ export function assertGroundingCaptureReady(result: GroundingBaselineCaptureResu
     );
   }
 }
-
-/**
- * Repeat anchors that could not be linked automatically.
- *
- * The warning at the moment of the decision scrolls past behind population
- * output and the readiness report, and the whole failure mode of #106 is that
- * the user never learns the scaffold is not being loaded. Saying it again at
- * the end is the last point where it is still in front of them.
- */
-function printAnchorNotes(notes: readonly string[]): void {
-  if (notes.length === 0) return;
-  console.log();
-  header("Action needed: these files do not point at the scaffold yet");
-  console.log();
-  for (const note of notes) warn(note);
-  console.log();
-  info("Until one always-loaded file names `.mex/`, your agent will not read the scaffold.");
-  info("Run `mex check` after fixing them to confirm.");
-}
-
-function printCommitCheckpoint(selectedTools: readonly AiTool[]): void {
-  header("Commit the canonical MEX setup before opening Hub");
-  console.log();
-  info("Review the scoped files, then commit them. MEX will not stage or commit automatically.");
-  for (const command of setupCommitCheckpointCommands(selectedTools)) {
-    console.log(`    ${command}`);
-  }
-  console.log();
-  info("After that commit, start Hub with `mex hub` (or `npx mex-agent hub`).");
-}
-
-async function promptGlobalInstall(): Promise<void> {
-  if (!stdin.isTTY) {
-    printNextSteps(false);
-    return;
-  }
-  const rl = createInterface({ input: stdin, output: stdout });
-  try {
-    header("One more thing");
-    console.log();
-    info("Install mex globally so `mex check` works anywhere?");
-    console.log();
-
-    const answer = (await rl.question("  Install mex globally? [y/N] ")).trim().toLowerCase();
-
-    if (answer === "y" || answer === "yes") {
-      console.log();
-      info("Installing mex-agent globally...");
-      try {
-        const { SetupGlobalInstaller } = await import("./global-install.js");
-        const installer = new SetupGlobalInstaller();
-        const interrupt = () => { process.exitCode = 130; void installer.shutdown(); };
-        const terminate = () => { process.exitCode = 143; void installer.shutdown(); };
-        process.once("SIGINT", interrupt);
-        process.once("SIGTERM", terminate);
-        let result;
-        try { installer.start(); result = await installer.wait(); }
-        finally { process.removeListener("SIGINT", interrupt); process.removeListener("SIGTERM", terminate); }
-        if (result.state !== "succeeded") throw new Error(result.message);
-        console.log();
-        ok(result.message);
-        printNextSteps(true);
-      } catch {
-        console.log();
-        warn("Global install failed. You can retry manually:");
-        console.log(`    npm install -g mex-agent@${VERSION}`);
-        console.log();
-        printNextSteps(false);
-      }
-    } else {
-      console.log();
-      info("No problem. You can always install later:");
-      console.log(`    npm install -g mex-agent@${VERSION}`);
-      console.log();
-      printNextSteps(false);
-    }
-  } finally {
-    rl.close();
-  }
-}
-
-async function promptSetupContact(): Promise<void> {
-  if (!stdin.isTTY) return;
-  const { readContactPreference, rememberContactPreference, submitSetupContact } = await import("./contact.js");
-  if (readContactPreference().status !== "unasked") return;
-  const rl = createInterface({ input: stdin, output: stdout });
-  try {
-    header("Help shape MEX (optional)");
-    info("Leave your email if we may follow up about your experience with MEX. Your details are sent through Web3Forms, separately from usage telemetry.");
-    const answer = (await rl.question("  May we contact you? [y/N] ")).trim().toLowerCase();
-    if (answer !== "y" && answer !== "yes") {
-      await rememberContactPreference({ status: "skipped" });
-      return;
-    }
-    const email = (await rl.question("  Email (leave empty to skip): ")).trim();
-    if (!email) { await rememberContactPreference({ status: "skipped" }); return; }
-    const name = (await rl.question("  Name (optional): ")).trim();
-    const { SetupContactRequestSchema } = await import("@mex/hub-contracts/setup");
-    const parsed = SetupContactRequestSchema.safeParse({ email, name });
-    if (!parsed.success) { warn("The contact details were not valid, so nothing was sent. Setup is complete."); return; }
-    const result = await submitSetupContact(parsed.data);
-    if (result.ok) ok(result.message); else warn(result.message);
-  } catch {
-    warn("The optional contact step could not finish. Setup is complete; you can continue using MEX.");
-  } finally { rl.close(); }
-}
-
-function printNextSteps(globalInstalled: boolean) {
-  header("What's next");
-  console.log();
-  info("Verify — start a fresh session and ask:");
-  console.log('    "Read .mex/ROUTER.md and tell me what you know about this project."');
-  console.log();
-
-  if (globalInstalled) {
-    info("Ongoing commands:");
-    console.log("    mex check              Drift score — are scaffold files still accurate?");
-    console.log("    mex check --quiet      One-liner drift score");
-    console.log("    mex sync               Fix drift — AI updates only what's broken");
-    console.log("    mex watch              Auto-check drift after every commit");
-  } else {
-    info("Ongoing commands (via npx):");
-    console.log(`    npx mex-agent@${VERSION} check                Drift score — are scaffold files still accurate?`);
-    console.log(`    npx mex-agent@${VERSION} check --quiet        One-liner drift score`);
-    console.log(`    npx mex-agent@${VERSION} sync                 Fix drift — AI updates only what's broken`);
-    console.log(`    npx mex-agent@${VERSION} watch                Auto-check drift after every commit`);
-    console.log();
-    info("Or install globally to use the shorter `mex` command:");
-    console.log(`    npm install -g mex-agent@${VERSION}`);
-  }
-  console.log();
-}
diff --git a/src/setup/interactive-population.ts b/src/setup/interactive-population.ts
new file mode 100644
index 00000000..1b9105ce
--- /dev/null
+++ b/src/setup/interactive-population.ts
@@ -0,0 +1,273 @@
+import crossSpawn from "cross-spawn";
+import { execFile, type ChildProcess } from "node:child_process";
+import { buildAgentCommand } from "../agent-command.js";
+import { AI_TOOLS, type AiTool } from "../types.js";
+import { createPopulationSession, type SetupAgentTool } from "./population.js";
+
+const DISCOVERY_TIMEOUT_MS = 5_000;
+const PROCESS_SNAPSHOT_TIMEOUT_MS = 2_000;
+const PROCESS_SNAPSHOT_BYTES = 2 * 1024 * 1024;
+const MAX_OWNED_PROCESSES = 4_096;
+const PROCESS_POLL_MS = 100;
+const TERMINATE_GRACE_MS = 500;
+
+export interface InteractivePopulationResult {
+  readonly tool: SetupAgentTool | null;
+  /** A clean agent exit is not confirmation that setup is complete. */
+  readonly status: "exited" | "failed" | "cancelled" | "unavailable";
+  readonly exitCode: number | null;
+  readonly signal: NodeJS.Signals | null;
+  readonly message?: string;
+}
+
+interface ProcessIdentity {
+  readonly pid: number;
+  readonly parentPid: number;
+  readonly started: string;
+}
+
+export interface InteractivePopulationOptions {
+  readonly selectedTools: readonly AiTool[];
+  readonly prompt: string;
+  readonly projectRoot: string;
+  readonly signal?: AbortSignal;
+  /** Local subprocess test seams, never accepted from a setup request. */
+  readonly __internal?: {
+    readonly isAvailable?: (command: string) => Promise<boolean>;
+    readonly spawn?: typeof crossSpawn;
+    readonly snapshot?: () => Promise<readonly ProcessIdentity[] | null>;
+    readonly kill?: (pid: number, signal: NodeJS.Signals) => void;
+  };
+}
+
+/** Hand the existing terminal to the agent; the caller suspends and resumes its UI. */
+export async function launchInteractiveSetupPopulation(
+  options: InteractivePopulationOptions,
+): Promise<InteractivePopulationResult> {
+  let tool: SetupAgentTool | null = null;
+  const outcome = (status: InteractivePopulationResult["status"], message: string): InteractivePopulationResult => ({
+    tool, status, exitCode: null, signal: null, message,
+  });
+  if (options.signal?.aborted) return outcome("cancelled", "AI population was cancelled. You can resume setup when ready.");
+
+  for (const candidate of options.selectedTools) {
+    if (candidate !== "claude" && candidate !== "codex") continue;
+    let available: boolean;
+    try {
+      available = await (options.__internal?.isAvailable ?? ((command) => isAvailable(command, options.signal)))(AI_TOOLS[candidate].cli!);
+    } catch {
+      return outcome(options.signal?.aborted ? "cancelled" : "failed", options.signal?.aborted
+        ? "AI population was cancelled. You can resume setup when ready."
+        : "MEX could not check the selected AI CLI. Check its installation and PATH, then resume setup.");
+    }
+    if (options.signal?.aborted) return outcome("cancelled", "AI population was cancelled. You can resume setup when ready.");
+    if (available) { tool = candidate; break; }
+  }
+  if (!tool) return outcome("unavailable", "No selected interactive AI CLI is available. Install and sign in to a selected CLI, then resume setup.");
+
+  let session: ReturnType<typeof createPopulationSession>;
+  try {
+    session = createPopulationSession(options.prompt, options.projectRoot);
+  } catch {
+    return outcome("failed", "The private setup population prompt could not be prepared. Check .mex/local permissions and available disk space, then resume setup.");
+  }
+
+  let result: InteractivePopulationResult;
+  try {
+    result = await runInteractiveAgent(tool, session.instruction, session.root, options);
+  } finally {
+    // Cleanup happens only after process cleanup, including cancellation escalation.
+    try { session.cleanup(); }
+    catch {
+      result = outcome(options.signal?.aborted ? "cancelled" : "failed", "The private setup prompt could not be removed. Check .mex/local permissions and remove its setup-population folder before resuming setup.");
+    }
+  }
+  return result!;
+}
+
+function isAvailable(command: string, signal?: AbortSignal): Promise<boolean> {
+  return new Promise((resolve) => {
+    const child = crossSpawn(process.platform === "win32" ? "where" : "which", [command], {
+      stdio: "ignore", windowsHide: true, timeout: DISCOVERY_TIMEOUT_MS, signal,
+    });
+    child.once("error", () => resolve(false));
+    child.once("close", (code) => resolve(code === 0));
+  });
+}
+
+function runInteractiveAgent(
+  tool: SetupAgentTool,
+  instruction: string,
+  cwd: string,
+  options: InteractivePopulationOptions,
+): Promise<InteractivePopulationResult> {
+  const name = AI_TOOLS[tool].name;
+  const cancelled = (): InteractivePopulationResult => ({ tool, status: "cancelled", exitCode: null, signal: null,
+    message: "AI population was cancelled. You can resume setup when ready." });
+  if (options.signal?.aborted) return Promise.resolve(cancelled());
+  const invocation = buildAgentCommand(tool, instruction, "interactive")!;
+  return new Promise((resolve) => {
+    let child: ChildProcess;
+    try {
+      child = (options.__internal?.spawn ?? crossSpawn)(invocation.command, invocation.args, {
+        cwd,
+        stdio: "inherit",
+        // A detached POSIX child cannot read the foreground terminal normally.
+        // Never signal its process group: it shares that group with MEX.
+        detached: false,
+      });
+    } catch {
+      resolve({ tool, status: "failed", exitCode: null, signal: null,
+        message: `${name} could not start. Check its installation and resume setup.` });
+      return;
+    }
+
+    let launchFailed = false;
+    let cleanupVerified = true;
+    let wasCancelled = false;
+    let closed = false;
+    let cleanup: Promise<void> | undefined;
+    const owner = ownProcessTree(child, options);
+    const startCleanup = () => owner.stop().then((verified) => { cleanupVerified = verified; }).catch(() => {
+      // A cleanup error must not strand the UI waiting for this launch result.
+      cleanupVerified = false;
+      try { child.kill("SIGKILL"); } catch { /* Already gone. */ }
+    });
+    const stop = () => {
+      if (closed) return;
+      wasCancelled = true;
+      cleanup ??= startCleanup();
+    };
+    options.signal?.addEventListener("abort", stop, { once: true });
+    child.once("error", () => { launchFailed = true; cleanup ??= startCleanup(); });
+    child.once("exit", () => { cleanup ??= startCleanup(); });
+    child.once("close", async (exitCode, signal) => {
+      closed = true;
+      options.signal?.removeEventListener("abort", stop);
+      cleanup ??= startCleanup();
+      await cleanup;
+      const cleanupWarning = "MEX could not verify that the agent's helper processes stopped. Close any remaining agent sessions before resuming setup.";
+      if (wasCancelled || options.signal?.aborted || signal === "SIGINT") resolve({ ...cancelled(), exitCode, signal,
+        ...(!cleanupVerified ? { message: `AI population was cancelled. ${cleanupWarning}` } : {}) });
+      else if (launchFailed) resolve({ tool, status: "failed", exitCode, signal,
+        message: `${name} could not start. Check its installation and resume setup.` });
+      else if (!cleanupVerified) resolve({ tool, status: "failed", exitCode, signal, message: cleanupWarning });
+      else if (exitCode !== 0 || signal) resolve({ tool, status: "failed", exitCode, signal,
+        message: `${name} stopped before a clean exit. Review its terminal output and resume setup.` });
+      else resolve({ tool, status: "exited", exitCode, signal });
+    });
+    if (options.signal?.aborted) stop();
+  });
+}
+
+/**
+ * Inherited terminal access precludes the detached group used by headless setup.
+ * Track only this child's observed descendants and revalidate identities before
+ * signalling individual PIDs. Never adopt siblings or signal the foreground group.
+ * A descendant that daemonizes between snapshots cannot safely be rediscovered.
+ */
+function ownProcessTree(child: ChildProcess, options: InteractivePopulationOptions): { stop: () => Promise<boolean> } {
+  const pid = child.pid;
+  const snapshot = options.__internal?.snapshot ?? snapshotProcesses;
+  const kill = options.__internal?.kill ?? ((target, signal) => { process.kill(target, signal); });
+  const owned = new Map<number, ProcessIdentity>();
+  let exited = false;
+  let stopping = false;
+  let refresh: Promise<boolean> | undefined;
+  child.once("exit", () => { exited = true; });
+
+  const capture = (): Promise<boolean> => {
+    if (refresh) return refresh;
+    refresh = (async () => {
+      let processes: readonly ProcessIdentity[] | null;
+      try { processes = await snapshot(); } catch { return false; }
+      if (!processes) return false;
+      const byPid = new Map(processes.map((entry) => [entry.pid, entry]));
+      for (const [target, identity] of owned) {
+        if (byPid.get(target)?.started !== identity.started) owned.delete(target);
+      }
+      const root = pid ? byPid.get(pid) : undefined;
+      if (!exited && root && !owned.has(root.pid)) owned.set(root.pid, root);
+      // Reparented descendants remain owned only while their start identity matches.
+      const children = new Map<number, ProcessIdentity[]>();
+      for (const entry of processes) {
+        const siblings = children.get(entry.parentPid) ?? [];
+        siblings.push(entry);
+        children.set(entry.parentPid, siblings);
+      }
+      const parents = [...owned.keys()];
+      for (let index = 0; index < parents.length && owned.size < MAX_OWNED_PROCESSES; index++) {
+        for (const entry of children.get(parents[index]!) ?? []) {
+          if (owned.size >= MAX_OWNED_PROCESSES) break;
+          if (owned.has(entry.pid) || entry.pid === process.pid) continue;
+          owned.set(entry.pid, entry);
+          parents.push(entry.pid);
+        }
+      }
+      return owned.size < MAX_OWNED_PROCESSES;
+    })().finally(() => { refresh = undefined; });
+    return refresh;
+  };
+  const timer = process.platform !== "win32" && pid ? setInterval(() => { if (!stopping) void capture(); }, PROCESS_POLL_MS) : undefined;
+  timer?.unref();
+  if (process.platform !== "win32" && pid) void capture();
+
+  const signalOwned = async (signal: NodeJS.Signals) => {
+    const refreshed = await capture();
+    let verified = refreshed;
+    // Descendants first; parents can reap them before they themselves stop.
+    for (const target of refreshed ? [...owned.keys()].reverse() : []) {
+      if (target === pid || target === process.pid) continue;
+      try { kill(target, signal); }
+      catch (error) { if ((error as NodeJS.ErrnoException)?.code !== "ESRCH") verified = false; }
+    }
+    if (!exited) {
+      try { if (!child.kill(signal)) verified = false; }
+      catch (error) { if ((error as NodeJS.ErrnoException)?.code !== "ESRCH") verified = false; }
+    }
+    return verified;
+  };
+  return {
+    stop: async () => {
+      stopping = true;
+      if (timer) clearInterval(timer);
+      if (!pid) return true;
+      if (process.platform === "win32") {
+        return exited || await stopWindowsTree(child);
+      }
+      const terminated = await signalOwned("SIGTERM");
+      if (terminated && exited && owned.size === 0) return true;
+      await new Promise((resolve) => setTimeout(resolve, TERMINATE_GRACE_MS));
+      return await signalOwned("SIGKILL") && terminated;
+    },
+  };
+}
+
+function snapshotProcesses(): Promise<readonly ProcessIdentity[] | null> {
+  return new Promise((resolve) => {
+    execFile("ps", ["-A", "-o", "pid=,ppid=,lstart="], {
+      encoding: "utf8", env: { ...process.env, LC_ALL: "C" },
+      timeout: PROCESS_SNAPSHOT_TIMEOUT_MS, maxBuffer: PROCESS_SNAPSHOT_BYTES, killSignal: "SIGKILL",
+    }, (error, stdout) => {
+      if (error) { resolve(null); return; }
+      const processes: ProcessIdentity[] = [];
+      for (const line of stdout.split("\n")) {
+        const match = /^\s*(\d+)\s+(\d+)\s+(.+?)\s*$/u.exec(line);
+        if (match) processes.push({ pid: Number(match[1]), parentPid: Number(match[2]), started: match[3]! });
+      }
+      resolve(processes);
+    });
+  });
+}
+
+function stopWindowsTree(child: ChildProcess): Promise<boolean> {
+  return new Promise((resolve) => {
+    // Reuse the headless ownership strategy for npm .cmd wrappers on Windows.
+    const killer = crossSpawn("taskkill", ["/pid", String(child.pid), "/T", "/F"], {
+      stdio: "ignore", windowsHide: true, timeout: DISCOVERY_TIMEOUT_MS,
+    });
+    const done = (verified: boolean) => { try { child.kill("SIGKILL"); } catch { /* Already gone. */ } resolve(verified); };
+    killer.once("error", () => done(false));
+    killer.once("close", (code) => done(code === 0));
+  });
+}
diff --git a/src/setup/maintenance-errors.ts b/src/setup/maintenance-errors.ts
new file mode 100644
index 00000000..2243a276
--- /dev/null
+++ b/src/setup/maintenance-errors.ts
@@ -0,0 +1,157 @@
+import { GraphCandidateProcessError } from "../graph/candidate-process.js";
+import { IndexInUseError, IndexPathError } from "../wiki/index/dbfile.js";
+import { WikiSourceReadError } from "../wiki/index/source-read.js";
+import { WIKI_DIAGNOSTICS, type WikiDiagnostic } from "../wiki/model/diagnostic.js";
+import { SetupError, classifySetupFileSystemError } from "./errors.js";
+import type { SetupWikiFinalizationStage } from "./wiki-finalize.js";
+
+type SetupMaintenancePhase = "graph" | "grounding" | "wiki";
+
+const PHASE_LABELS: Record<SetupMaintenancePhase, string> = {
+  graph: "Code graph setup",
+  grounding: "Grounding finalization",
+  wiki: "Wiki finalization",
+};
+
+/** Closed codes select authored advice; exception text remains terminal-only. */
+const RECOVERY_BY_CODE: Readonly<Record<string, string>> = {
+  GRAPH_INDEX_MISSING: "The code graph is missing. Run `mex graph rebuild`, then retry setup.",
+  GRAPH_INDEX_NOT_REFRESHABLE: "The code graph needs a rebuild. Run `mex graph rebuild`, resolve any reported problems, then retry setup.",
+  GRAPH_INDEX_NOT_REPAIRABLE: "The code graph cannot be repaired safely. Run `mex graph rebuild`, then retry setup.",
+  GRAPH_MAINTENANCE_LOCKED: "Another graph operation is active. Wait for it to finish, then retry setup.",
+  GRAPH_MAINTENANCE_GATE_STALE: "An interrupted graph operation left .mex/graph.db.lock.gate behind. Verify no MEX process is running before removing that gate, then retry setup.",
+  GRAPH_MAINTENANCE_CANCELLED: "Graph maintenance was interrupted. Retry setup when ready.",
+  GRAPH_MAINTENANCE_PATH_UNSAFE: "A graph database or maintenance path is unsafe. Check .mex for redirected or conflicting paths, correct them, then retry setup.",
+  GRAPH_MAINTENANCE_RACE: "The graph or project files changed during maintenance. Wait for other writers to finish, then retry setup.",
+  GRAPH_CANDIDATE_INVALID: "The rebuilt graph failed validation. Run `mex graph rebuild` to inspect its diagnostics, resolve the reported problems, then retry setup.",
+  GRAPH_PUBLICATION_FAILED: "The graph could not be published safely and may need recovery. Keep any .mex/graph.db recovery files and inspect `mex graph status` before retrying setup.",
+  GRAPH_SOURCE_STAGING_FAILED: "Source files could not be read or parsed safely. Check `mex graph rebuild` diagnostics, correct the reported files, then retry setup.",
+  WIKI_MAINTENANCE_LOCKED: "Another Wiki operation is active. Wait for it to finish, then retry setup.",
+  WIKI_CORPUS_LIMIT_EXCEEDED: "The Wiki exceeds a file, directory, or size safety limit. Reduce oversized content or exclude unrelated files using wiki.exclude in .mex/config.json, then retry setup.",
+  WIKI_INDEX_RECOVERY_REQUIRED: "The Wiki index could not be published and recovery files were retained. Keep the .mex/wiki.db recovery files and inspect them before retrying setup.",
+  OPERATION_INTERRUPTED: "Wiki files changed or maintenance was interrupted. Wait for other writers to finish, then retry setup.",
+};
+
+/** Expected maintenance failures only. Unknown exceptions retain the Hub fallback. */
+export function classifySetupMaintenanceError(
+  error: unknown,
+  phase: SetupMaintenancePhase,
+): SetupError | null {
+  if (error instanceof SetupError) return error;
+  if (!(error instanceof Error)) return null;
+  const label = PHASE_LABELS[phase];
+  let recovery: string | undefined;
+  if ("code" in error && typeof error.code === "string" && Object.hasOwn(RECOVERY_BY_CODE, error.code)) {
+    recovery = RECOVERY_BY_CODE[error.code];
+  } else if (error instanceof GraphCandidateProcessError) {
+    recovery = error.category === "compatibility"
+      ? "The graph worker could not use the current index. Run `mex graph rebuild` with the current MEX installation, then retry setup."
+      : error.category === "staging"
+        ? RECOVERY_BY_CODE.GRAPH_SOURCE_STAGING_FAILED
+        : error.category === "unsafe"
+          ? RECOVERY_BY_CODE.GRAPH_MAINTENANCE_PATH_UNSAFE
+          : error.category === "cancelled"
+            ? RECOVERY_BY_CODE.GRAPH_MAINTENANCE_CANCELLED
+            : graphWorkerRecovery(error);
+  } else if (error instanceof IndexInUseError) {
+    recovery = "The Wiki index is busy or changed during publication. Close other processes using it, then retry setup.";
+  } else if (error instanceof IndexPathError || error instanceof WikiSourceReadError) {
+    recovery = "A Wiki file or index path could not be read safely. Check .mex for unreadable, redirected, or conflicting paths, correct them, then retry setup.";
+  } else {
+    recovery = sqliteRecovery(error);
+  }
+  if (recovery !== undefined) {
+    return new SetupError(`${label} failed: ${error.message}`, {
+      cause: error,
+      userMessage: `${label} could not finish. ${recovery}`,
+    });
+  }
+  return classifySetupFileSystemError(error, `${label} could not finish.`);
+}
+
+function graphWorkerRecovery(error: GraphCandidateProcessError): string {
+  if (error.diagnostic?.resourceFailure === "heap-limit") {
+    return "The graph worker reached Node's JavaScript heap limit. Retry setup with a larger heap using NODE_OPTIONS=--max-old-space-size=<MB>, sized for your available memory.";
+  }
+  switch (error.diagnostic?.reason) {
+    case "entrypoint-missing":
+      return "The graph worker is missing from this MEX installation. Rebuild MEX if running from source, or reinstall it, then retry setup.";
+    case "spawn":
+      return "The graph worker could not start. Check the Node runtime and execution permissions, then retry setup.";
+    case "startup-timeout":
+      return "The graph worker did not start before its startup deadline. Retry setup; if this repeats, check the Node runtime and MEX installation.";
+    case "build-timeout":
+      return "The graph worker exceeded its build time limit. Review the last reported phase and worker diagnostics before retrying setup.";
+    case "protocol":
+      return "The graph worker returned an invalid response. Rebuild MEX if running from source, or reinstall it, then retry setup.";
+    case "ipc-disconnected":
+      return "Setup lost communication with the graph worker. Check the worker diagnostics, then retry setup.";
+    case "observer":
+      return "Setup could not process a graph worker update. Retry setup; if this repeats, report the terminal diagnostics.";
+    case "exit": {
+      const diagnostic = error.diagnostic;
+      const status = diagnostic.signal
+        ? "The graph worker was terminated by a signal."
+        : Number.isSafeInteger(diagnostic.exitCode) && diagnostic.exitCode !== null
+          ? `The graph worker exited with status ${diagnostic.exitCode}.`
+          : "The graph worker exited without completing the build.";
+      return `${status} Check the worker diagnostics, then retry setup.`;
+    }
+    default:
+      return "The graph worker could not complete the build. Check the worker diagnostics or run `mex graph rebuild`, then retry setup.";
+  }
+}
+
+function sqliteRecovery(error: Error): string | undefined {
+  if (!("code" in error) || typeof error.code !== "string") return undefined;
+  const code = error.code;
+  // node:sqlite reports numeric SQLite result codes behind ERR_SQLITE_ERROR.
+  // The low byte identifies the primary result, including extended codes.
+  const primary = code === "ERR_SQLITE_ERROR" && "errcode" in error
+    && typeof error.errcode === "number" && Number.isSafeInteger(error.errcode) && error.errcode >= 0
+    ? error.errcode & 0xff : undefined;
+  if (["SQLITE_BUSY", "SQLITE_LOCKED", "ERR_SQLITE_BUSY", "ERR_SQLITE_LOCKED"].includes(code)
+    || primary === 5 || primary === 6) {
+    return "The local database is busy. Wait for other MEX or database processes to finish, then retry setup.";
+  }
+  if (["SQLITE_FULL", "ERR_SQLITE_FULL"].includes(code) || primary === 13) {
+    return "The local database ran out of storage. Free disk space or increase the quota, then retry setup.";
+  }
+  if (["SQLITE_READONLY", "ERR_SQLITE_READONLY"].includes(code) || primary === 8) {
+    return "The local database is read-only. Check the checkout and database permissions, then retry setup.";
+  }
+  return undefined;
+}
+
+/** Select registry-owned remediation, never a diagnostic's raw message or override. */
+export function setupWikiFailureMessage(
+  stage: SetupWikiFinalizationStage,
+  diagnostics: readonly WikiDiagnostic[],
+): string {
+  const label = stage === "plan" ? "Wiki migration planning"
+    : stage === "migration" ? "Wiki migration"
+      : stage === "index" ? "Wiki indexing" : "Wiki validation";
+  const diagnostic = diagnostics.find((entry) => entry.severity === "error" && Object.hasOwn(WIKI_DIAGNOSTICS, entry.code));
+  if (!diagnostic) return `${label} could not finish. Review the .mex files and retry setup after correcting the problem.`;
+  const location = safeScaffoldPath(diagnostic.file ?? diagnostic.location?.file);
+  const subject = `${diagnostic.code}${location === null ? "" : ` in ${location}`}`;
+  const remediation = diagnostic.code === "WRITE_SCOPE_VIOLATION"
+    ? "Check the affected file and wiki.readOnly rules in .mex/config.json. Preserve protected files or intentionally update their configuration."
+    : diagnostic.code === "WIKI_INDEX_MISSING"
+      ? "The Wiki index is missing. Setup can rebuild it on retry."
+    : diagnostic.code === "WIKI_INDEX_REBUILD_REQUIRED"
+      ? "Close other processes using the Wiki index before retrying. If the problem persists, run `mex wiki rebuild-index` to inspect its diagnostics."
+      : WIKI_DIAGNOSTICS[diagnostic.code].remediation;
+  const retry = " Retry setup after correcting this problem.";
+  const detail = `${label} could not finish (${subject}). ${remediation}`;
+  const available = 512 - retry.length;
+  return `${detail.length > available ? `${detail.slice(0, available - 1)}…` : detail}${retry}`;
+}
+
+function safeScaffoldPath(path: string | undefined): string | null {
+  if (path === undefined || path.length > 160 || /[\u0000-\u001f\u007f]/u.test(path)) return null;
+  const normalized = path.replaceAll("\\", "/");
+  if (normalized.startsWith("/") || /^[a-z]:/iu.test(normalized)
+    || normalized.split("/").some((part) => part === "" || part === "." || part === "..")) return null;
+  return normalized.startsWith(".mex/") ? normalized : `.mex/${normalized}`;
+}
diff --git a/src/setup/phases.ts b/src/setup/phases.ts
index 268ea103..660085b2 100644
--- a/src/setup/phases.ts
+++ b/src/setup/phases.ts
@@ -3,6 +3,9 @@ import { resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadConfiguredSetupMode, saveConfiguredSetupMode } from "../config.js";
 import { ensureSetupIgnoreProtection, renderSetupIgnoreProtection, verifySetupIgnoreProtection } from "./ignore.js";
+import { SetupError, classifySetupFileSystemError } from "./errors.js";
+import { classifySetupMaintenanceError } from "./maintenance-errors.js";
+import type { GraphMaintenanceProgress } from "../team/contracts/graph.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -46,18 +49,25 @@ export function verifyExistingSetupConfig(mexDir: string): void {
     if (error instanceof Error
       && "code" in error
       && (error as NodeJS.ErrnoException).code === "ENOENT") return;
-    throw new Error("Could not inspect existing .mex/config.json. Fix its permissions before rerunning setup.", {
-      cause: error,
-    });
+    throw classifySetupFileSystemError(error, "Could not inspect .mex/config.json.") ?? new SetupError(
+      "Could not inspect existing .mex/config.json. Fix its permissions before rerunning setup.",
+      { cause: error },
+    );
   }
   if (stats.isSymbolicLink() || !stats.isFile()) {
-    throw new Error("Existing .mex/config.json must be a regular file. Fix it before rerunning setup.");
+    throw new SetupError("Existing .mex/config.json must be a regular file. Fix it before rerunning setup.");
+  }
+  let contents: string;
+  try {
+    contents = readFileSync(path, "utf8");
+  } catch (error) {
+    throw classifySetupFileSystemError(error, "Could not read .mex/config.json.") ?? error;
   }
   try {
-    const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+    const parsed: unknown = JSON.parse(contents);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error();
   } catch {
-    throw new Error("Existing .mex/config.json is not a valid JSON object. Fix it before rerunning setup.");
+    throw new SetupError("Existing .mex/config.json is not a valid JSON object. Fix it before rerunning setup.");
   }
 }
 
@@ -74,15 +84,18 @@ export function setupTemplatesDirectory(): string {
   for (const candidate of candidates) {
     if (existsSync(candidate)) return candidate;
   }
-  throw new Error(
+  throw new SetupError(
     `Templates directory not found. Looked in:\n${candidates.map((path) => `  - ${path}`).join("\n")}\nThe mex-agent package may be corrupted — try reinstalling.`,
+    { userMessage: "MEX setup templates are missing. Reinstall mex-agent, restart the Hub, then retry setup." },
   );
 }
 
 export function normalizeSetupMode(raw: string | undefined): SetupMode {
   const mode = raw ?? "code-repo";
   if (mode === "code-repo" || mode === "agent-memory") return mode;
-  throw new Error(`Unknown setup mode "${mode}". Use code-repo or agent-memory.`);
+  throw new SetupError(`Unknown setup mode "${mode}". Use code-repo or agent-memory.`, {
+    userMessage: "The setup mode is not supported. Choose code-repo or agent-memory, then retry setup.",
+  });
 }
 
 /** Explicit choices override persisted intent; a resume uses the original mode. */
@@ -112,10 +125,21 @@ export function createSetupScaffold(options: {
     const memorySource = resolve(templatesDir, "agent-memory", file);
     const source = mode === "agent-memory" && existsSync(memorySource)
       ? memorySource : resolve(templatesDir, file);
-    const action = ensureScaffoldFile(source, resolve(mexDir, file), dryRun);
+    let action: ScaffoldFileAction;
+    try {
+      action = ensureScaffoldFile(source, resolve(mexDir, file), dryRun);
+    } catch (error) {
+      throw classifySetupFileSystemError(error, `Could not create .mex/${file}.`) ?? error;
+    }
     options.onFile?.(file, action);
   }
-  if (!dryRun) saveConfiguredSetupMode(mexDir, mode);
+  if (!dryRun) {
+    try {
+      saveConfiguredSetupMode(mexDir, mode);
+    } catch (error) {
+      throw classifySetupFileSystemError(error, "Could not save the setup mode in .mex/config.json.") ?? error;
+    }
+  }
 }
 
 /** Scanner failure is optional: both transports fall back to filesystem discovery. */
@@ -133,6 +157,7 @@ export async function scanSetupCodebase(projectRoot: string, mexDir: string): Pr
 export async function buildSetupGraph(projectRoot: string, options: {
   signal?: AbortSignal;
   background?: boolean;
+  onProgress?: (progress: GraphMaintenanceProgress) => void;
 } = {}): Promise<void> {
   throwIfSetupAborted(options.signal);
   try {
@@ -140,9 +165,12 @@ export async function buildSetupGraph(projectRoot: string, options: {
     await rebuildGraph(projectRoot, {
       ...(options.signal === undefined ? {} : { signal: options.signal }),
       ...(options.background ? { candidateExecution: "process" as const } : {}),
+      ...(options.onProgress ? { onProgress: options.onProgress } : {}),
     });
   } catch (error) {
     throwIfSetupAborted(options.signal);
+    const expected = classifySetupMaintenanceError(error, "graph");
+    if (expected) throw expected;
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Code graph setup failed: ${message}. Fix the problem and rerun mex setup.`);
   }
diff --git a/src/setup/population.ts b/src/setup/population.ts
index 72d6536a..0813b9d3 100644
--- a/src/setup/population.ts
+++ b/src/setup/population.ts
@@ -96,7 +96,7 @@ export async function launchSetupPopulationAsync(
   }
 }
 
-function createPopulationSession(prompt: string, projectRoot: string): {
+export function createPopulationSession(prompt: string, projectRoot: string): {
   root: string;
   instruction: string;
   cleanup: () => void;
diff --git a/src/setup/terminal-events.ts b/src/setup/terminal-events.ts
new file mode 100644
index 00000000..609ce12b
--- /dev/null
+++ b/src/setup/terminal-events.ts
@@ -0,0 +1,13 @@
+const MAX_EVENTS = 64;
+const MAX_EVENT_CHARS = 1_024;
+const MAX_HISTORY_CHARS = 16_384;
+
+/** Checkout/process-local activity; old events expire at deterministic bounds. */
+export function appendTerminalSetupEvent(history: readonly string[], message: string): readonly string[] {
+  const entry = message.slice(0, MAX_EVENT_CHARS);
+  if (!entry || entry === history.at(-1)) return history;
+  const next = [...history, entry].slice(-MAX_EVENTS);
+  let size = next.reduce((total, value) => total + value.length, 0);
+  while (size > MAX_HISTORY_CHARS) size -= next.shift()!.length;
+  return next;
+}
diff --git a/src/setup/terminal-return.ts b/src/setup/terminal-return.ts
new file mode 100644
index 00000000..8cf617ac
--- /dev/null
+++ b/src/setup/terminal-return.ts
@@ -0,0 +1,48 @@
+import { spawn, type ChildProcess } from "node:child_process";
+
+/** Exit 0 on Enter; exit 3 at end of input (Ctrl+D on POSIX, Ctrl+Z then Enter on Windows). */
+const WAIT_FOR_ENTER = "process.stdin.on('data', d => { if (/[\\r\\n]/.test(String(d))) process.exit(0); });"
+  + " process.stdin.on('end', () => process.exit(3));";
+
+export interface TerminalReturnOptions {
+  readonly spawn?: (command: string, args: readonly string[], options: { stdio: ["inherit", "ignore", "inherit"]; windowsHide: boolean }) => ChildProcess;
+}
+
+/**
+ * Wait for Enter while the HUD is suspended.
+ *
+ * A short-lived child reads the inherited terminal, exactly like the native
+ * agent handoff, so this process never reads stdin between Ink mounts. On
+ * Windows, any parent read there (readline in either mode, or raw `data`)
+ * leaves the next Ink renderer without input, and a cooked read still pending
+ * at exit holds the process until another Enter. Readline's keypress decoder
+ * also consumes the first key after Ink remounts. Ctrl+C reaches this process
+ * as SIGINT; callers cancel on that signal and abort, which stops the child.
+ */
+export function waitForTerminalReturn(signal: AbortSignal, options: TerminalReturnOptions = {}): Promise<"return" | "cancel"> {
+  if (signal.aborted) return Promise.resolve("cancel");
+  return new Promise((resolve) => {
+    let child: ChildProcess;
+    try {
+      child = (options.spawn ?? spawn)(process.execPath, ["-e", WAIT_FOR_ENTER], { stdio: ["inherit", "ignore", "inherit"], windowsHide: true });
+    } catch {
+      // Without a reader the pause cannot complete; return to the HUD rather than strand it.
+      resolve("return");
+      return;
+    }
+    let settled = false;
+    const finish = (result: "return" | "cancel") => {
+      if (settled) return;
+      settled = true;
+      signal.removeEventListener("abort", onAbort);
+      resolve(result);
+    };
+    const onAbort = () => {
+      try { child.kill(); } catch { /* Already gone. */ }
+      finish("cancel");
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    child.once("error", () => finish("return"));
+    child.once("exit", code => finish(code === 0 ? "return" : "cancel"));
+  });
+}
diff --git a/src/setup/terminal-ui.ts b/src/setup/terminal-ui.ts
new file mode 100644
index 00000000..03791768
--- /dev/null
+++ b/src/setup/terminal-ui.ts
@@ -0,0 +1,484 @@
+import React, { useEffect, useState } from "react";
+import { stdin } from "node:process";
+import { Box, Text, render, useInput, useStdin, useStdout, type Instance } from "ink";
+import type { AiTool } from "../types.js";
+import type { SetupProgressStep } from "./headless.js";
+
+const h = React.createElement;
+
+export interface TerminalSetupView {
+  projectName: string;
+  mode: string;
+  screen: "configure" | "progress" | "population" | "error" | "hub";
+  tools: readonly { id: AiTool; name: string; selected: boolean; cliAvailable: boolean }[];
+  initialTool?: AiTool | "continue";
+  activeStep?: SetupProgressStep;
+  completedSteps: readonly SetupProgressStep[];
+  detail: string;
+  events?: readonly string[];
+  startedAt: number;
+  phaseStartedAt?: number;
+  lastActivityAt?: number;
+  progress?: { completed?: number; total?: number; unit?: string };
+  error?: string;
+  hubUrl?: string;
+  populationAgent?: string | null;
+  stopping?: boolean;
+}
+
+export type TerminalSetupAction =
+  | { type: "toggle"; tool: AiTool }
+  | { type: "start"; tool?: AiTool }
+  | { type: "cancel" | "agent" | "prompt" | "check" | "exit" | "retry" | "link" };
+
+type ActionHandler = (action: TerminalSetupAction) => void;
+type Line = { text: string; color?: string; backgroundColor?: string; dimColor?: boolean; bold?: boolean };
+type Choice = { label: string; action: TerminalSetupAction };
+
+const BANNER = [
+  "88888b.d88b.   .d88b.  888  888",
+  "888 \"888 \"88b d8P  Y8b `Y8bd8P'",
+  "888  888  888 88888888   X88K",
+  "888  888  888 Y8b.     .d8\"\"8b.",
+  "888  888  888  \"Y8888  888  888",
+];
+const COLOR = {
+  ink: "#ECE5D5",
+  accent: "#F0B67F",
+  cyan: "#74D2D0",
+  border: "#496674",
+  muted: "#95A6AC",
+  complete: "#8CBAA3",
+  selected: "#203440",
+};
+const SPINNER = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const PHASES: readonly [SetupProgressStep, string][] = [
+  ["detect", "Project"],
+  ["scaffold", "Scaffold"],
+  ["tools", "AI tools"],
+  ["skills", "Agent skills"],
+  ["identity", "Identity"],
+  ["scan", "Codebase scan"],
+  ["graph", "Code graph"],
+  ["population", "Project knowledge"],
+  ["finalize", "Grounding + Wiki"],
+];
+
+// Text supplied by a subprocess or a project must not control the terminal.
+function plain(value: string): string {
+  return value
+    .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "")
+    .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/[\u0000-\u001f\u007f-\u009f]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function wrapped(value: string, width: number, limit: number): Line[] {
+  if (limit < 1) return [];
+  // Bound work as well as output when an agent supplies a very large detail.
+  let remaining = plain(value.slice(0, 8_192));
+  const result: Line[] = [];
+  const span = Math.max(1, width - 1);
+  while (remaining && result.length < limit) {
+    if (remaining.length <= span) {
+      result.push({ text: remaining });
+      remaining = "";
+    } else if (result.length === limit - 1) {
+      result.push({ text: remaining.slice(0, Math.max(1, span - 3)) + "..." });
+      remaining = "";
+    } else {
+      const space = remaining.lastIndexOf(" ", span);
+      const end = space > span / 2 ? space : span;
+      result.push({ text: remaining.slice(0, end) });
+      remaining = remaining.slice(end).trimStart();
+    }
+  }
+  return result;
+}
+
+function elapsed(startedAt: number, now: number): string {
+  const seconds = Math.max(0, Math.floor((now - startedAt) / 1_000)) || 0;
+  return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m ${String(seconds % 60).padStart(2, "0")}s`;
+}
+
+function reportedCount(progress: TerminalSetupView["progress"]): string | undefined {
+  if (!progress || !Number.isFinite(progress.completed) || progress.completed! < 0) return undefined;
+  const completed = Math.floor(progress.completed!);
+  const total = Number.isFinite(progress.total) && progress.total! >= completed ? Math.floor(progress.total!) : undefined;
+  return `${completed.toLocaleString("en-US")}${total === undefined ? "" : ` / ${total.toLocaleString("en-US")}`}${progress.unit ? ` ${plain(progress.unit)}` : ""}`;
+}
+
+function divider(width: number, label: string, start = "├", end = "┤"): string {
+  const text = plain(label).slice(0, Math.max(0, width - 6));
+  return start + "─ " + text + " " + "─".repeat(Math.max(0, width - text.length - 5)) + end;
+}
+
+function choices(view: TerminalSetupView): Choice[] {
+  if (view.screen === "population") {
+    return [
+      ...(view.populationAgent ? [{ label: `Open ${plain(view.populationAgent)}`, action: { type: "agent" as const } }] : []),
+      { label: "Show setup prompt", action: { type: "prompt" } },
+      { label: "Check populated files", action: { type: "check" } },
+      { label: "Finish later", action: { type: "exit" } },
+    ];
+  }
+  if (view.screen === "error") {
+    return [
+      { label: "Retry setup", action: { type: "retry" } },
+      { label: "Exit setup", action: { type: "exit" } },
+    ];
+  }
+  return [];
+}
+
+function title(view: TerminalSetupView): string {
+  if (view.stopping) return "Stopping safely";
+  switch (view.screen) {
+    case "configure": return "Choose your AI tools";
+    case "population": return "Add project knowledge";
+    case "error": return "Setup needs attention";
+    case "hub": return "Continue in your browser";
+    case "progress": return "Preparing your project";
+  }
+}
+
+function footer(view: TerminalSetupView, width: number): string {
+  if (view.stopping) return "Waiting for the current operation to stop...";
+  let labels: readonly string[];
+  switch (view.screen) {
+    case "configure": labels = ["Enter select/start  Space multi-select  Up/Down move  Ctrl+C exit", "Enter select/start Space multi ↑↓ Ctrl+C", "Enter start Space multi ↑↓ ^C", "Enter Space ↑↓ ^C"]; break;
+    case "population": labels = ["Up/Down move  Enter choose  d details  Ctrl+C stop", "↑↓ Enter  d details  Ctrl+C", "↑↓ Enter d ^C"]; break;
+    case "error": labels = ["Up/Down move  Enter choose  d diagnostics  Ctrl+C stop", "↑↓ Enter  d diagnostics  Ctrl+C", "↑↓ Enter d ^C"]; break;
+    case "hub": labels = ["d details  l copy link  q / Ctrl+C stop Hub", "d details l link q/Ctrl+C stop", "d l link q/^C"]; break;
+    case "progress": labels = ["d details  Ctrl+C stop setup", "d details ^C stop"]; break;
+  }
+  return labels.find(label => label.length <= width) ?? "^C";
+}
+
+function initialFocus(view: TerminalSetupView): number {
+  if (view.screen !== "configure") return 0;
+  if (view.initialTool === "continue") return view.tools.length;
+  const index = view.tools.findIndex(tool => tool.id === view.initialTool);
+  return Math.max(0, index);
+}
+
+function visibleChoices(groups: Line[][], focus: number, height: number): Line[] {
+  const focusEnd = groups.slice(0, focus + 1).reduce((total, group) => total + group.length, 0);
+  const start = Math.max(0, focusEnd - height);
+  return groups.flat().slice(start, start + height);
+}
+
+function phaseLines(view: TerminalSetupView): Line[] {
+  return PHASES.filter(([step]) => {
+    if (view.mode === "agent-memory" && ["scan", "graph", "finalize"].includes(step)) return false;
+    return step !== "skills" || view.tools.some(tool => tool.selected && (tool.id === "claude" || tool.id === "codex"));
+  }).map(([step, label], index) => {
+    const line = phaseLine(view, step, label);
+    return { ...line, text: `${String(index + 1).padStart(2, "0")} ${line.text}` };
+  });
+}
+
+function phaseLine(view: TerminalSetupView, step: SetupProgressStep, label: string): Line {
+  if (view.completedSteps.includes(step)) return { text: `[done] ${label}`, color: COLOR.complete };
+  if (view.screen === "hub") return { text: `[skip] ${label}`, color: COLOR.muted };
+  if (view.activeStep === step) {
+    const status = view.stopping ? "stop" : view.screen === "error" ? "fail" : view.screen === "population" ? "wait" : "now ";
+    return { text: `[${status}] ${label}`, color: COLOR.accent, bold: true };
+  }
+  return { text: `[wait] ${label}`, color: COLOR.muted };
+}
+
+/** The renderer owns input only while mounted; native agents get the entire terminal. */
+export function TerminalSetupHUD({ view, onAction }: { view: TerminalSetupView; onAction: ActionHandler }): React.ReactElement {
+  const { stdout } = useStdout();
+  const { stdin: input } = useStdin();
+  const [dimensions, setDimensions] = useState(() => ({ columns: stdout.columns || 80, rows: stdout.rows || 24 }));
+  const [focus, setFocus] = useState(() => initialFocus(view));
+  const [expanded, setExpanded] = useState(false);
+  const [detailOffset, setDetailOffset] = useState(0);
+  const [now, setNow] = useState(Date.now);
+  const working = view.screen === "progress" && !view.stopping;
+  const menu = choices(view);
+  const count = view.screen === "configure" ? view.tools.length + 1 : menu.length;
+  const selected = Math.min(focus, Math.max(0, count - 1));
+
+  useEffect(() => {
+    const resize = () => setDimensions({ columns: stdout.columns || 80, rows: stdout.rows || 24 });
+    stdout.on("resize", resize);
+    return () => { stdout.off("resize", resize); };
+  }, [stdout]);
+  useEffect(() => { setFocus(initialFocus(view)); setExpanded(false); setDetailOffset(0); }, [view.screen, view.initialTool]);
+  useEffect(() => { if (!view.events?.length) setDetailOffset(0); }, [view.detail, view.error, view.hubUrl]);
+  useEffect(() => {
+    setNow(Date.now());
+    if (!working) return;
+    const timer = setInterval(() => { setNow(Date.now()); }, 120);
+    return () => { clearInterval(timer); };
+  }, [working]);
+
+  useInput((input, key) => {
+    if (view.stopping) return;
+    if ((key.ctrl && (input === "c" || input === "d")) || (view.screen === "hub" && input.toLowerCase() === "q")) {
+      onAction({ type: "cancel" });
+      return;
+    }
+    if (input === "d" && view.screen !== "configure") {
+      // Open at the current diagnostics; older retained notices remain above.
+      if (!expanded) setDetailOffset(view.events?.length ? maxOffset : 0);
+      setExpanded(!expanded);
+      return;
+    }
+    if (input.toLowerCase() === "l" && view.screen === "hub" && view.hubUrl) {
+      onAction({ type: "link" });
+      return;
+    }
+    if (expanded) {
+      if (key.escape) setExpanded(false);
+      else if (key.upArrow) setDetailOffset(Math.max(0, visibleOffset - 1));
+      else if (key.downArrow) setDetailOffset(Math.min(maxOffset, visibleOffset + 1));
+      else if (key.pageUp) setDetailOffset(Math.max(0, visibleOffset - Math.max(1, bodyHeight - 1)));
+      else if (key.pageDown) setDetailOffset(Math.min(maxOffset, visibleOffset + Math.max(1, bodyHeight - 1)));
+      return;
+    }
+    if (key.upArrow && count) setFocus((selected + count - 1) % count);
+    else if (key.downArrow && count) setFocus((selected + 1) % count);
+    else if (view.screen === "configure" && input === " " && view.tools[selected]) {
+      onAction({ type: "toggle", tool: view.tools[selected].id });
+    } else if (key.return) {
+      if (view.screen === "configure") onAction(view.tools[selected] ? { type: "start", tool: view.tools[selected].id } : { type: "start" });
+      else if (menu[selected]) onAction(menu[selected].action);
+    }
+  });
+  useEffect(() => {
+    // Readline pauses the stream on close. Resume only after useInput has
+    // installed Ink's readable handler, so the first returning key is retained.
+    input.resume();
+  }, [input]);
+
+  const height = Math.max(1, Math.min(23, dimensions.rows - 1));
+  const padding = dimensions.columns >= 30 ? 1 : 0;
+  const width = Math.max(1, dimensions.columns - padding * 2);
+  const framed = width >= 24 && height >= 7;
+  const insideWidth = framed ? width - 4 : width;
+  const fullBanner = view.screen === "configure" && dimensions.columns >= 60 && height >= 21;
+  const header: Line[] = fullBanner
+    ? BANNER.map((text, index) => {
+      const caption = index === 1 ? "    PROJECT MEMORY / SETUP" : index === 3 ? "    A place for project knowledge." : "";
+      return { text: text + (text.length + caption.length <= insideWidth ? caption : ""), color: COLOR.cyan, bold: true };
+    })
+    : [];
+  if (fullBanner) {
+    header.unshift({ text: "" });
+    header.push({ text: "" });
+  }
+  if (height >= 11) header.push({ text: `${plain(view.projectName)}  /  ${plain(view.mode)}${width >= 60 ? `  /  TOTAL ${elapsed(view.startedAt, now)}` : ""}`, color: COLOR.muted });
+  const bodyHeight = Math.max(0, height - header.length - (framed ? 4 : 2));
+  const split = !expanded && width >= 74 && bodyHeight >= 9;
+  const railWidth = view.screen === "configure" ? 46 : 31;
+  const contentWidth = split ? width - railWidth - 5 : insideWidth;
+  const fullDetail = [view.error, view.detail, view.hubUrl].filter((value, index, values) => value && values.indexOf(value) === index).join("\n\n");
+  const boundedDetail = fullDetail.length > 4_096
+    ? fullDetail.slice(0, 3_040) + "\n[Middle of detail omitted]\n" + fullDetail.slice(-1_024)
+    : fullDetail;
+  const detailLines = view.events?.length
+    ? [...view.events.slice(-64).flatMap(event => [...wrapped(event.slice(0, 1_024), insideWidth, 1_024), { text: "" }]),
+      ...wrapped(boundedDetail, insideWidth, 4_096)]
+    : wrapped(boundedDetail, insideWidth, 4_096);
+  const maxOffset = Math.max(0, detailLines.length - bodyHeight);
+  const visibleOffset = Math.min(detailOffset, maxOffset);
+  let content: Line[] = [];
+  let rail: Line[] = [];
+
+  if (expanded) {
+    content = detailLines.slice(visibleOffset, visibleOffset + bodyHeight);
+  } else if (view.screen === "configure") {
+    const selectedCount = view.tools.filter(tool => tool.selected).length;
+    const continueFocused = selected === view.tools.length;
+    const continueLabel = selectedCount ? "Continue with selected tools" : "Continue without an agent";
+    const continueLines = wrapped(continueLabel, (split ? railWidth - 2 : insideWidth) - 2, 3).map((item, index) => ({
+      text: `${continueFocused && index === 0 ? ">" : " "} ${item.text}`,
+      color: continueFocused ? COLOR.accent : COLOR.cyan,
+      backgroundColor: continueFocused ? COLOR.selected : undefined,
+      bold: continueFocused,
+    }));
+    const toolLines = view.tools.map((tool, index) => ({
+      text: `${index === selected ? ">" : " "} [${tool.selected ? "x" : " "}] ${plain(tool.name)}  ${tool.id === "claude" || tool.id === "codex" ? tool.cliAvailable ? "CLI ready" : "CLI not found" : "integration only"}`,
+      color: index === selected ? COLOR.accent : COLOR.ink,
+      backgroundColor: index === selected ? COLOR.selected : undefined,
+      bold: index === selected,
+    }));
+    if (split) {
+      const spaceChoices = toolLines.length * 2 + continueLines.length <= bodyHeight;
+      rail = visibleChoices([...toolLines.map(item => spaceChoices ? [item, { text: "" }] : [item]), continueLines], selected, bodyHeight);
+      const tool = view.tools[selected];
+      const native = tool?.id === "claude" || tool?.id === "codex";
+      content = [
+        { text: continueFocused ? "CONTINUE" : native ? "NATIVE SETUP" : "INTEGRATION", color: COLOR.cyan, bold: true },
+        { text: tool?.name ?? (selectedCount ? "Your selected tools" : "Manual setup"), color: COLOR.accent, bold: true },
+        { text: "" },
+        ...wrapped(continueFocused
+          ? selectedCount
+            ? "Start with only the checked tools. A selected Claude or Codex CLI can populate project knowledge."
+            : "Start without selecting a tool. MEX will show a prompt to complete project knowledge manually."
+          : native
+            ? tool.cliAvailable
+              ? `${tool.selected ? "Enter starts setup with this tool selected." : "Enter selects this tool and starts setup."} Its CLI is available.`
+              : "Enter adds its instructions and starts setup. CLI not found; population may need the manual prompt."
+            : "Enter adds this integration and starts setup. Populate project knowledge with a selected Claude or Codex CLI, or the manual prompt.", contentWidth, bodyHeight - 5),
+        { text: "" },
+        { text: `${selectedCount} selected`, color: COLOR.cyan },
+      ];
+    } else {
+      // A compact Continue choice can occupy two lines; keep its full label
+      // visible while moving through the same logical rows as a wider terminal.
+      content = visibleChoices([...toolLines.map(item => [item]), continueLines], selected, bodyHeight);
+      if (content.length < bodyHeight) content.push({ text: "" }, ...wrapped(view.detail || "Enter selects a tool and starts setup. Space optionally selects multiple tools.", contentWidth, bodyHeight - content.length - 1));
+    }
+  } else {
+    if (split) rail = phaseLines(view);
+    const menuBudget = Math.min(menu.length, Math.max(0, bodyHeight - 1));
+    const detailBudget = Math.max(0, Math.min(6, bodyHeight - menuBudget - (menu.length ? 1 : 0)));
+    if (working) {
+      const activeLabel = PHASES.find(([step]) => step === view.activeStep)?.[1] ?? "Preparing setup";
+      const phaseTime = elapsed(view.phaseStartedAt ?? view.startedAt, now);
+      const quietTime = view.lastActivityAt === undefined ? undefined : elapsed(view.lastActivityAt, now);
+      const counter = reportedCount(view.progress);
+      content.push(
+        { text: `${SPINNER[Math.floor(now / 120) % SPINNER.length]}  ${activeLabel}`, color: COLOR.accent, bold: true },
+        { text: `Phase ${phaseTime}${!split && quietTime ? `  /  Quiet ${quietTime}` : ""}`, color: COLOR.ink },
+      );
+      if (counter && content.length < bodyHeight - 1) content.push({ text: counter, color: COLOR.cyan, bold: true });
+      if (split) content.push({ text: "" }, { text: "LATEST EVENT", color: COLOR.cyan, bold: true });
+      const remaining = Math.max(0, bodyHeight - content.length - (split ? 4 : 0));
+      content.push(...wrapped(view.detail, contentWidth, Math.min(split ? 6 : 3, remaining)));
+      if (split) content.push(
+        { text: "" },
+        { text: quietTime ? `No new events for ${quietTime}` : "No activity update yet", color: COLOR.muted },
+        { text: "Waiting for the next reported event.", color: COLOR.muted },
+      );
+    } else if (!split && view.activeStep && bodyHeight >= menuBudget + 3) {
+      const active = PHASES.find(([step]) => step === view.activeStep);
+      if (active) content.push(phaseLine(view, ...active));
+    }
+    const detail = view.screen === "error" ? view.error || view.detail : view.detail;
+    if (!working) content.push(...wrapped(detail, contentWidth, Math.max(0, detailBudget - content.length)).map(line => ({ ...line, color: view.screen === "error" ? COLOR.accent : COLOR.ink })));
+    if (view.screen === "error" && view.detail && view.detail !== detail && bodyHeight - menuBudget - content.length >= 4) {
+      content.push({ text: "" }, { text: "DIAGNOSTICS  [d] expand", color: COLOR.cyan, bold: true });
+      content.push(...wrapped(view.detail, contentWidth, Math.min(5, bodyHeight - menuBudget - content.length - 1)).map(item => ({ ...item, color: COLOR.muted })));
+    }
+    if (view.screen === "hub" && view.hubUrl && content.length < bodyHeight) content.push(...wrapped(view.hubUrl, contentWidth, bodyHeight - content.length).map(item => ({ ...item, color: COLOR.cyan })));
+    if (menu.length) {
+      if (content.length < bodyHeight - menuBudget) content.push({ text: "" });
+      const start = Math.max(0, selected - menuBudget + 1);
+      content.push(...menu.slice(start, start + menuBudget).map((choice, offset) => ({
+        text: `${start + offset === selected ? ">" : " "} ${choice.label}`,
+        color: start + offset === selected ? COLOR.accent : COLOR.ink,
+        backgroundColor: start + offset === selected ? COLOR.selected : undefined,
+        bold: start + offset === selected,
+      })));
+    }
+  }
+
+  const line = (item: Line, key: string) => h(Text, { key, color: item.color ?? COLOR.ink, backgroundColor: item.backgroundColor, bold: item.bold, dimColor: item.dimColor, wrap: "truncate-end" }, item.text || " ");
+  const edge = (text: string, key: string) => line({ text, color: COLOR.border }, key);
+  const framedRow = (item: Line, key: string) => h(Box, { key, height: 1, flexShrink: 0 },
+    ...(framed ? [edge("│ ", `${key}-left`)] : []),
+    h(Box, { width: insideWidth, flexShrink: 0 }, line(item, `${key}-text`)),
+    ...(framed ? [edge(" │", `${key}-right`)] : []),
+  );
+  const body = Array.from({ length: bodyHeight }, (_, index) => split
+    ? h(Box, { key: `row-${index}`, height: 1, flexShrink: 0 },
+      edge("│ ", `left-${index}`),
+      h(Box, { width: railWidth - 2, flexShrink: 0 }, line(rail[index] || { text: "" }, `phase-${index}`)),
+      edge(" │ ", `middle-${index}`),
+      h(Box, { width: contentWidth, flexShrink: 0 }, line(content[index] || { text: "" }, `content-${index}`)),
+      edge(" │", `right-${index}`),
+    )
+    : framedRow(content[index] || { text: "" }, `row-${index}`));
+  const sectionTitle = expanded ? `Details ${visibleOffset + 1}-${Math.min(visibleOffset + bodyHeight, detailLines.length)} / ${detailLines.length}` : title(view);
+  const section = split
+    ? divider(railWidth + 2, view.screen === "configure" ? "Choose your AI tools" : "WORKFLOW", "├", "┬") + divider(width - railWidth - 1, view.screen === "configure" ? "FOCUS" : sectionTitle, "", "┤")
+    : divider(width, sectionTitle);
+
+  return h(Box, { flexDirection: "column", width: dimensions.columns, height, paddingX: padding, overflow: "hidden" },
+    ...(height >= 2 ? [line({ text: framed ? divider(width, "MEX / SETUP", "╭", "╮") : "MEX / SETUP", color: COLOR.cyan, bold: true }, "brand")] : []),
+    ...header.map((item, index) => framedRow(item, `header-${index}`)),
+    ...(framed ? [line({ text: section, color: COLOR.border, bold: true }, "section")] : []),
+    ...body,
+    ...(framed ? [edge(split ? "╰" + "─".repeat(railWidth) + "┴" + "─".repeat(width - railWidth - 3) + "╯" : "╰" + "─".repeat(width - 2) + "╯", "bottom")] : []),
+    line({ text: expanded ? (["Up/Down / PgUp/PgDn scroll  d / Esc back  Ctrl+C stop", "Arrows scroll d/Esc back Ctrl+C", "↑↓ d/Esc ^C"].find(label => label.length <= width) ?? "^C") : footer(view, width), color: COLOR.muted }, "footer"),
+  );
+}
+
+export function createTerminalSetupUI(initial: TerminalSetupView, onAction: ActionHandler): {
+  update(view: TerminalSetupView): void;
+  suspend(): Promise<void>;
+  resume(view: TerminalSetupView): void;
+  close(): Promise<void>;
+} {
+  let view = initial;
+  let instance: Instance | undefined;
+  let pending: Promise<void> | undefined;
+  let suspended = false;
+  let closed = false;
+  const mount = () => {
+    if (closed || suspended || instance) return;
+    // Ink unrefs stdin on unmount. Keep the process alive until the fresh
+    // renderer's input effect takes ownership again.
+    if (stdin.isTTY) stdin.ref();
+    instance = render(h(TerminalSetupHUD, { view, onAction }), {
+      alternateScreen: true,
+      patchConsole: false,
+      exitOnCtrlC: false,
+    });
+  };
+  const unmount = (): Promise<void> => {
+    if (pending) return pending;
+    const current = instance;
+    instance = undefined;
+    if (!current) return Promise.resolve();
+    const teardown = (async () => {
+      try {
+        current.unmount();
+        await current.waitUntilExit();
+      } finally {
+        current.cleanup();
+      }
+    })();
+    pending = teardown.finally(() => { pending = undefined; });
+    return pending;
+  };
+  mount();
+  return {
+    update(next) {
+      view = next;
+      instance?.rerender(h(TerminalSetupHUD, { view, onAction }));
+    },
+    async suspend() {
+      suspended = true;
+      await unmount();
+      // Removing Ink's listener alone leaves Node reading ahead on the shared
+      // descriptor, which can consume keystrokes intended for the native child.
+      stdin.pause();
+    },
+    resume(next) {
+      view = next;
+      suspended = false;
+      if (closed) return;
+      if (instance) instance.rerender(h(TerminalSetupHUD, { view, onAction }));
+      else if (pending) void pending.then(mount, () => {});
+      else mount();
+    },
+    async close() {
+      closed = true;
+      try {
+        await unmount();
+      } finally {
+        // A pending Windows console read can otherwise hold shutdown until Enter.
+        stdin.pause();
+        if (stdin.isTTY) stdin.unref();
+      }
+    },
+  };
+}
diff --git a/src/setup/terminal.ts b/src/setup/terminal.ts
new file mode 100644
index 00000000..3e939e84
--- /dev/null
+++ b/src/setup/terminal.ts
@@ -0,0 +1,329 @@
+import { basename, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { stdin, stdout } from "node:process";
+import { AI_TOOLS, type AiTool } from "../types.js";
+import { loadConfiguredAiTools } from "../config.js";
+import { isCliAvailable } from "../cli-tools.js";
+import {
+  ensureToolAnchors, findSetupProjectRoot, installSetupAgentAssets, isScaffoldPopulated,
+  type SetupRunOptions, type SetupRunResult,
+} from "./index.js";
+import { createSetupScaffold, resolveSetupMode, setupTemplatesDirectory, throwIfSetupAborted } from "./phases.js";
+import { runHeadlessSetup, type HeadlessSetupResult } from "./headless.js";
+import { SetupError } from "./errors.js";
+import { classifySetupAgentAssetsError } from "./agent-errors.js";
+import { selectSetupAgent } from "./population.js";
+import { formatSetupGraphActivity, setupGraphActivity } from "./graph-progress.js";
+import type { TerminalSetupAction, TerminalSetupView } from "./terminal-ui.js";
+import { appendTerminalSetupEvent } from "./terminal-events.js";
+import { waitForTerminalReturn } from "./terminal-return.js";
+
+const CONTINUE = "Run `mex setup` to continue. Existing authored files are preserved.";
+
+/** The terminal owns presentation and interaction; all writes use the shared setup engine. */
+export async function runTerminalSetup(options: SetupRunOptions): Promise<SetupRunResult> {
+  const projectRoot = findSetupProjectRoot();
+  const mexDir = resolve(projectRoot, ".mex");
+  const mode = resolveSetupMode(mexDir, options.mode);
+  const selectedTools = [...new Set(options.tools ?? loadConfiguredAiTools(mexDir))];
+  if (options.dryRun) return previewSetup(projectRoot, mode, selectedTools, options.tools !== undefined);
+  const interactive = Boolean(stdin.isTTY && stdout.isTTY && !options.yes && !process.env.CI && process.env.TERM !== "dumb");
+  const abort = new AbortController();
+  let cancelCode = 130;
+  let cancellationDetail = "";
+  let nativeSession = false;
+  let notifyCancel = () => {};
+  const cancel = (code = 130) => {
+    cancelCode = code;
+    abort.abort();
+    notifyCancel();
+  };
+  // In a native session Ctrl+C belongs to the agent. SIGTERM still stops the owned run.
+  const interrupt = () => { if (!nativeSession) cancel(); };
+  const terminate = () => cancel(143);
+  const endInput = () => { if (!nativeSession) cancel(); };
+  process.on("SIGINT", interrupt);
+  process.on("SIGTERM", terminate);
+  if (interactive) stdin.on("end", endInput);
+  try {
+    if (!interactive) {
+      console.log(`MEX setup · ${basename(projectRoot)} · ${mode}`);
+      let lastGraphPhase = "";
+      let lastGraphLogAt = 0;
+      const result = await runHeadlessSetup({
+        projectRoot, mode, tools: selectedTools, confirmPopulation: true, signal: abort.signal,
+        onProgress: update => console.log(`${update.label}${update.detail ? ` — ${update.detail}` : ""}`),
+        onMessage: message => console.log(message),
+        onGraphProgress: progress => {
+          const now = Date.now();
+          if (progress.phase !== lastGraphPhase || now - lastGraphLogAt >= 1000
+            || (progress.total !== undefined && progress.completed === progress.total)) {
+            console.log(formatSetupGraphActivity(progress));
+            lastGraphPhase = progress.phase;
+            lastGraphLogAt = now;
+          }
+        },
+      });
+      for (const note of result.anchorNotes) console.log(`Action needed: ${note}`);
+      if (!result.ready) {
+        console.log(`\nSetup paused: scaffold population is still required.\n${CONTINUE}`);
+        if (result.prompt) console.log(`\nPopulation prompt:\n\n${result.prompt}`);
+        return { outcome: "paused", exitCode: 2, message: "Scaffold population is still required." };
+      }
+      console.log(result.message);
+      console.log("Run `mex setup --browser` to open the setup completion page.");
+      return { outcome: "complete", exitCode: 0, message: result.message };
+    }
+
+    const { createTerminalSetupUI } = await import("./terminal-ui.js");
+    let view: TerminalSetupView = {
+      projectName: basename(projectRoot), mode, screen: "configure", startedAt: Date.now(),
+      completedSteps: [], detail: "Highlight a tool and press Enter to select it and begin. Space optionally selects additional tools.",
+      initialTool: selectedTools[0] ?? (options.tools?.length === 0 ? "continue" : undefined),
+      tools: (Object.keys(AI_TOOLS) as AiTool[]).map(id => ({
+        id, name: AI_TOOLS[id].name, selected: selectedTools.includes(id),
+        cliAvailable: AI_TOOLS[id].cli !== null && isCliAvailable(AI_TOOLS[id].cli!),
+      })),
+    };
+    let pending: ((action: TerminalSetupAction) => void) | undefined;
+    const update = (changes: Partial<TerminalSetupView>) => {
+      view = { ...view, ...changes,
+        events: changes.detail ? appendTerminalSetupEvent(view.events ?? [], changes.detail) : view.events };
+      ui.update(view);
+    };
+    const ui = createTerminalSetupUI(view, action => {
+      if (action.type === "cancel") { cancel(); return; }
+      if (action.type === "toggle" && view.screen === "configure") {
+        update({ tools: view.tools.map(tool => tool.id === action.tool ? { ...tool, selected: !tool.selected } : tool) });
+        return;
+      }
+      if (action.type === "link" && view.hubUrl) {
+        // Suspend only after Ink's input handler returns. Unmounting inside it
+        // leaves Ink's read loop to start a cooked read that steals the Enter.
+        queueMicrotask(() => void showHubLink());
+        return;
+      }
+      pending?.(action);
+    });
+    // Setup can finish in the browser while the link is shown; closing releases the wait.
+    let linkWait: AbortController | undefined;
+    const showHubLink = async () => {
+      const release = new AbortController();
+      linkWait = release;
+      try {
+        await ui.suspend();
+        // Outside the frame, terminal wrapping adds no border characters to a copy.
+        console.log(`\nHub link (keep it private):\n${view.hubUrl}\n`);
+        if (await pressEnterToReturn(AbortSignal.any([abort.signal, release.signal])) === "cancel"
+          && !abort.signal.aborted && !release.signal.aborted) cancel();
+      } catch (error) {
+        if (!abort.signal.aborted) update({ detail: error instanceof Error ? error.message : "Could not show the Hub link." });
+      } finally {
+        if (linkWait === release) linkWait = undefined;
+        ui.resume(view);
+      }
+    };
+    const choose = (): Promise<TerminalSetupAction> => {
+      if (abort.signal.aborted) return Promise.resolve({ type: "cancel" });
+      return new Promise(resolve => {
+        pending = action => { pending = undefined; resolve(action); };
+      });
+    };
+    notifyCancel = () => {
+      update({ stopping: true, detail: "Stopping setup safely. Waiting for the active operation to settle…" });
+      pending?.({ type: "cancel" });
+    };
+    let outcome: SetupRunResult | undefined;
+    let validated: HeadlessSetupResult | undefined;
+    let anchorNotes: readonly string[] = [];
+    let populationFailure: string | undefined;
+    try {
+      const action = await choose();
+      if (action.type !== "start") throwIfSetupAborted(abort.signal);
+      const focusedTool = action.type === "start" ? action.tool : undefined;
+      if (focusedTool) {
+        update({ tools: view.tools.map(tool => tool.id === focusedTool ? { ...tool, selected: true } : tool) });
+      }
+      const chosen = new Set(view.tools.filter(tool => tool.selected).map(tool => tool.id));
+      // Enter explicitly chooses the preferred tool. Other selected integrations
+      // retain their saved order; the Continue row uses that order unchanged.
+      const tools = [...new Set([
+        ...(focusedTool ? [focusedTool] : []),
+        ...selectedTools.filter(tool => chosen.has(tool)),
+        ...chosen,
+      ])];
+      while (!outcome) {
+        try {
+          if (!validated) {
+            update({ screen: "progress", activeStep: undefined, completedSteps: [], error: undefined, stopping: false,
+              phaseStartedAt: Date.now(), lastActivityAt: Date.now(), progress: undefined });
+            const result = await runHeadlessSetup({
+              projectRoot, mode, tools, signal: abort.signal,
+              onProgress: progress => update({
+                activeStep: progress.step,
+                completedSteps: view.activeStep ? [...new Set([...view.completedSteps, view.activeStep])] : view.completedSteps,
+                detail: progress.detail ?? progress.label,
+                phaseStartedAt: Date.now(),
+                lastActivityAt: Date.now(),
+                progress: undefined,
+              }),
+              onMessage: detail => update({ detail, lastActivityAt: Date.now() }),
+              onGraphProgress: progress => {
+                const activity = setupGraphActivity(progress);
+                update({ detail: activity.detail, progress: activity.progress, lastActivityAt: Date.now() });
+              },
+              onAnchorNotes: notes => { anchorNotes = notes; },
+              populate: async input => {
+                let tool = selectSetupAgent(input.selectedTools);
+                let first = true;
+                let detail = tool
+                  ? `Opening ${AI_TOOLS[tool].name} with your setup instructions. Exit the agent session to return to MEX.`
+                  : "No selected Claude Code or Codex CLI is available. Use the manual prompt, then check again.";
+                while (!abort.signal.aborted) {
+                  tool = selectSetupAgent(input.selectedTools);
+                  update({ screen: "population", detail, populationAgent: tool ? AI_TOOLS[tool].name : null });
+                  const action = first && tool ? { type: "agent" as const } : await choose();
+                  first = false;
+                  if (action.type === "cancel") throwIfSetupAborted(abort.signal);
+                  if (action.type === "exit") {
+                    populationFailure = undefined;
+                    return { tool, completed: false };
+                  }
+                  if (action.type === "agent" && tool) {
+                    const { launchInteractiveSetupPopulation } = await import("./interactive-population.js");
+                    await ui.suspend();
+                    nativeSession = true;
+                    let launched;
+                    try {
+                      console.log(`\nOpening ${AI_TOOLS[tool].name} with your setup instructions. Exit the agent session to return to MEX.\n`);
+                      launched = await launchInteractiveSetupPopulation(input);
+                    }
+                    finally { nativeSession = false; ui.resume(view); }
+                    if (abort.signal.aborted) cancellationDetail = launched.message ?? "";
+                    throwIfSetupAborted(abort.signal);
+                    populationFailure = launched.status === "failed" ? launched.message ?? "The agent failed." : undefined;
+                    if (launched.status === "exited" && isScaffoldPopulated(mexDir)) {
+                      update({ screen: "progress" });
+                      return { tool: launched.tool, completed: true };
+                    }
+                    detail = launched.status === "exited"
+                      ? "The agent exited, but required scaffold placeholders remain. Reopen the session or finish manually."
+                      : launched.message ?? `The agent ${launched.status === "cancelled" ? "was interrupted" : "failed"}. Reopen it or use the manual prompt.`;
+                  } else if (action.type === "prompt") {
+                    await ui.suspend();
+                    try {
+                      console.log(`\nCopy this prompt into your AI tool:\n\n${input.prompt}\n`);
+                      if (await pressEnterToReturn(abort.signal) === "cancel" && !abort.signal.aborted) cancel();
+                    }
+                    finally {
+                      ui.resume(view);
+                    }
+                  } else if (action.type === "check") {
+                    if (isScaffoldPopulated(mexDir)) {
+                      update({ screen: "progress" });
+                      return { tool, completed: true };
+                    }
+                    detail = "Required scaffold placeholders remain. Finish population, then choose Check again.";
+                  }
+                }
+                throwIfSetupAborted(abort.signal);
+                return { tool, completed: false };
+              },
+            });
+            if (!result.ready) {
+              outcome = { outcome: populationFailure ? "failed" : "paused", exitCode: populationFailure ? 1 : 2,
+                message: `${populationFailure ? `Setup failed: ${populationFailure}` : "Setup paused at population."} ${CONTINUE}` };
+              continue;
+            }
+            validated = result;
+          }
+          throwIfSetupAborted(abort.signal);
+          update({ screen: "progress", completedSteps: view.activeStep ? [...new Set([...view.completedSteps, view.activeStep])] : view.completedSteps,
+            activeStep: undefined, phaseStartedAt: Date.now(), lastActivityAt: Date.now(), progress: undefined,
+            detail: "Opening the setup completion page…", error: undefined });
+          const { runSetupHubCommand } = await import("../hub/command.js");
+          let listening = false;
+          await runSetupHubCommand({
+            projectRoot, initialMode: mode, port: options.port, openBrowser: options.openBrowser !== false,
+            signal: abort.signal,
+            onListening: ({ bootstrapUrl }) => { listening = true; update({ screen: "hub", hubUrl: bootstrapUrl,
+              detail: mode === "code-repo"
+                ? "Continue in your browser to review the setup commit, finish optional details, and open Hub."
+                : "Agent memory is ready. Finish the optional details in your browser." }); },
+            onMessage: detail => update({ detail }),
+          });
+          if (!listening) throwIfSetupAborted(abort.signal);
+          const { projectSetupStatus } = await import("../hub/setup/readiness.js");
+          const finished = await projectSetupStatus(projectRoot);
+          const message = finished.mode === "agent-memory" || finished.ready
+            ? "Setup complete. Hub stopped. Run `mex hub` to open Hub again."
+            : `${validated.message} Hub stopped. Run \`mex setup --browser\` to reopen the completion page.`;
+          outcome = { outcome: "complete", exitCode: 0, message };
+        } catch (error) {
+          if (abort.signal.aborted) throw error;
+          const detail = error instanceof SetupError ? error.userMessage : error instanceof Error ? error.message : String(error);
+          const rawDiagnostic = error instanceof Error && error.message !== detail ? error.message : undefined;
+          const diagnostic = rawDiagnostic ? `\nDiagnostics: ${rawDiagnostic}` : "";
+          const recovery = `${validated ? "Setup is ready; the Hub could not start." : "Setup could not finish."} Resolve the problem and retry.`;
+          update({ screen: "error", error: detail, detail: rawDiagnostic ? `${rawDiagnostic}\n${recovery}` : recovery, stopping: false });
+          const action = await choose();
+          throwIfSetupAborted(abort.signal);
+          if (action.type !== "retry") outcome = { outcome: "failed", exitCode: 1, message: `${detail}${diagnostic}\n${CONTINUE}` };
+        }
+      }
+    } finally {
+      notifyCancel = () => {};
+      linkWait?.abort();
+      await ui.close();
+      for (const note of anchorNotes) console.log(`Action needed: ${note}`);
+    }
+    console.log(outcome.message);
+    return outcome;
+  } catch (error) {
+    if (abort.signal.aborted) {
+      const message = `Setup cancelled. ${cancellationDetail ? `${cancellationDetail} ` : ""}${CONTINUE}`;
+      console.log(message);
+      return { outcome: "cancelled", exitCode: cancelCode, message };
+    }
+    throw error;
+  } finally {
+    process.removeListener("SIGINT", interrupt);
+    process.removeListener("SIGTERM", terminate);
+    stdin.removeListener("end", endInput);
+  }
+}
+
+function pressEnterToReturn(signal: AbortSignal): Promise<"return" | "cancel"> {
+  stdout.write("Press Enter to return to MEX…");
+  return waitForTerminalReturn(signal);
+}
+
+function previewSetup(projectRoot: string, mode: "code-repo" | "agent-memory", tools: AiTool[], explicit: boolean): SetupRunResult {
+  console.log(`MEX setup · DRY RUN · ${mode === "agent-memory" ? "agent-memory workspace" : basename(projectRoot)}`);
+  console.log("No files will be created or modified.");
+  if (mode === "code-repo" && !existsSync(resolve(projectRoot, ".git"))) {
+    throw new SetupError("No Git repository found. Run `git init` first, then rerun setup.");
+  }
+  console.log(`Using ${explicit ? "requested" : "configured"} AI tools: ${tools.map(tool => AI_TOOLS[tool].name).join(", ") || "none"}`);
+  createSetupScaffold({ projectRoot, mode, dryRun: true,
+    onIgnore: message => console.log(message),
+    onFile: (file, action) => console.log(`${action === "skip" ? "Keep" : "Would create"} .mex/${file}`),
+  });
+  ensureToolAnchors(projectRoot, setupTemplatesDirectory(), tools, true);
+  try {
+    const assets = installSetupAgentAssets({ projectRoot, selectedTools: tools, dryRun: true, checkIgnored: mode === "code-repo" });
+    for (const action of assets?.actions ?? []) console.log(action.message);
+    for (const warning of assets?.warnings ?? []) console.log(warning.message);
+    if (assets?.conflicted) throw new SetupError("Official MEX agent assets have conflicts. Review `mex skills sync --dry-run` before applying setup.");
+  } catch (error) { throw classifySetupAgentAssetsError(error) ?? error; }
+  console.log("Would verify or assign the project identity.");
+  if (mode === "code-repo") console.log("Would build the code graph before population.");
+  console.log(isScaffoldPopulated(resolve(projectRoot, ".mex"))
+    ? "Would preserve and verify the populated scaffold."
+    : "Would populate the scaffold with a selected agent or the manual prompt.");
+  if (mode === "code-repo") console.log("Would capture grounding, migrate and index Wiki, then validate the result.");
+  console.log("Interactive setup would then open the Hub completion page.");
+  const message = "Dry run complete. Population and validation were not run.";
+  console.log(message);
+  return { outcome: "dry-run", exitCode: 0, message };
+}
diff --git a/src/setup/wiki-finalize.ts b/src/setup/wiki-finalize.ts
index a7d0d445..c9e66140 100644
--- a/src/setup/wiki-finalize.ts
+++ b/src/setup/wiki-finalize.ts
@@ -1,4 +1,5 @@
 import { resolve } from "node:path";
+import { throwIfSetupAborted } from "./phases.js";
 import {
   createWikiEngine,
   type MigrationApplyResult,
@@ -20,6 +21,7 @@ export interface SetupWikiFinalizationOptions {
   readOnly?: readonly string[];
   onProgress?: (message: string) => void;
   onWarning?: (message: string) => void;
+  signal?: AbortSignal;
 }
 
 /** A compact, setup-oriented summary over the existing Wiki service results. */
@@ -48,6 +50,7 @@ export interface SetupWikiFinalizationResult {
 export async function finalizeSetupWiki(
   options: SetupWikiFinalizationOptions,
 ): Promise<SetupWikiFinalizationResult> {
+  throwIfSetupAborted(options.signal);
   const projectRoot = resolve(options.projectRoot);
   const scaffoldRoot = resolve(options.scaffoldRoot);
   const engine = createWikiEngine({
@@ -101,7 +104,9 @@ export async function finalizeSetupWiki(
   });
 
   options.onProgress?.("Planning Wiki migration...");
+  throwIfSetupAborted(options.signal);
   const plan = await engine.planMigration();
+  throwIfSetupAborted(options.signal);
   collectDiagnostics(plan.diagnostics);
   plannedEntities = plan.data.report.planned.length;
   filesScanned = plan.data.report.filesScanned;
@@ -116,6 +121,7 @@ export async function finalizeSetupWiki(
   // validation supplies the blocking diagnostic that keeps setup from writing
   // other files around a scaffold which is already structurally unsafe.
   const preflight = await engine.validate({ projectRoot });
+  throwIfSetupAborted(options.signal);
   // Every knowledge file outside the Wiki is either adopted by the migration
   // this run applies next or already reported above as one of its
   // abstentions, so telling the user to run `mex wiki migrate` here would be
@@ -128,7 +134,9 @@ export async function finalizeSetupWiki(
   }
 
   options.onProgress?.("Applying Wiki migration...");
+  throwIfSetupAborted(options.signal);
   const applied = await engine.applyMigration(plan.data);
+  throwIfSetupAborted(options.signal);
   collectDiagnostics(applied.diagnostics);
   migrated = migrationChangedFiles(applied).length > 0;
   if (!applied.data.applied || hasErrors(applied)) {
@@ -136,7 +144,9 @@ export async function finalizeSetupWiki(
   }
 
   options.onProgress?.("Rebuilding Wiki index...");
-  const rebuilt = await engine.rebuildIndex();
+  throwIfSetupAborted(options.signal);
+  const rebuilt = await engine.rebuildIndex(options.signal ? { signal: options.signal } : undefined);
+  throwIfSetupAborted(options.signal);
   collectDiagnostics(rebuilt.diagnostics);
   indexedEntities = rebuilt.data.entityCount;
   if (hasErrors(rebuilt)) {
@@ -144,7 +154,9 @@ export async function finalizeSetupWiki(
   }
 
   options.onProgress?.("Validating Wiki scaffold...");
+  throwIfSetupAborted(options.signal);
   const validated = await engine.validate({ projectRoot });
+  throwIfSetupAborted(options.signal);
   // An untyped context file was reported as a migration abstention above. A
   // file still not adopted after the migration is not expected, and is kept.
   collectDiagnostics(withoutAdoptionGaps(validated.diagnostics, ["KNOWLEDGE_UNTYPED"]));
diff --git a/src/wiki/grounding/adapter.ts b/src/wiki/grounding/adapter.ts
index 81e157cb..b954aef7 100644
--- a/src/wiki/grounding/adapter.ts
+++ b/src/wiki/grounding/adapter.ts
@@ -72,6 +72,8 @@ export interface GroundedNode {
  * what would make drift disappear behind a helpful-looking cache update.
  */
 export interface GroundingGraph {
+  /** A stable parse gap permits direct verified targets, but proves no absence. */
+  readonly incompleteReason?: string;
   /** The node under this id, or null when the graph has no such node. */
   getNode(nodeId: string): GroundedNode | null;
   /** The node's serialized fingerprint in this checkout, or null. */
diff --git a/src/wiki/grounding/provenance.ts b/src/wiki/grounding/provenance.ts
index 87953f40..058d0539 100644
--- a/src/wiki/grounding/provenance.ts
+++ b/src/wiki/grounding/provenance.ts
@@ -69,7 +69,16 @@ export function checkGroundingProvenance(
   if (graph === null) {
     return verifyGroundingProvenance(groundings, () => false);
   }
-  return verifyGroundingProvenance(groundings, (grounding) => isGraphDerivedGrounding(graph, grounding));
+  const failures: Array<string | undefined> = [];
+  const diagnostics = verifyGroundingProvenance(groundings, (grounding) => {
+    const verified = isGraphDerivedGrounding(graph, grounding);
+    if (!verified) failures.push(graph.getNode(grounding.node) === null ? graph.incompleteReason : undefined);
+    return verified;
+  });
+  return diagnostics.map((diagnostic, index) => failures[index]
+    ? { ...diagnostic, message: `${diagnostic.message} ${failures[index]}`,
+      remediation: "Fix the named incomplete files or exclude intentional fixtures, refresh the graph, then retry." }
+    : diagnostic);
 }
 
 /**
diff --git a/src/wiki/grounding/resolve.ts b/src/wiki/grounding/resolve.ts
index 970f798e..306196cf 100644
--- a/src/wiki/grounding/resolve.ts
+++ b/src/wiki/grounding/resolve.ts
@@ -95,6 +95,9 @@ export function resolveGrounding(
 
   const direct = graph.getNode(grounding.node);
   if (direct !== null) return compare(grounding, graph, direct, grounding.node, context);
+  if (graph.incompleteReason) {
+    return { state: "unresolved", health: "unverified", node: grounding.node, reason: graph.incompleteReason };
+  }
 
   // Tier-1 miss. The committed fingerprint is what finds the symbol again —
   // this is the job MinHash is actually for.
diff --git a/templates/SETUP.md b/templates/SETUP.md
index dd5d7040..8b8c5375 100644
--- a/templates/SETUP.md
+++ b/templates/SETUP.md
@@ -10,15 +10,17 @@ This scaffold is currently empty. Follow the steps below to populate it for your
 mex setup
 ```
 
-This opens the local browser Hub. Use `mex setup --cli` for terminal setup,
-or `mex setup --dry-run` for a read-only terminal preview.
+This opens the terminal setup HUD. Highlight your AI tool and press Enter to
+select it and start; Space optionally selects additional integrations. Use
+`mex setup --browser` for browser setup, or `mex setup --dry-run` for a read-only
+terminal preview. `--cli` remains an alias for the default terminal flow.
 
-The Hub handles the setup workflow:
+Setup runs the following steps, then opens the Hub for review and completion:
 1. Detects your project state without overwriting existing scaffold files
 2. Protects `.mex/graph.db*`, `.mex/wiki.db*`, and `.mex/local/` from Git
-3. Asks which AI tool you use and installs the right project instructions
+3. Installs the project instructions for your selected AI tools
 4. Scans the codebase and builds the local code graph
-5. Launches the first selected available Claude Code or Codex CLI, or shows a copyable prompt when no agent is available or the agent fails
+5. Hands the terminal to the first selected available Claude Code or Codex CLI; exiting the agent returns to MEX for file checks, with a manual prompt when population is incomplete (browser setup uses a background agent session)
 6. Captures grounding, migrates the populated Markdown, builds the Wiki index, and validates it
 7. Shows the exact setup diff for an explicit local commit, with a manual Git option
 8. Shows a completion guide, optional global install at the running version, and optional contact details before **Open Hub**
@@ -28,6 +30,12 @@ choose to send contact details; name is optional. Contact details go through the
 embedded form service and stay out of project files and usage telemetry.
 The introductory Hub tour begins after opening the full Hub.
 
+For scripts, use `--yes` and repeatable `--tool` flags (or `--tool none`).
+Piped input/output and CI also use plain output and never launch an agent or
+long-lived Hub. Exit 2 means population is pending; populate the scaffold and
+rerun setup to continue. Exit 0 means preparation is complete. Use
+`mex setup --browser` to open the commit and completion page afterward.
+
 For Claude Code and Codex, setup also copies the packaged `mex-inbox` and
 `mex-relay` skills into the project. No plugin or separate skill installer is
 needed. A plain `npm install` delivers the payload without changing the
diff --git a/test/fixtures/capabilities/not-git.json b/test/fixtures/capabilities/not-git.json
index 53d60100..93c70636 100644
--- a/test/fixtures/capabilities/not-git.json
+++ b/test/fixtures/capabilities/not-git.json
@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "ok": true,
   "data": {
-    "mexVersion": "0.8.3",
+    "mexVersion": "0.8.4",
     "repository": {
       "initializationState": "not_git_repository",
       "graphIndexState": "unavailable",
diff --git a/test/fixtures/capabilities/ready.json b/test/fixtures/capabilities/ready.json
index 609b0984..8eb3dd4e 100644
--- a/test/fixtures/capabilities/ready.json
+++ b/test/fixtures/capabilities/ready.json
@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "ok": true,
   "data": {
-    "mexVersion": "0.8.3",
+    "mexVersion": "0.8.4",
     "repository": {
       "initializationState": "ready",
       "graphIndexState": "fresh",
diff --git a/test/graph-grounding-source-drift.test.ts b/test/graph-grounding-source-drift.test.ts
index 112908bb..2b43720e 100644
--- a/test/graph-grounding-source-drift.test.ts
+++ b/test/graph-grounding-source-drift.test.ts
@@ -359,3 +359,53 @@ describe("check grounds against a graph stale only by changed source (#228)", ()
     expect(stale.warnings.join("\n")).toContain("grounding checks skipped");
   }, 120_000);
 });
+
+describe("check grounds against a graph with incompletely parsed files", () => {
+  const BROKEN = "export function partialTarget(): number { return 1; }\nexport const broken = ;\n";
+
+  it("keeps exact verdicts for fully parsed files and marks the parse gap unverified", async () => {
+    const { root, scaffold, config, ids } = await fixture();
+    const fresh = await check(config);
+    write(root, "src/fixtures/broken.ts", BROKEN);
+    await rebuild(root);
+    const degraded = await check(config);
+    expect(degraded.report.graphStatus.status).toBe("degraded");
+    // Before, a single unparseable fixture skipped every grounding and scored 100.
+    expect(verdicts(degraded.report, ids)).toEqual(verdicts(fresh.report, ids));
+    expect(verdicts(degraded.report, ids).predrifted).toBe("GROUNDING_DRIFT");
+    expect(degraded.warnings.join("\n")).toContain("groundings in incompletely parsed source files were marked unverified");
+
+    // A target inside the partial file, and one the graph lacks, cannot be settled.
+    const engine = createGraphEngine({ rootDir: root });
+    const partial = engine.searchNodes("partialTarget").find((node) => node.name === "partialTarget")!;
+    engine.close();
+    expect(partial.filePath).toBe("src/fixtures/broken.ts");
+    const template = extractGroundings(readFileSync(scaffold, "utf-8"))[0]!;
+    const missing = `function:${"0".repeat(32)}`;
+    writeFileSync(scaffold, writeGroundings(readFileSync(scaffold, "utf-8"), [
+      ...extractGroundings(readFileSync(scaffold, "utf-8")),
+      { ...template, node: partial.id },
+      { ...template, node: missing },
+    ]));
+    const gaps = await check(config);
+    const unverified = gaps.report.issues.filter((entry) => entry.code === "GROUNDING_UNVERIFIED");
+    expect(unverified.find((entry) => entry.message.includes(partial.id))!.message)
+      .toMatch(/cannot be verified while the graph has incomplete parses: .*src\/fixtures\/broken\.ts did not parse completely/u);
+    expect(unverified.find((entry) => entry.message.includes(missing))!.message)
+      .toContain("not in the graph, which could not fully parse src/fixtures/broken.ts");
+    expect(gaps.report.issues.some((entry) => entry.message.includes(missing) && entry.code !== "GROUNDING_UNVERIFIED"))
+      .toBe(false);
+    expect(gaps.report.score).toBeLessThan(degraded.report.score);
+  }, 120_000);
+
+  it("still detects a body edit when changed source and a parse gap combine", async () => {
+    const { root, config, ids } = await fixture();
+    write(root, "src/fixtures/broken.ts", BROKEN);
+    await rebuild(root);
+    applyEdits(root, { "py/body.py": EDITS["py/body.py"]! });
+    const both = await check(config);
+    expect(verdicts(both.report, ids).compute_total).toBe("GROUNDING_DRIFT");
+    expect(verdicts(both.report, ids).steady).toBe("OK");
+    expect(both.warnings.join("\n")).toContain("changed or incompletely parsed source files");
+  }, 120_000);
+});
diff --git a/test/helpers/setup-pty.py b/test/helpers/setup-pty.py
new file mode 100644
index 00000000..d7e7269e
--- /dev/null
+++ b/test/helpers/setup-pty.py
@@ -0,0 +1,158 @@
+"""Run one bounded terminal acceptance plan using only the Python standard library.
+
+The plan arrives on stdin as JSON. Actions wait for output, send terminal input,
+or signal only the CLI parent. Failure cleanup owns the entire PTY process group.
+"""
+
+import errno
+import fcntl
+import json
+import os
+import pty
+import re
+import select
+import signal
+import socket
+import struct
+import sys
+import termios
+import time
+import urllib.parse
+
+
+def main():
+    plan = json.load(sys.stdin)
+    child, master = pty.fork()
+    if child == 0:
+        try:
+            os.chdir(plan["cwd"])
+            environment = os.environ.copy()
+            for name in plan.get("unsetEnv", []):
+                environment.pop(name, None)
+            environment.update(plan.get("env", {}))
+            fcntl.ioctl(0, termios.TIOCSWINSZ, struct.pack("HHHH", plan.get("rows", 40), plan.get("columns", 140), 0, 0))
+            os.execvpe(plan["command"][0], plan["command"], environment)
+        except Exception as error:
+            os.write(2, str(error).encode())
+            os._exit(127)
+
+    output = bytearray()
+    events = []
+    status = None
+    eof = False
+    cursor = 0
+    failure = None
+    deadline = time.monotonic() + plan.get("timeoutMs", 20000) / 1000
+    max_bytes = plan.get("maxBytes", 1024 * 1024)
+
+    def poll():
+        nonlocal status
+        if status is None:
+            finished, value = os.waitpid(child, os.WNOHANG)
+            if finished:
+                status = value
+
+    def read_once(wait=0.05):
+        nonlocal eof
+        if not eof and select.select([master], [], [], wait)[0]:
+            try:
+                chunk = os.read(master, 65536)
+            except OSError as error:
+                if error.errno != errno.EIO:
+                    raise
+                chunk = b""
+            if chunk:
+                output.extend(chunk)
+                if len(output) > max_bytes:
+                    raise RuntimeError("PTY output exceeded its byte limit")
+            else:
+                eof = True
+        elif eof:
+            time.sleep(min(wait, 0.01))
+        poll()
+
+    def plain():
+        value = output.decode("utf-8", errors="replace")
+        value = re.sub(r"\x1b\][^\x07]*(?:\x07|\x1b\\)", "", value)
+        return re.sub(r"\x1b\[[0-?]*[ -/]*[@-~]", "", value).replace("\r", "")
+
+    def check_time():
+        if time.monotonic() >= deadline:
+            raise RuntimeError("PTY scenario timed out")
+
+    try:
+        for action in plan.get("actions", []):
+            event = {}
+            if "expect" in action:
+                pattern = action["expect"] if action.get("regex") else re.escape(action["expect"])
+                while True:
+                    match = re.search(pattern, plain()[cursor:])
+                    if match:
+                        cursor += match.end()
+                        event["match"] = match.group(0)
+                        break
+                    check_time()
+                    if status is not None and eof:
+                        raise RuntimeError("CLI exited before expected output: " + action["expect"])
+                    read_once()
+            for path in action.get("missing", []):
+                if os.path.lexists(os.path.join(plan["cwd"], path)):
+                    raise RuntimeError("Setup wrote before confirmation: " + path)
+            if action.get("quietMs"):
+                start = len(output)
+                until = time.monotonic() + action["quietMs"] / 1000
+                while time.monotonic() < until:
+                    check_time()
+                    read_once(min(0.05, max(0, until - time.monotonic())))
+                event["quietOutput"] = output[start:].decode("utf-8", errors="replace")
+            if action.get("probe"):
+                address = urllib.parse.urlsplit(event["match"])
+                with socket.create_connection((address.hostname, address.port), timeout=2):
+                    event["connected"] = True
+            if "input" in action:
+                # A frame can be painted before React installs its input effect.
+                # Model a human keypress, rather than injecting into that gap.
+                until = time.monotonic() + action.get("settleMs", 100) / 1000
+                while time.monotonic() < until:
+                    check_time()
+                    read_once(min(0.02, max(0, until - time.monotonic())))
+                os.write(master, action["input"].encode())
+            if "signal" in action:
+                os.kill(child, getattr(signal, action["signal"]))
+            events.append(event)
+        while status is None:
+            check_time()
+            read_once()
+        # Capture the closing summary without waiting on a potentially leaked child.
+        until = time.monotonic() + 0.2
+        while not eof and time.monotonic() < until:
+            read_once()
+    except Exception as error:
+        failure = str(error)
+        try:
+            os.killpg(child, signal.SIGTERM)
+        except ProcessLookupError:
+            pass
+        until = time.monotonic() + 0.75
+        while status is None and time.monotonic() < until:
+            read_once()
+        try:
+            os.killpg(child, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        if status is None:
+            _, status = os.waitpid(child, 0)
+    finally:
+        os.close(master)
+
+    json.dump({
+        "exitCode": os.waitstatus_to_exitcode(status),
+        "output": plain(),
+        "raw": output.decode("utf-8", errors="replace"),
+        "events": events,
+        "error": failure,
+    }, sys.stdout)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/test/hub-e2e/setup-commit.spec.ts b/test/hub-e2e/setup-commit.spec.ts
index 59fe42b9..1f9dfd2b 100644
--- a/test/hub-e2e/setup-commit.spec.ts
+++ b/test/hub-e2e/setup-commit.spec.ts
@@ -22,6 +22,57 @@ const architectureAfter = architectureBefore.replace(architectureRemoved, `${arc
 interface CommitPreview { revision: string; files: Array<{ path: string; status: string }>; }
 
 test.describe("built setup commit checkpoint", () => {
+  test("terminal-finalized projects reach review, then completion after the canonical commit", async ({ page }) => {
+    const fixture = createFixture({ existingScaffold: true });
+    let hub: ChildProcess | undefined;
+    try {
+      rmSync(join(fixture.project, ".mex/graph.db"));
+      rmSync(join(fixture.project, ".mex/wiki.db"));
+      const terminal = spawnSync(process.execPath, [join(repositoryRoot, "dist/cli.js"), "setup", "--cli", "--yes", "--tool", "none"], {
+        cwd: fixture.project, env: fixture.env, encoding: "utf8", timeout: 20_000,
+      });
+      expect(terminal.status, terminal.stderr + terminal.stdout).toBe(0);
+      expect(terminal.stdout).toContain("Graph and Wiki are ready");
+      assertUnrelatedPreserved(fixture);
+      hub = (await openFixtureHub(page, fixture)).hub;
+      await expect(page.getByRole("button", { name: "Review setup changes", exact: true })).toBeVisible();
+      await expect(page.getByRole("region", { name: "Background session output", exact: true })).toHaveCount(0);
+      // Checking the outstanding commit is not an agent session. It must not
+      // manufacture an empty transcript, including after reconnecting the page.
+      await page.getByText("Commit manually", { exact: true }).click();
+      await page.getByRole("button", { name: "Check commit and continue", exact: true }).click();
+      await expect(page.getByRole("button", { name: "Review setup changes", exact: true })).toBeVisible();
+      await expect.poll(async () => {
+        const response = await page.request.get(new URL("/api/v1/setup/run", page.url()).href);
+        expect(response.ok()).toBe(true);
+        const run = await response.json();
+        return { status: run.status, transcriptId: run.transcriptId ?? null };
+      }).toEqual({ status: "paused", transcriptId: null });
+      await expect(page.getByRole("region", { name: "Background session output", exact: true })).toHaveCount(0);
+      await expect(page.getByText("This session produced no output.", { exact: true })).toHaveCount(0);
+      await page.reload();
+      await expect(page.getByRole("button", { name: "Review setup changes", exact: true })).toBeVisible();
+      await expect(page.getByRole("region", { name: "Background session output", exact: true })).toHaveCount(0);
+      expect(existsSync(join(fixture.root, "provider-invoked"))).toBe(false);
+      await stopHub(hub);
+      // An explicit fixture Git checkpoint models the user's manual commit path.
+      git(fixture, "add", "--", ".mex");
+      git(fixture, "commit", "--quiet", "--only", "-m", "Accept terminal setup", "--", ".mex");
+      assertUnrelatedPreserved(fixture);
+      const opened = await openFixtureHub(page, fixture, false);
+      hub = opened.hub;
+      await expect(page.getByRole("heading", { name: "You’re ready", exact: true })).toBeVisible();
+      await expect(page.getByLabel("Email", { exact: true })).toBeVisible();
+      await expect(page.getByRole("region", { name: "Background session output", exact: true })).toHaveCount(0);
+      await page.getByRole("button", { name: "Open Hub", exact: true }).click();
+      await expect(page.getByRole("heading", { name: "Overview", exact: true })).toBeVisible();
+      expect(existsSync(join(fixture.root, "provider-invoked"))).toBe(false);
+    } finally {
+      try { if (hub) await stopHub(hub); }
+      finally { rmSync(fixture.root, { recursive: true, force: true }); }
+    }
+  });
+
   test("reviews and commits only setup files while preserving unrelated staged work", async ({ page }, testInfo) => {
     const fixture = createFixture();
     let hub: ChildProcess | undefined;
@@ -293,8 +344,8 @@ function gitBytes(fixture: GitFixture, ...args: string[]): Buffer {
 function git(fixture: GitFixture, ...args: string[]): string { return gitBytes(fixture, ...args).toString("utf8"); }
 function shellQuote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
 
-async function openFixtureHub(page: Page, fixture: Fixture) {
-  const hub = spawn(process.execPath, [join(repositoryRoot, "dist/cli.js"), "setup", "--no-open"], {
+async function openFixtureHub(page: Page, fixture: Fixture, expectReview = true) {
+  const hub = spawn(process.execPath, [join(repositoryRoot, "dist/cli.js"), "setup", "--browser", "--no-open"], {
     cwd: fixture.project, env: fixture.env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true,
   });
   try {
@@ -305,7 +356,7 @@ async function openFixtureHub(page: Page, fixture: Fixture) {
     page.on("pageerror", (error) => pageErrors.push(error.message));
     page.on("request", (request) => { if (new URL(request.url()).origin !== origin) externalRequests.push(request.url()); });
     await page.goto(bootstrap);
-    await expect(page.getByRole("button", { name: "Review setup changes", exact: true })).toBeVisible();
+    if (expectReview) await expect(page.getByRole("button", { name: "Review setup changes", exact: true })).toBeVisible();
     return { hub, origin, pageErrors, externalRequests };
   } catch (error) { await stopHub(hub); throw error; }
 }
diff --git a/test/setup-cli-routing.test.ts b/test/setup-cli-routing.test.ts
index 87642088..694dbd7c 100644
--- a/test/setup-cli-routing.test.ts
+++ b/test/setup-cli-routing.test.ts
@@ -1,22 +1,26 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-const mocks = vi.hoisted(() => ({ hub: vi.fn(), setup: vi.fn(), tui: vi.fn(), capture: vi.fn() }));
+const mocks = vi.hoisted(() => ({ hub: vi.fn(), setup: vi.fn(), entry: vi.fn(), parseTools: vi.fn(), tui: vi.fn(), capture: vi.fn() }));
 vi.mock("../src/hub/command.js", () => ({ launchHub: mocks.hub }));
-vi.mock("../src/setup/index.js", () => ({ runSetup: mocks.setup }));
+vi.mock("../src/setup/index.js", () => ({ runSetup: mocks.setup, parseSetupTools: mocks.parseTools }));
+vi.mock("../src/setup/entry.js", () => ({ resolveDefaultEntry: mocks.entry }));
 vi.mock("../src/tui.js", () => ({ launchTui: mocks.tui }));
 vi.mock("../src/telemetry/index.js", async (original) => ({
   ...await original<typeof import("../src/telemetry/index.js")>(), captureEvent: mocks.capture, flush: async () => {},
 }));
 
-beforeEach(() => { vi.resetModules(); vi.clearAllMocks(); vi.stubEnv("MEX_TELEMETRY", "0"); });
+beforeEach(() => {
+  vi.resetModules(); vi.clearAllMocks(); vi.stubEnv("MEX_TELEMETRY", "0");
+  mocks.setup.mockResolvedValue({ outcome: "complete", message: "Setup complete.", exitCode: 0 });
+  mocks.entry.mockResolvedValue("setup");
+  mocks.parseTools.mockImplementation((tools: string[]) => tools.includes("none") ? [] : tools);
+});
 afterEach(() => { vi.unstubAllEnvs(); vi.restoreAllMocks(); process.exitCode = 0; });
 
 describe("setup entry points", () => {
   it.each([
-    [[], { openBrowser: true }],
-    [["--no-open", "--port", "48123"], { openBrowser: false, port: 48123 }],
-    [["setup"], { openBrowser: true, setup: true }],
-    [["setup", "--mode", "agent-memory", "--no-open", "--port", "48124"], { openBrowser: false, setup: true, mode: "agent-memory", port: 48124 }],
+    [["setup", "--browser"], { openBrowser: true, setup: true }],
+    [["setup", "--browser", "--mode", "agent-memory", "--no-open", "--port", "48124"], { openBrowser: false, setup: true, mode: "agent-memory", port: 48124 }],
     [["hub", "--no-open"], { openBrowser: false }],
   ] as const)("launches the browser flow for %j", async (args, options) => {
     const { program } = await import("../src/cli.js");
@@ -25,13 +29,43 @@ describe("setup entry points", () => {
     expect(mocks.setup).not.toHaveBeenCalled();
     expect(mocks.tui).not.toHaveBeenCalled();
     expect(mocks.capture).not.toHaveBeenCalled();
+    expect(mocks.entry).not.toHaveBeenCalled();
+  });
+
+  it.each(["setup", "hub"] as const)("opens the correct default surface for a checkout needing %s", async (entry) => {
+    mocks.entry.mockResolvedValue(entry);
+    const { program } = await import("../src/cli.js");
+    await program.parseAsync(["--no-open", "--port", "48123"], { from: "user" });
+    expect(mocks.entry).toHaveBeenCalledExactlyOnceWith();
+    if (entry === "setup") {
+      expect(mocks.setup).toHaveBeenCalledExactlyOnceWith({ dryRun: undefined, mode: undefined, port: 48123, openBrowser: false });
+      expect(mocks.hub).not.toHaveBeenCalled();
+    } else {
+      expect(mocks.hub).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ port: 48123, openBrowser: false }));
+      expect(mocks.setup).not.toHaveBeenCalled();
+    }
   });
 
-  it.each([["setup", "--cli"], ["setup", "--dry-run"], ["setup", "--cli", "--mode", "agent-memory"]])("keeps terminal setup for %j", async (...args) => {
+  it.each([["setup"], ["setup", "--cli"], ["setup", "--dry-run"], ["setup", "--mode", "agent-memory"]])("uses terminal setup for %j", async (...args) => {
     const { program } = await import("../src/cli.js");
     await program.parseAsync(args, { from: "user" });
-    expect(mocks.setup).toHaveBeenCalledExactlyOnceWith({ dryRun: args.includes("--dry-run") || undefined, mode: args.includes("--mode") ? "agent-memory" : undefined });
+    expect(mocks.setup).toHaveBeenCalledExactlyOnceWith({
+      dryRun: args.includes("--dry-run") || undefined,
+      mode: args.includes("--mode") ? "agent-memory" : undefined,
+      port: undefined, openBrowser: true,
+    });
+    expect(mocks.hub).not.toHaveBeenCalled();
+    expect(mocks.entry).not.toHaveBeenCalled();
+  });
+
+  it.each([["--cli"], ["--dry-run"], ["--yes"], ["--tool", "codex"]])("rejects browser setup combined with terminal option %s", async (...flags) => {
+    const { program } = await import("../src/cli.js");
+    const command = program.commands.find(command => command.name() === "setup")!;
+    command.exitOverride().configureOutput({ writeErr: () => {} });
+    await expect(program.parseAsync(["setup", "--browser", ...flags], { from: "user" }))
+      .rejects.toMatchObject({ code: "commander.conflictingOption" });
     expect(mocks.hub).not.toHaveBeenCalled();
+    expect(mocks.setup).not.toHaveBeenCalled();
   });
 
   it("keeps the TUI explicitly available", async () => {
@@ -41,11 +75,62 @@ describe("setup entry points", () => {
     expect(mocks.hub).not.toHaveBeenCalled();
   });
 
-  it("rejects browser flags with a terminal dry run before either action", async () => {
+  it.each(["--cli", "--dry-run", "--yes"])("passes finishing Hub options to terminal setup with %s", async (flag) => {
+    const { program } = await import("../src/cli.js");
+    await program.parseAsync(["setup", flag, "--no-open", "--port", "48125"], { from: "user" });
+    expect(mocks.setup).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ port: 48125, openBrowser: false }));
+    expect(mocks.hub).not.toHaveBeenCalled();
+    expect(process.exitCode).toBe(0);
+  });
+
+  it("retains explicit empty tool selection for terminal setup", async () => {
+    const { program } = await import("../src/cli.js");
+    await program.parseAsync(["setup", "--tool", "none", "--no-open"], { from: "user" });
+    expect(mocks.parseTools).toHaveBeenCalledExactlyOnceWith(["none"]);
+    expect(mocks.setup).toHaveBeenCalledExactlyOnceWith(expect.objectContaining({ tools: [], openBrowser: false }));
+    expect(mocks.hub).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["complete", 0], ["paused", 2], ["cancelled", 130], ["failed", 1], ["dry-run", 0],
+  ])("maps the %s result to its exit code", async (outcome, exitCode) => {
+    const { program } = await import("../src/cli.js");
+    mocks.setup.mockResolvedValue({ outcome, exitCode, message: "Setup result." });
+    await program.parseAsync(["setup"], { from: "user" });
+    expect(process.exitCode).toBe(exitCode);
+  });
+
+  it("handles a failed bare-command inspection without starting setup or the Hub", async () => {
+    const { program } = await import("../src/cli.js");
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    mocks.entry.mockRejectedValue(new Error("Could not inspect the project."));
+    await program.parseAsync([], { from: "user" });
+    expect(process.exitCode).toBe(1);
+    expect(error).toHaveBeenCalledWith("Could not inspect the project.");
+    expect(mocks.setup).not.toHaveBeenCalled();
+    expect(mocks.hub).not.toHaveBeenCalled();
+  });
+
+  it("reports thrown terminal setup failures with exit code one", async () => {
+    const { program } = await import("../src/cli.js");
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    mocks.setup.mockRejectedValue(new Error("Setup could not start."));
+    await program.parseAsync(["setup", "--cli"], { from: "user" });
+    expect(process.exitCode).toBe(1);
+    expect(error).toHaveBeenCalledWith("Setup could not start.");
+    expect(mocks.hub).not.toHaveBeenCalled();
+  });
+
+  it("prints recovery instructions before local diagnostics for expected terminal failures", async () => {
     const { program } = await import("../src/cli.js");
-    vi.spyOn(console, "error").mockImplementation(() => {});
-    await program.parseAsync(["setup", "--dry-run", "--no-open"], { from: "user" });
+    const { SetupError } = await import("../src/setup/errors.js");
+    const error = vi.spyOn(console, "error").mockImplementation(() => {});
+    mocks.setup.mockRejectedValue(new SetupError("EACCES: /local/config", { userMessage: "Could not save configuration. Fix its permissions and retry setup." }));
+    await program.parseAsync(["setup", "--cli", "--yes"], { from: "user" });
+    expect(error.mock.calls).toEqual([
+      ["Could not save configuration. Fix its permissions and retry setup."],
+      ["Diagnostics: EACCES: /local/config"],
+    ]);
     expect(process.exitCode).toBe(1);
-    expect(mocks.hub).not.toHaveBeenCalled(); expect(mocks.setup).not.toHaveBeenCalled();
   });
 });
diff --git a/test/setup-terminal-pty.test.ts b/test/setup-terminal-pty.test.ts
new file mode 100644
index 00000000..c151094c
--- /dev/null
+++ b/test/setup-terminal-pty.test.ts
@@ -0,0 +1,438 @@
+import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createConnection } from "node:net";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { afterEach, beforeAll, describe, expect, it } from "vitest";
+
+const repo = fileURLToPath(new URL("..", import.meta.url));
+const cli = join(repo, "dist/cli.js");
+const harness = join(repo, "test/helpers/setup-pty.py");
+const python = process.platform === "win32" ? undefined : spawnSync("python3", ["-c", "import pty, termios, sys; print(sys.executable)"], { encoding: "utf8", timeout: 3000 });
+const pythonPath = python?.status === 0 ? python.stdout.trim() : undefined;
+const skipReason = process.platform === "win32" ? "requires a POSIX PTY" : !pythonPath ? "requires Python 3 with pty/termios" : undefined;
+const fixtures: Fixture[] = [];
+
+interface Fixture { root: string; project: string; record: string; env: NodeJS.ProcessEnv; cli?: string; workerRecord?: string }
+interface Action { expect?: string; regex?: boolean; missing?: string[]; quietMs?: number; input?: string; signal?: string; probe?: boolean }
+interface Result { exitCode: number; output: string; raw: string; error: string | null; events: { match?: string; quietOutput?: string; connected?: boolean }[] }
+interface AgentRecord { pid: number; agent: string; stdinTTY: boolean; stdoutTTY: boolean; stderrTTY: boolean; canonical: boolean; echo: boolean; input?: string; argv: string[]; promptExists: boolean }
+
+beforeAll(() => {
+  if (!skipReason && !existsSync(cli)) throw new Error("Build dist/cli.js with npm run build before running the terminal PTY acceptance tests.");
+});
+afterEach(() => {
+  for (const fixture of fixtures.splice(0)) {
+    if (existsSync(fixture.record)) {
+      const record = agentRecord(fixture);
+      // Only a failed acceptance can leave its fake agent behind.
+      if (isAlive(record.pid)) { try { process.kill(record.pid, "SIGKILL"); } catch {} }
+    }
+    if (fixture.workerRecord && existsSync(fixture.workerRecord)) {
+      const record = JSON.parse(readFileSync(fixture.workerRecord, "utf8")) as { pid: number };
+      if (isAlive(record.pid)) { try { process.kill(record.pid, "SIGKILL"); } catch {} }
+    }
+    rmSync(fixture.root, { recursive: true, force: true });
+  }
+});
+
+describe.skipIf(Boolean(skipReason))(`built terminal setup acceptance${skipReason ? ` (${skipReason})` : ""}`, { timeout: 35_000 }, () => {
+  it.each([
+    { entry: "mex setup", command: ["setup"] },
+    { entry: "bare mex", command: [] },
+  ])("$entry shows the ASCII banner and choices at 80x24 before any setup writes, then cancels cleanly", async ({ command }) => {
+    const f = fixture("incomplete");
+    const result = await terminal(f, [], [{ expect: "Choose your AI tools", missing: [".mex", ".agents", "AGENTS.md", ".gitignore"], input: "\u0003" }], { columns: 80, rows: 24, command });
+    expect(result.exitCode, result.output).toBe(130);
+    expect(result.output).toContain("88888b.d88b.   .d88b.  888  888");
+    expect(result.output).toContain("Codex");
+    expect(result.output).toContain("Space multi-select");
+    expect(result.output).toContain("Setup cancelled.");
+    expect(readdirSync(f.project)).toEqual([]);
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("Ctrl+D on the configuration screen cancels without creating files", async () => {
+    const f = fixture("incomplete");
+    const result = await terminal(f, [], [{ expect: "Choose your AI tools", missing: [".mex"], input: "\u0004" }]);
+    expect(result.exitCode, result.output).toBe(130);
+    expect(result.output).toContain("Setup cancelled.");
+    expect(readdirSync(f.project)).toEqual([]);
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("Ctrl+D at the manual prompt cancels instead of returning to a stranded recovery menu", async () => {
+    const f = fixture("incomplete");
+    const result = await terminal(f, ["--tool", "none"], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "> Show setup prompt", input: "\r" },
+      { expect: "Press Enter to return to MEX", input: "\u0004" },
+    ]);
+    expect(result.exitCode, result.output).toBe(130);
+    expect(result.output).toContain("Copy this prompt into your AI tool");
+    expect(result.output).toContain("Setup cancelled.");
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("accepts the first HUD key after returning from the manual prompt", async () => {
+    const f = fixture("incomplete");
+    const result = await terminal(f, ["--tool", "none"], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "> Show setup prompt", input: "\r" },
+      { expect: "Press Enter to return to MEX", input: "\r" },
+      { expect: "> Show setup prompt", input: "\u001b[A" },
+      { expect: "> Finish later", input: "\r" },
+    ]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Setup paused at population");
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it.each([
+    { description: "a fresh project", savedTools: [] },
+    { description: "a project with Claude already selected", savedTools: ["claude"] },
+  ])("Enter selects and starts highlighted Codex in $description without pressing Space", async ({ savedTools }) => {
+    const f = fixture("incomplete");
+    if (savedTools.length) {
+      mkdirSync(join(f.project, ".mex"));
+      writeFileSync(join(f.project, ".mex/config.json"), JSON.stringify({ aiTools: savedTools, setupMode: "agent-memory" }));
+    }
+    const result = await terminal(f, [], [
+      { expect: `> [${savedTools.length ? "x" : " "}] Claude Code`, input: "\u001b[B" },
+      { expect: "> [ ] Cursor", input: "\u001b[B" },
+      { expect: "> [ ] Windsurf", input: "\u001b[B" },
+      { expect: "> [ ] Copilot", input: "\u001b[B" },
+      { expect: "> [ ] OpenCode", input: "\u001b[B" },
+      { expect: "> [ ] Codex", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", input: "selected with Enter\n" },
+      { expect: "required scaffold placeholders remain", input: "\u001b[A" },
+      { expect: "> Finish later", input: "\r" },
+    ], { defaultTool: false });
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Opening Codex");
+    expect(result.output).not.toContain("Opening Claude Code");
+    expect(agentRecord(f)).toMatchObject({ agent: "codex", stdinTTY: true, canonical: true, input: "selected with Enter" });
+    expect(JSON.parse(readFileSync(join(f.project, ".mex/config.json"), "utf8")).aiTools).toEqual(["codex", ...savedTools]);
+    expectPromptCleaned(f);
+  });
+
+  it("hands a cooked real terminal to Codex, accepts keyboard input, and recovers from incomplete exit zero", async () => {
+    const f = fixture("incomplete");
+    const result = await terminal(f, [], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", quietMs: 1250, input: "hello native agent\n" },
+      { expect: "required scaffold placeholders remain", input: "\u001b[B" },
+      { expect: "> Show setup prompt", input: "\u001b[B" },
+      { expect: "> Check populated files", input: "\r" },
+      { expect: "Required scaffold placeholders remain", input: "\u001b[B" },
+      { expect: "> Finish later", input: "\r" },
+    ]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.events[1].quietOutput).toBe("");
+    expect(agentRecord(f)).toMatchObject({ stdinTTY: true, stdoutTTY: true, stderrTTY: true, canonical: true, echo: true, input: "hello native agent", promptExists: true });
+    expect(agentRecord(f).argv.join(" ")).toContain("Read the full setup population prompt");
+    const nativeOutput = result.raw.split("MEX_PTY_CHILD_READY")[1]?.split("MEX_PTY_CHILD_DONE")[0];
+    expect(nativeOutput).toContain("hello native agent");
+    expect(nativeOutput).not.toContain("PROJECT MEMORY / SETUP");
+    expect(nativeOutput).not.toContain("\u001b[?1049h");
+    expect(result.output).toContain("Run `mex setup` to continue");
+    expect(JSON.parse(readFileSync(join(f.project, ".mex/config.json"), "utf8")).aiTools).toEqual(["codex"]);
+    expectPromptCleaned(f);
+  });
+
+  it("returns to recovery after a nonzero native agent exit and pauses on Finish later", async () => {
+    const f = fixture("failed");
+    const result = await terminal(f, [], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", input: "finish\n" },
+      { expect: "Codex stopped before a clean exit", input: "\u001b[A" },
+      { expect: "> Finish later", input: "\r" },
+    ]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Setup paused at population");
+    expect(result.output).toContain("Show setup prompt");
+    expect(result.output).toContain("Run `mex setup` to continue");
+    expectPromptCleaned(f);
+  });
+
+  it("validates populated files, exposes the finishing Hub URL, and closes its listener with q", async () => {
+    const f = fixture("complete");
+    const result = await terminal(f, [], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", input: "populate\n" },
+      { expect: "http://127\\.0\\.0\\.1:[0-9]+/#token=[A-Za-z0-9_-]+", regex: true, probe: true, input: "q" },
+    ]);
+    expect(result.exitCode, result.output).toBe(0);
+    expect(result.output).toContain("Continue in your browser");
+    expect(result.events[2].connected).toBe(true);
+    expect(result.output).toContain("Hub stopped");
+    expect(existsSync(join(f.root, "browser-open"))).toBe(false);
+    const address = new URL(result.events[2].match!);
+    expect(await canConnect(Number(address.port))).toBe(false);
+    expect(readFileSync(join(f.project, ".mex/AGENTS.md"), "utf8")).not.toContain("[YYYY-MM-DD]");
+    expect(existsSync(join(f.project, ".mex/graph.db"))).toBe(false);
+    expect(existsSync(join(f.project, ".mex/wiki.db"))).toBe(false);
+    expectPromptCleaned(f);
+  });
+
+  it("shows a clean copyable Hub link at 60x16 and exits after returning to the HUD", async () => {
+    const f = fixture("complete");
+    const result = await terminal(f, [], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", input: "populate\n" },
+      { expect: "Continue in your browser", input: "l" },
+      { expect: "Hub link \\(keep it private\\):\\n(http://127\\.0\\.0\\.1:[0-9]+/#token=[A-Za-z0-9_-]{43})\\n", regex: true },
+      { expect: "Press Enter to return to MEX", input: "\r" },
+      { expect: "Continue in your browser", input: "q" },
+    ], { columns: 60, rows: 16 });
+    expect(result.exitCode, result.output).toBe(0);
+    const link = result.events[3].match!.split("\n")[1];
+    expect(result.raw).toContain(`Hub link (keep it private):\r\n${link}\r\n`);
+    expect(result.output).toContain("Setup complete. Hub stopped.");
+    const address = new URL(link);
+    expect(await canConnect(Number(address.port))).toBe(false);
+    expectPromptCleaned(f);
+  });
+
+  it("SIGTERM stops the CLI and its active native child before removing the private prompt", async () => {
+    const f = fixture("hold");
+    const result = await terminal(f, [], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "MEX_PTY_CHILD_READY", signal: "SIGTERM" },
+    ]);
+    expect(result.exitCode, result.output).toBe(143);
+    expect(result.output).toContain("Setup cancelled.");
+    expect(isAlive(agentRecord(f).pid)).toBe(false);
+    expectPromptCleaned(f);
+  });
+
+  it("--yes remains plain in a real terminal, writes scaffold files, and never starts an agent", async () => {
+    const f = fixture("complete");
+    const result = await terminal(f, ["--yes"]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Setup paused");
+    expect(result.output).toContain("Population prompt:");
+    expect(result.output).not.toContain("Choose your AI tools");
+    expect(result.raw).not.toContain("\u001b[?1049h");
+    expect(existsSync(join(f.project, ".mex/config.json"))).toBe(true);
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("shows real code graph parsing progress before pausing for manual population", async () => {
+    const f = fixture("incomplete");
+    codeRepository(f);
+    const result = await terminal(f, ["--mode", "code-repo", "--tool", "none"], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "Parsing source files" },
+      { expect: "files parsed" },
+      { expect: "> Show setup prompt", input: "\u001b[A" },
+      { expect: "> Finish later", input: "\r" },
+    ]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Code graph");
+    expect(result.output).toMatch(/\d+\s*\/\s*20\s+files parsed/);
+    expect(result.output).not.toContain("Setup needs attention");
+    expect(existsSync(join(f.project, ".mex/graph.db"))).toBe(true);
+    expect(existsSync(join(f.project, ".mex/wiki.db"))).toBe(false);
+    expect(existsSync(f.record)).toBe(false);
+    expect(() => execFileSync("git", ["rev-parse", "HEAD"], { cwd: f.project, stdio: "ignore" })).toThrow();
+  });
+
+  it("prints real graph phases and final file counts in plain code-repository setup", async () => {
+    const f = fixture("incomplete");
+    codeRepository(f);
+    const result = await terminal(f, ["--mode", "code-repo", "--tool", "none", "--yes"]);
+    expect(result.exitCode, result.output).toBe(2);
+    expect(result.output).toContain("Parsing source files: 0 / 20 files parsed");
+    expect(result.output).toContain("Parsing source files: 20 / 20 files parsed");
+    expect(result.output).toContain("Resolving code references");
+    expect(result.output).toContain("Validating the rebuilt graph");
+    expect(result.output).toContain("Saving the verified graph");
+    expect(result.output).toContain("Population prompt:");
+    expect(result.output).not.toContain("Choose your AI tools");
+    expect(existsSync(join(f.project, ".mex/graph.db"))).toBe(true);
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("shows a graph worker heap-limit failure and retains its diagnostics after leaving the HUD", async () => {
+    const f = fixture("incomplete");
+    codeRepository(f, 3);
+    // Keep this copied runtime outside the indexed project. Only its worker is
+    // replaced; the actual built CLI, supervisor, setup engine, and HUD run.
+    const runtime = join(f.root, "runtime");
+    mkdirSync(runtime);
+    cpSync(join(repo, "dist"), join(runtime, "dist"), { recursive: true });
+    symlinkSync(join(repo, "node_modules"), join(runtime, "node_modules"), "dir");
+    symlinkSync(join(repo, "templates"), join(runtime, "templates"), "dir");
+    cpSync(join(repo, "package.json"), join(runtime, "package.json"));
+    f.cli = join(runtime, "dist/cli.js");
+    f.workerRecord = join(f.root, "graph-worker.json");
+    f.env.MEX_PTY_GRAPH_RECORD = f.workerRecord;
+    writeFileSync(join(runtime, "dist/graph-candidate.js"), String.raw`
+import { writeFileSync, writeSync } from "node:fs";
+process.once("message", request => {
+  writeFileSync(process.env.MEX_PTY_GRAPH_RECORD, JSON.stringify({ pid: process.pid, workspace: request.workspace, candidatePath: request.candidatePath }));
+  writeFileSync(request.candidatePath, "unpublished partial candidate\n");
+  process.send({ type: "progress", progress: { phase: "parse", completed: 1, total: 3 } }, () => {
+    writeSync(2, "FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory\nMEX_PTY_HEAP_SENTINEL\n");
+    process.exit(17);
+  });
+});
+process.send({ type: "ready" });
+`);
+
+    const result = await terminal(f, ["--mode", "code-repo", "--tool", "none"], [
+      { expect: "Choose your AI tools", input: "\r" },
+      { expect: "heap limit" },
+      { expect: "d diagnostics", input: "d" },
+      { expect: "Details" },
+      { expect: "MEX_PTY_HEAP_SENTINEL", input: "d" },
+      { expect: "> Retry setup", input: "\u001b[B" },
+      { expect: "> Exit setup", input: "\r" },
+    ], { columns: 80, rows: 24 });
+
+    expect(result.exitCode, result.output).toBe(1);
+    expect(result.output).toContain("Setup needs attention");
+    expect(result.output).toContain("d diagnostics");
+    expect(result.output).toContain("NODE_OPTIONS=--max-old-space-size");
+    // Assertions after the final alternate-screen exit prove these details
+    // survive teardown, rather than existing only in a discarded HUD frame.
+    const exitScreen = "\u001b[?1049l";
+    expect(result.raw).toContain(exitScreen);
+    const restoredAt = result.raw.lastIndexOf(exitScreen);
+    expect(result.raw.slice(0, restoredAt)).toContain("JavaScript heap limit");
+    expect(result.raw.slice(0, restoredAt)).toContain("d diagnostics");
+    const summary = result.raw.slice(restoredAt + exitScreen.length);
+    expect(summary).toContain("JavaScript heap limit");
+    expect(summary).toContain("last progress: parse 1/3 files");
+    expect(summary).toContain("MEX_PTY_HEAP_SENTINEL");
+    expect(summary).toContain("FATAL ERROR: Reached heap limit");
+    expect(existsSync(f.record)).toBe(false);
+    expect(existsSync(join(f.project, ".mex/graph.db"))).toBe(false);
+    const worker = JSON.parse(readFileSync(f.workerRecord, "utf8")) as { pid: number; workspace: string; candidatePath: string };
+    expect(isAlive(worker.pid)).toBe(false);
+    expect(existsSync(worker.workspace)).toBe(false);
+    expect(existsSync(worker.candidatePath)).toBe(false);
+    expect(readdirSync(join(f.project, ".mex")).filter(name => name.startsWith("graph.db"))).toEqual([]);
+  });
+
+  it("piped terminal setup uses the plain path without waiting or launching an agent", () => {
+    const f = fixture("complete");
+    const result = spawnSync(process.execPath, [cli, ...args()], { cwd: f.project, env: f.env, encoding: "utf8", timeout: 20_000, maxBuffer: 1024 * 1024 });
+    expect(result.error).toBeUndefined();
+    expect(result.status, result.stdout + result.stderr).toBe(2);
+    expect(result.stdout).toContain("Setup paused");
+    expect(result.stdout).not.toContain("Choose your AI tools");
+    expect(existsSync(join(f.project, ".mex/config.json"))).toBe(true);
+    expect(existsSync(f.record)).toBe(false);
+  });
+
+  it("--dry-run remains read-only in a real terminal and never starts an agent", async () => {
+    const f = fixture("complete");
+    const result = await terminal(f, ["--dry-run"]);
+    expect(result.exitCode, result.output).toBe(0);
+    expect(result.output).toContain("DRY RUN");
+    expect(result.output).toContain("Dry run complete");
+    expect(result.output).not.toContain("Choose your AI tools");
+    expect(result.raw).not.toContain("\u001b[?1049h");
+    expect(readdirSync(f.project)).toEqual([]);
+    expect(existsSync(f.record)).toBe(false);
+  });
+});
+
+function args(extra: string[] = [], defaultTool = true): string[] {
+  return ["setup", ...(extra.includes("--mode") ? [] : ["--mode", "agent-memory"]), ...(!defaultTool || extra.includes("--tool") ? [] : ["--tool", "codex"]), "--no-open", ...extra];
+}
+
+function codeRepository(f: Fixture, files = 20): void {
+  execFileSync("git", ["-c", "init.templateDir=", "init", "--quiet"], { cwd: f.project, stdio: "pipe", env: f.env });
+  mkdirSync(join(f.project, "src"));
+  for (let index = 0; index < files; index++) {
+    writeFileSync(join(f.project, "src", `module-${index}.ts`), `export function calculate${index}(value: number): number { return value + ${index}; }\n`);
+  }
+}
+
+function fixture(mode: "incomplete" | "failed" | "complete" | "hold"): Fixture {
+  const root = mkdtempSync(join(tmpdir(), "mex-setup-pty-"));
+  const project = join(root, "project");
+  const bin = join(root, "bin");
+  const record = join(root, "agent.json");
+  mkdirSync(project); mkdirSync(bin);
+  // Both launchable agents are fake, including when a selection regression
+  // chooses Claude instead of the highlighted Codex integration.
+  for (const command of ["codex", "claude"]) {
+    const executable = join(bin, command);
+    writeFileSync(executable, `#!${pythonPath}\n${FAKE_AGENT}`);
+    chmodSync(executable, 0o755);
+  }
+  // A --no-open regression must never launch the developer's actual browser.
+  for (const command of ["open", "xdg-open"]) {
+    const launcher = join(bin, command);
+    writeFileSync(launcher, `#!${pythonPath}\nimport os, pathlib\npathlib.Path(os.environ["MEX_PTY_BROWSER_RECORD"]).write_text("unexpected browser launch")\n`);
+    chmodSync(launcher, 0o755);
+  }
+  const env: NodeJS.ProcessEnv = { ...process.env, PATH: [bin, dirname(process.execPath), process.env.PATH].join(":"), TERM: "xterm-256color", MEX_TELEMETRY: "0", DO_NOT_TRACK: "1", MEX_PTY_FAKE_MODE: mode, MEX_PTY_RECORD: record, MEX_PTY_BROWSER_RECORD: join(root, "browser-open") };
+  delete env.CI; delete env.NO_COLOR; delete env.FORCE_COLOR;
+  const f = { root, project, record, env };
+  fixtures.push(f);
+  return f;
+}
+
+function terminal(f: Fixture, extra: string[] = [], actions: Action[] = [], options: { columns?: number; rows?: number; defaultTool?: boolean; command?: string[] } = {}): Promise<Result> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(pythonPath!, [harness], { encoding: "utf8", timeout: 30_000, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (error) { reject(new Error(`PTY harness failed: ${error.message}\n${stderr}\n${stdout.slice(-4000)}`)); return; }
+      try {
+        const result = JSON.parse(stdout) as Result;
+        if (result.error) throw new Error(`${result.error} (CLI exit ${result.exitCode})\nCompleted actions: ${JSON.stringify(result.events)}\n${result.output.slice(-4000)}`);
+        resolve(result);
+      } catch (error) { reject(error); }
+    });
+    child.stdin!.end(JSON.stringify({ command: [process.execPath, f.cli ?? cli, ...(options.command ?? args(extra, options.defaultTool !== false))], cwd: f.project, env: f.env, unsetEnv: ["CI", "NO_COLOR", "FORCE_COLOR"], columns: options.columns ?? 140, rows: options.rows ?? 40, actions, timeoutMs: 25_000 }));
+  });
+}
+
+function agentRecord(f: Fixture): AgentRecord { return JSON.parse(readFileSync(f.record, "utf8")); }
+function expectPromptCleaned(f: Fixture): void {
+  const local = join(f.project, ".mex/local");
+  expect(existsSync(local) ? readdirSync(local).filter(name => name.startsWith("setup-population-")) : []).toEqual([]);
+}
+function isAlive(pid: number): boolean { try { process.kill(pid, 0); return true; } catch { return false; } }
+function canConnect(port: number): Promise<boolean> {
+  return new Promise(resolve => {
+    const socket = createConnection({ host: "127.0.0.1", port });
+    const finish = (connected: boolean) => { socket.destroy(); resolve(connected); };
+    socket.once("connect", () => finish(true));
+    socket.once("error", () => finish(false));
+    socket.setTimeout(1000, () => finish(false));
+  });
+}
+
+const FAKE_AGENT = String.raw`
+import json, os, pathlib, re, signal, sys, termios
+
+target = pathlib.Path(os.environ["MEX_PTY_RECORD"])
+mode = os.environ["MEX_PTY_FAKE_MODE"]
+flags = termios.tcgetattr(0)[3]
+pointer = re.search(r"\x60([^\x60]+prompt\.md)\x60", " ".join(sys.argv[1:]))
+record = {
+    "pid": os.getpid(), "agent": pathlib.Path(sys.argv[0]).name, "argv": sys.argv[1:],
+    "stdinTTY": os.isatty(0), "stdoutTTY": os.isatty(1), "stderrTTY": os.isatty(2),
+    "canonical": bool(flags & termios.ICANON), "echo": bool(flags & termios.ECHO),
+    "promptExists": bool(pointer and pathlib.Path(pointer.group(1)).is_file()),
+}
+target.write_text(json.dumps(record))
+print("MEX_PTY_CHILD_READY", flush=True)
+if mode == "hold":
+    signal.pause()
+else:
+    record["input"] = sys.stdin.readline().rstrip("\r\n")
+    target.write_text(json.dumps(record))
+    if mode == "complete":
+        for path in pathlib.Path(".mex").rglob("*.md"):
+            content = path.read_text().replace("[Project Name]", "PTY fixture").replace("[Agent / Workspace Name]", "PTY fixture").replace("[YYYY-MM-DD]", "2026-01-01")
+            path.write_text(content)
+    print("MEX_PTY_CHILD_DONE", flush=True)
+    sys.exit(7 if mode == "failed" else 0)
+`;
diff --git a/test/telemetry-delivery.test.ts b/test/telemetry-delivery.test.ts
index 234fd864..819c5db1 100644
--- a/test/telemetry-delivery.test.ts
+++ b/test/telemetry-delivery.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
 import { createServer, type Server } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -336,7 +336,8 @@ describe("noninitializing audit and filesystem containment", () => {
     symlinkSync(outside, join(root, ".mex", "telemetry"), "dir");
     expect(enqueue(event())).toBe(false);
     expect(readdirSync(outside)).toEqual([]);
-    rmSync(join(root, ".mex", "telemetry")); mkdirSync(join(root, ".mex", "telemetry"));
+    expect(lstatSync(join(root, ".mex", "telemetry")).isSymbolicLink()).toBe(true);
+    unlinkSync(join(root, ".mex", "telemetry")); mkdirSync(join(root, ".mex", "telemetry"));
     const other = join(outside, "other"); writeFileSync(other, "do not change");
     symlinkSync(other, dbPath());
     expect(enqueue(event())).toBe(false);
diff --git a/test/wiki-architecture.test.ts b/test/wiki-architecture.test.ts
index 56fa0f3a..cee191ec 100644
--- a/test/wiki-architecture.test.ts
+++ b/test/wiki-architecture.test.ts
@@ -766,6 +766,7 @@ describe("no unscoped scaffold writes", () => {
     const KNOWN: Readonly<Record<string, string>> = {
       "src/agent-skills/installer.ts": "atomically installs fixed packaged skill trees and marker-scoped root instructions",
       "src/graph/audit-record.ts": "writes only the local audited-digest record beside the graph index it describes",
+      "src/graph/candidate-entry.ts": "writes bounded worker failure diagnostics only to stderr (fd 2), never scaffold files",
       "src/graph/candidate-process.ts": "removes only the identity-bound parent-owned temporary workspace after the candidate child closes",
       "src/graph/engine-impl.ts": "writes only a private, bounded temporary source spool that is removed before graph publication",
       "src/graph/grounding-evidence.ts": "writes only checkout-local, content-addressed grounded bodies under .mex/local/grounded-bodies",
@@ -803,6 +804,13 @@ describe("no unscoped scaffold writes", () => {
     const runtime = withoutComments(read("src/graph/runtime.ts"));
     expect([...runtime.matchAll(/writeFileSync\s*\(/g)]).toHaveLength(1);
     expect([...runtime.matchAll(/renameSync\s*\(/g)]).toHaveLength(1);
+
+    // The worker's fd writer is a stderr diagnostic sink, not a file-write
+    // exemption. Keep its only direct write on fd 2 and catch added mutations.
+    const candidateEntry = withoutComments(read("src/graph/candidate-entry.ts"));
+    expect([...candidateEntry.matchAll(WRITE_CALLS)]).toHaveLength(0);
+    expect([...candidateEntry.matchAll(FD_WRITE_CALLS)]).toHaveLength(1);
+    expect(candidateEntry).toMatch(/\bwriteSync\s*\(\s*2\s*,/);
   });
 
   it("does not constrain code outside the wiki engine", () => {
diff --git a/test/wiki-cli-degraded-grounding.test.ts b/test/wiki-cli-degraded-grounding.test.ts
new file mode 100644
index 00000000..9c0027d4
--- /dev/null
+++ b/test/wiki-cli-degraded-grounding.test.ts
@@ -0,0 +1,93 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { createRepositoryGraphPort } from "../src/graph/application-adapter.js";
+import { loadFreshGraphReadSession } from "../src/graph/read-session.js";
+import { FingerprintStore } from "../src/graph/fingerprint-store.js";
+import { serializeFingerprint } from "../src/graph/fingerprint.js";
+import { runApply } from "../src/wiki/cli/commands.js";
+import { resolveGrounding } from "../src/wiki/grounding/resolve.js";
+import { envelope, JWT, makeScaffold, type Scaffold } from "../src/wiki/operations/__tests__/helpers.js";
+
+const scaffolds: Scaffold[] = [];
+afterEach(() => { for (const scaffold of scaffolds.splice(0)) scaffold.dispose(); });
+
+async function fixture() {
+  const scaffold = makeScaffold();
+  scaffolds.push(scaffold);
+  mkdirSync(join(scaffold.root, "src"));
+  writeFileSync(join(scaffold.root, "src/good.ts"), "export function goodTarget() { return 42; }\n");
+  writeFileSync(join(scaffold.root, "tsconfig.json"), '{"compilerOptions":{"strict":true},"include":["src"]}');
+  writeFileSync(join(scaffold.root, "src/broken.ts"), "export function partialTarget() { return 1; }\nexport const broken = ;\n");
+  const port = createRepositoryGraphPort(scaffold.root);
+  await port.rebuild();
+  const loaded = await loadFreshGraphReadSession(scaffold.root, { allowDegradedReads: true });
+  expect(loaded.graphStatus.status).toBe("degraded");
+  expect(loaded.session!.degradations).toEqual(["parse-degraded"]);
+  const session = loaded.session!;
+  try {
+    const store = new FingerprintStore(session.db);
+    const grounding = (name: string) => {
+      const node = session.graph.searchNodes(name).find(node => node.name === name)!;
+      expect(node).toBeDefined();
+      return { node: node.id, fingerprint: serializeFingerprint(store.get(node.id)!), bodyHash: node.bodyHash };
+    };
+    return { scaffold, port, good: grounding("goodTarget"), partial: grounding("partialTarget") };
+  } finally { session.close(); }
+}
+
+describe("Wiki CLI grounding with an unrelated incomplete parse", () => {
+  it("applies an exact healthy grounding, rejects partial-file facts, and names the real remedy", async () => {
+    const { scaffold, port, good, partial } = await fixture();
+    const lines: string[] = [];
+    const operation = join(scaffold.root, "operation.json");
+    const io = { projectRoot: scaffold.root, scaffoldRoot: scaffold.root, groundingBridge: port,
+      write: (value: string) => lines.push(value), setExitCode: () => {} };
+    writeFileSync(operation, JSON.stringify(envelope(scaffold, "set-grounding", { groundsTo: [good] }, { entityId: JWT })));
+    await runApply(io, operation, { json: true, apply: true });
+    expect(JSON.parse(lines.at(-1)!).data.applied).toBe(true);
+    expect(scaffold.entity(JWT).groundsTo[0]?.node).toBe(good.node);
+    const before = readFileSync(join(scaffold.root, "context/architecture.md"), "utf8");
+    lines.length = 0;
+    writeFileSync(operation, JSON.stringify(envelope(scaffold, "set-grounding", { groundsTo: [partial] }, { entityId: JWT })));
+    await runApply(io, operation, { json: true, apply: true });
+    const rejected = JSON.parse(lines.at(-1)!);
+    expect(rejected.data.applied).toBe(false);
+    expect(rejected.diagnostics).toEqual(expect.arrayContaining([expect.objectContaining({
+      code: "GROUNDING_UNVERIFIED", message: expect.stringContaining("src/broken.ts"),
+    })]));
+    expect(JSON.stringify(rejected)).not.toContain("changed during this pass");
+    expect(readFileSync(join(scaffold.root, "context/architecture.md"), "utf8")).toBe(before);
+    await port.refresh();
+    await port.withFreshGroundingSnapshot(snapshot => {
+      expect(snapshot.getNode(good.node)).not.toBeNull();
+      expect(snapshot.getNode(partial.node)).toBeNull();
+      expect(snapshot.getFingerprint(partial.node)).toBeNull();
+      expect(snapshot.getSymbols([good.node, partial.node]).map(symbol => symbol.ref.symbolId)).toEqual([good.node]);
+      expect(resolveGrounding(partial, snapshot)).toMatchObject({ health: "unverified", reason: expect.stringContaining("src/broken.ts") });
+      expect(resolveGrounding({ ...good, node: `function:${"0".repeat(32)}` }, snapshot))
+        .toMatchObject({ health: "unverified", reason: expect.stringContaining("src/broken.ts") });
+    });
+  });
+
+  it("refuses source drift and discards a prepared publication if source changes during the pass", async () => {
+    const { scaffold, port, good } = await fixture();
+    let committed = false;
+    let discarded = false;
+    await expect(port.withFreshGroundingPublication(snapshot => {
+      expect(snapshot.getNode(good.node)).not.toBeNull();
+      writeFileSync(join(scaffold.root, "src/good.ts"), "export function goodTarget() { return 43; }\n");
+      return { preflight() {}, commit() { committed = true; }, discard() { discarded = true; } };
+    })).rejects.toMatchObject({ problem: { code: "OPERATION_INTERRUPTED" } });
+    expect({ committed, discarded }).toEqual({ committed: false, discarded: true });
+    await expect(port.withFreshGroundingSnapshot(() => {})).rejects.toMatchObject({ problem: { code: "INDEX_STALE" } });
+  });
+
+  it("does not admit configuration drift through the incomplete-parse exception", async () => {
+    const { scaffold, port } = await fixture();
+    writeFileSync(join(scaffold.root, "tsconfig.json"), '{"compilerOptions":{"strict":true,"baseUrl":"src"},"include":["src"]}');
+    let used = false;
+    await expect(port.withFreshGroundingSnapshot(() => { used = true; })).rejects.toMatchObject({ problem: { code: "INDEX_STALE" } });
+    expect(used).toBe(false);
+  });
+});