From fe758d469414710288bff8130e1541e1a2a0a6c4 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 14 Oct 2026 00:21:13 +0000
Subject: [PATCH 1/3] fix(hub-ui-onboard): require a terminal code to install
 or disable

---
 docs/content/1.guide/23.hub-ui-onboard.md     | 16 ++++-
 docs/content/6.errors/DF9005.md               | 20 ++++++
 docs/content/6.errors/DF9006.md               | 20 ++++++
 docs/content/8.references/6.hub-api.md        |  8 ++-
 examples/hub-onboard-vite/README.md           |  4 +-
 packages/hub-ui-onboard/playground/index.html |  2 +-
 .../hub-ui-onboard/playground/vite.config.ts  |  9 ++-
 packages/hub-ui-onboard/src/client/index.ts   | 63 +++++++++++++++---
 packages/hub-ui-onboard/src/client/style.css  |  5 ++
 packages/hub-ui-onboard/src/diagnostics.ts    |  8 +++
 packages/hub-ui-onboard/src/index.ts          | 50 +++++++++++---
 packages/hub-ui-onboard/src/protocol.ts       |  2 +
 packages/hub-ui-onboard/src/types.ts          |  4 ++
 .../hub-ui-onboard/test/onboarding.test.ts    | 66 +++++++++++++++++--
 .../hub-ui-onboard/index.snapshot.d.ts        |  2 +
 15 files changed, 247 insertions(+), 32 deletions(-)
 create mode 100644 docs/content/6.errors/DF9005.md
 create mode 100644 docs/content/6.errors/DF9006.md
 create mode 100644 packages/hub-ui-onboard/src/protocol.ts

diff --git a/docs/content/1.guide/23.hub-ui-onboard.md b/docs/content/1.guide/23.hub-ui-onboard.md
index f3fc9a9a..60a91ce8 100644
--- a/docs/content/1.guide/23.hub-ui-onboard.md
+++ b/docs/content/1.guide/23.hub-ui-onboard.md
@@ -19,6 +19,8 @@ The button sits at the bottom left, dimmed until hovered. It opens a panel with
 - **Hide for now** removes the button for the current browser tab.
 - **Disable entirely** writes a state file so the host stops injecting the button on every later start.
 
+Install and Disable entirely first ask for a 6-digit code that the dev server prints in the terminal (below).
+
 The panel follows the shared design tokens, the host's `primaryColor`, and the user's hub color scheme, so the swap to the real dock looks like one product.
 
 ## Create the onboarding
@@ -39,7 +41,17 @@ const onboarding = createOnboarding({
 - `scriptSrc`: `<base>embedded.js`, the URL to inject as `<script type="module">`.
 - `disabled` and `installed`: what the host needs to decide whether to inject the script at all (below).
 
-`packages` are package specs as the package manager accepts them. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn`, `bun`, `deno`), `dev: true` adds `-D`, and `cwd` (default `process.cwd()`) is the project that receives the dependency. In a workspace, point `cwd` at the package that runs the dev server. The packages are fixed at creation, and a `POST` from another origin is refused.
+`packages` are package specs as the package manager accepts them. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn`, `bun`, `deno`), `dev: true` adds `-D`, and `cwd` (default `process.cwd()`) is the project that receives the dependency. In a workspace, point `cwd` at the package that runs the dev server. The packages are fixed at creation.
+
+## Confirm with the terminal code
+
+Install and Disable entirely change the project, and a dev server can listen on the network. So the onboarding accepts them only from a person who can read the terminal:
+
+1. The first `POST` from the panel has no code. The onboarding prints [DF9005](/errors/DF9005) with a 6-digit code and answers `401`.
+2. The panel shows a field for the code. The user types it, and the panel sends it again in the `x-devframes-onboard-code` header.
+3. After five wrong codes, both actions answer `429` with [DF9006](/errors/DF9006) until the dev server restarts.
+
+The code stays the same for the life of the process, so Retry after a failed install does not ask again. A `POST` from another origin is also refused with `403`. The host has nothing to configure.
 
 ## Hand the base to the hub
 
@@ -184,4 +196,4 @@ Frameworks with a `Request => Response` surface (Hono, Nitro, Deno) mount `onboa
 
 ## Errors
 
-The Node side reports through `DF9000` to `DF9004`. An install failure or a throwing `onInstalled` also reaches the panel as `{ state: 'error', error: { code, message } }`, with a Retry button. See the [error reference](/errors).
+The Node side reports through `DF9000` to `DF9006`. An install failure or a throwing `onInstalled` also reaches the panel as `{ state: 'error', error: { code, message } }`, with a Retry button. See the [error reference](/errors).
diff --git a/docs/content/6.errors/DF9005.md b/docs/content/6.errors/DF9005.md
new file mode 100644
index 00000000..15673fc5
--- /dev/null
+++ b/docs/content/6.errors/DF9005.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9005: Onboarding Code Requested'
+description: 'A browser asked to {action}. To allow it, enter this code in the panel: {code}'
+---
+
+## Message
+
+> A browser asked to `{action}`. To allow it, enter this code in the panel: `{code}`
+
+## Cause
+
+Install and Disable change the project, and a dev server can listen on the network. So the onboarding panel must send a 6-digit code that only the terminal shows. A request to `POST <base>__onboard/install` or `POST <base>__onboard/disable` came without the `x-devframes-onboard-code` header, and `createOnboarding()` printed the code. The code stays the same until the process exits.
+
+## Fix
+
+If you clicked Install or Disable entirely, type the code into the panel. If you did not, another device or page can reach this dev server. Do not enter the code anywhere, and bind the dev server to `localhost`.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` prints this and answers with status 401 when the request has no code.
diff --git a/docs/content/6.errors/DF9006.md b/docs/content/6.errors/DF9006.md
new file mode 100644
index 00000000..bc42daac
--- /dev/null
+++ b/docs/content/6.errors/DF9006.md
@@ -0,0 +1,20 @@
+---
+title: 'DF9006: Too Many Wrong Onboarding Codes'
+description: 'Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.'
+---
+
+## Message
+
+> Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.
+
+## Cause
+
+Install and Disable need the code that [DF9005](/errors/DF9005) prints. After five wrong codes, `createOnboarding()` refuses both actions for the rest of the process, so nobody can guess the code.
+
+## Fix
+
+Restart the dev server. It prints a new code the next time you click Install or Disable entirely. If you did not enter the wrong codes, another device or page can reach this dev server: bind it to `localhost`. You can also run the install command from the panel in a terminal.
+
+## Source
+
+- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` reports this on the fifth wrong code, then answers each later Install or Disable with status 429 and this code.
diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md
index 55f084a9..bf4b0079 100644
--- a/docs/content/8.references/6.hub-api.md
+++ b/docs/content/8.references/6.hub-api.md
@@ -96,15 +96,17 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
 | `stateDir` | `<cwd>/node_modules/.devframe` | Directory of the `hub-ui-onboard.json` state file |
 | `dev` | `true` | Install as a devDependency |
 | `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
-| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `hide`, `disable`, `installing`, `restart`, `retry` |
+| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `code`, `wrongCode`, `hide`, `disable`, `installing`, `restart`, `retry` |
 | `onInstalled` | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over `base` |
 
 | Route | Serves |
 | --- | --- |
 | `GET <base>embedded.js` | the floating button, a self-contained ES module |
 | `GET <base>__onboard/status` | `{ state, command, branding, messages, error? }` |
-| `POST <base>__onboard/install` | starts the install (`202`), same-origin only |
-| `POST <base>__onboard/disable` | writes the state file (`204`), same-origin only |
+| `POST <base>__onboard/install` | starts the install (`202`), with the terminal code only |
+| `POST <base>__onboard/disable` | writes the state file (`204`), with the terminal code only |
+
+Both `POST` routes answer `403` to another origin. Without the `x-devframes-onboard-code` header, they print the code ([DF9005](/errors/DF9005)) and answer `401`. A wrong code also gets `401`. After five wrong codes, they answer `429` with [DF9006](/errors/DF9006) until the process restarts.
 
 | `state` | Meaning |
 | --- | --- |
diff --git a/examples/hub-onboard-vite/README.md b/examples/hub-onboard-vite/README.md
index 334b122a..b8cea2cd 100644
--- a/examples/hub-onboard-vite/README.md
+++ b/examples/hub-onboard-vite/README.md
@@ -6,12 +6,14 @@ A Vite host that ships only `@devframes/hub-ui-onboard` (about 20 kB in the brow
 pnpm --filter hub-onboard-vite dev
 ```
 
-Open the printed URL. The button at the bottom left opens a panel with two actions:
+Open the printed URL. The button at the bottom left opens a panel with three actions:
 
 - Install runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
 - Hide for now hides the button for this browser tab.
 - Disable entirely writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
 
+Install and Disable entirely ask for the 6-digit code that the dev server prints in the terminal (`DF9005`).
+
 When the three packages are already installed, the button never shows: the host's `onInstalled` runs on the first request and the real dock appears directly.
 
 Install changes this example's `package.json` and the lockfile. Run `git checkout -- examples/hub-onboard-vite pnpm-lock.yaml` and delete the state file to reset the demo.
diff --git a/packages/hub-ui-onboard/playground/index.html b/packages/hub-ui-onboard/playground/index.html
index a9b40833..425d62c4 100644
--- a/packages/hub-ui-onboard/playground/index.html
+++ b/packages/hub-ui-onboard/playground/index.html
@@ -14,7 +14,7 @@
   </head>
   <body>
     <h1>hub-ui-onboard</h1>
-    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API.</p>
+    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API. When Install or Disable asks for the terminal code, enter <code>123456</code>.</p>
     <fieldset>
       <legend>State</legend>
       <button data-state="idle">idle</button>
diff --git a/packages/hub-ui-onboard/playground/vite.config.ts b/packages/hub-ui-onboard/playground/vite.config.ts
index a04c68b6..d6a2c727 100644
--- a/packages/hub-ui-onboard/playground/vite.config.ts
+++ b/packages/hub-ui-onboard/playground/vite.config.ts
@@ -4,15 +4,18 @@ import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import { defaultMessages } from '../src/index'
+import { CODE_HEADER } from '../src/protocol'
 
 const root = fileURLToPath(new URL('..', import.meta.url))
 const productName = 'Devframes'
+const MOCK_CODE = '123456'
 
 /**
  * A fake of the `__onboard/*` routes `createOnboarding` serves. The client
  * resolves them next to its own module (`/src/client/`). The playground page
  * picks the state through `/__mock/state`; Install runs a timer instead of a
- * package manager and ends in `installed` or `error`.
+ * package manager and ends in `installed` or `error`. Install and Disable
+ * accept only the code `123456`.
  */
 function mockOnboarding(): Plugin {
   let state: OnboardingState = 'idle'
@@ -46,6 +49,10 @@ function mockOnboarding(): Plugin {
         if (!url.pathname.startsWith('/src/client/__onboard/'))
           return next()
         const route = url.pathname.split('/').pop()
+        if (route !== 'status' && req.headers[CODE_HEADER] !== MOCK_CODE) {
+          res.statusCode = 401
+          return res.end()
+        }
         if (route === 'install') {
           state = 'installing'
           timer = setTimeout(() => (state = outcome), 2500)
diff --git a/packages/hub-ui-onboard/src/client/index.ts b/packages/hub-ui-onboard/src/client/index.ts
index b6a9e6ac..8c286554 100644
--- a/packages/hub-ui-onboard/src/client/index.ts
+++ b/packages/hub-ui-onboard/src/client/index.ts
@@ -1,4 +1,5 @@
 import type { OnboardingBranding, OnboardingStatus } from '../types'
+import { CODE_HEADER } from '../protocol'
 import css from './.generated/css'
 import { DEVFRAME_LOGO } from './logo'
 
@@ -189,9 +190,32 @@ function mount(initial: OnboardingStatus): void {
   commandRow.className = 'devframes-onboard-command-row'
   commandRow.append(command, copy)
 
+  // Shown when the server asks for the code it printed in the terminal.
+  // A form, so Enter repeats the action that asked for it.
+  let pending: 'install' | 'disable' = 'install'
+  const codeForm = document.createElement('form')
+  codeForm.hidden = true
+  const codeField = document.createElement('label')
+  codeField.className = 'flex flex-col gap-1 text-xs color-muted'
+  const codeInput = document.createElement('input')
+  codeInput.className = 'devframes-onboard-code'
+  codeInput.inputMode = 'numeric'
+  codeInput.autocomplete = 'one-time-code'
+  codeInput.maxLength = 6
+  codeField.append(messages.code, codeInput)
+  codeForm.append(codeField)
+  codeForm.addEventListener('submit', (event) => {
+    event.preventDefault()
+    void (pending === 'install' ? startInstall() : disableDevtools())
+  })
+
   const note = document.createElement('p')
-  note.className = 'm-0 text-xs'
+  note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
   note.hidden = true
+  const showNote = (text: string) => {
+    note.hidden = !text
+    note.textContent = text
+  }
 
   const install = button('btn-primary text-sm justify-center gap-1', messages.install, () => void startInstall())
   // The spinner takes its space from the line height, so the button keeps its size.
@@ -213,7 +237,7 @@ function mount(initial: OnboardingStatus): void {
   actions.className = 'flex flex-col gap-2'
   actions.append(secondary, install)
 
-  panel.append(heading, description, commandRow, note, actions)
+  panel.append(heading, description, commandRow, codeForm, note, actions)
   scheme.append(glow, pill, panel)
 
   let open = false
@@ -246,11 +270,7 @@ function mount(initial: OnboardingStatus): void {
       : state === 'installed'
         ? messages.restart
         : state === 'error' ? messages.retry : messages.install
-    note.hidden = state !== 'error'
-    note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
-    note.textContent = state === 'error'
-      ? `${status.error?.code}: ${status.error?.message}`
-      : ''
+    showNote(state === 'error' ? `${status.error?.code}: ${status.error?.message}` : '')
   }
 
   async function poll(): Promise<void> {
@@ -265,15 +285,38 @@ function mount(initial: OnboardingStatus): void {
       setTimeout(() => void poll(), POLL_MS)
   }
 
+  /** POST `action` with the entered code; `true` when the server accepted it. */
+  async function send(action: typeof pending): Promise<boolean> {
+    pending = action
+    // Kept after success, so Retry does not ask again.
+    const code = codeInput.value.trim()
+    const response = await api(action, { method: 'POST', headers: code ? { [CODE_HEADER]: code } : {} })
+    if (response.status === 401) {
+      showNote(code ? messages.wrongCode : '')
+      codeInput.value = ''
+      codeForm.hidden = false
+      codeInput.focus()
+      return false
+    }
+    if (!response.ok) {
+      // A `DF90xx` body: too many wrong codes, or the state file failed.
+      const error: OnboardingStatus['error'] = await response.json().catch(() => undefined)
+      showNote(error ? `${error.code}: ${error.message}` : '')
+      return false
+    }
+    codeForm.hidden = true
+    return true
+  }
+
   async function startInstall(): Promise<void> {
+    if (!await send('install'))
+      return
     render({ ...initial, state: 'installing' })
-    await api('install', { method: 'POST' })
     await poll()
   }
 
   async function disableDevtools(): Promise<void> {
-    const response = await api('disable', { method: 'POST' })
-    if (response.ok)
+    if (await send('disable'))
       host.remove()
   }
 
diff --git a/packages/hub-ui-onboard/src/client/style.css b/packages/hub-ui-onboard/src/client/style.css
index 675c6a08..5cf9427b 100644
--- a/packages/hub-ui-onboard/src/client/style.css
+++ b/packages/hub-ui-onboard/src/client/style.css
@@ -57,6 +57,11 @@
   --uno: transition-opacity duration-200;
 }
 
+.devframes-onboard-code {
+  --uno: w-full min-w-0 rounded border border-base bg-base color-base px-2.5 py-1 font-mono text-sm tabular-nums tracking-widest;
+  --uno: outline-none transition focus-visible:border-active focus-visible:ring-2 ring-primary-400;
+}
+
 .devframes-onboard-spinner[hidden] {
   --uno: hidden;
 }
diff --git a/packages/hub-ui-onboard/src/diagnostics.ts b/packages/hub-ui-onboard/src/diagnostics.ts
index c2151d49..ed8caf00 100644
--- a/packages/hub-ui-onboard/src/diagnostics.ts
+++ b/packages/hub-ui-onboard/src/diagnostics.ts
@@ -29,5 +29,13 @@ export const diagnostics = defineDiagnostics({
       why: (p: { file: string }) => `The onboarding state file ${p.file} could not be read or written.`,
       fix: 'Make sure that `stateDir` is writable, or point it at another directory.',
     },
+    DF9005: {
+      why: (p: { action: string, code: string }) => `A browser asked to ${p.action}. To allow it, enter this code in the panel: ${p.code}`,
+      fix: 'If you did not click the button, another device can reach this dev server. Do not enter the code, and bind the dev server to localhost.',
+    },
+    DF9006: {
+      why: 'Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.',
+      fix: 'Restart the dev server to get a new code. If you did not enter these codes, another device can reach this dev server: bind it to localhost.',
+    },
   },
 })
diff --git a/packages/hub-ui-onboard/src/index.ts b/packages/hub-ui-onboard/src/index.ts
index f69497b8..231bead4 100644
--- a/packages/hub-ui-onboard/src/index.ts
+++ b/packages/hub-ui-onboard/src/index.ts
@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ResolvedCommand } from 'package-manager-detector'
 import type { CreateOnboardingOptions, Onboarding, OnboardingHandler, OnboardingMessages, OnboardingState, OnboardingStatus } from './types'
 import { Buffer } from 'node:buffer'
+import { randomInt, timingSafeEqual } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
@@ -12,10 +13,12 @@ import { fileURLToPath } from 'node:url'
 import { Diagnostic } from 'nostics'
 import { diagnostics } from './diagnostics'
 import { packagesInstalled, resolveInstallCommand, runInstall } from './install'
+import { CODE_HEADER } from './protocol'
 
 export type * from './types'
 
 const STATE_FILE = 'hub-ui-onboard.json'
+const MAX_WRONG_CODES = 5
 
 /** `devframes` → `/devframes/`, same rule as `normalizeHubBase` in `@devframes/hub`. */
 function normalizeBase(base: string): string {
@@ -38,6 +41,8 @@ export function defaultMessages(productName: string): OnboardingMessages {
     title: productName,
     description: `${productName} enables development features in your project. Install it with:`,
     install: `Install ${productName}`,
+    code: 'Enter the code that the dev server printed in your terminal.',
+    wrongCode: 'Wrong code. Try again.',
     hide: 'Hide in this session',
     disable: 'Disable entirely',
     installing: 'Installing...',
@@ -185,6 +190,38 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
     return new Response(null, { status: 204 })
   }
 
+  function startInstall(): Response {
+    if (state === 'idle' || state === 'error')
+      void install()
+    return new Response(null, { status: 202 })
+  }
+
+  // The dev server can listen on the network, and a non-browser request can
+  // send any `Origin`. So Install and Disable also need a code that only the terminal shows.
+  const code = Buffer.from(String(randomInt(1_000_000)).padStart(6, '0'))
+  let wrongCodes = 0
+  let locked: Diagnostic | undefined
+
+  /** The refusal to send, or `undefined` when the request may run `action`. */
+  function authorize(request: Request, action: string): Response | undefined {
+    if (!isSameOrigin(request))
+      return new Response(null, { status: 403 })
+    if (!locked) {
+      const given = request.headers.get(CODE_HEADER)
+      if (given === null) {
+        diagnostics.DF9005({ action, code: code.toString() })
+        return new Response(null, { status: 401 })
+      }
+      const candidate = Buffer.from(given)
+      if (candidate.length === code.length && timingSafeEqual(candidate, code))
+        return undefined
+      if (++wrongCodes < MAX_WRONG_CODES)
+        return new Response(null, { status: 401 })
+      locked = diagnostics.DF9006()
+    }
+    return json({ code: locked.code, message: locked.message }, 429)
+  }
+
   async function status(): Promise<OnboardingStatus> {
     const command = await getCommand()
     return { state, command: [command.command, ...command.args], branding, messages, error }
@@ -207,15 +244,10 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
     }
     if (route === 'GET __onboard/status')
       return json(await status())
-    if (route === 'POST __onboard/install' || route === 'POST __onboard/disable') {
-      if (!isSameOrigin(request))
-        return new Response(null, { status: 403 })
-      if (route.endsWith('disable'))
-        return disable()
-      if (state === 'idle' || state === 'error')
-        void install()
-      return new Response(null, { status: 202 })
-    }
+    if (route === 'POST __onboard/install')
+      return authorize(request, `install ${plan.packages.join(' ')}`) ?? startInstall()
+    if (route === 'POST __onboard/disable')
+      return authorize(request, 'disable the onboarding button') ?? disable()
     return new Response(null, { status: 404 })
   }
 
diff --git a/packages/hub-ui-onboard/src/protocol.ts b/packages/hub-ui-onboard/src/protocol.ts
new file mode 100644
index 00000000..a2fe41db
--- /dev/null
+++ b/packages/hub-ui-onboard/src/protocol.ts
@@ -0,0 +1,2 @@
+/** The request header that carries the code the terminal printed (`DF9005`). */
+export const CODE_HEADER = 'x-devframes-onboard-code'
diff --git a/packages/hub-ui-onboard/src/types.ts b/packages/hub-ui-onboard/src/types.ts
index 6bacf92c..36956dd6 100644
--- a/packages/hub-ui-onboard/src/types.ts
+++ b/packages/hub-ui-onboard/src/types.ts
@@ -17,6 +17,10 @@ export interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string
   install: string
+  /** Label of the field for the code that Install and Disable need. */
+  code: string
+  /** Shown when the server refused the code. */
+  wrongCode: string
   /** Hides the button for this browser tab (`sessionStorage`). */
   hide: string
   /** Writes the state file; the host stops injecting the button. */
diff --git a/packages/hub-ui-onboard/test/onboarding.test.ts b/packages/hub-ui-onboard/test/onboarding.test.ts
index 2e171c25..c6b301e0 100644
--- a/packages/hub-ui-onboard/test/onboarding.test.ts
+++ b/packages/hub-ui-onboard/test/onboarding.test.ts
@@ -6,8 +6,9 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import process from 'node:process'
 import { fileURLToPath } from 'node:url'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createOnboarding } from '../src'
+import { CODE_HEADER } from '../src/protocol'
 
 const FIXTURE = fileURLToPath(new URL('./fixtures/pkg', import.meta.url))
 
@@ -57,6 +58,31 @@ async function waitFor<T>(read: () => Promise<T>, done: (value: T) => boolean):
 
 const settled = (s: OnboardingStatus) => s.state !== 'installing' && s.state !== 'idle'
 
+function post(origin: string, action: 'install' | 'disable', code?: string): Promise<Response> {
+  return fetch(`${origin}/__devframes/__onboard/${action}`, {
+    method: 'POST',
+    headers: { origin, ...(code ? { [CODE_HEADER]: code } : {}) },
+  })
+}
+
+/** Ask without a code, as the panel does first, and read the code the terminal shows. */
+async function codeFromTerminal(origin: string, action: 'install' | 'disable'): Promise<string> {
+  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+  try {
+    expect((await post(origin, action)).status).toBe(401)
+    const printed = String(warn.mock.lastCall?.[0])
+    expect(printed).toContain('DF9005')
+    return printed.match(/panel: (\d{6})/)![1]!
+  }
+  finally {
+    warn.mockRestore()
+  }
+}
+
+async function confirm(origin: string, action: 'install' | 'disable'): Promise<Response> {
+  return post(origin, action, await codeFromTerminal(origin, action))
+}
+
 describe('createOnboarding', () => {
   it('refuses an empty package list', () => {
     expect(() => createOnboarding({ packages: [] })).toThrow(expect.objectContaining({ code: 'DF9000' }))
@@ -105,10 +131,40 @@ describe('createOnboarding', () => {
     expect((await status(origin)).state).toBe('idle')
   })
 
+  it('refuses an install or disable without the code from the terminal', async () => {
+    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
+    for (const action of ['install', 'disable'] as const) {
+      // A non-browser client sends neither `Origin` nor `Sec-Fetch-Site`.
+      expect((await fetch(`${origin}/__devframes/__onboard/${action}`, { method: 'POST' })).status).toBe(401)
+      const code = await codeFromTerminal(origin, action)
+      const wrong = code === '000000' ? '000001' : '000000'
+      expect((await post(origin, action, wrong)).status).toBe(401)
+    }
+    expect((await status(origin)).state).toBe('idle')
+  })
+
+  it('blocks install and disable after five wrong codes', async () => {
+    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
+    const code = await codeFromTerminal(origin, 'disable')
+    const wrong = code === '000000' ? '000001' : '000000'
+    for (let i = 0; i < 4; i++)
+      expect((await post(origin, 'disable', wrong)).status).toBe(401)
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    const blocked = await post(origin, 'disable', wrong)
+    warn.mockRestore()
+    expect(blocked.status).toBe(429)
+    expect(await blocked.json()).toMatchObject({ code: 'DF9006' })
+
+    expect((await post(origin, 'disable', code)).status).toBe(429)
+    expect((await post(origin, 'install', code)).status).toBe(429)
+    expect((await status(origin)).state).toBe('idle')
+  })
+
   it('persists disable on disk for the next process', async () => {
     const cwd = tempProject()
     const origin = await serve(createOnboarding({ cwd, packages: ['x'] }))
-    const response = await fetch(`${origin}/__devframes/__onboard/disable`, { method: 'POST', headers: { origin } })
+    const response = await confirm(origin, 'disable')
     expect(response.status).toBe(204)
     expect((await status(origin)).state).toBe('disabled')
 
@@ -126,7 +182,7 @@ describe('createOnboarding', () => {
     })
     const origin = await serve(onboarding)
 
-    const accepted = await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    const accepted = await confirm(origin, 'install')
     expect(accepted.status).toBe(202)
 
     const script = () => fetch(`${origin}/__devframes/embedded.js`).then(r => r.text())
@@ -160,7 +216,7 @@ describe('createOnboarding', () => {
   it('reports a failed install as an error the client can retry', async () => {
     const cwd = tempProject()
     const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'] }))
-    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    await confirm(origin, 'install')
     const final = await waitFor(() => status(origin), s => s.state === 'error')
     expect(final.error?.code).toBe('DF9001')
     expect(final.error?.message).toContain('npm i -D file:/nonexistent/onboard-missing')
@@ -169,7 +225,7 @@ describe('createOnboarding', () => {
   it('asks for a restart when onInstalled returns nothing', async () => {
     const cwd = tempProject()
     const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false }))
-    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
+    await confirm(origin, 'install')
     const final = await waitFor(() => status(origin), settled)
     expect(final.state).toBe('installed')
     expect(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).dependencies).toHaveProperty('onboard-fixture')
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
index aedb7804..9cf71195 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
@@ -28,6 +28,8 @@ export interface OnboardingMessages {
   title: string;
   description: string;
   install: string;
+  code: string;
+  wrongCode: string;
   hide: string;
   disable: string;
   installing: string;

From ebcbd344763f0102209beb1d18487e738b594d70 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 14 Oct 2026 00:38:55 +0000
Subject: [PATCH 2/3] fix(hub-ui-onboard): confirm installs in the terminal
 through a configurable hook

---
 docs/content/1.guide/23.hub-ui-onboard.md     |  29 +++--
 docs/content/6.errors/DF9005.md               |  14 ++-
 docs/content/6.errors/DF9006.md               |  12 +-
 docs/content/8.references/6.hub-api.md        |   9 +-
 examples/hub-onboard-vite/README.md           |   6 +-
 packages/hub-ui-onboard/playground/index.html |   3 +-
 .../hub-ui-onboard/playground/vite.config.ts  |  33 +++---
 packages/hub-ui-onboard/src/client/index.ts   |  70 +++--------
 packages/hub-ui-onboard/src/client/style.css  |   5 -
 packages/hub-ui-onboard/src/diagnostics.ts    |   8 +-
 packages/hub-ui-onboard/src/index.ts          |  66 +++++------
 packages/hub-ui-onboard/src/protocol.ts       |   2 -
 .../hub-ui-onboard/src/terminal-confirm.ts    |  26 ++++
 packages/hub-ui-onboard/src/types.ts          |  26 +++-
 .../hub-ui-onboard/test/onboarding.test.ts    | 111 +++++++++---------
 .../test/terminal-confirm.test.ts             |  44 +++++++
 .../hub-ui-onboard/index.snapshot.d.ts        |  10 +-
 17 files changed, 269 insertions(+), 205 deletions(-)
 delete mode 100644 packages/hub-ui-onboard/src/protocol.ts
 create mode 100644 packages/hub-ui-onboard/src/terminal-confirm.ts
 create mode 100644 packages/hub-ui-onboard/test/terminal-confirm.test.ts

diff --git a/docs/content/1.guide/23.hub-ui-onboard.md b/docs/content/1.guide/23.hub-ui-onboard.md
index 60a91ce8..93d8c8c7 100644
--- a/docs/content/1.guide/23.hub-ui-onboard.md
+++ b/docs/content/1.guide/23.hub-ui-onboard.md
@@ -15,12 +15,10 @@ A hub UI provider, its Vue runtime, and the devframes it mounts add tens of mega
 
 The button sits at the bottom left, dimmed until hovered. It opens a panel with the product name and logo, one sentence, the exact command the install will run (for example `pnpm add -D @nuxt/devtools`), and three actions:
 
-- **Install** runs the command in the project. The panel shows progress, then either the real dock replaces the button in place, or the panel asks for a restart.
+- **Install** runs the command in the project after the developer allows it in the terminal (below). The panel shows progress, then either the real dock replaces the button in place, or the panel asks for a restart.
 - **Hide for now** removes the button for the current browser tab.
 - **Disable entirely** writes a state file so the host stops injecting the button on every later start.
 
-Install and Disable entirely first ask for a 6-digit code that the dev server prints in the terminal (below).
-
 The panel follows the shared design tokens, the host's `primaryColor`, and the user's hub color scheme, so the swap to the real dock looks like one product.
 
 ## Create the onboarding
@@ -43,15 +41,28 @@ const onboarding = createOnboarding({
 
 `packages` are package specs as the package manager accepts them. The package manager comes from the lockfile (`npm`, `pnpm`, `yarn`, `bun`, `deno`), `dev: true` adds `-D`, and `cwd` (default `process.cwd()`) is the project that receives the dependency. In a workspace, point `cwd` at the package that runs the dev server. The packages are fixed at creation.
 
-## Confirm with the terminal code
+## Confirm the install
+
+Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. By default, the onboarding asks in the terminal that runs the dev server:
+
+1. The user clicks Install. The panel shows "Confirm in your terminal..." and its request waits.
+2. The terminal prints [DF9005](/errors/DF9005). The developer types `y` and presses Enter to allow the install. Any other answer refuses it.
+3. The install runs. After a refusal, the panel says that the dev server did not allow the install.
 
-Install and Disable entirely change the project, and a dev server can listen on the network. So the onboarding accepts them only from a person who can read the terminal:
+When stdin is not a TTY (CI, a detached container, a task runner that pipes stdin), nobody can answer. The onboarding then refuses at once with [DF9006](/errors/DF9006). Only one question is open at a time: more clicks while it is open share its answer. A `POST` from another origin is refused with `403` before any question.
 
-1. The first `POST` from the panel has no code. The onboarding prints [DF9005](/errors/DF9005) with a 6-digit code and answers `401`.
-2. The panel shows a field for the code. The user types it, and the panel sends it again in the `x-devframes-onboard-code` header.
-3. After five wrong codes, both actions answer `429` with [DF9006](/errors/DF9006) until the dev server restarts.
+To ask in another way, pass `confirm`. It gets the `packages`, the exact `command`, and the panel's `request`, and returns `true` to allow the install. For example, a Nuxt module can ask through `consola`:
+
+```ts
+import { consola } from 'consola'
+
+const onboarding = createOnboarding({
+  packages: ['@nuxt/devtools'],
+  confirm: ({ command }) => consola.prompt(`Run \`${command.join(' ')}\` for the browser that asked?`, { type: 'confirm' }),
+})
+```
 
-The code stays the same for the life of the process, so Retry after a failed install does not ask again. A `POST` from another origin is also refused with `403`. The host has nothing to configure.
+Disable entirely does not ask. It changes only the state file in `node_modules/.devframe`.
 
 ## Hand the base to the hub
 
diff --git a/docs/content/6.errors/DF9005.md b/docs/content/6.errors/DF9005.md
index 15673fc5..985b8b7c 100644
--- a/docs/content/6.errors/DF9005.md
+++ b/docs/content/6.errors/DF9005.md
@@ -1,20 +1,22 @@
 ---
-title: 'DF9005: Onboarding Code Requested'
-description: 'A browser asked to {action}. To allow it, enter this code in the panel: {code}'
+title: 'DF9005: Confirm the Install'
+description: 'A browser asked to run `{command}`. Type y and press Enter to allow it.'
 ---
 
 ## Message
 
-> A browser asked to `{action}`. To allow it, enter this code in the panel: `{code}`
+> A browser asked to run `{command}`. Type y and press Enter to allow it.
 
 ## Cause
 
-Install and Disable change the project, and a dev server can listen on the network. So the onboarding panel must send a 6-digit code that only the terminal shows. A request to `POST <base>__onboard/install` or `POST <base>__onboard/disable` came without the `x-devframes-onboard-code` header, and `createOnboarding()` printed the code. The code stays the same until the process exits.
+Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. The panel's `POST <base>__onboard/install` waits until you answer. Without a `confirm` option, `createOnboarding()` asks in the terminal that runs the dev server.
 
 ## Fix
 
-If you clicked Install or Disable entirely, type the code into the panel. If you did not, another device or page can reach this dev server. Do not enter the code anywhere, and bind the dev server to `localhost`.
+If you clicked Install, type `y` and press Enter. Any other answer refuses the install, and the panel tells the user. If you did not click Install, press Enter. Another device or page can reach this dev server, so bind it to `localhost`.
+
+To ask in another way, for example with your own logger, pass a `confirm` function to `createOnboarding()`.
 
 ## Source
 
-- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` prints this and answers with status 401 when the request has no code.
+- [`packages/hub-ui-onboard/src/terminal-confirm.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/terminal-confirm.ts): `confirmInTerminal()` prints this, then reads one line from stdin.
diff --git a/docs/content/6.errors/DF9006.md b/docs/content/6.errors/DF9006.md
index bc42daac..7034c9df 100644
--- a/docs/content/6.errors/DF9006.md
+++ b/docs/content/6.errors/DF9006.md
@@ -1,20 +1,20 @@
 ---
-title: 'DF9006: Too Many Wrong Onboarding Codes'
-description: 'Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.'
+title: 'DF9006: No Terminal to Confirm the Install'
+description: 'A browser asked to run `{command}`, but no interactive terminal can confirm it. The install was refused.'
 ---
 
 ## Message
 
-> Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.
+> A browser asked to run `{command}`, but no interactive terminal can confirm it. The install was refused.
 
 ## Cause
 
-Install and Disable need the code that [DF9005](/errors/DF9005) prints. After five wrong codes, `createOnboarding()` refuses both actions for the rest of the process, so nobody can guess the code.
+Each install that the panel asks for needs the developer's permission ([DF9005](/errors/DF9005)). Without a `confirm` option, `createOnboarding()` asks in the terminal. Here stdin is not a TTY, so nobody can answer. This happens in CI, in a detached container, or when a task runner pipes stdin. The install is refused at once, and the panel tells the user.
 
 ## Fix
 
-Restart the dev server. It prints a new code the next time you click Install or Disable entirely. If you did not enter the wrong codes, another device or page can reach this dev server: bind it to `localhost`. You can also run the install command from the panel in a terminal.
+Run the command from the panel in a terminal yourself. Or pass a `confirm` function to `createOnboarding()` that asks in another way.
 
 ## Source
 
-- [`packages/hub-ui-onboard/src/index.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/index.ts): `authorize()` reports this on the fifth wrong code, then answers each later Install or Disable with status 429 and this code.
+- [`packages/hub-ui-onboard/src/terminal-confirm.ts`](https://github.com/devframes/devframe/blob/main/packages/hub-ui-onboard/src/terminal-confirm.ts): `confirmInTerminal()` reports this and returns `false` when stdin is not a TTY.
diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md
index bf4b0079..67df2c2b 100644
--- a/docs/content/8.references/6.hub-api.md
+++ b/docs/content/8.references/6.hub-api.md
@@ -96,17 +96,16 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
 | `stateDir` | `<cwd>/node_modules/.devframe` | Directory of the `hub-ui-onboard.json` state file |
 | `dev` | `true` | Install as a devDependency |
 | `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
-| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `code`, `wrongCode`, `hide`, `disable`, `installing`, `restart`, `retry` |
+| `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `confirming`, `refused`, `hide`, `disable`, `installing`, `restart`, `retry` |
 | `onInstalled` | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over `base` |
+| `confirm` | `y/N` in the terminal | Gets `{ packages, command, request }` before each install the panel asks for; return `true` to allow it. Refuses when stdin is not a TTY |
 
 | Route | Serves |
 | --- | --- |
 | `GET <base>embedded.js` | the floating button, a self-contained ES module |
 | `GET <base>__onboard/status` | `{ state, command, branding, messages, error? }` |
-| `POST <base>__onboard/install` | starts the install (`202`), with the terminal code only |
-| `POST <base>__onboard/disable` | writes the state file (`204`), with the terminal code only |
-
-Both `POST` routes answer `403` to another origin. Without the `x-devframes-onboard-code` header, they print the code ([DF9005](/errors/DF9005)) and answer `401`. A wrong code also gets `401`. After five wrong codes, they answer `429` with [DF9006](/errors/DF9006) until the process restarts.
+| `POST <base>__onboard/install` | waits for `confirm`, then starts the install (`202`) or refuses it (`403`); same-origin only |
+| `POST <base>__onboard/disable` | writes the state file (`204`), same-origin only |
 
 | `state` | Meaning |
 | --- | --- |
diff --git a/examples/hub-onboard-vite/README.md b/examples/hub-onboard-vite/README.md
index b8cea2cd..c979a812 100644
--- a/examples/hub-onboard-vite/README.md
+++ b/examples/hub-onboard-vite/README.md
@@ -6,14 +6,12 @@ A Vite host that ships only `@devframes/hub-ui-onboard` (about 20 kB in the brow
 pnpm --filter hub-onboard-vite dev
 ```
 
-Open the printed URL. The button at the bottom left opens a panel with three actions:
+Open the printed URL. The button at the bottom left opens a panel with two actions:
 
-- Install runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
+- Install asks you to type `y` in the terminal that runs Vite, then runs `pnpm add -D @devframes/hub @devframes/hub-ui @devframes/plugin-git` in this directory. When it finishes, the host starts the real hub on `/__devframes/` in the same process and the button swaps itself for the floating dock.
 - Hide for now hides the button for this browser tab.
 - Disable entirely writes `node_modules/.devframe/hub-ui-onboard.json`. The host reads `onboarding.disabled` on the next start and injects no script.
 
-Install and Disable entirely ask for the 6-digit code that the dev server prints in the terminal (`DF9005`).
-
 When the three packages are already installed, the button never shows: the host's `onInstalled` runs on the first request and the real dock appears directly.
 
 Install changes this example's `package.json` and the lockfile. Run `git checkout -- examples/hub-onboard-vite pnpm-lock.yaml` and delete the state file to reset the demo.
diff --git a/packages/hub-ui-onboard/playground/index.html b/packages/hub-ui-onboard/playground/index.html
index 425d62c4..996b5dc2 100644
--- a/packages/hub-ui-onboard/playground/index.html
+++ b/packages/hub-ui-onboard/playground/index.html
@@ -14,7 +14,7 @@
   </head>
   <body>
     <h1>hub-ui-onboard</h1>
-    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API. When Install or Disable asks for the terminal code, enter <code>123456</code>.</p>
+    <p>The floating button loads from <code>src/client</code> and talks to a mock <code>__onboard</code> API.</p>
     <fieldset>
       <legend>State</legend>
       <button data-state="idle">idle</button>
@@ -22,6 +22,7 @@ <h1>hub-ui-onboard</h1>
       <button data-state="installed">installed</button>
       <button data-state="error">error</button>
       <button data-state="idle" data-outcome="error">idle (install fails)</button>
+      <button data-state="idle" data-outcome="refused">idle (install refused)</button>
     </fieldset>
     <fieldset>
       <legend>Theme</legend>
diff --git a/packages/hub-ui-onboard/playground/vite.config.ts b/packages/hub-ui-onboard/playground/vite.config.ts
index d6a2c727..17e66d83 100644
--- a/packages/hub-ui-onboard/playground/vite.config.ts
+++ b/packages/hub-ui-onboard/playground/vite.config.ts
@@ -4,22 +4,20 @@ import { spawn } from 'node:child_process'
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vite'
 import { defaultMessages } from '../src/index'
-import { CODE_HEADER } from '../src/protocol'
 
 const root = fileURLToPath(new URL('..', import.meta.url))
 const productName = 'Devframes'
-const MOCK_CODE = '123456'
 
 /**
  * A fake of the `__onboard/*` routes `createOnboarding` serves. The client
  * resolves them next to its own module (`/src/client/`). The playground page
- * picks the state through `/__mock/state`; Install runs a timer instead of a
- * package manager and ends in `installed` or `error`. Install and Disable
- * accept only the code `123456`.
+ * picks the state through `/__mock/state`; Install waits as if the developer
+ * answered in the terminal, then is refused, or runs a timer instead of a
+ * package manager and ends in `installed` or `error`.
  */
 function mockOnboarding(): Plugin {
   let state: OnboardingState = 'idle'
-  let outcome: 'installed' | 'error' = 'installed'
+  let outcome: 'installed' | 'error' | 'refused' = 'installed'
   let timer: ReturnType<typeof setTimeout> | undefined
 
   const status = (): OnboardingStatus => ({
@@ -43,23 +41,28 @@ function mockOnboarding(): Plugin {
         if (url.pathname === '/__mock/state') {
           clearTimeout(timer)
           state = (url.searchParams.get('state') ?? 'idle') as OnboardingState
-          outcome = url.searchParams.get('outcome') === 'error' ? 'error' : 'installed'
+          const requested = url.searchParams.get('outcome')
+          outcome = requested === 'error' || requested === 'refused' ? requested : 'installed'
           return send({ state, outcome })
         }
         if (!url.pathname.startsWith('/src/client/__onboard/'))
           return next()
         const route = url.pathname.split('/').pop()
-        if (route !== 'status' && req.headers[CODE_HEADER] !== MOCK_CODE) {
-          res.statusCode = 401
-          return res.end()
-        }
         if (route === 'install') {
-          state = 'installing'
-          timer = setTimeout(() => (state = outcome), 2500)
+          setTimeout(() => {
+            if (outcome === 'refused') {
+              res.statusCode = 403
+              return res.end()
+            }
+            const end = outcome
+            state = 'installing'
+            timer = setTimeout(() => (state = end), 2500)
+            send({ ok: true })
+          }, 1500)
+          return
         }
-        else if (route === 'disable') {
+        if (route === 'disable')
           state = 'disabled'
-        }
         send(route === 'status' ? status() : { ok: true })
       })
     },
diff --git a/packages/hub-ui-onboard/src/client/index.ts b/packages/hub-ui-onboard/src/client/index.ts
index 8c286554..c01523c8 100644
--- a/packages/hub-ui-onboard/src/client/index.ts
+++ b/packages/hub-ui-onboard/src/client/index.ts
@@ -1,5 +1,4 @@
 import type { OnboardingBranding, OnboardingStatus } from '../types'
-import { CODE_HEADER } from '../protocol'
 import css from './.generated/css'
 import { DEVFRAME_LOGO } from './logo'
 
@@ -190,32 +189,9 @@ function mount(initial: OnboardingStatus): void {
   commandRow.className = 'devframes-onboard-command-row'
   commandRow.append(command, copy)
 
-  // Shown when the server asks for the code it printed in the terminal.
-  // A form, so Enter repeats the action that asked for it.
-  let pending: 'install' | 'disable' = 'install'
-  const codeForm = document.createElement('form')
-  codeForm.hidden = true
-  const codeField = document.createElement('label')
-  codeField.className = 'flex flex-col gap-1 text-xs color-muted'
-  const codeInput = document.createElement('input')
-  codeInput.className = 'devframes-onboard-code'
-  codeInput.inputMode = 'numeric'
-  codeInput.autocomplete = 'one-time-code'
-  codeInput.maxLength = 6
-  codeField.append(messages.code, codeInput)
-  codeForm.append(codeField)
-  codeForm.addEventListener('submit', (event) => {
-    event.preventDefault()
-    void (pending === 'install' ? startInstall() : disableDevtools())
-  })
-
   const note = document.createElement('p')
-  note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
+  note.className = 'm-0 text-xs'
   note.hidden = true
-  const showNote = (text: string) => {
-    note.hidden = !text
-    note.textContent = text
-  }
 
   const install = button('btn-primary text-sm justify-center gap-1', messages.install, () => void startInstall())
   // The spinner takes its space from the line height, so the button keeps its size.
@@ -237,7 +213,7 @@ function mount(initial: OnboardingStatus): void {
   actions.className = 'flex flex-col gap-2'
   actions.append(secondary, install)
 
-  panel.append(heading, description, commandRow, codeForm, note, actions)
+  panel.append(heading, description, commandRow, note, actions)
   scheme.append(glow, pill, panel)
 
   let open = false
@@ -270,7 +246,11 @@ function mount(initial: OnboardingStatus): void {
       : state === 'installed'
         ? messages.restart
         : state === 'error' ? messages.retry : messages.install
-    showNote(state === 'error' ? `${status.error?.code}: ${status.error?.message}` : '')
+    note.hidden = state !== 'error'
+    note.className = 'm-0 text-xs text-red-600 dark:text-red-400'
+    note.textContent = state === 'error'
+      ? `${status.error?.code}: ${status.error?.message}`
+      : ''
   }
 
   async function poll(): Promise<void> {
@@ -285,38 +265,24 @@ function mount(initial: OnboardingStatus): void {
       setTimeout(() => void poll(), POLL_MS)
   }
 
-  /** POST `action` with the entered code; `true` when the server accepted it. */
-  async function send(action: typeof pending): Promise<boolean> {
-    pending = action
-    // Kept after success, so Retry does not ask again.
-    const code = codeInput.value.trim()
-    const response = await api(action, { method: 'POST', headers: code ? { [CODE_HEADER]: code } : {} })
-    if (response.status === 401) {
-      showNote(code ? messages.wrongCode : '')
-      codeInput.value = ''
-      codeForm.hidden = false
-      codeInput.focus()
-      return false
-    }
-    if (!response.ok) {
-      // A `DF90xx` body: too many wrong codes, or the state file failed.
-      const error: OnboardingStatus['error'] = await response.json().catch(() => undefined)
-      showNote(error ? `${error.code}: ${error.message}` : '')
-      return false
-    }
-    codeForm.hidden = true
-    return true
-  }
-
   async function startInstall(): Promise<void> {
-    if (!await send('install'))
+    // The request stays open until the developer answers in the terminal.
+    install.disabled = true
+    installLabel.textContent = messages.confirming
+    const response = await api('install', { method: 'POST' })
+    if (!response.ok) {
+      await poll()
+      note.hidden = false
+      note.textContent = messages.refused
       return
+    }
     render({ ...initial, state: 'installing' })
     await poll()
   }
 
   async function disableDevtools(): Promise<void> {
-    if (await send('disable'))
+    const response = await api('disable', { method: 'POST' })
+    if (response.ok)
       host.remove()
   }
 
diff --git a/packages/hub-ui-onboard/src/client/style.css b/packages/hub-ui-onboard/src/client/style.css
index 5cf9427b..675c6a08 100644
--- a/packages/hub-ui-onboard/src/client/style.css
+++ b/packages/hub-ui-onboard/src/client/style.css
@@ -57,11 +57,6 @@
   --uno: transition-opacity duration-200;
 }
 
-.devframes-onboard-code {
-  --uno: w-full min-w-0 rounded border border-base bg-base color-base px-2.5 py-1 font-mono text-sm tabular-nums tracking-widest;
-  --uno: outline-none transition focus-visible:border-active focus-visible:ring-2 ring-primary-400;
-}
-
 .devframes-onboard-spinner[hidden] {
   --uno: hidden;
 }
diff --git a/packages/hub-ui-onboard/src/diagnostics.ts b/packages/hub-ui-onboard/src/diagnostics.ts
index ed8caf00..99999256 100644
--- a/packages/hub-ui-onboard/src/diagnostics.ts
+++ b/packages/hub-ui-onboard/src/diagnostics.ts
@@ -30,12 +30,12 @@ export const diagnostics = defineDiagnostics({
       fix: 'Make sure that `stateDir` is writable, or point it at another directory.',
     },
     DF9005: {
-      why: (p: { action: string, code: string }) => `A browser asked to ${p.action}. To allow it, enter this code in the panel: ${p.code}`,
-      fix: 'If you did not click the button, another device can reach this dev server. Do not enter the code, and bind the dev server to localhost.',
+      why: (p: { command: string }) => `A browser asked to run \`${p.command}\`. Type y and press Enter to allow it.`,
+      fix: 'If you did not click Install, press Enter to refuse. Another device can reach this dev server, so bind it to localhost.',
     },
     DF9006: {
-      why: 'Five wrong onboarding codes were entered. Install and Disable are blocked until the dev server restarts.',
-      fix: 'Restart the dev server to get a new code. If you did not enter these codes, another device can reach this dev server: bind it to localhost.',
+      why: (p: { command: string }) => `A browser asked to run \`${p.command}\`, but no interactive terminal can confirm it. The install was refused.`,
+      fix: 'Run the command yourself, or pass a `confirm` function to `createOnboarding()`.',
     },
   },
 })
diff --git a/packages/hub-ui-onboard/src/index.ts b/packages/hub-ui-onboard/src/index.ts
index 231bead4..aa8e213c 100644
--- a/packages/hub-ui-onboard/src/index.ts
+++ b/packages/hub-ui-onboard/src/index.ts
@@ -2,7 +2,6 @@ import type { IncomingMessage, ServerResponse } from 'node:http'
 import type { ResolvedCommand } from 'package-manager-detector'
 import type { CreateOnboardingOptions, Onboarding, OnboardingHandler, OnboardingMessages, OnboardingState, OnboardingStatus } from './types'
 import { Buffer } from 'node:buffer'
-import { randomInt, timingSafeEqual } from 'node:crypto'
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import { join } from 'node:path'
@@ -13,12 +12,11 @@ import { fileURLToPath } from 'node:url'
 import { Diagnostic } from 'nostics'
 import { diagnostics } from './diagnostics'
 import { packagesInstalled, resolveInstallCommand, runInstall } from './install'
-import { CODE_HEADER } from './protocol'
+import { confirmInTerminal } from './terminal-confirm'
 
 export type * from './types'
 
 const STATE_FILE = 'hub-ui-onboard.json'
-const MAX_WRONG_CODES = 5
 
 /** `devframes` → `/devframes/`, same rule as `normalizeHubBase` in `@devframes/hub`. */
 function normalizeBase(base: string): string {
@@ -41,8 +39,8 @@ export function defaultMessages(productName: string): OnboardingMessages {
     title: productName,
     description: `${productName} enables development features in your project. Install it with:`,
     install: `Install ${productName}`,
-    code: 'Enter the code that the dev server printed in your terminal.',
-    wrongCode: 'Wrong code. Try again.',
+    confirming: 'Confirm in your terminal...',
+    refused: 'The dev server did not allow the install. Check its terminal, or run the command above yourself.',
     hide: 'Hide in this session',
     disable: 'Disable entirely',
     installing: 'Installing...',
@@ -190,41 +188,34 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
     return new Response(null, { status: 204 })
   }
 
-  function startInstall(): Response {
-    if (state === 'idle' || state === 'error')
-      void install()
-    return new Response(null, { status: 202 })
+  const commandLine = async () => {
+    const resolved = await getCommand()
+    return [resolved.command, ...resolved.args]
   }
 
-  // The dev server can listen on the network, and a non-browser request can
-  // send any `Origin`. So Install and Disable also need a code that only the terminal shows.
-  const code = Buffer.from(String(randomInt(1_000_000)).padStart(6, '0'))
-  let wrongCodes = 0
-  let locked: Diagnostic | undefined
+  // The dev server can be reachable from other devices, and a non-browser
+  // request can send any `Origin`. So the developer allows each install.
+  const confirm = options.confirm ?? (({ command }) => confirmInTerminal(command))
+  let asking: Promise<boolean> | undefined
 
-  /** The refusal to send, or `undefined` when the request may run `action`. */
-  function authorize(request: Request, action: string): Response | undefined {
-    if (!isSameOrigin(request))
+  async function startInstall(request: Request): Promise<Response> {
+    if (state !== 'idle' && state !== 'error')
+      return new Response(null, { status: 202 })
+    asking ??= commandLine()
+      .then(command => confirm({ packages: plan.packages, command, request }))
+      .finally(() => {
+        asking = undefined
+      })
+    if (!await asking)
       return new Response(null, { status: 403 })
-    if (!locked) {
-      const given = request.headers.get(CODE_HEADER)
-      if (given === null) {
-        diagnostics.DF9005({ action, code: code.toString() })
-        return new Response(null, { status: 401 })
-      }
-      const candidate = Buffer.from(given)
-      if (candidate.length === code.length && timingSafeEqual(candidate, code))
-        return undefined
-      if (++wrongCodes < MAX_WRONG_CODES)
-        return new Response(null, { status: 401 })
-      locked = diagnostics.DF9006()
-    }
-    return json({ code: locked.code, message: locked.message }, 429)
+    // Clicks that shared the answer start one install.
+    if (state === 'idle' || state === 'error')
+      void install()
+    return new Response(null, { status: 202 })
   }
 
   async function status(): Promise<OnboardingStatus> {
-    const command = await getCommand()
-    return { state, command: [command.command, ...command.args], branding, messages, error }
+    return { state, command: await commandLine(), branding, messages, error }
   }
 
   const handler: OnboardingHandler = async (request) => {
@@ -244,10 +235,11 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
     }
     if (route === 'GET __onboard/status')
       return json(await status())
-    if (route === 'POST __onboard/install')
-      return authorize(request, `install ${plan.packages.join(' ')}`) ?? startInstall()
-    if (route === 'POST __onboard/disable')
-      return authorize(request, 'disable the onboarding button') ?? disable()
+    if (route === 'POST __onboard/install' || route === 'POST __onboard/disable') {
+      if (!isSameOrigin(request))
+        return new Response(null, { status: 403 })
+      return route.endsWith('disable') ? disable() : startInstall(request)
+    }
     return new Response(null, { status: 404 })
   }
 
diff --git a/packages/hub-ui-onboard/src/protocol.ts b/packages/hub-ui-onboard/src/protocol.ts
deleted file mode 100644
index a2fe41db..00000000
--- a/packages/hub-ui-onboard/src/protocol.ts
+++ /dev/null
@@ -1,2 +0,0 @@
-/** The request header that carries the code the terminal printed (`DF9005`). */
-export const CODE_HEADER = 'x-devframes-onboard-code'
diff --git a/packages/hub-ui-onboard/src/terminal-confirm.ts b/packages/hub-ui-onboard/src/terminal-confirm.ts
new file mode 100644
index 00000000..16c1a798
--- /dev/null
+++ b/packages/hub-ui-onboard/src/terminal-confirm.ts
@@ -0,0 +1,26 @@
+import type { Buffer } from 'node:buffer'
+import type { Readable } from 'node:stream'
+import process from 'node:process'
+import { diagnostics } from './diagnostics'
+
+/**
+ * The default `confirm`: a `y/N` question in the terminal that runs the dev
+ * server. Without an interactive terminal nobody can answer, so it refuses.
+ */
+export function confirmInTerminal(command: string[], input: Readable & { isTTY?: boolean } = process.stdin): Promise<boolean> {
+  if (!input.isTTY) {
+    diagnostics.DF9006({ command: command.join(' ') })
+    return Promise.resolve(false)
+  }
+  diagnostics.DF9005({ command: command.join(' ') })
+  // Vite reads the same stream for its shortcuts. Listen next to it, and
+  // pause again only when nothing read the stream before.
+  const flowing = input.readableFlowing
+  return new Promise((resolve) => {
+    input.once('data', (chunk: Buffer | string) => {
+      if (!flowing)
+        input.pause()
+      resolve(/^y(?:es)?$/i.test(String(chunk).trim()))
+    })
+  })
+}
diff --git a/packages/hub-ui-onboard/src/types.ts b/packages/hub-ui-onboard/src/types.ts
index 36956dd6..79050b65 100644
--- a/packages/hub-ui-onboard/src/types.ts
+++ b/packages/hub-ui-onboard/src/types.ts
@@ -17,10 +17,10 @@ export interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string
   install: string
-  /** Label of the field for the code that Install and Disable need. */
-  code: string
-  /** Shown when the server refused the code. */
-  wrongCode: string
+  /** Install button label while `confirm` waits for the developer. */
+  confirming: string
+  /** Shown when `confirm` refused the install. */
+  refused: string
   /** Hides the button for this browser tab (`sessionStorage`). */
   hide: string
   /** Writes the state file; the host stops injecting the button. */
@@ -34,6 +34,16 @@ export interface OnboardingMessages {
 /** A web-standard request handler the hub exposes once installed. */
 export type OnboardingHandler = (request: Request) => Response | Promise<Response>
 
+/** What `confirm` receives when the panel asks to install. */
+export interface OnboardingConfirmation {
+  /** The packages Install adds, as given in `packages`. */
+  packages: string[]
+  /** The exact command Install runs. */
+  command: string[]
+  /** The panel's request, for example to read its `Origin` or `User-Agent`. */
+  request: Request
+}
+
 export interface CreateOnboardingOptions {
   /** Packages to install when the user clicks Install. Package specs as the package manager accepts them. */
   packages: string[]
@@ -54,6 +64,14 @@ export interface CreateOnboardingOptions {
    * user to restart the dev server.
    */
   onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>
+  /**
+   * Ask the developer to allow an install that the panel requested; the
+   * dev server can be reachable from other devices. Return `true` to run
+   * it. Only one call is open at a time: clicks meanwhile share its answer.
+   * Default: a `y/N` question in the terminal, or a refusal when stdin is
+   * not a TTY.
+   */
+  confirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>
 }
 
 export type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled'
diff --git a/packages/hub-ui-onboard/test/onboarding.test.ts b/packages/hub-ui-onboard/test/onboarding.test.ts
index c6b301e0..2db34922 100644
--- a/packages/hub-ui-onboard/test/onboarding.test.ts
+++ b/packages/hub-ui-onboard/test/onboarding.test.ts
@@ -1,5 +1,5 @@
 import type { AddressInfo } from 'node:net'
-import type { Onboarding, OnboardingStatus } from '../src/types'
+import type { Onboarding, OnboardingConfirmation, OnboardingStatus } from '../src/types'
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { createServer } from 'node:http'
 import { tmpdir } from 'node:os'
@@ -8,7 +8,6 @@ import process from 'node:process'
 import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createOnboarding } from '../src'
-import { CODE_HEADER } from '../src/protocol'
 
 const FIXTURE = fileURLToPath(new URL('./fixtures/pkg', import.meta.url))
 
@@ -57,31 +56,9 @@ async function waitFor<T>(read: () => Promise<T>, done: (value: T) => boolean):
 }
 
 const settled = (s: OnboardingStatus) => s.state !== 'installing' && s.state !== 'idle'
+const allow = () => true
 
-function post(origin: string, action: 'install' | 'disable', code?: string): Promise<Response> {
-  return fetch(`${origin}/__devframes/__onboard/${action}`, {
-    method: 'POST',
-    headers: { origin, ...(code ? { [CODE_HEADER]: code } : {}) },
-  })
-}
-
-/** Ask without a code, as the panel does first, and read the code the terminal shows. */
-async function codeFromTerminal(origin: string, action: 'install' | 'disable'): Promise<string> {
-  const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-  try {
-    expect((await post(origin, action)).status).toBe(401)
-    const printed = String(warn.mock.lastCall?.[0])
-    expect(printed).toContain('DF9005')
-    return printed.match(/panel: (\d{6})/)![1]!
-  }
-  finally {
-    warn.mockRestore()
-  }
-}
-
-async function confirm(origin: string, action: 'install' | 'disable'): Promise<Response> {
-  return post(origin, action, await codeFromTerminal(origin, action))
-}
+const install = (origin: string) => fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
 
 describe('createOnboarding', () => {
   it('refuses an empty package list', () => {
@@ -131,40 +108,67 @@ describe('createOnboarding', () => {
     expect((await status(origin)).state).toBe('idle')
   })
 
-  it('refuses an install or disable without the code from the terminal', async () => {
-    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
-    for (const action of ['install', 'disable'] as const) {
-      // A non-browser client sends neither `Origin` nor `Sec-Fetch-Site`.
-      expect((await fetch(`${origin}/__devframes/__onboard/${action}`, { method: 'POST' })).status).toBe(401)
-      const code = await codeFromTerminal(origin, action)
-      const wrong = code === '000000' ? '000001' : '000000'
-      expect((await post(origin, action, wrong)).status).toBe(401)
-    }
+  it('installs only after `confirm` allows it', async () => {
+    const asked: OnboardingConfirmation[] = []
+    let allowed = false
+    const origin = await serve(createOnboarding({
+      cwd: tempProject(),
+      packages: ['file:/nonexistent/onboard-missing'],
+      confirm: (confirmation) => {
+        asked.push(confirmation)
+        return allowed
+      },
+    }))
+
+    expect((await install(origin)).status).toBe(403)
     expect((await status(origin)).state).toBe('idle')
+    expect(asked[0]).toMatchObject({
+      packages: ['file:/nonexistent/onboard-missing'],
+      command: ['npm', 'i', '-D', 'file:/nonexistent/onboard-missing'],
+    })
+    expect(asked[0]!.request.headers.get('origin')).toBe(origin)
+
+    allowed = true
+    expect((await install(origin)).status).toBe(202)
+    // The package does not exist, so the install that ran ends in an error.
+    expect((await waitFor(() => status(origin), settled)).state).toBe('error')
   })
 
-  it('blocks install and disable after five wrong codes', async () => {
-    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
-    const code = await codeFromTerminal(origin, 'disable')
-    const wrong = code === '000000' ? '000001' : '000000'
-    for (let i = 0; i < 4; i++)
-      expect((await post(origin, 'disable', wrong)).status).toBe(401)
+  it('shares one open question between clicks', async () => {
+    let calls = 0
+    let answer: (allowed: boolean) => void = () => {}
+    const onboarding = createOnboarding({
+      cwd: tempProject(),
+      packages: ['x'],
+      confirm: () => {
+        calls++
+        return new Promise(resolve => answer = resolve)
+      },
+    })
+    const click = () => onboarding.handler(new Request('http://localhost/__devframes/__onboard/install', { method: 'POST' }))
+
+    const clicks = [click(), click()]
+    await waitFor(async () => calls, n => n > 0)
+    answer(false)
+    expect((await Promise.all(clicks)).map(r => r.status)).toEqual([403, 403])
+    expect(calls).toBe(1)
+  })
 
+  it('refuses an install when no terminal can confirm it', async () => {
+    // Vitest gives its workers a piped stdin, so the default `confirm` sees no TTY.
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    const blocked = await post(origin, 'disable', wrong)
-    warn.mockRestore()
-    expect(blocked.status).toBe(429)
-    expect(await blocked.json()).toMatchObject({ code: 'DF9006' })
+    cleanups.push(() => warn.mockRestore())
+    const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
 
-    expect((await post(origin, 'disable', code)).status).toBe(429)
-    expect((await post(origin, 'install', code)).status).toBe(429)
+    expect((await install(origin)).status).toBe(403)
+    expect(String(warn.mock.lastCall?.[0])).toContain('DF9006')
     expect((await status(origin)).state).toBe('idle')
   })
 
   it('persists disable on disk for the next process', async () => {
     const cwd = tempProject()
     const origin = await serve(createOnboarding({ cwd, packages: ['x'] }))
-    const response = await confirm(origin, 'disable')
+    const response = await fetch(`${origin}/__devframes/__onboard/disable`, { method: 'POST', headers: { origin } })
     expect(response.status).toBe(204)
     expect((await status(origin)).state).toBe('disabled')
 
@@ -179,10 +183,11 @@ describe('createOnboarding', () => {
       cwd,
       packages: [`file:${FIXTURE}`],
       onInstalled: () => () => new Response('hub here'),
+      confirm: allow,
     })
     const origin = await serve(onboarding)
 
-    const accepted = await confirm(origin, 'install')
+    const accepted = await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     expect(accepted.status).toBe(202)
 
     const script = () => fetch(`${origin}/__devframes/embedded.js`).then(r => r.text())
@@ -215,8 +220,8 @@ describe('createOnboarding', () => {
 
   it('reports a failed install as an error the client can retry', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'] }))
-    await confirm(origin, 'install')
+    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'], confirm: allow }))
+    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), s => s.state === 'error')
     expect(final.error?.code).toBe('DF9001')
     expect(final.error?.message).toContain('npm i -D file:/nonexistent/onboard-missing')
@@ -224,8 +229,8 @@ describe('createOnboarding', () => {
 
   it('asks for a restart when onInstalled returns nothing', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false }))
-    await confirm(origin, 'install')
+    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false, confirm: allow }))
+    await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), settled)
     expect(final.state).toBe('installed')
     expect(JSON.parse(readFileSync(join(cwd, 'package.json'), 'utf8')).dependencies).toHaveProperty('onboard-fixture')
diff --git a/packages/hub-ui-onboard/test/terminal-confirm.test.ts b/packages/hub-ui-onboard/test/terminal-confirm.test.ts
new file mode 100644
index 00000000..d6d0645c
--- /dev/null
+++ b/packages/hub-ui-onboard/test/terminal-confirm.test.ts
@@ -0,0 +1,44 @@
+import { PassThrough } from 'node:stream'
+import { afterEach, expect, it, vi } from 'vitest'
+import { confirmInTerminal } from '../src/terminal-confirm'
+
+const COMMAND = ['pnpm', 'add', '-D', '@nuxt/devtools']
+
+const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
+afterEach(() => warn.mockClear())
+
+const terminal = () => Object.assign(new PassThrough(), { isTTY: true })
+const printed = () => String(warn.mock.lastCall?.[0])
+
+it.each([
+  ['y\n', true],
+  ['Yes\n', true],
+  ['\n', false],
+  ['n\n', false],
+])('answers %j with %s and releases the terminal', async (line, allowed) => {
+  const input = terminal()
+  const answer = confirmInTerminal(COMMAND, input)
+  expect(printed()).toContain('DF9005')
+  expect(printed()).toContain('pnpm add -D @nuxt/devtools')
+
+  input.write(line)
+  expect(await answer).toBe(allowed)
+  expect(input.readableFlowing).toBe(false)
+})
+
+it('keeps the terminal flowing for a reader that was there first', async () => {
+  const input = terminal()
+  const shortcuts: string[] = []
+  input.on('data', chunk => shortcuts.push(String(chunk)))
+
+  const answer = confirmInTerminal(COMMAND, input)
+  input.write('y\n')
+  expect(await answer).toBe(true)
+  expect(input.readableFlowing).toBe(true)
+  expect(shortcuts).toEqual(['y\n'])
+})
+
+it('refuses at once without a TTY', async () => {
+  expect(await confirmInTerminal(COMMAND, new PassThrough())).toBe(false)
+  expect(printed()).toContain('DF9006')
+})
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
index 9cf71195..05152096 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
@@ -11,6 +11,7 @@ export interface CreateOnboardingOptions {
   branding?: OnboardingBranding;
   messages?: Partial<OnboardingMessages>;
   onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>;
+  confirm?: (_: OnboardingConfirmation) => boolean | Promise<boolean>;
 }
 export interface Onboarding {
   handler: OnboardingHandler;
@@ -24,12 +25,17 @@ export interface OnboardingBranding {
   logo?: OnboardingLogo;
   primaryColor?: string;
 }
+export interface OnboardingConfirmation {
+  packages: string[];
+  command: string[];
+  request: Request;
+}
 export interface OnboardingMessages {
   title: string;
   description: string;
   install: string;
-  code: string;
-  wrongCode: string;
+  confirming: string;
+  refused: string;
   hide: string;
   disable: string;
   installing: string;

From 401ebed4fd55fc503ebc6f93263478c59a135737 Mon Sep 17 00:00:00 2001
From: "Anthony Fu (via agent)" <reg-github-bot@antfu.me>
Date: Wed, 14 Oct 2026 05:15:45 +0000
Subject: [PATCH 3/3] refactor(hub-ui-onboard): rename confirm option to
 onConfirm

---
 docs/content/1.guide/23.hub-ui-onboard.md          |  4 ++--
 docs/content/6.errors/DF9005.md                    |  4 ++--
 docs/content/6.errors/DF9006.md                    |  4 ++--
 docs/content/8.references/6.hub-api.md             |  4 ++--
 packages/hub-ui-onboard/src/diagnostics.ts         |  2 +-
 packages/hub-ui-onboard/src/index.ts               |  4 ++--
 packages/hub-ui-onboard/src/terminal-confirm.ts    |  2 +-
 packages/hub-ui-onboard/src/types.ts               |  8 ++++----
 packages/hub-ui-onboard/test/onboarding.test.ts    | 14 +++++++-------
 .../@devframes/hub-ui-onboard/index.snapshot.d.ts  |  2 +-
 10 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/docs/content/1.guide/23.hub-ui-onboard.md b/docs/content/1.guide/23.hub-ui-onboard.md
index 93d8c8c7..c676a318 100644
--- a/docs/content/1.guide/23.hub-ui-onboard.md
+++ b/docs/content/1.guide/23.hub-ui-onboard.md
@@ -51,14 +51,14 @@ Install changes `package.json` and the lockfile, and a dev server can be reachab
 
 When stdin is not a TTY (CI, a detached container, a task runner that pipes stdin), nobody can answer. The onboarding then refuses at once with [DF9006](/errors/DF9006). Only one question is open at a time: more clicks while it is open share its answer. A `POST` from another origin is refused with `403` before any question.
 
-To ask in another way, pass `confirm`. It gets the `packages`, the exact `command`, and the panel's `request`, and returns `true` to allow the install. For example, a Nuxt module can ask through `consola`:
+To ask in another way, pass `onConfirm`. It gets the `packages`, the exact `command`, and the panel's `request`, and returns `true` to allow the install. For example, a Nuxt module can ask through `consola`:
 
 ```ts
 import { consola } from 'consola'
 
 const onboarding = createOnboarding({
   packages: ['@nuxt/devtools'],
-  confirm: ({ command }) => consola.prompt(`Run \`${command.join(' ')}\` for the browser that asked?`, { type: 'confirm' }),
+  onConfirm: ({ command }) => consola.prompt(`Run \`${command.join(' ')}\` for the browser that asked?`, { type: 'confirm' }),
 })
 ```
 
diff --git a/docs/content/6.errors/DF9005.md b/docs/content/6.errors/DF9005.md
index 985b8b7c..cdab38a8 100644
--- a/docs/content/6.errors/DF9005.md
+++ b/docs/content/6.errors/DF9005.md
@@ -9,13 +9,13 @@ description: 'A browser asked to run `{command}`. Type y and press Enter to allo
 
 ## Cause
 
-Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. The panel's `POST <base>__onboard/install` waits until you answer. Without a `confirm` option, `createOnboarding()` asks in the terminal that runs the dev server.
+Install changes `package.json` and the lockfile, and a dev server can be reachable from other devices. So each install that the panel asks for needs the developer's permission. The panel's `POST <base>__onboard/install` waits until you answer. Without an `onConfirm` option, `createOnboarding()` asks in the terminal that runs the dev server.
 
 ## Fix
 
 If you clicked Install, type `y` and press Enter. Any other answer refuses the install, and the panel tells the user. If you did not click Install, press Enter. Another device or page can reach this dev server, so bind it to `localhost`.
 
-To ask in another way, for example with your own logger, pass a `confirm` function to `createOnboarding()`.
+To ask in another way, for example with your own logger, pass an `onConfirm` function to `createOnboarding()`.
 
 ## Source
 
diff --git a/docs/content/6.errors/DF9006.md b/docs/content/6.errors/DF9006.md
index 7034c9df..49b17f93 100644
--- a/docs/content/6.errors/DF9006.md
+++ b/docs/content/6.errors/DF9006.md
@@ -9,11 +9,11 @@ description: 'A browser asked to run `{command}`, but no interactive terminal ca
 
 ## Cause
 
-Each install that the panel asks for needs the developer's permission ([DF9005](/errors/DF9005)). Without a `confirm` option, `createOnboarding()` asks in the terminal. Here stdin is not a TTY, so nobody can answer. This happens in CI, in a detached container, or when a task runner pipes stdin. The install is refused at once, and the panel tells the user.
+Each install that the panel asks for needs the developer's permission ([DF9005](/errors/DF9005)). Without an `onConfirm` option, `createOnboarding()` asks in the terminal. Here stdin is not a TTY, so nobody can answer. This happens in CI, in a detached container, or when a task runner pipes stdin. The install is refused at once, and the panel tells the user.
 
 ## Fix
 
-Run the command from the panel in a terminal yourself. Or pass a `confirm` function to `createOnboarding()` that asks in another way.
+Run the command from the panel in a terminal yourself. Or pass an `onConfirm` function to `createOnboarding()` that asks in another way.
 
 ## Source
 
diff --git a/docs/content/8.references/6.hub-api.md b/docs/content/8.references/6.hub-api.md
index 67df2c2b..06bfa890 100644
--- a/docs/content/8.references/6.hub-api.md
+++ b/docs/content/8.references/6.hub-api.md
@@ -98,13 +98,13 @@ What `createOnboarding()` from `@devframes/hub-ui-onboard` accepts and serves: [
 | `branding` | `{}` | `productName` (default `Devframes`), `logo` (URL or `{ light, dark }`), `primaryColor` |
 | `messages` | derived from `productName` | Overrides for `title`, `description`, `install`, `confirming`, `refused`, `hide`, `disable`, `installing`, `restart`, `retry` |
 | `onInstalled` | none | Runs after a verified install, or on the first request when the packages already exist; a returned handler takes over `base` |
-| `confirm` | `y/N` in the terminal | Gets `{ packages, command, request }` before each install the panel asks for; return `true` to allow it. Refuses when stdin is not a TTY |
+| `onConfirm` | `y/N` in the terminal | Gets `{ packages, command, request }` before each install the panel asks for; return `true` to allow it. Refuses when stdin is not a TTY |
 
 | Route | Serves |
 | --- | --- |
 | `GET <base>embedded.js` | the floating button, a self-contained ES module |
 | `GET <base>__onboard/status` | `{ state, command, branding, messages, error? }` |
-| `POST <base>__onboard/install` | waits for `confirm`, then starts the install (`202`) or refuses it (`403`); same-origin only |
+| `POST <base>__onboard/install` | waits for `onConfirm`, then starts the install (`202`) or refuses it (`403`); same-origin only |
 | `POST <base>__onboard/disable` | writes the state file (`204`), same-origin only |
 
 | `state` | Meaning |
diff --git a/packages/hub-ui-onboard/src/diagnostics.ts b/packages/hub-ui-onboard/src/diagnostics.ts
index 99999256..158f395c 100644
--- a/packages/hub-ui-onboard/src/diagnostics.ts
+++ b/packages/hub-ui-onboard/src/diagnostics.ts
@@ -35,7 +35,7 @@ export const diagnostics = defineDiagnostics({
     },
     DF9006: {
       why: (p: { command: string }) => `A browser asked to run \`${p.command}\`, but no interactive terminal can confirm it. The install was refused.`,
-      fix: 'Run the command yourself, or pass a `confirm` function to `createOnboarding()`.',
+      fix: 'Run the command yourself, or pass an `onConfirm` function to `createOnboarding()`.',
     },
   },
 })
diff --git a/packages/hub-ui-onboard/src/index.ts b/packages/hub-ui-onboard/src/index.ts
index aa8e213c..ee3da148 100644
--- a/packages/hub-ui-onboard/src/index.ts
+++ b/packages/hub-ui-onboard/src/index.ts
@@ -195,14 +195,14 @@ export function createOnboarding(options: CreateOnboardingOptions): Onboarding {
 
   // The dev server can be reachable from other devices, and a non-browser
   // request can send any `Origin`. So the developer allows each install.
-  const confirm = options.confirm ?? (({ command }) => confirmInTerminal(command))
+  const onConfirm = options.onConfirm ?? (({ command }) => confirmInTerminal(command))
   let asking: Promise<boolean> | undefined
 
   async function startInstall(request: Request): Promise<Response> {
     if (state !== 'idle' && state !== 'error')
       return new Response(null, { status: 202 })
     asking ??= commandLine()
-      .then(command => confirm({ packages: plan.packages, command, request }))
+      .then(command => onConfirm({ packages: plan.packages, command, request }))
       .finally(() => {
         asking = undefined
       })
diff --git a/packages/hub-ui-onboard/src/terminal-confirm.ts b/packages/hub-ui-onboard/src/terminal-confirm.ts
index 16c1a798..1d54a8e5 100644
--- a/packages/hub-ui-onboard/src/terminal-confirm.ts
+++ b/packages/hub-ui-onboard/src/terminal-confirm.ts
@@ -4,7 +4,7 @@ import process from 'node:process'
 import { diagnostics } from './diagnostics'
 
 /**
- * The default `confirm`: a `y/N` question in the terminal that runs the dev
+ * The default `onConfirm`: a `y/N` question in the terminal that runs the dev
  * server. Without an interactive terminal nobody can answer, so it refuses.
  */
 export function confirmInTerminal(command: string[], input: Readable & { isTTY?: boolean } = process.stdin): Promise<boolean> {
diff --git a/packages/hub-ui-onboard/src/types.ts b/packages/hub-ui-onboard/src/types.ts
index 79050b65..d72865dd 100644
--- a/packages/hub-ui-onboard/src/types.ts
+++ b/packages/hub-ui-onboard/src/types.ts
@@ -17,9 +17,9 @@ export interface OnboardingMessages {
   /** Short sentence under the heading. */
   description: string
   install: string
-  /** Install button label while `confirm` waits for the developer. */
+  /** Install button label while `onConfirm` waits for the developer. */
   confirming: string
-  /** Shown when `confirm` refused the install. */
+  /** Shown when `onConfirm` refused the install. */
   refused: string
   /** Hides the button for this browser tab (`sessionStorage`). */
   hide: string
@@ -34,7 +34,7 @@ export interface OnboardingMessages {
 /** A web-standard request handler the hub exposes once installed. */
 export type OnboardingHandler = (request: Request) => Response | Promise<Response>
 
-/** What `confirm` receives when the panel asks to install. */
+/** What `onConfirm` receives when the panel asks to install. */
 export interface OnboardingConfirmation {
   /** The packages Install adds, as given in `packages`. */
   packages: string[]
@@ -71,7 +71,7 @@ export interface CreateOnboardingOptions {
    * Default: a `y/N` question in the terminal, or a refusal when stdin is
    * not a TTY.
    */
-  confirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>
+  onConfirm?: (confirmation: OnboardingConfirmation) => boolean | Promise<boolean>
 }
 
 export type OnboardingState = 'idle' | 'installing' | 'installed' | 'ready' | 'error' | 'disabled'
diff --git a/packages/hub-ui-onboard/test/onboarding.test.ts b/packages/hub-ui-onboard/test/onboarding.test.ts
index 2db34922..1d2f940c 100644
--- a/packages/hub-ui-onboard/test/onboarding.test.ts
+++ b/packages/hub-ui-onboard/test/onboarding.test.ts
@@ -108,13 +108,13 @@ describe('createOnboarding', () => {
     expect((await status(origin)).state).toBe('idle')
   })
 
-  it('installs only after `confirm` allows it', async () => {
+  it('installs only after `onConfirm` allows it', async () => {
     const asked: OnboardingConfirmation[] = []
     let allowed = false
     const origin = await serve(createOnboarding({
       cwd: tempProject(),
       packages: ['file:/nonexistent/onboard-missing'],
-      confirm: (confirmation) => {
+      onConfirm: (confirmation) => {
         asked.push(confirmation)
         return allowed
       },
@@ -140,7 +140,7 @@ describe('createOnboarding', () => {
     const onboarding = createOnboarding({
       cwd: tempProject(),
       packages: ['x'],
-      confirm: () => {
+      onConfirm: () => {
         calls++
         return new Promise(resolve => answer = resolve)
       },
@@ -155,7 +155,7 @@ describe('createOnboarding', () => {
   })
 
   it('refuses an install when no terminal can confirm it', async () => {
-    // Vitest gives its workers a piped stdin, so the default `confirm` sees no TTY.
+    // Vitest gives its workers a piped stdin, so the default `onConfirm` sees no TTY.
     const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
     cleanups.push(() => warn.mockRestore())
     const origin = await serve(createOnboarding({ cwd: tempProject(), packages: ['x'] }))
@@ -183,7 +183,7 @@ describe('createOnboarding', () => {
       cwd,
       packages: [`file:${FIXTURE}`],
       onInstalled: () => () => new Response('hub here'),
-      confirm: allow,
+      onConfirm: allow,
     })
     const origin = await serve(onboarding)
 
@@ -220,7 +220,7 @@ describe('createOnboarding', () => {
 
   it('reports a failed install as an error the client can retry', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'], confirm: allow }))
+    const origin = await serve(createOnboarding({ cwd, packages: ['file:/nonexistent/onboard-missing'], onConfirm: allow }))
     await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), s => s.state === 'error')
     expect(final.error?.code).toBe('DF9001')
@@ -229,7 +229,7 @@ describe('createOnboarding', () => {
 
   it('asks for a restart when onInstalled returns nothing', async () => {
     const cwd = tempProject()
-    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false, confirm: allow }))
+    const origin = await serve(createOnboarding({ cwd, packages: [`file:${FIXTURE}`], dev: false, onConfirm: allow }))
     await fetch(`${origin}/__devframes/__onboard/install`, { method: 'POST', headers: { origin } })
     const final = await waitFor(() => status(origin), settled)
     expect(final.state).toBe('installed')
diff --git a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
index 05152096..bdfd38a7 100644
--- a/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
+++ b/tests/__snapshots__/tsnapi/@devframes/hub-ui-onboard/index.snapshot.d.ts
@@ -11,7 +11,7 @@ export interface CreateOnboardingOptions {
   branding?: OnboardingBranding;
   messages?: Partial<OnboardingMessages>;
   onInstalled?: () => void | OnboardingHandler | Promise<void | OnboardingHandler>;
-  confirm?: (_: OnboardingConfirmation) => boolean | Promise<boolean>;
+  onConfirm?: (_: OnboardingConfirmation) => boolean | Promise<boolean>;
 }
 export interface Onboarding {
   handler: OnboardingHandler;