Wizard orchestration (T11): fork-join-pick-configure-finale state machine (LLP 0135)

[bgmcmullen]

What

Lands T11 of the install-experience overhaul plan (LLP 0136): the runInitWizard orchestrator that composes the already-landed phase modules into the full guided flow, plus the three items the phase modules had left open.

• Orchestration (src/core/cli/wizard/index.js, LLP 0135 #orchestration): returning gate, then fork -> join -> pick -> configure -> finale -> privacy narration. A failed or abandoned join prints why and re-presents the fork (LLP 0129 #failed-join-returns-to-fork). Non-interactive shapes (--yes, --dry-run, presets, --from-file) short-circuit to pick + finale exactly as before. hyp init slims down to entry detection plus a wizard call (src/core/commands/init.js, -312 lines).
• Picker manifests for @hypaware/openclaw and @hypaware/hermes (both use the settings_file probe; the path probe literal is absolute-only, which a static manifest cannot express for a home-relative directory).
• Managed-machine row annotation (LLP 0132 #never-silent): on a machine with a central layer, every non-locked picker row carries · stays on this machine.
• First-sync privacy narration as the wizard's closing words on the team pathway, after the finale output so it cannot scroll away.

One deliberate deviation from T11's letter, documented in the LLP 0136 completion note: on the team pathway the finale skips only the daemon install (new skipDaemonInstall flag, distinct from skipDaemon); the restart still runs, because the wizard just wrote a new local layer the daemon must pick up.

LLP 0135/0136 updated in the same commit (0136 marked Implemented).

Known issue, out of scope

Real-world testing of this branch on an enrolled machine surfaced #380: on a fully fleet-managed machine the finale installs no skills/agents because clientsPicked is derived from the locked-filtered source list. That defect predates this branch (shipped with #375 in v1.17.0, pick.js derivation unchanged here); fixing it is tracked separately so it can be hotfixed independently.

Testing

• npm test: 2631 pass, 1 skipped, 0 fail (includes new test/core/cli/wizard/index.test.js and extended pick/join/compose/init-entry tests).

🤖 Generated with Claude Code

[philcunliffe]

neutral review — PR #381 (T11 wizard orchestration)

Verdict: CLEAN. Reviewed the full diff at 4d965c5 against master, cross-checked against LLP 0135/0136 and the referenced decisions (0129, 0131, 0132, 0134, 0101, 0058). No actionable correctness, security, contract, or test-coverage defects found.

What I verified

• Orchestration state machine (src/core/cli/wizard/index.js): the fork→join→pick→configure→finale→privacy flow is correct. The while (!pathway) loop handles quit/local/team and re-presents the fork on a failed or abandoned join (printJoinFailure → continue), matching LLP 0129 #failed-join-returns-to-fork. Gate actions quit/status/scoped-reconfigure are handled; first-run and solo reconfigure correctly fall through to the fork. Non-interactive (picks set) short-circuits past gate/fork/join. Pick-phase threading of locked/managed/scoped is correct, including the empty-lockedSources-but-managed:true team case.
• skipDaemonInstall vs restart (walkthrough.js:789,807,1024): skipInstall = skipDaemon || skipDaemonInstall gates only the install block; the restart at line 1024 is gated by skipDaemon/skipDaemonRestart (not skipDaemonInstall), so the team pathway skips install but still restarts, exactly as the LLP 0135/0136 completion note requires. The skip is conditional on report.daemon.installed, so a non-installed daemon still installs.
• skipAttachClients (walkthrough.js:876): attached clients are marked {ok:true, skipped:true} and rendered as "already attached"; status collection is best-effort (try/catch) so a status failure just re-runs idempotent steps.
• Privacy narration ordering: printed after writeWalkthroughRunSummary, i.e. truly last on the team pathway (LLP 0128/0100/0101); reads the login-lane-written first-sync hold read-only and stays silent when no live deadline exists. Local/scoped pathways correctly never narrate.
• renderConfigSummary move (init.js → wizard/fork.js): the first-run guard (!configExists || !configValid → early return) precedes the summary render, so an invalid config never renders a summary; the moved copy adds defensive optional-chaining on cache/retention. No dangling references to the deleted runConfiguredEntry/buildConfiguredMenuOptions/legacyConfiguredActionPrompt remain.
• Picker manifests (openclaw/hermes): compose tests confirm openclaw pulls the gateway + anthropic upstream + adapter, and hermes composes the gateway with an empty upstream list (requires_gateway without gateway_upstream), which compileUpstreams accepts. settings_file probes verified.
• @ref annotations: every referenced anchor exists — 0129#{failed-join-returns-to-fork, returning-gate, join-before-picker}, 0132#never-silent, 0101#deadline, 0134#login-lane, 0135#{orchestration, pick, finale}, 0130#picker-block, 0031#status-provenance, 0058#d7. Refs are honest.
• Tests: the new test/core/cli/wizard/index.test.js (16 cases) plus the extended pick/join/compose/init-entry suites all pass (61/61 in the affected files). Coverage spans gate short-circuits, the fork/join loop, join-failure classification (incl. the new org_selection_required), the non-interactive short-circuit, cancel/refusal exits, and the privacy narration.
• Style: no semicolons or em dashes introduced (the em dashes in remote_commands.js are pre-existing lines outside this diff). Design docs updated in the same commit (0136 → Implemented).

Notes (non-blocking, not defects in this PR)

• test/core/leave-command.test.js fails 7/10 in this sandbox, but identically on master at the merge base — a pre-existing environment artifact (hyp remote leave exits 1), not introduced by this PR. All PR-touched suites are green.
• PickerSource now types 'claude-desktop', but parseInitFlags's --source enum still omits it (openclaw/hermes were added to both). This asymmetry predates Wizard orchestration (T11): fork-join-pick-configure-finale state machine (LLP 0135) #381 (Install-experience overhaul: guided wizard with join-team and local pathways (LLP 0128) #375 shipped the claude-desktop row without a --source entry), so it is not a regression here. Worth a follow-up if --source claude-desktop is meant to be reachable non-interactively.
• The author already flags Wizard finale installs no skills/agents on fleet-managed machines (empty clientsPicked when org locks the clients) #380 (fleet-managed clientsPicked derivation) as an out-of-scope pre-existing defect from Install-experience overhaul: guided wizard with join-team and local pathways (LLP 0128) #375; pick.js derivation is unchanged here, consistent with that claim.

Held for a maintainer to merge.

[philcunliffe]

Reviewed clean at 4d965c5. Held for maintainer to merge.