Release 0.8.4: terminal setup by default and clearer failures

[theDakshJaitly]

What

Make the terminal HUD the default for mex setup and for bare mex in incomplete projects, with the lowercase cyan banner, native Claude/Codex handoff, live graph activity, and resumable outcomes. Established projects still open the Hub; setup --browser selects browser setup and --cli remains supported. Expected setup failures retain actionable recovery text, and checking a completed setup no longer creates an empty agent-session panel.

Prepare 0.8.4: update package/lockfile metadata, capability fixtures, all README installation pins, shipped setup guidance, release notes, and compatibility guidance. The release notes cover the changes already merged since v0.8.3 as well as this setup work.

Why

Setup could look stalled during graph construction, hide expected failures behind a generic terminal fallback, and make terminal agent interaction difficult. The new default exposes the actual agent session and returns users to MEX for validation and the Hub commit/completion flow.

Type of change

• Bug fix
• New feature
• Refactor
• Docs
• CI/Tooling

How to test

Local validation uses a disposable checkout so an active setup/Hub keeps its original build. The standard production build, root/Hub typechecks, 33 CLI tests, 16 terminal PTY cases, seven built CLI smoke cases, all three setup-completion browser cases, fresh packed-install Hub/skills smoke, and 86 evaluator tests pass. The built CLI reports 0.8.4 and its public declarations are unchanged.

The broad root run had 4,708 passes, eight failures, and two skips. Four failures were missing temporary-checkout Git/scaffold metadata, one was the new stderr writer missing from the architecture inventory, and two were Node 24.4.1 symlink-fixture cleanup. Those are corrected; the remaining Hub Wiki-read failure passes unchanged serially. All affected files pass in 143 targeted rerun tests. Full evidence is in docs/design/0.8.4-release-plan.md.

• Run setup from an incomplete project in a real terminal; Enter selects the highlighted integration, and cancellation before starting leaves no scaffold.
• Return from the native agent session, check the populated files, finish validation, and review the setup diff in the Hub.
• For automation, setup --yes --tool codex pauses with exit 2 until explicit population, then resumes with exit 0. The packed-install smoke verifies that available agents are not launched in this mode.
• Check setup --browser, the --cli alias, expected errors, small-terminal layouts, and established-project Hub recovery.

Checklist

• Clean full CI run pending; local regression and all affected reruns are recorded above.
• Compatibility changes documented below and in COMPATIBILITY.md.
• Tested locally with real terminal sessions and disposable project fixtures.

Compatibility and remaining work

Upgrade all collaborators before committing new mh2: grounding fingerprints: 0.8.3 and earlier cannot read them. The notes also document the additive DriftIssue/IssueCode changes already on main and the maintainer-selected 0.8.4 version. Historical release entries, private workspace versions, and dependency versions are preserved.

Large-repository compiler heap exhaustion, the browser completion readiness shortcut, and oversized Hub population prompts remain separate follow-ups. This PR does not change graph identity/schema or extraction semantics, and it does not publish npm, create a release tag, or merge itself.

Code-graph changes

The setup work forwards real progress and retains bounded worker failure diagnostics. Extraction, graph identity, reconciliation, schemas, and drift semantics are unchanged by this PR. The writer-inventory test explicitly restricts the new diagnostic sink to stderr.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[Akshtdhamija]

Windows review: tested end to end on a real project

I tested 10aca78 on Windows 11 (Node 24.14.1, Git 2.53, Claude Code 2.1.289) using a disposable clone of a real ~560-file TypeScript/Go pnpm monorepo, with its MEX scaffold removed so it looked like a new project. I ran the interactive HUD in a Windows ConPTY, sending real keystrokes. Claude Code populated the scaffold through the native handoff, and headless Edge drove the completion page through to commit and Open Hub.

The overall design held up. Setup ran from tool choice through graph build, handoff, finalize and browser commit to the Hub, and the error, retry and cancel screens worked. I found four blocking issues: three in this PR and one already on main that ships in 0.8.4 and breaks this PR's main flow on real repositories.

Blocking: this PR

1. Windows: mex does not exit after a native agent handoff until the user presses Enter.
To reproduce: run interactive setup, let the agent exit, let setup finish, then press q on the Hub screen. The final outcome message prints, but the process stays alive with no child processes, and the shell prompt never comes back. Enter or Ctrl+C releases it with exit 0. A diagnostic interval stopped firing, so the main thread is blocked rather than idle. The likely cause is a pending line-mode console read left by the suspend/resume cycle. This happened 2 of 2 times with a handoff. Without a handoff, the same flow exited normally both times, including after a browser commit.
I verified this one-line fix 2 of 2 times: call stdin.pause() right after await ui.close() in runTerminalSetup's finally (src/setup/terminal.ts). The PTY suite skips on Windows, so nothing automated covers this today.

2. Windows CI failure: the smoke's new PATH check compares where.exe output as a string (scripts/hub-pack-smoke.mjs, runFreshCodeRepoSetup).
where.exe expands 8.3 short names and rewrites case. On GitHub's Windows runners, os.tmpdir() is under C:\Users\RUNNER~1\..., so the correct codex.cmd fails the resolve(a) !== resolve(b) check. I reproduced the exact CI error locally by setting TEMP to a short path. With the patch below, the full npm run test:hub:package passes on Windows with that short temp path:

+  realpathSync,
 ...
+  // where.exe expands 8.3 short names and normalizes case, so compare real paths.
+  const canonical = (path) => {
+    const real = realpathSync.native(path);
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  };
   if (locatedAgent.error || locatedAgent.status !== 0
-    || resolve(locatedAgent.stdout.split(/\r?\n/u)[0].trim()) !== resolve(expectedAgent)) {
+    || canonical(locatedAgent.stdout.split(/\r?\n/u)[0].trim()) !== canonical(expectedAgent)) {

3. New flaky test: candidate-process.test.ts, "distinguishes a invalid protocol from graph build failure".
Both cases use startupTimeoutMs: 100. Node often takes longer than 100 ms to start on Windows, so the protocol case reports startup-timeout instead (2 of 3 local runs failed). Use the short deadline only for the startup-deadline case.

Blocking for the release: already on main, ships in 0.8.4

4. A degraded graph blocks all Wiki grounding and reports it as a concurrent change.
In a real repo, one deliberately broken test fixture (.../fixtures/ts-app/src/broken.ts) makes the graph degraded. errorForStatus maps degraded to OPERATION_INTERRUPTED (src/graph/application-adapter.ts), and src/wiki/cli/grounding.ts maps that to changed. As a result, every grounded mex wiki apply fails with GROUNDING_UNVERIFIED plus "The code graph or the source changed during this pass… Run mex graph". Nothing changed, and mex graph cannot fix it.

• Effect: during population, Claude Code retried and investigated MEX internals for about 28 minutes before writing anything. Once told the cause, it finished, but it had to put groundings at file level because per-claim entities were impossible.
• Proof: with only that fixture hidden, the graph reports fresh and the identical operation plans successfully.
• Origin: came in with 0fcbef4 (#263), after v0.8.3, so this is a regression since the last release. The main and PR builds behave the same.
• Suggestion: allow grounding against parse-degraded graphs for nodes in files that parsed. At minimum, give it a distinct reason whose message names the failed files and the real remedy.

Should fix (this PR)

5. Stale final message after a browser commit. It still says "Review and commit the canonical MEX setup… Run mex setup to reopen the completion page."
6. The HUD d view shows only the latest event. Finalize warnings, such as several AMBIGUOUS_MIGRATION notices, flash past and can't be reviewed afterwards. A bounded event log under d would fix this.
7. "Finish later" after a failed agent launch reports failed / exit 1 instead of paused / exit 2. populationFailure stays set when the user moves to another option.
8. Narrow terminals (60×16): the one-time Hub link wraps inside the frame, so copying it picks up border characters. The footer is also truncated between about 55 and 66 columns.
9. Misleading worker diagnostic. It says "reported an error (signal SIGTERM…)" when the worker reported an error and MEX then sent SIGTERM itself. Consider excluding sentSignals from the message, as you already do for ipc-disconnected.
10. release-performance: the first PR run passed, and only test files changed since, so this is likely runner noise. Worth a rerun.

Outside this PR (pre-existing on main; separate issues)

• Four Windows test failures on main: three symlink tests fail with EPERM when Developer Mode is off and should skip when symlinks can't be created, and headless-population "reports a launch failure instead of manual population" fails.
• Fresh templates trigger AMBIGUOUS_MIGRATION warnings on every first setup.
• Narrow edge case: refresh the graph while an unparseable file is absent, restore the file, and mex graph rebuild then hard-fails with "The source no longer parses" instead of degrading. A from-scratch rebuild works.

Verified working on Windows

• Build, root and Hub typecheck, CLI reports 0.8.4. Of the 545 tests in the affected files, 514 pass and 26 skip. Of the 5 failures, 4 also fail on main, and 1 is item 3.
• --dry-run wrote nothing. --browser conflicts are rejected. Expected errors print an authored message plus Diagnostics:.
• --yes --tool claude paused with exit 2 without launching an agent and printed live graph counts (132 files). The resume exited 0, and local DBs and .mex/local stayed ignored with nothing staged.
• HUD: banner and layout render at 120×40, and the compact layout works at 60×16. CLI detection is correct. Ctrl+C before start exits 130 with nothing written.
• Handoff: Claude Code found the PR's mex on PATH and used the graph commands. Ctrl+C inside the agent never stopped MEX. After an agent crash, the population menu and "Open Claude Code" reopened correctly. /exit returned control cleanly, and finalize captured 73 baselines.
• Error screen with Retry: a graph failure showed authored text, diagnostics and a working Retry. Exit after a Hub start failure returned 1.
• Completion page in Edge: 34 files, commit enabled only after every diff was viewed, local commit created, "You're ready" shown, Open Hub led to Overview. The Hub showed the degraded graph accurately.
• An established project opens the Hub. Graph worker stderr never reaches the browser; it is translated by translateMaintenanceError and SetupError.userMessage.