feat(bundle): the web and one-shot apps own their own flags

dsh-web-app owns --host/--port/--dev/--workspace-root/--trusted-host and its --help in a web-startup row; the rows it configures wait for the webStartup service, and the client-plugin HMR receiver now ships disabled so --dev is a row toggle rather than a runtime insert (the Loader cannot resolve a row inserted from inside a mounting plugin). dsh-headless owns the task positional and rejects a missing task as its own usage error. Its runner ships disabled, not merely waiting: the schema requires the task, and a row's config is validated when its fiber is created, before the startup row can supply one. A composition has exactly one command-line owner, so the patch disables the web startup row and this one provides webStartup too, leaving the web rows on their composed one-shot values. The keyless web scaffold provides the same three values with no arguments, which is what an embedding host with no command line does.
2026-08-06 20:52:26 +08:00
parent 788368e314
commit 82728808d4
23 changed files with 692 additions and 36 deletions
--- a/packages/bundle/web-app/README.i18n.yaml
+++ b/packages/bundle/web-app/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/web-app/README.md
-README.md: d89ae4a7e28506166498caf0032f864bbb109cc5
-README.zh.md: 746ec2e8b6748a0d72f697d0aea5f3809e7106ee
+README.md: 1b54e6d29ad49c62b7862bf7fffcd6d24831c643
+README.zh.md: 82b7c4c2574aa93697e8483c362cf4ec75630f34
--- a/packages/bundle/web-app/README.md
+++ b/packages/bundle/web-app/README.md
@@ -2,7 +2,7 @@

 English | [中文](README.zh.md)

-The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
+The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. This bundle also owns the app command line: the `web-startup` row ([`src/startup.ts`](src/startup.ts)) parses `--host`, `--port`, `--dev`, `--workspace-root`, and repeatable `--trusted-host` from `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)) and prints the app's `--help`. Every row it configures injects `webStartup`, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. `mode` and `lanAddresses` resolve on every boot because they describe the invocation. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.

 ## Model Experience

--- a/packages/bundle/web-app/README.zh.md
+++ b/packages/bundle/web-app/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。本组合包还持有应用命令行：`web-startup` 行（[`src/startup.ts`](src/startup.ts)）从 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)）解析 `--host`、`--port`、`--dev`、`--workspace-root` 以及可重复的 `--trusted-host`，并打印应用自己的 `--help`。它所配置的每一行都注入 `webStartup`，因此在参数解析完成之前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。`mode` 与 `lanAddresses` 在每次 boot 时解析，因为它们描述的是本次调用。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。

 ## 模型体验

--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -3,9 +3,13 @@
 # the profile's own cordis.patch.yml and any --patch overlays still to come.
 #
 # A patch replaces the targeted row's whole `config`, so each row below
-# restates every key it owns. The `dsh web` launcher alias turns --host/--port/
-# --dev/--trusted-host into further patches over these rows
-# (`--dev` inserts the dsh-client-hmr row).
+# restates every key it owns.
+#
+# Rows this app configures from flags declare `inject: [webStartup]`: they wait
+# until the web-startup row has parsed --host/--port/--dev/--workspace-root/
+# --trusted-host and provided that service with the resolved values.
+# `dsh --profile web --help` therefore prints this app's own help and exits
+# without ever binding a port.

 # ── surface-specific values the base deliberately omits ─────────────────────

@@ -76,6 +80,11 @@
    - id: api-gateway
      name: '@deepseek-ai/dsh-host-apiproxy'

+    # Owns the web flag family and its --help; provides webStartup with the
+    # values this invocation resolved. Nothing waiting on it starts first.
+    - id: web-startup
+      name: '@deepseek-ai/dsh-web-app/startup'
+
    # ── layer 2: transport/service ──────────────────────────────────────────────

    # Plain route-registration carrier; host and port arrive as `dsh web`
@@ -83,6 +92,7 @@
    # row below through the fallback seat.
    - id: webserver
      name: '@deepseek-ai/dsh-host-webserver'
+      inject: [webStartup]
      config:
        host: 127.0.0.1
        port: 3080
@@ -96,12 +106,19 @@
    # these host-owned shell variables.
    - id: web-runtime
      name: '@deepseek-ai/dsh-web-app'
+      inject: [webStartup]
      config:
        mode: production
        printUrl: true
        surfaceContext: true

-    # ── browser plugin roster (dsh.client rows; node halves are layer-2 hosts) ──
+    # The client-plugin HMR receiver ships disabled; `--dev` enables it.
+    - id: client-hmr
+      name: '@deepseek-ai/dsh-client-hmr'
+      inject: [webStartup]
+      disabled: true
+
+    # ── browser plugin roster (dshClient rows; node halves are layer-2 hosts) ──

    # Dual-face: node half scans this very tree for dsh.client rows, composes
    # window.__DSH_BOOT__, serves /plugins/<id>/client.js; browser half is the
@@ -114,6 +131,7 @@
    # webserver under /api; browser half is the fetch/SSE client.
    - id: connection
      name: '@deepseek-ai/dsh-client-connection'
+      inject: [webStartup]

    - id: api-remotes
      name: '@deepseek-ai/dsh-api-remotes'
--- a/packages/bundle/web-app/package.json
+++ b/packages/bundle/web-app/package.json
@@ -11,6 +11,10 @@
      "types": "./lib/types/index.d.ts",
      "default": "./lib/index.js"
    },
+    "./startup": {
+      "types": "./lib/types/startup.d.ts",
+      "default": "./lib/startup.js"
+    },
    "./invariant": {
      "types": "./lib/types/invariant.d.ts",
      "default": "./lib/invariant.js"
@@ -22,6 +26,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
+    "lib/startup.js",
    "cordis.patch.yml",
    "lib/types/**/*.d.ts"
  ],
@@ -61,6 +66,7 @@
    "@deepseek-ai/dsh-client-ui-tool": "workspace:^",
    "@deepseek-ai/dsh-client-ui-trajectory": "workspace:^",
    "@deepseek-ai/dsh-client-ui-workspace": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
    "@deepseek-ai/dsh-frontend": "workspace:^",
    "@deepseek-ai/dsh-frontend-static": "workspace:^",
@@ -74,15 +80,18 @@
    "@deepseek-ai/dsh-storage-domain": "workspace:^",
    "@deepseek-ai/dsh-storage-json": "workspace:^",
    "@deepseek-ai/dsh-workspace": "workspace:^",
-    "@deepseek-ai/schemastery": "^3.18.0"
+    "@deepseek-ai/schemastery": "^3.18.0",
+    "commander": "^15.0.0"
  },
  "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.0-rc.5",
    "@deepseek-ai/dsh-bash-env": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/cordis": "^4.0.0-rc.7"
  },
  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-bash-env": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/bundle/web-app/src/startup.ts
+++ b/packages/bundle/web-app/src/startup.ts
@@ -0,0 +1,152 @@
+/**
+ * The web app's startup row: it owns the `dsh --profile web` flag family
+ * (`--host`, `--port`, `--dev`, `--workspace-root`, `--trusted-host`) and its
+ * `--help` text, turns those flags into changes on the rows that inject
+ * {@link WEB_STARTUP_SERVICE}, and then provides it. Until it does, no web row
+ * starts, so `dsh --profile web --help` prints this command's help and the
+ * server never binds.
+ * @module @deepseek-ai/dsh-web-app/startup
+ */
+
+import { networkInterfaces } from 'node:os'
+import { Command } from 'commander'
+import type { Context } from 'cordis'
+import type { EntryOptions } from '@cordisjs/plugin-loader'
+import { overrideConfig, runStartup, type RowChange } from '@deepseek-ai/dsh-cmdline'
+
+/** Stable Cordis plugin name. */
+export const name = 'web-startup'
+
+/** Services required before the flags can be resolved. */
+export const inject = ['cmdlineArgs']
+
+/**
+ * The startup service every flag-configured web row injects. The rows are
+ * listed in this bundle's `cordis.patch.yml`; a row this startup plans changes
+ * for without injecting the service fails loud.
+ */
+export const WEB_STARTUP_SERVICE = 'webStartup'
+
+/** The webserver schema's all-interfaces bind literal: only this bind derives LAN authorities. */
+const ALL_INTERFACES_HOST = '0.0.0.0'
+
+/**
+ * Non-internal IPv4 interface addresses of this machine — the IP-literal
+ * authorities an all-interfaces bind is reachable by on the LAN.
+ * @returns the addresses in interface order (possibly empty).
+ */
+function lanIPv4Addresses(): string[] {
+  return Object.values(networkInterfaces()).flat()
+    .filter((iface): iface is NonNullable<typeof iface> => iface !== undefined && iface.family === 'IPv4' && !iface.internal)
+    .map(iface => iface.address)
+}
+
+/**
+ * One LAN-trust resolution for one invocation, sampled exactly once: the
+ * machine's LAN IP literals when the effective bind is all-interfaces, and the
+ * `trustedHosts` value built from them plus the explicit extras. The single
+ * sample is deliberate — display must advertise only addresses the fence was
+ * configured with, so the `web-runtime` row receives this same snapshot.
+ * Derived entries are port-less IP literals: DNS rebinding needs an
+ * attacker-controlled name, so an IP-literal Host is safe on any port, and the
+ * bound port may be OS-assigned, unknowable before the server binds.
+ * @param bindHost - the effective webserver bind host (the flag, else the composed row value).
+ * @param extra - `--trusted-host` values, in argv order.
+ * @returns the sampled LAN addresses and the connection row's `trustedHosts` value (each possibly empty).
+ */
+export function resolveLanTrust(
+  bindHost: string | undefined,
+  extra: readonly string[],
+): { lanAddresses: string[]; trustedHosts: string[] } {
+  const lanAddresses = bindHost === ALL_INTERFACES_HOST ? lanIPv4Addresses() : []
+  return { lanAddresses, trustedHosts: [...lanAddresses, ...extra] }
+}
+
+/** The web flag family, as commander parsed it. */
+interface WebOptions {
+  host?: string
+  port?: string
+  dev?: boolean
+  workspaceRoot?: string
+  trustedHost?: string[]
+}
+
+/**
+ * This app's command: its flags, its description, and its help text.
+ * @returns a fresh program, so one process can parse more than once (tests).
+ */
+function webCommand(): Command {
+  return new Command()
+    .name('dsh --profile web')
+    .description('Serve the DeepSeek Harness browser UI.')
+    .helpOption('-h, --help', 'show this help')
+    .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
+    .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
+    .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
+    .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
+    .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
+    .addHelpText('after', `
+Examples:
+  dsh web                          serve on the composed host and port
+  dsh web --port 8080              serve on another port
+  dsh web --host 0.0.0.0           reach it from another machine on the LAN
+  dsh web --dev                    mount the client-plugin HMR receiver
+`)
+}
+
+/**
+ * Turn the parsed flags into the changes each waiting row needs.
+ * @param program - the parsed web command.
+ * @param rows - the waiting rows' composed options, in tree order.
+ * @returns row id → changes; rows absent from the map start on their composed values.
+ */
+function planWebStartup(program: Command, rows: readonly EntryOptions[]): Map<string, RowChange> {
+  const options = program.opts<WebOptions>()
+  if (options.port !== undefined && !/^\d+$/.test(options.port)) {
+    program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`)
+  }
+  const row = (id: string): EntryOptions => {
+    const found = rows.find(candidate => candidate.id === id)
+    if (found === undefined) throw new Error(`web-startup: the web composition has no waiting "${id}" row to configure`)
+    return found
+  }
+  const plan = new Map<string, RowChange>()
+  const webserver = row('webserver')
+  const composedHost = (webserver.config as { host?: string } | undefined)?.host
+  plan.set('webserver', overrideConfig(webserver, {
+    ...options.host !== undefined && { host: options.host },
+    ...options.port !== undefined && { port: Number(options.port) },
+  }))
+  if (options.workspaceRoot !== undefined) {
+    plan.set('api-gateway', overrideConfig(row('api-gateway'), { workspaceRoot: options.workspaceRoot }))
+  }
+  const { lanAddresses, trustedHosts } = resolveLanTrust(options.host ?? composedHost, options.trustedHost ?? [])
+  if (trustedHosts.length > 0) {
+    // Additive over the composed value: a cordis.patch.yml-configured fence
+    // authority must survive the derived LAN literals and the flag extras —
+    // dropping it silently would weaken security-relevant configuration.
+    const connection = row('connection')
+    const composedTrusted = (connection.config as { trustedHosts?: string[] } | undefined)?.trustedHosts ?? []
+    plan.set('connection', overrideConfig(connection, { trustedHosts: [...composedTrusted, ...trustedHosts] }))
+  }
+  // mode and lanAddresses are resolved on every boot, never pass-throughs of
+  // composed values: they describe this invocation, not the deployment.
+  plan.set('web-runtime', overrideConfig(row('web-runtime'), {
+    mode: options.dev === true ? 'development' : 'production',
+    lanAddresses,
+  }))
+  // The receiver ships disabled so `--dev` is a row toggle rather than a
+  // runtime insert (the Loader cannot resolve a row inserted from inside a
+  // mounting plugin).
+  if (options.dev === true) plan.set('client-hmr', { disabled: false })
+  return plan
+}
+
+/**
+ * Resolve the web flag family and start the rows waiting for it.
+ * @param ctx - plugin context carrying the command line and the Loader.
+ * @returns nothing once the waiting rows are released, or once `--help` requested exit.
+ */
+export function apply(ctx: Context): Promise<void> {
+  return runStartup(ctx, WEB_STARTUP_SERVICE, webCommand(), planWebStartup)
+}
--- a/packages/bundle/web-app/tests/startup.spec.ts
+++ b/packages/bundle/web-app/tests/startup.spec.ts
@@ -0,0 +1,163 @@
+/**
+ * The web app's startup row over a REAL Loader tree carrying this bundle's
+ * waiting row ids: flags reach the rows they configure, absent flags leave the
+ * composed values standing, `--dev` enables the shipped-disabled HMR receiver,
+ * and `--help` leaves the app unstarted.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import { internals, provideCmdline } from '@deepseek-ai/dsh-cmdline'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { apply, WEB_STARTUP_SERVICE } from '../src/startup.ts'
+
+vi.mock('node:os', async importOriginal => ({
+  ...await importOriginal<typeof import('node:os')>(),
+  networkInterfaces: () => ({
+    lo0: [{ family: 'IPv4', internal: true, address: '127.0.0.1' }],
+    en0: [{ family: 'IPv4', internal: false, address: '192.168.1.5' }],
+  }),
+}))
+
+/** What one boot of the fixture tree observed. */
+interface Observed {
+  /** Config each waiting row started with, by row id; absent means it never started. */
+  started: Record<string, Record<string, unknown>>
+  exits: number[]
+  out: string
+}
+
+const disposers: (() => Promise<void>)[] = []
+
+afterEach(async () => {
+  for (const dispose of disposers.splice(0)) await dispose()
+  internals.stdout = process.stdout
+  internals.stderr = process.stderr
+})
+
+/** One stand-in for a row this bundle's patch makes wait for the web startup. */
+interface WaitingRow {
+  id: string
+  config?: Record<string, unknown>
+  disabled?: boolean
+}
+
+/** The waiting rows this bundle's patch declares, with the composed values they ship. */
+const WAITING_ROWS: WaitingRow[] = [
+  { id: 'webserver', config: { host: '127.0.0.1', port: 3080 } },
+  { id: 'api-gateway', config: { provider: 'deepseek-official' } },
+  { id: 'connection', config: { trustedHosts: ['configured.internal'] } },
+  { id: 'web-runtime', config: { mode: 'production', printUrl: true } },
+  { id: 'client-hmr', disabled: true },
+]
+
+/**
+ * Boot the real startup row over stand-ins for this bundle's waiting rows.
+ * @param args - the invocation's inner arguments.
+ * @returns what the boot observed.
+ */
+async function bootStartup(args: string[], rows: readonly WaitingRow[] = WAITING_ROWS): Promise<Observed> {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-web-startup-'))
+  const observed: Observed = { started: {}, exits: [], out: '' }
+  writeFileSync(join(dir, 'row.mjs'), `
+export function apply(ctx, config) { globalThis.__webStartupObserved.started[ctx.fiber.entry.options.id] = config ?? {} }
+`)
+  // The Loader imports a row through Node's own resolver, which cannot resolve
+  // this workspace's sources; the row delegates to the real plugin the test
+  // imported through the source-plane path mapping.
+  writeFileSync(join(dir, 'startup-row.mjs'), `
+export const name = 'web-startup'
+export const inject = ['cmdlineArgs']
+export const apply = ctx => globalThis.__webStartupApply(ctx)
+`)
+  const rowUrl = pathToFileURL(join(dir, 'row.mjs')).href
+  const lines = rows.flatMap(row => [
+    `- id: ${row.id}`,
+    `  name: ${rowUrl}`,
+    `  inject: [${WEB_STARTUP_SERVICE}]`,
+    ...row.disabled === true ? ['  disabled: true'] : [],
+    ...row.config === undefined ? [] : ['  config:', ...Object.entries(row.config).map(([key, value]) => `    ${key}: ${JSON.stringify(value)}`)],
+  ])
+  lines.push('- id: web-startup', `  name: ${pathToFileURL(join(dir, 'startup-row.mjs')).href}`)
+  writeFileSync(join(dir, 'cordis.yml'), lines.join('\n') + '\n')
+  const observing = { write: (chunk: string) => { observed.out += chunk; return true } }
+  internals.stdout = observing
+  internals.stderr = observing
+  const globals = globalThis as unknown as { __webStartupObserved: Observed; __webStartupApply: typeof apply }
+  globals.__webStartupObserved = observed
+  globals.__webStartupApply = apply
+
+  const ctx = new Context()
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  provideCmdline(ctx, { args, exit: code => void observed.exits.push(code) })
+  await ctx.loader.create({ name: 'cordis:include', config: { path: pathToFileURL(join(dir, 'cordis.yml')).href } })
+  await ctx.loader.await()
+  disposers.push(async () => { await ctx.fiber.dispose() })
+  return observed
+}
+
+describe('web startup', () => {
+  it('applies each flag to the row that owns it and leaves the rest composed', async () => {
+    const observed = await bootStartup(['--port', '8080', '--workspace-root', '/w'])
+    expect(observed.started.webserver).toEqual({ host: '127.0.0.1', port: 8080 })
+    expect(observed.started['api-gateway']).toEqual({ provider: 'deepseek-official', workspaceRoot: '/w' })
+    expect(observed.started['web-runtime']).toEqual({ mode: 'production', printUrl: true, lanAddresses: [] })
+    expect(observed.started['client-hmr']).toBeUndefined()
+    expect(observed.exits).toEqual([])
+  })
+
+  it('starts every row on its composed values when the invocation carries no flags', async () => {
+    const observed = await bootStartup([])
+    expect(observed.started.webserver).toEqual({ host: '127.0.0.1', port: 3080 })
+    expect(observed.started.connection).toEqual({ trustedHosts: ['configured.internal'] })
+  })
+
+  it('adds the LAN literals over the configured fence authorities for an all-interfaces bind', async () => {
+    const observed = await bootStartup(['--host', '0.0.0.0', '--trusted-host', 'lab.internal'])
+    expect(observed.started.webserver).toEqual({ host: '0.0.0.0', port: 3080 })
+    expect(observed.started.connection).toEqual({ trustedHosts: ['configured.internal', '192.168.1.5', 'lab.internal'] })
+    // Display gets the same single sample the fence was configured with.
+    expect(observed.started['web-runtime']).toEqual({ mode: 'production', printUrl: true, lanAddresses: ['192.168.1.5'] })
+  })
+
+  it('enables the shipped-disabled HMR receiver for --dev', async () => {
+    const observed = await bootStartup(['--dev'])
+    expect(observed.started['client-hmr']).toEqual({})
+    expect(observed.started['web-runtime']).toEqual({ mode: 'development', printUrl: true, lanAddresses: [] })
+  })
+
+  it('prints its own help and starts nothing', async () => {
+    const observed = await bootStartup(['--help'])
+    expect(observed.out).toContain('dsh --profile web')
+    expect(observed.out).toContain('--trusted-host')
+    expect(observed.started).toEqual({})
+    expect(observed.exits).toEqual([0])
+  })
+
+  it('fails the boot when the composition lost a row this app configures', async () => {
+    // The bundle patch and this startup plugin must agree on the row set; a
+    // missing row would otherwise silently drop the flag that targets it.
+    const withoutWebserver = WAITING_ROWS.filter(row => row.id !== 'webserver')
+    await expect(bootStartup([], withoutWebserver))
+      .rejects.toThrow('the web composition has no waiting "webserver" row')
+  })
+
+  it('derives the fence authorities alone when the composition configured none', async () => {
+    const withoutTrust = WAITING_ROWS.map(row => row.id === 'connection' ? { id: 'connection' } : row)
+    const observed = await bootStartup(['--host', '0.0.0.0'], withoutTrust)
+    expect(observed.started.connection).toEqual({ trustedHosts: ['192.168.1.5'] })
+  })
+
+  it('rejects a non-numeric port before anything binds', async () => {
+    const observed = await bootStartup(['--port', 'abc'])
+    expect(observed.out).toContain('--port must be a number')
+    expect(observed.started).toEqual({})
+    expect(observed.exits).toEqual([1])
+  })
+})
--- a/packages/bundle/web-app/tests/trusted-hosts.spec.ts
+++ b/packages/bundle/web-app/tests/trusted-hosts.spec.ts
@@ -0,0 +1,33 @@
+/** Single-sample LAN-trust resolution for the /api browser-trust fence (`resolveLanTrust`). */
+
+import { describe, expect, it, vi } from 'vitest'
+import { resolveLanTrust } from '../src/startup.ts'
+
+vi.mock('node:os', () => ({
+  networkInterfaces: () => ({
+    lo0: [
+      { family: 'IPv4', internal: true, address: '127.0.0.1' },
+    ],
+    en0: [
+      { family: 'IPv6', internal: false, address: 'fe80::1' },
+      { family: 'IPv4', internal: false, address: '192.168.1.5' },
+    ],
+    en1: [
+      { family: 'IPv4', internal: false, address: '10.0.0.7' },
+    ],
+    utun0: undefined,
+  }),
+}))
+
+describe('resolveLanTrust', () => {
+  it('samples non-internal IPv4 addresses once for an all-interfaces bind: trust and display share them', () => {
+    const { lanAddresses, trustedHosts } = resolveLanTrust('0.0.0.0', ['harness.internal:3080'])
+    expect(lanAddresses).toEqual(['192.168.1.5', '10.0.0.7'])
+    expect(trustedHosts).toEqual(['192.168.1.5', '10.0.0.7', 'harness.internal:3080'])
+  })
+
+  it('derives nothing for a loopback or unresolved bind — extras alone stand, no LAN URL to print', () => {
+    expect(resolveLanTrust('127.0.0.1', [])).toEqual({ lanAddresses: [], trustedHosts: [] })
+    expect(resolveLanTrust(undefined, ['lab.internal'])).toEqual({ lanAddresses: [], trustedHosts: ['lab.internal'] })
+  })
+})
--- a/packages/bundle/web-app/tsconfig.json
+++ b/packages/bundle/web-app/tsconfig.json
@@ -14,6 +14,12 @@
    {
      "path": "../../../vendor/schemastery"
    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../ui/cmdline"
+    },
    {
      "path": "../../host/frontend-static"
    },