Release 0.8.4: terminal setup by default and clearer failures

.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

.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.

.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,27 +64,102 @@ 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.
 
 - A global CLI can report the same version while containing different bytes;
   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
 

.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.