feat: unified first-run flow — merge wizard + gateway install (IUH-M03)

Collapse `mosaic wizard` and `mosaic gateway install` into a single cohesive
first-run experience. Gateway config and admin bootstrap now run as terminal
stages of `runWizard`, sharing `WizardState` with the framework stages and
eliminating the fragile 10-minute `$XDG_RUNTIME_DIR/mosaic-install-state.json`
session-file bridge.

- Extract `gatewayConfigStage` and `gatewayBootstrapStage` as first-class
  wizard stages with full spec coverage (headless + interactive paths).
- `mosaic gateway install` becomes a thin wrapper that invokes the same
  two stages — the CLI entry point is preserved for operators who only
  need to (re)configure the daemon.
- Honor explicit `--port` override even on resume: when the override
  differs from the saved GATEWAY_PORT, force a config regeneration so
  `.env` and `meta.json` cannot drift.
- Honor `state.hooks.accepted === false` in the finalize stage and in
  `mosaic-link-runtime-assets`: declined hooks are now actually opted-out,
  with a stable `mosaic-managed: true` marker in the template so cleanup
  survives template updates without touching user-owned configs.
- Headless rerun of an already-bootstrapped gateway with no local token
  cache is a successful no-op (no more false-positive install failures).
- `tools/install.sh` calls `mosaic wizard` only — the follow-up
  `mosaic gateway install` auto-launch is removed.

Closes mosaicstack/mosaic-stack#427.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/scratchpads/install-ux-hardening-20260405.md

@@ -156,3 +156,84 @@ ASSUMPTION: The `hooks` subcommands under `config` operate on `~/.claude/hooks-c
 ASSUMPTION: For the hooks preview stage, the "name" field displayed per hook entry is the top-level event key (e.g. "PostToolUse") plus the matcher from nested hooks array. This is the most user-readable representation given the hooks-config.json structure.
 ASSUMPTION: `config hooks list/enable/disable` use `CLAUDE_HOME` env or `~/.claude` as the target directory for hooks files.
 ASSUMPTION: The headless TTY detection (`!process.stdin.isTTY`) is sufficient; `MOSAIC_ASSUME_YES=1` is an explicit override for cases where stdin is a TTY but the user still wants non-interactive (e.g., scripted installs with piped terminal).
+
+---
+
+## Session 4: 2026-04-05 (agent-a7875fbd) — IUH-M03 Unified First-Run
+
+### Problem recap
+
+`mosaic wizard` and `mosaic gateway install` currently run as two separate phases bridged by a fragile 10-minute session file at `$XDG_RUNTIME_DIR/mosaic-install-state.json`. `tools/install.sh` auto-launches both sequentially so the user perceives two wizards stitched together; state is not shared, prompts are duplicated, and if the user walks away the bridge expires.
+
+### Design decision — Option A: gateway install becomes terminal stages of `runWizard`
+
+Two options on the table:
+
+- (A) Extract `runConfigWizard` and `bootstrapFirstUser` into `stages/gateway-config.ts` and `stages/gateway-bootstrap.ts`, append them to `runWizard` as final stages, and make `mosaic gateway install` a thin wrapper that runs the same stages with an ephemeral state seeded from existing config.
+- (B) Introduce a new top-level orchestrator that composes the wizard and gateway install as siblings.
+
+**Chosen: Option A.** Rationale:
+
+1. The wizard already owns a `WizardState` that threads state across stages — gateway config/bootstrap fit naturally as additional stages without a new orchestration layer.
+2. `mosaic gateway install` as standalone entry point stays idempotent by seeding a minimal `WizardState` and running only the gateway stages, reusing the same functions.
+3. Avoids a parallel state object and keeps the call graph linear; easier to test and to reason about the "one cohesive flow" UX goal.
+4. Option B would leave `runWizard` and the gateway install as siblings that still need to share a state object — equivalent complexity without the narrative simplification.
+
+### Scope
+
+1. Extend `WizardState` with optional `gateway` slice: `{ tier, port, databaseUrl?, valkeyUrl?, anthropicKey?, corsOrigin, admin?: { name, email, password } }`. The admin password is held in memory only — never persisted to disk as part of the state object.
+2. New `packages/mosaic/src/stages/gateway-config.ts` — pure stage that:
+   - Reads existing `.env`/`mosaic.config.json` if present (resume path) and sets state.
+   - Otherwise prompts via `WizardPrompter` (interactive) or reads env vars (headless).
+   - Writes `.env` and `mosaic.config.json`, starts the daemon, waits for health.
+3. New `packages/mosaic/src/stages/gateway-bootstrap.ts` — pure stage that:
+   - Checks `/api/bootstrap/status`.
+   - If needsSetup, prompts for admin name/email/password (uses `promptMaskedConfirmed`) or reads env vars (headless); calls `/api/bootstrap/setup`; persists token in meta.
+   - If already setup, handles inline token recovery exactly as today.
+4. `packages/mosaic/src/wizard.ts` — append gateway-config and gateway-bootstrap as stages 11 and 12. Remove `writeInstallState` and the `INSTALL_STATE_FILE` constant entirely.
+5. `packages/mosaic/src/commands/gateway/install.ts` — becomes a thin wrapper that builds a minimal `WizardState` with a `ClackPrompter`, then calls `runGatewayConfigStage(...)` and `runGatewayBootstrapStage(...)` directly. Remove the session-file readers/writers. Headless detection is delegated to the stage itself. The wrapper still exposes the `runInstall({host, port, skipInstall})` API so `gateway.ts` command registration is unchanged.
+6. `tools/install.sh` — drop the second `mosaic gateway install` call; `mosaic wizard` now covers end-to-end. Leave `gateway install` guidance for non-auto-launch path so users still know the standalone entry point exists.
+7. **Hooks gating (bonus — folded in):** `finalize.ts` already runs `mosaic-link-runtime-assets`. When `state.hooks?.accepted === false`, set `MOSAIC_SKIP_CLAUDE_HOOKS=1` in the env for the subprocess; teach the script to skip copying `hooks-config.json` when that env var is set. Other runtime assets (CLAUDE.md, settings.json, context7) still get linked.
+
+### Files
+
+NEW:
+
+- `packages/mosaic/src/stages/gateway-config.ts` (+ `.spec.ts`)
+- `packages/mosaic/src/stages/gateway-bootstrap.ts` (+ `.spec.ts`)
+
+MODIFIED:
+
+- `packages/mosaic/src/types.ts` — extend WizardState with `gateway?:` slice
+- `packages/mosaic/src/wizard.ts` — append gateway stages, remove session-file bridge
+- `packages/mosaic/src/commands/gateway/install.ts` — thin wrapper over stages, remove 10-min bridge
+- `packages/mosaic/src/stages/finalize.ts` — honor `state.hooks.accepted === false` by setting `MOSAIC_SKIP_CLAUDE_HOOKS=1`
+- `packages/mosaic/framework/tools/_scripts/mosaic-link-runtime-assets` — honor `MOSAIC_SKIP_CLAUDE_HOOKS=1`
+- `tools/install.sh` — single unified auto-launch
+
+### Assumptions
+
+ASSUMPTION: Gateway stages must run **after** `finalizeStage` because finalize writes identity files and links runtime assets that the gateway admin UX may later display — reversed ordering would leave Claude runtime linkage incomplete when the admin token banner prints.
+ASSUMPTION: Standalone `mosaic gateway install` uses a `ClackPrompter` (interactive) by default; the headless path is still triggered by `MOSAIC_ASSUME_YES=1` or non-TTY stdin, and the stage functions detect this internally.
+ASSUMPTION: When `runWizard` reaches the gateway stages, `state.mosaicHome` is authoritative for GATEWAY_HOME resolution if it differs from the default — we set `process.env.MOSAIC_GATEWAY_HOME` before importing gateway modules so the constants resolve correctly.
+ASSUMPTION: Keeping backwards compatibility for `runInstall({host, port, skipInstall})` is enough — no other internal caller exists.
+ASSUMPTION: Removing the session file is safe because the old bridge is at most a 10-minute window; there is no on-disk migration to do.
+
+### Test plan
+
+- `gateway-config.spec.ts`: fresh install writes .env + mosaic.config.json (mock fs + prompter); resume path reuses existing BETTER_AUTH_SECRET; headless path respects MOSAIC_STORAGE_TIER/MOSAIC_GATEWAY_PORT/etc.
+- `gateway-bootstrap.spec.ts`: calls `/api/bootstrap/setup` with collected creds (mock fetch); handles "already setup" branch; honors headless env vars; persists token via `writeMeta`.
+- Extend existing passing tests — no regressions in `login.spec`, `recover-token.spec`, `rotate-token.spec`.
+- Unified flow integration is covered at the stage-level; no new e2e test infra required.
+
+### Delivery cycle
+
+plan (this entry) → code → typecheck/lint/format → test → codex review (`~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`) → remediate → commit → ci-queue-wait push → push → PR → CI green → merge → close #427.
+
+### Remediation log (codex review rounds)
+
+- **Round 1** — hooks opt-out did not remove an existing managed file; port override ignored on resume; headless errors swallowed. Fixed: hooks cleanup, `portOverride` honored, errors re-thrown.
+- **Round 2** — headless stage failures exited 0; port override on decline-rerun mismatched; no default-path integration test. Fixed: `process.exit(1)` in headless, revert portOverride on decline, add `unified-wizard.test.ts`.
+- **Round 3** — hooks removal too broad (would touch user-owned files); port override written to meta but not .env (drift); wizard swallowed errors. Fixed: `cmp -s` managed-file check, force regeneration when portOverride differs from saved port, re-throw unexpected errors.
+- **Round 4** — port-override regeneration tripped the corrupt-partial-state guard (blocker); headless already-bootstrapped-with-no-local-token path reported failure instead of no-op; hooks byte-equality fragile across template updates. Fixed: introduce `forcePortRegen` flag bypassing the guard (with a dedicated spec test), headless rerun of already-bootstrapped gateway now returns `{ completed: true }` (with spec coverage), hooks cleanup now checks for a stable `"mosaic-managed": true` marker embedded in the template (byte-equality remains as a fallback for legacy installs).
+- Round 5 codex review attempted but blocked by upstream usage limit (quota). Rerun after quota refresh if further findings appear; all round-4 findings are code-covered.