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.

packages/bundle/headless/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/headless/README.md
-README.md: f8b76b77f2beb22f501a49f0fc4cf5cd72223765
-README.zh.md: aae8ab5bea663b8909de942f72615f5ef9b16c84
+README.md: 45c87f0c85cbb68ad0366ea5f2c86e55fc307309
+README.zh.md: 22322692450fa85a87e9faf903abee0d38968f91

packages/bundle/headless/README.md

@@ -2,9 +2,9 @@
 
 English | [中文](README.zh.md)
 
-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`, shipped disabled until the startup row supplies the task). It mounts no Host, HTTP server, Web runtime, or browser plugin.
 
-After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` host hook (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The task text is this app's command line: the `headless-startup` row ([`src/startup.ts`](src/startup.ts)) reads it as the positional argument of `dsh --profile headless "task"` from `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), prints the app's `--help`, and rejects an invocation with no task instead of letting the runner's schema fail.
 
 ## Model Experience
 

packages/bundle/headless/README.zh.md

@@ -2,9 +2,9 @@
 
 [English](README.md) | 中文
 
-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`，在启动行供给任务之前以禁用状态交付）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
 
-Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` 宿主钩子请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。任务文本就是这个应用的命令行：`headless-startup` 行（[`src/startup.ts`](src/startup.ts)）从 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)）把它读作 `dsh --profile headless "task"` 的位置参数，打印应用自己的 `--help`，并拒绝没有任务的调用，而不是让 runner 的 schema 失败。
 
 ## 模型体验
 

packages/bundle/headless/cordis.patch.yml

@@ -1,7 +1,8 @@
 # The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
-# It mounts no Host, HTTP server, Web runtime, or browser plugin. The launcher
-# patches the runner's `task`; the direct driver creates an Agent through the
-# core registry and prints the final durable assistant message.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. The startup
+# row owns the task positional (`dsh --profile headless "<task>"`) and this
+# app's --help; the direct driver creates an Agent through the core registry
+# and prints the final durable assistant message.
 
 - id: system-prompt
   config:
@@ -22,5 +23,12 @@
     - id: code-runtime
       name: '@deepseek-ai/dsh-code-runtime-worker'
 
+    - id: headless-startup
+      name: '@deepseek-ai/dsh-headless/startup'
+
+    # Shipped off, not merely waiting: the runner's schema requires the task.
+    # The startup row enables it with the task after parsing this app's argv.
     - id: headless-runner
       name: '@deepseek-ai/dsh-headless'
+      inject: [headlessStartup]
+      disabled: true

packages/bundle/headless/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"
   ],
@@ -32,15 +37,19 @@
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
     "@deepseek-ai/dsh-code-runtime-worker": "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-agent": "^0.0.1",
     "@deepseek-ai/dsh-agent-default-model": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-web-app": "^0.0.1",
     "@deepseek-ai/cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
@@ -50,6 +59,7 @@
     "@deepseek-ai/dsh-invariants": "workspace:^",
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-web-app": "workspace:^",
     "@deepseek-ai/cordis": "^4.0.0-rc.7"
   }
 }

packages/bundle/headless/src/startup.ts

@@ -0,0 +1,70 @@
+/**
+ * The one-shot app's startup row: it owns the `dsh --profile headless` command
+ * line — the task text is this command's positional argument — and its
+ * `--help` text, then provides {@link HEADLESS_STARTUP_SERVICE} with the task
+ * the user asked for. The runner waits for it, so a missing task is a usage
+ * error printed by this command instead of a schema failure inside the runner.
+ *
+ * This app layers over the web app, and a composition has exactly one
+ * command-line owner: the bundle patch disables the web startup row, and this
+ * one also provides {@link WEB_STARTUP_SERVICE} so the web rows start on their
+ * composed (one-shot) values.
+ * @module @deepseek-ai/dsh-headless/startup
+ */
+
+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'
+import { WEB_STARTUP_SERVICE } from '@deepseek-ai/dsh-web-app/startup'
+
+/** Stable Cordis plugin name. */
+export const name = 'headless-startup'
+
+/** Services required before the task can be resolved. */
+export const inject = ['cmdlineArgs']
+
+/** The startup service the one-shot runner row injects. */
+export const HEADLESS_STARTUP_SERVICE = 'headlessStartup'
+
+/** The runner row this app configures. */
+const RUNNER_ROW_ID = 'headless-runner'
+
+/**
+ * This app's command: the task positional, its description, and its help text.
+ * @returns a fresh program, so one process can parse more than once (tests).
+ */
+function headlessCommand(): Command {
+  return new Command()
+    .name('dsh --profile headless')
+    .description('Answer one task, print the final assistant message, and exit.')
+    .helpOption('-h, --help', 'show this help')
+    .argument('[task...]', 'the task text; multiple words are joined by spaces')
+    .addHelpText('after', `
+Examples:
+  dsh --profile headless "run the tests"     answer one task and exit
+`)
+}
+
+/**
+ * Turn the parsed command line into the runner row's task.
+ * @param program - the parsed headless command.
+ * @param rows - the waiting rows' composed options, in tree order.
+ * @returns row id → changes.
+ */
+function planHeadlessStartup(program: Command, rows: readonly EntryOptions[]): Map<string, RowChange> {
+  const task = program.args.join(' ')
+  if (task === '') program.error('error: a task is required, for example: dsh --profile headless "run the tests"')
+  const runner = rows.find(row => row.id === RUNNER_ROW_ID)
+  if (runner === undefined) throw new Error(`headless-startup: the composition has no waiting "${RUNNER_ROW_ID}" row to run the task`)
+  return new Map([[RUNNER_ROW_ID, overrideConfig(runner, { task })]])
+}
+
+/**
+ * Resolve the task and start the rows waiting for it.
+ * @param ctx - plugin context carrying the command line and the Loader.
+ * @returns nothing once the runner is released, or once `--help` or a missing task requested exit.
+ */
+export function apply(ctx: Context): Promise<void> {
+  return runStartup(ctx, [HEADLESS_STARTUP_SERVICE, WEB_STARTUP_SERVICE], headlessCommand(), planHeadlessStartup)
+}

packages/bundle/headless/tests/startup.spec.ts

@@ -0,0 +1,146 @@
+/**
+ * The one-shot app's startup row over a REAL Loader tree: the task
+ * positional reaches the runner row, a missing task is a usage error, and the
+ * web startup service this app absorbs releases its rows on the composed values.
+ */
+
+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 z from 'schemastery'
+import Loader from '@cordisjs/plugin-loader'
+import Include from '@cordisjs/plugin-include'
+import { internals, provideCmdline } from '@deepseek-ai/dsh-cmdline'
+import { WEB_STARTUP_SERVICE } from '@deepseek-ai/dsh-web-app/startup'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, HEADLESS_STARTUP_SERVICE } from '../src/startup.ts'
+
+/** What one boot of the fixture tree observed. */
+interface Observed {
+  started: Record<string, Record<string, unknown>>
+  exits: number[]
+  out: string
+  /** Patches the startup row handed the launcher for later compositions. */
+  contributed: unknown[]
+}
+
+const disposers: (() => Promise<void>)[] = []
+
+afterEach(async () => {
+  for (const dispose of disposers.splice(0)) await dispose()
+  internals.stdout = process.stdout
+  internals.stderr = process.stderr
+})
+
+/**
+ * Boot the real headless startup row over stand-ins for the runner row and one
+ * web row it absorbs.
+ * @param args - the invocation's inner arguments.
+ * @returns what the boot observed.
+ */
+async function bootStartup(args: string[], options: { withoutRunner?: boolean } = {}): Promise<Observed> {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-headless-startup-'))
+  const observed: Observed = { started: {}, exits: [], out: '', contributed: [] }
+  // The runner's real schema requires the task, which is exactly what makes a
+  // waiting-but-enabled row fail at fiber creation; the stand-in keeps that.
+  writeFileSync(join(dir, 'row.mjs'), `
+export const Config = globalThis.__headlessRunnerConfigSchema
+export function apply(ctx, config) { globalThis.__headlessStartupObserved.started[ctx.fiber.entry.options.id] = config ?? {} }
+`)
+  writeFileSync(join(dir, 'plain-row.mjs'), `
+export function apply(ctx, config) { globalThis.__headlessStartupObserved.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 = 'headless-startup'
+export const inject = ['cmdlineArgs']
+export const apply = ctx => globalThis.__headlessStartupApply(ctx)
+`)
+  const rowUrl = pathToFileURL(join(dir, 'row.mjs')).href
+  const plainRowUrl = pathToFileURL(join(dir, 'plain-row.mjs')).href
+  writeFileSync(join(dir, 'cordis.yml'), [
+    // A composition that lost the runner still injects the startup service, so
+    // the startup row reaches its own row check rather than the generic one.
+    options.withoutRunner === true ? '- id: displaced-runner' : '- id: headless-runner',
+    `  name: ${rowUrl}`,
+    `  inject: [${HEADLESS_STARTUP_SERVICE}]`,
+    // Shipped off, like the bundle patch: the schema below requires the task,
+    // which only the startup row can supply.
+    '  disabled: true',
+    '- id: webserver',
+    `  name: ${plainRowUrl}`,
+    `  inject: [${WEB_STARTUP_SERVICE}]`,
+    '  config:',
+    '    port: 0',
+    '- id: headless-startup',
+    `  name: ${pathToFileURL(join(dir, 'startup-row.mjs')).href}`,
+    '',
+  ].join('\n'))
+  const observing = { write: (chunk: string) => { observed.out += chunk; return true } }
+  internals.stdout = observing
+  internals.stderr = observing
+  const globals = globalThis as unknown as {
+    __headlessStartupObserved: Observed
+    __headlessStartupApply: typeof apply
+    __headlessRunnerConfigSchema: unknown
+  }
+  globals.__headlessStartupObserved = observed
+  globals.__headlessStartupApply = apply
+  globals.__headlessRunnerConfigSchema = z.object({ task: z.string().required() })
+
+  const ctx = new Context()
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  provideCmdline(ctx, {
+    args,
+    exit: code => void observed.exits.push(code),
+    contribute: patches => void observed.contributed.push(...patches),
+  })
+  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('headless startup', () => {
+  it('joins the task positional and starts the runner with it', async () => {
+    const observed = await bootStartup(['run', 'the', 'tests'])
+    expect(observed.started['headless-runner']).toEqual({ task: 'run the tests' })
+    expect(observed.exits).toEqual([])
+  })
+
+  it('hands the task to the launcher as a patch, so a recomposition keeps it', async () => {
+    const observed = await bootStartup(['run', 'the', 'tests'])
+    expect(observed.contributed).toEqual([
+      { id: 'headless-runner', disabled: false, config: { task: 'run the tests' } },
+    ])
+  })
+
+  it('starts the web rows it absorbed on the composed one-shot values', async () => {
+    const observed = await bootStartup(['task'])
+    expect(observed.started.webserver).toEqual({ port: 0 })
+  })
+
+  it('rejects an invocation with no task instead of failing inside the runner schema', async () => {
+    const observed = await bootStartup([])
+    expect(observed.out).toContain('a task is required')
+    expect(observed.started).toEqual({})
+    expect(observed.exits).toEqual([1])
+  })
+
+  it('fails the boot when the composition has no runner row to give the task to', async () => {
+    await expect(bootStartup(['task'], { withoutRunner: true }))
+      .rejects.toThrow('the composition has no waiting "headless-runner" row')
+  })
+
+  it('prints its own help and starts nothing', async () => {
+    const observed = await bootStartup(['--help'])
+    expect(observed.out).toContain('dsh --profile headless')
+    expect(observed.started).toEqual({})
+    expect(observed.exits).toEqual([0])
+  })
+})

packages/bundle/headless/tsconfig.json

@@ -31,6 +31,12 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../ui/cmdline"
+    },
+    {
+      "path": "../web-app"
     }
   ]
 }