feat: wizard remediation — password mask, hooks preview, headless (IUH-M02) (#431)

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

@@ -99,3 +99,60 @@ Committing as `docs: scaffold install-ux-hardening mission + archive cli-unifica
 ### Next action
 
 Delegate IUH-M02 to a sonnet subagent in an isolated worktree.
+
+---
+
+## Session 3: 2026-04-05 (agent-a6ff34a5) — IUH-M02 Wizard Remediation
+
+### Plan
+
+**AC-3: Password masking + confirmation**
+
+- New `packages/mosaic/src/prompter/masked-prompt.ts` — raw-mode stdin reader that suppresses echo, handles backspace/Ctrl+C/Enter.
+- `bootstrapFirstUser` in `packages/mosaic/src/commands/gateway/install.ts`: replace `rl.question('Admin password...')` with `promptMaskedPassword()`, require confirm pass, keep min-8 validation.
+- Headless path: when `MOSAIC_ASSUME_YES=1` or `!process.stdin.isTTY`, read `MOSAIC_ADMIN_PASSWORD` env var directly.
+
+**AC-4a: Hooks preview stage**
+
+- New `packages/mosaic/src/stages/hooks-preview.ts` — reads `hooks-config.json` from `state.sourceDir` or `state.mosaicHome`, displays each top-level hook category with name/trigger/command preview, prompts "Install these hooks? [Y/n]", stores result in `state.hooks`.
+- `packages/mosaic/src/types.ts` — add `hooks?: { accepted: boolean; acceptedAt?: string }` to `WizardState`.
+- `packages/mosaic/src/wizard.ts` — insert `hooksPreviewStage` between `runtimeSetupStage` and `skillsSelectStage`; skip if no claude runtime detected.
+
+**AC-4b: `mosaic config hooks` subcommands**
+
+- Add `hooks` subcommand group to `packages/mosaic/src/commands/config.ts`:
+  - `list`: reads `~/.claude/hooks-config.json`, shows hook names and enabled/disabled status
+  - `disable <name>`: prefixes matching hook key with `_disabled_` in the JSON
+  - `enable <name>`: removes `_disabled_` prefix if present
+
+**AC-5: Headless install path**
+
+- `runConfigWizard`: detect headless mode (`MOSAIC_ASSUME_YES=1` or `!process.stdin.isTTY`), read env vars with defaults, validate required vars, skip prompts entirely.
+- `bootstrapFirstUser`: detect headless mode, read `MOSAIC_ADMIN_NAME/EMAIL/PASSWORD`, validate, proceed without prompts.
+- Document env vars in `packages/mosaic/README.md` (create if absent).
+
+### File list
+
+NEW:
+
+- `packages/mosaic/src/prompter/masked-prompt.ts`
+- `packages/mosaic/src/prompter/masked-prompt.spec.ts`
+- `packages/mosaic/src/stages/hooks-preview.ts`
+- `packages/mosaic/src/stages/hooks-preview.spec.ts`
+
+MODIFIED:
+
+- `packages/mosaic/src/types.ts` — extend WizardState
+- `packages/mosaic/src/wizard.ts` — wire hooksPreviewStage
+- `packages/mosaic/src/commands/gateway/install.ts` — masked password + headless path
+- `packages/mosaic/src/commands/config.ts` — add hooks subcommands
+- `packages/mosaic/src/commands/config.spec.ts` — extend tests
+- `packages/mosaic/README.md` — document env vars
+
+### Assumptions
+
+ASSUMPTION: `hooks-config.json` location is `<sourceDir>/framework/runtime/claude/hooks-config.json` during wizard (sourceDir is package root). Fall back to `<mosaicHome>/runtime/claude/hooks-config.json` for installed config.
+ASSUMPTION: The `hooks` subcommands under `config` operate on `~/.claude/hooks-config.json` (the installed copy), not the package source.
+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).