Merge branch 'claudedo/852c2328ec8b4fc1bf143df203e1dc6c'

src/ClaudeDo.Installer/CLAUDE.md

@@ -31,8 +31,8 @@ the on-disk installer to run the *app* update. App-update detection is unaffecte
 
 | Mode | Condition | Window |
 |---|---|---|
-| `FreshInstall` | No `install.json` | Full wizard (all pages) |
-| `Update` | `install.json` present + newer release available | Wizard — Welcome + Install pages only |
+| `FreshInstall` | No `install.json` | Full wizard: Welcome → **SystemCheck** → Paths → Service → UiSettings → Install |
+| `Update` | `install.json` present + newer release available | Wizard — Welcome + Install pages only (SystemCheck **not** shown) |
 | `Config` | Current version, or Gitea API unreachable | `SettingsWindow` (settings / repair / uninstall) |
 
 ## Install Pipelines
@@ -60,7 +60,8 @@ Installer/
                ConfigModels, InstallerService, UninstallRunner, PageResolver,
                AutostartShortcut, ShortcutFactory, ProcessRunner, DarkTitleBar
               Interfaces/ — IInstallStep + StepResult/StepStatus/StepProgress, IInstallerPage
-  Pages/    — WelcomePage, PathsPage, ServicePage, UiSettingsPage, InstallPage
+  Checks/   — environment preflight checks, see "Environment Checks" below
+  Pages/    — WelcomePage, SystemCheckPage, PathsPage, ServicePage, UiSettingsPage, InstallPage
                (each: ViewModel + View.xaml)
   Views/    — WizardWindow(+WizardViewModel), SettingsWindow(+SettingsViewModel)
 ```
@@ -124,3 +125,52 @@ and restored if it fails.
 | `%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup\ClaudeDo Worker.lnk` | Worker autostart |
 
 The Apps & Features uninstall string and "Rerun Installer" both point at `<InstallDir>\uninstaller\ClaudeDo.Installer.exe` with no `/uninstall` flag — Config mode is detected from `install.json`.
+
+## Environment Checks
+
+> **Merge status (2026-08-05): not yet on `main`.** The `Checks/` folder, `SystemCheckPage`,
+> and `ExecutableResolver` described below exist only on unmerged task branches
+> (`claudedo/06aca9b3afec4b939f59b627bfe21737` for the Installer side,
+> `claudedo/40272c0bb3b14562b59c022d09c382b6` for the `ClaudeDo.Worker` wiring). Build/test
+> verification for this section was done against a local scratch integration of both, not
+> against this repo's actual `main`. Merge them (or re-derive equivalent commits) before trusting
+> this section against the checked-out code. See `docs/open.md` for the outstanding gap this
+> leaves (`Checks/` and `SystemCheckPage` are real, but the "Claude Help Me" button and the
+> Config-mode Diagnose section described as follow-ups were never implemented — both follow-up
+> tasks blocked on this same missing merge and shipped no code).
+
+`Checks/` holds one `IEnvironmentCheck` per concern, run in parallel by `EnvironmentCheckService.RunAllAsync`:
+
+| Check | Severity | What it verifies |
+|---|---|---|
+| `GitCheck` | Error | `git` resolvable (via `ExecutableResolver`) and runs |
+| `WriteAccessCheck` | Error | install dir + `%APPDATA%` (or first existing parent) are writable |
+| `ClaudeCliCheck` | Error | `claude` resolvable on PATH, including npm `.cmd`/`.bat`/`.ps1` shims |
+| `ClaudeVersionCheck` | Error | resolved `claude --version` ≥ `ClaudeVersionCheck.MinimumVersion` (currently `2.1.220`) |
+| `ClaudeAuthCheck` | Error | `claude auth status --json` reports `loggedIn: true` (never sends a prompt) |
+| `GitIdentityCheck` | Warning | `git config user.name`/`user.email` are set |
+| `PortCheck` | Warning | `SignalRPort`/`ExternalMcpPort` are free, or already owned by a running `ClaudeDo.Worker` |
+| `PermissionModeAutoCheck` | Warning | CLI's `--help` still lists `auto` as a `--permission-mode` choice |
+
+Each check returns a `CheckResult` with `CheckStatus` (`Ok` / `Failed` / `Unknown`). A check that
+throws is caught by `EnvironmentCheckService` and turned into `Unknown`, never a crash.
+
+**Gating rule:** `EnvironmentCheckReport.HasBlockingError` is true only when a check with
+`Severity == Error` has `Status == Failed`. Warnings never block, and `Unknown` never blocks
+regardless of severity (an indeterminate result — e.g. the CLI not found, so version/auth/auto-mode
+can't be checked — must not strand the user; the underlying `Error`-severity check for the CLI
+itself, `ClaudeCliCheck`, is what blocks in that case).
+
+`SystemCheckPage` (`Pages/SystemCheckPage/`) hosts the check list in the **FreshInstall** wizard
+only, registered via `PageResolver` at `Order = 1` (directly after `WelcomePage`); `WizardViewModel`
+filters it back out in `Update` mode along with Paths/Service/UiSettings. Checks run automatically
+on page entry (`LoadAsync`, guarded against double-entry). "Next" is disabled via
+`IInstallerPage.BlocksNavigation` (`IsRunning || HasBlockingError`) — `WizardViewModel.CanGoNext`
+subscribes to `PropertyChanged` on the current page so a live recheck can flip it back. A "Recheck"
+button re-runs `EnvironmentCheckService.RunAllAsync` (disabled while already running).
+
+**Not implemented (see merge-status note above):** a "Claude Help Me" button that launches an
+external terminal with a live `claude` session for setup troubleshooting, and a Diagnose section
+in `SettingsWindow` (Config mode) that re-runs the same checks against the installed configuration.
+Both were speced as follow-up tasks; both blocked before writing any code because their prerequisite
+(this section) wasn't on `main` yet.

src/ClaudeDo.Worker/CLAUDE.md

@@ -16,7 +16,8 @@ Worker/
   State/        — TaskStateService + TransitionResult (sole owner of Status/PlanningPhase/BlockedBy writes)
   Queue/        — IQueueWaker, IQueuePicker, QueueService, OverrideSlotService, RunCancellationRegistry
   Lifecycle/    — StaleTaskRecovery, TaskResetService, TaskMergeService, VerifyCommandRunner,
-                  ClaudeCliPreflight, OrphanRecovery, PlanningLineageRecovery,
+                  ClaudeCliPreflight (resolves via ExecutableResolver, see Key Components below),
+                  OrphanRecovery, PlanningLineageRecovery,
                   AttachmentOrphanRecovery, PromptFileRecovery  (last four = startup sweeps)
   Worktrees/    — WorktreeMaintenanceService
   Agents/       — AgentFileService, DefaultAgentSeeder
@@ -111,7 +112,8 @@ Full flow, invariants, and model/effort/max-turns resolution (including the low-
 
 ## Key Components
 
-- **ClaudeProcess** — spawns `claude -p --output-format stream-json --verbose --permission-mode auto` (or whatever app settings specify). Prompt via stdin, NDJSON from stdout. CancellationToken kills the process tree.
+- **ClaudeCliPreflight** — startup check that `claude --version` runs; resolves the binary via `ExecutableResolver` first and returns a clear "not found on PATH" result instead of a raw `Process.Start` exception when it doesn't. *(Not yet on `main` — see below.)*
+- **ClaudeProcess** — spawns `claude -p --output-format stream-json --verbose --permission-mode auto` (or whatever app settings specify). Prompt via stdin, NDJSON from stdout. CancellationToken kills the process tree. Resolves `_cfg.ClaudeBin` via `ExecutableResolver` (`ClaudeDo.Data`, shared with `ClaudeCliPreflight` and the Installer's checks) before spawning — a `.cmd`/`.bat` shim (e.g. an npm-installed `claude`) is launched through `cmd.exe /c` since `UseShellExecute = false` can't exec a shim directly; a resolved `.exe` starts exactly as before. Throws if nothing resolves. *(Not yet on `main` — see `Environment Checks` in `ClaudeDo.Installer/CLAUDE.md`.)*
 - **ClaudeArgsBuilder** — `--model`, `--effort`, `--max-turns`, `--append-system-prompt`, `--agents`, `--json-schema`, `--resume`
 - **StreamAnalyzer** — parses NDJSON; extracts session_id, token counts, turn counts, result text, structured output. Replaced MessageParser.
 - **WorktreeManager** — worktrees on `claudedo/{taskId[:8]}` branches; commits with semantic messages, updates DB with head commit + diff stats