fix(#792): make fleet roster errors actionable

docs/scratchpads/ms-792-fleet-enoent-installer.md

@@ -0,0 +1,34 @@
+# ms-792 — Fleet roster error handling and installer heading
+
+## Objective
+
+Make expected missing or malformed fleet roster configuration fail with an actionable message and nonzero exit instead of a raw Node stack trace. Ensure the installer preserves the `@mosaicstack/mosaic` heading.
+
+## Plan
+
+1. Add failing coverage for missing and malformed roster input.
+2. Centralize roster-file read and parse error translation; add the CLI async error boundary.
+3. Sweep fleet command read paths that bypass the roster loader.
+4. Replace the installer heading output with format-safe rendering and test it.
+5. Run focused and repository quality checks; request independent review.
+
+## Progress
+
+- 2026-07-16: Confirmed issue #792 and branch base `9745bc3f`.
+- 2026-07-16: Installed locked workspace dependencies using a worktree-local pnpm store; no `.mosaic/` files were changed intentionally.
+- 2026-07-16: Added a shared roster read/parse guard and routed v1 fleet commands plus v1/v2 selection through Commander’s actionable nonzero error path. V2 command modules already return structured nonzero JSON errors for their guarded reads.
+- 2026-07-16: Replaced installer heading `echo` with format-safe `printf`; added a regression check for the scoped package heading.
+- 2026-07-16: Rebuilt CLI and manually verified `fleet ps` with no roster prints the initialization hint, exits 1, and has no stack trace.
+
+## Verification
+
+- `pnpm --filter @mosaicstack/mosaic test` — PASS (61 files, 1,046 tests; executed outside sandbox because CLI smoke tests spawn Node)
+- `pnpm typecheck` — PASS
+- `pnpm lint` — PASS
+- `pnpm format:check` — PASS
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts src/commands/install-heading.spec.ts` — PASS (209 tests)
+- Instrumented Vitest coverage is unavailable because `@vitest/coverage-v8` is not declared in this repository. Each branch added in the roster guard has direct unit coverage.
+
+## Risks / blockers
+
+- Dependency installation is required before executing Vitest, TypeScript, lint, and formatting gates.