Setup ends on a question, and can start the client on it (LLP 0195)

[bgmcmullen]

Setup proved it had captured something (LLP 0135 #first-look) but never taught what to do with it. Ten skills land in ~/.claude/skills and the finale reports skills: 10 copied - a file operation, not a capability. The gap was activation, not information: printing example prompts still leaves the user to open a terminal, start a client, and retype one, and the drop-off across those three steps is the whole distance between "installed" and "used".

Both first-party CLI clients take the opening prompt as argv (claude [options] [prompt], codex [OPTIONS] [PROMPT]), so setup can be the launcher.

What it looks like

After the first look and the privacy narration:

┌────────────────────────────────────────────┐
│ Ask your first question                    │
│ Starts Claude Code on the question you pick.
│ up/down · enter start · esc not now        │
│                                            │
│ > Biggest token costs this week            │
│   Where agents stall or waste effort       │
│   Repeated work worth turning into a skill │
│   Where a subagent would pay off           │
│   Not now                                  │
└────────────────────────────────────────────┘

Enter, and Claude comes up already working on that question. No copy-paste step.

Design notes

Full rationale in LLP 0195. The decisions worth reviewing:

The manifest owns the launch; core owns the questions. contributes.client.launch ({ bin, args, label }) says how to start a client on a question, so a future adapter becomes launchable with no core edit - the same rule LLP 0180 set for the finale's client list. A spec missing the {prompt} placeholder is rejected at catalog build: launchable-and-mute looks like the feature working.

Launchability is a $PATH probe, not the picker's detection. A ~/.claude/settings.json does not imply a claude on $PATH, and Claude Desktop is detectable, pickable, attachable, and has no prompt argument at all. Only clients both picked and resolvable are offered - starting an unattached client would open a session nothing captures.

An empty cache suppresses the launch and says why. Every question is about recorded history, so a fresh install with nothing backfilled would spend its one first impression on an empty answer. The first look's result already distinguishes the cases: slow means the opposite of empty and still launches; error/unknown never withholds the offer.

Nothing here can fail a finished install. Missing binary, spawn error, cancel, unforeseen throw - all degrade to the printed list. The child's exit code is deliberately not propagated: quitting the client with ctrl+c is not a failed install.

The launched session is not pre-authorized. No --allowedTools. The client asks its own permission the first time the skill runs hyp query, and that prompt stands. A tool whose pitch is "see what your AI clients are doing" should not open by quietly widening what one of them may do.

hyp ask makes the list re-runnable, and hyp ask "<question>" skips the menu. Every other closing surface names a durable entry point; a menu reachable only by re-running hyp init would be the exception.

Two changes to existing behaviour

The prompt is framed (#frame), which no other wizard prompt is. Position is what makes it necessary: every other prompt owns its screen, while this one lands under the first look's tables, rules and dim footers, where an unframed list of sentences reads as more output to skim rather than the one thing still awaiting a keypress. The frame is a shape rather than a colour, so it survives NO_COLOR and a colour-blind reader, and is suppressed rather than soft-wrapped when it would not fit - a broken rectangle is worse than no rectangle.

Setup's first look runs ['models', 'daily'], not all four sections (#wizard-sections). This takes up the seam LLP 0135 explicitly left open ("the seam for a shorter variant remains if setup output ever needs trimming") and reverses its judgment that all four was right, recorded as a new decision with a forward-ref rather than an edit to what 0135 settled. Both halves of the cost were real: ~60 lines, and ~5s on a 91k-row cache against a planner that budgeted ~2s - so setup routinely printed "Stopped here to keep setup moving - the repos and tools sections did not finish". A block that regularly announces its own truncation is worse than a shorter block that finishes. hyp query overview is unchanged and still renders all four.

That trim needed one fix in the shared module: missingSections now takes the requested set. Without it the wizard would claim repos and tools "did not finish" on every run - a claim about work nobody started, and the exact thing that sentence exists to prevent.

Known issue, not fixed here

The overview planner's SECTION_COST_VS_PROBE is calibrated at 1.9x and measures ~3.4x on a real cache, so it picks windows it cannot finish. Filed as #665 with measurements. The trim reduces how often the wizard trips over it but does not fix it, and a real run after this change still hit the deadline - the issue carries that evidence and argues against the obvious fix (re-measuring the constant), since the probe reads a prunable column and structurally cannot predict what the sections cost.

Testing

• npm test: 3613 pass, 1 fail - usage-policy-fold.test.js:387, confirmed failing identically at master in a clean worktree. Unrelated to this branch.
• npm run typecheck: clean.
• Smokes green: walkthrough_picker_to_first_query, cli_bundled_plugins_activated, package_bin_boot, status_diagnostics.
• New coverage: test/core/cli/wizard/first-ask.test.js (16), test/core/client-launch-manifest.test.js (4), plus the framed-render and wizard-orchestration cases. Launch tests stub the spawn seam - no test starts a real client.
• Verified by hand on macOS: both claude and codex resolve from the real manifests; hyp ask, hyp ask --list, and the no-launcher path (empty $PATH) behave as described.

🤖 Generated with Claude Code

[philcunliffe]

Neutral review round 1 of 2 (adopted PR, neutral:adopt) - e3d3287 - verdict: findings

Two blocking, plus ten non-blocking. Neutral is pushing fixes for the two blockers and the
cheap subset; the rest are left to you and listed below.

This is strong, careful work. Dense and honest rationale, a well-factored boxed
extraction, generous seams for testing, and 16 genuinely good tests around first_ask.js.
The problems are concentrated in the one new file that has no tests at all.

Execution evidence

CI reported no checks on this head, so this local run is the only execution evidence.

Check	Result
node scripts/run-tests.js	3616 tests / 3615 pass / 0 fail / 1 skipped
npx tsc -p tsconfig.json --noEmit	clean, exit 0
smokes walkthrough_picker_to_first_query, cli_bundled_plugins_activated, package_bin_boot, status_diagnostics	all ok

No em dashes anywhere in the diff. No statement-terminating semicolons. All 28
@ref LLP 0195#... anchors resolve and the glosses were spot-checked as accurate.

One correction: the PR body claims usage-policy-fold.test.js:387 fails at master. It did
not fail here; the suite was fully green at this head.

BLOCKING 1 - LLP 0195 is claimed twice

origin/fix/issue-653      llp/0195-upstream-less-gateway-idles.decision.md
origin/wizard-first-ask   llp/0195-setup-ends-on-a-question.decision.md
origin/master             (no llp/0195)

The filenames differ, so git will not conflict - both would land silently as duplicate
LLP 0195s. The llp-check duplicate-numbers job exists precisely for this and has not
run on this head. PR #658 is neutral:approved and held for merge, so it lands first,
which makes this PR the one to renumber.

The next free number is 0198, not 0196: PR #668 just renumbered into 0196/0197.
Computing the next number from master alone (which is only at 0194) is exactly how this
happened - it has to be computed across master and every branch.

Neutral is pushing the renumber to 0198, including all 28 @ref sites, the
Extended-by: block in LLP 0135, and the doc's own title.

BLOCKING 2 - hyp ask launches an unattached client, contradicting its own help text

src/core/commands/ask.js:122-141. if (attached.length > 0) return attached conflates
"probe succeeded, zero clients attached" with "probe threw", so a successful report
showing nothing attached falls through to launching every client on $PATH.

Reproduced on a fresh HYP_HOME with nothing attached and a stub claude on $PATH:
hyp ask "hello world" launched it, exit 0.

That falsifies three statements shipped in this same PR:

• core_commands.js:~272 help: "Only clients that are attached (hyp status) and whose CLI
  is on your PATH can be started."
• ask.js:110-118 docblock: "The clients hyp ask may start: those HypAware is actually
  recording."
• the new LLP #path-probe: "an unpicked client is one HypAware is not recording, so
  opening it would produce a session the user did not consent to capture."

The docblock's own reasoning is right - a probe that cannot read is not evidence of
detachment - but a probe that succeeds and reports zero is. Neutral is pushing the
restructure so only a thrown probe falls through. An unattached machine then correctly
reaches the existing no-launcher message and exit 1.

Also being fixed by neutral

• N1 - src/core/commands/ask.js has zero test coverage. 143 new lines behind a new
  top-level verb, and grep -rln "runAsk\|commands/ask" test/ returns nothing. A single
  test over askableClients would have caught Blocking 2. Adding test/core/commands/ask.test.js.
• N2 - two surviving mutants in firstLookHadRows (wizard/index.js:~556): treating a
  slow first look as empty, and treating an absent one as empty, both leave the suite
  green. The new LLP's #empty-cache says outright that "collapsing any two of them would
  be the bug", and slow-means-yes is the least intuitive of the three.
• N6 - the #no-preauth decision has no test. It is the most security-relevant
  decision in the change and nothing pins it. Adding an assertion that the bundled launch
  args carry no permission-widening flag.
• N7 - hyp ask --list always claims launchability (ask.js:39 hardcodes
  launchable: true), so a machine with nothing on $PATH is told to run a command that
  exits 1.
• N8 - ask.js:28 says "the same five questions"; SUGGESTED_PROMPTS has four.

Left for you, deliberately

• N3 - hyp ask "<question>" never checks for a TTY (ask.js:46-63); it spawns with
  stdio: 'inherit' unconditionally, so in cron/CI/a git hook it can block until the
  client exits. The wizard path is correctly gated (mutation-confirmed) and the menu path
  is gated on isTty; only the named-question path is open. Defensible ("the user asked to
  launch"), but it is the one headless-hang vector the change introduces. Worth either
  refusing on non-TTY or documenting it.
• N4 - hyp ask "q" silently picks launchers[0] when several clients are attached,
  while the menu path asks which should answer. report.clients order is not user-meaningful.
  A --client <name> flag would settle it.
• N5 - "exactly one {prompt}" is documented but not enforced. The LLP and the
  PluginClientLaunchManifest JSDoc both say exactly one, but plugin_catalog.js:93
  validates with .some() and launchClient replaceAlls in every element - and
  first-ask.test.js:151 deliberately asserts multi-slot substitution works. The code's
  behaviour is the better one; the docs should soften to "at least one". Your Draft LLP,
  so your call.
• N9 - resolveOnPath platform seam is host-coupled (first_ask.js:109-111):
  bin.includes(path.sep) and path.join use the host separator while platform is a
  parameter. Harmless in production. Separately, on win32 exts never includes '', so an
  extensionless shim on PATH will not resolve.
• N10 - stray duplicated docblock at test/core/cli/wizard/index.test.js:~683.

Mutation testing: 9 of 11 killed

Killed: requested-set filtering, empty-cache suppression (2), launch spec without
{prompt}, oversized box suppression, stdio mode, unpicked clients offered (7),
first-look section count (3), the non-interactive gate, {prompt} substitution.
Survivors: both in firstLookHadRows (N2 above).

On the specific risks checked

• Declined path: correct and well covered. "Not now", PromptCancelledError, and the
  back error all collapse to declined, print the list, launch nothing, exit 0.
• Idempotent/reversible: yes. The launch writes nothing durable; it is a spawn after
  the last durable write, and the child's exit code is deliberately dropped so quitting the
  client cannot fail a finished install.
• Headless hang: wizard path safe, menu path gated, one open vector (N3).

[philcunliffe]

Neutral review round 2 of 2 (adopted PR) - b87f6a7 - verdict: findings

The one blocker this round was neutral's own defect, not yours, and it has been fixed
(84354cc). Everything else in the heal verified as correct.

BLOCKING (neutral's) - the renumber missed .d.ts files. Fixed.

Neutral's 0195 → 0198 sweep covered .js and .md but not .d.ts, leaving seven
prose citations behind:

hypaware-plugin-kernel-types.d.ts:182,195   (LLP 0195#split)
src/core/types.d.ts:40                      (LLP 0195#split)
src/core/cli/wizard/types.d.ts:405          (LLP 0195#path-probe)
src/core/cli/wizard/types.d.ts:418          (LLP 0195#real-launch)
src/core/cli/wizard/types.d.ts:422,443      (LLP 0195#empty-cache)

All seven were introduced by this PR (zero on master), and they are prose form, not @ref,
so neither ref-check nor duplicate-numbers sees them. Once fix/issue-653 merges they
would have resolved to a real but entirely unrelated document, which is worse than
dangling. hypaware-plugin-kernel-types.d.ts ships to plugin authors via package.json
files, so it would have gone out as the kernel contract.

This is exactly the failure mode the original Blocking 1 existed to prevent, and neutral
reproduced it one file-extension over. Worth noting the verification missed it for the same
reason the fix did: the confirming grep also filtered to .js/.md.

Fixed in 84354cc: zero LLP 0195 references remain anywhere on the branch, and all four
cited anchors (split, path-probe, real-launch, empty-cache) resolve in the 0198 doc.

The rest of the heal verified

Renumber, otherwise correct. llp/0198-… exists, title renumbered, the 0195- filename
gone. All 9 anchors used by @ref LLP 0198#… resolve to real <a id> definitions; a
repo-wide @ref sweep found zero dangling refs. LLP 0135's Extended-by: block is
well-formed. 0198 is free across every origin/* branch (0195 still belongs to
fix/issue-653, 0196/0197 to llp/0193-vendor-report-renderer).

askableClients - correct and complete, verified by trace rather than assumption:

• Its only caller is runAsk (ask.js:38), which passes no options, so the production
  call path is byte-for-byte unchanged (collectStatus defaults to collectHypAwareStatus
  with identical args). No other module imports it.
• Zero-attached traced end to end: clients: [] → resolveLaunchers returns []
  (first_ask.js:147-170) → launchers.length === 0 at :313 → reason:'no-launcher' →
  runAsk:83 returns 1.
• The help text at core_commands.js:274-276 is now true.
• Newly exported, but ask.js is not in package.json exports, so no published-API widening.

The new tests - mutation-verified, not read-verified. Reverting the fix fails exactly the
zero-attached unit test; both N2 mutants (slow → false, !result → false) die. One honest
caveat: ask.test.js:98 ("no-launcher exits 1") passes with or without the fix because
PATH: '' empties the launchers regardless - it is an exit-code contract test and the file
labels it as such; the discriminating test is the unit test at :66.

N6 - a genuine negative test, but a thin denylist. It is not vacuous (assert.ok(launch)
first pins that both clients are launchable, so dropping the launch block fails rather than
silently passing). But Array.includes is exact-element with two entries, so it would not
catch --permission-mode acceptEdits, --full-auto, --yolo, --sandbox danger-full-access,
-a never, or an =true suffixed form. Worth widening to a regex over
(-{1,2})(dangerously|allowedTools|permission-mode|full-auto|yolo|sandbox|ask-for-approval).
Left to you - the pin is real, just narrow.

Fresh pass over the full diff

Read everything neutral did not touch (style.js boxed/visibleWidth, the tui/render.js
frame split, tui/runtime.js per-frame columns, first_look.js section trim,
overview.js missingSections(rows, sections), plugin_catalog.js launch validation, both
manifests, README). No em dashes, no statement-terminating semicolons, no inline import('…')
types, type-import specifiers root-anchored. The render/countPhysicalRows width agreement
is explicitly handled and commented. Nothing the heal broke.

One non-blocking observation: runAsk now calls askableClients (a full
collectHypAwareStatus: config load, layered merge, plugin catalog build) before the
--list early return, so hyp ask --list is measurably slower for a command documented as
"print the suggested questions and exit". Verified read-only and network-free, so it is
latency only. Computing launchers lazily inside the --list branch would avoid it.

Round 1's N3, N4, N5, N9, N10 remain open as intended.

Execution evidence

Check	Result
node scripts/run-tests.js	3624 pass / 0 fail / 1 skipped, exit 0
npx tsc -p tsconfig.json --noEmit	clean, exit 0
Mutation probes (3)	all 3 mutants killed

CI ran green on b87f6a7 - 9 check runs, all success, including duplicate-numbers.
That is a change from round 1, when no checks had run at all. The 84354cc fix is
docs/types-only and re-verified locally (3624 pass, tsc exit 0); CI will re-run on it.

[philcunliffe]

Verdict: changes requested - five items that are yours to decide

Two review rounds are used, so the residual findings go back to you rather than being
deferred to a follow-up issue. None of them is a defect neutral found and left broken -
both blockers are fixed and on the branch:

• LLP 0195 → 0198 renumber (neutral pushed): 0195 was claimed by fix/issue-653,
  0196/0197 by llp/0193-vendor-report-renderer, so 0198 was the next free number across
  every branch. Zero LLP 0195 references remain.
• hyp ask launching an unattached client (neutral pushed): a successful probe reporting
  zero attached now returns [] instead of falling through to every launchable client. Only
  a thrown probe falls through. Traced end to end: the zero-attached case now reaches
  no-launcher and exit 1, so the help text's "only clients that are attached ... can be
  started" is true.
• Neutral's own renumber missed seven .d.ts citations; that was neutral's defect and is
  fixed in 84354cc.

CI is green and the suite is 3624 pass / 0 fail, tsc clean.

What is left, all requiring your judgment

1. hyp ask "<question>" has no TTY check (ask.js:46-63) - it spawns with
   stdio: 'inherit' unconditionally, so in cron, CI, or a git hook it can block until the
   client exits. The wizard path is correctly gated (mutation-confirmed) and the hyp ask
   menu is gated on isTty; the named-question path is the one open vector. Defensible as
   "the user asked to launch" - but it should be a decision, either refusing on non-TTY or
   documenting it.
2. hyp ask "q" silently picks launchers[0] when several clients are attached, while
   the menu path asks which should answer. report.clients order is not user-meaningful. A
   --client <name> flag would settle it.
3. "Exactly one {prompt}" is documented but not enforced. Your LLP and the
   PluginClientLaunchManifest JSDoc both say exactly one, but plugin_catalog.js:93
   validates with .some() and launchClient replaceAlls every element - and
   first-ask.test.js:151 deliberately asserts multi-slot substitution works. The code's
   behaviour is the better one; the docs should soften to "at least one". Your Draft doc,
   your call.
4. The no-preauth assertion is real but thin. It is not vacuous - assert.ok(launch)
   first pins that both clients are launchable - but Array.includes is exact-element over
   two entries. It would not catch --permission-mode acceptEdits,
   --dangerously-bypass-approvals-and-sandbox, --full-auto, --yolo,
   --sandbox danger-full-access, -a never, or an =true suffixed form. Since this pins
   the most security-relevant decision in the change, widening it to a regex over
   (-{1,2})(dangerously|allowedTools|permission-mode|full-auto|yolo|sandbox|ask-for-approval)
   is worth the two minutes.
5. resolveOnPath's platform seam is host-coupled (first_ask.js:109-111):
   bin.includes(path.sep) and path.join use the host separator while platform is a
   parameter, so platform: 'win32' on POSIX builds POSIX paths. Harmless in production.
   Separately, on win32 exts never includes '', so an extensionless shim on PATH will
   not resolve.

Also worth a look, non-blocking: runAsk now calls askableClients (a full
collectHypAwareStatus - config load, layered merge, plugin catalog build) before the
--list early return, so hyp ask --list got measurably slower for a command documented as
"print the suggested questions and exit". It is read-only and network-free, so latency only;
computing launchers lazily inside the --list branch avoids it. And there is a stray
duplicated docblock at test/core/cli/wizard/index.test.js:~683.

Push any commit and neutral re-engages on its next tick with a fresh review at the new head.

[philcunliffe]

Two things from #665 that affect this PR, separate from the review verdict above.

1. Your LLP is now 0198, not 0195. Neutral renumbered it on this branch because
fix/issue-653 already claims llp/0195-upstream-less-gateway-idles.decision.md. The
filenames differ, so git would not have conflicted - both would have landed silently as
duplicate 0195s, and the duplicate-numbers job had not run on the branch at that point.
0196/0197 were taken by #668, so 0198 was the next free number across every branch.

This matters beyond the file: your prose in #665 cites LLP 0195 #wizard-sections, and that
number no longer exists here. The anchor is at
llp/0198-setup-ends-on-a-question.decision.md:141.

2. This PR and #666 have a merge-order dependency. first_look.js:187 here requests a
two-section subset, but rowsAffordable on master still hardcodes
OVERVIEW_SECTIONS.length (four). With this PR merged and #666 not, the planner charges for
four sections while two run, narrowing the window to roughly half what the budget allows and
truncating more than necessary - the "Stopped here to keep setup moving" symptom, from the
opposite direction.

#666 should merge before or together with this PR. It is neutral:approved and held.

Neutral's earlier comment on #665 claimed the wizard does not request a subset. That was
checked against master only and was wrong about your branch; corrected on the issue.