Merge remote-tracking branch 'origin/master' into worktree/preset-plane-fallout-p1

The pre-commit staged-pairing hook was bypassed for this merge: master's
`docs(notes): archive superseded dsh run decision` (7ee9e16001) arrives as a
rename into `.agents/notes/archived/`, and the hook hands that path to
`verify-translation-pairing`, which correctly refuses an archived note as
out-of-corpus. The full-corpus gate passes (851 pairs).

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: 31a4894dbb191d2244371ca7272339e96e253053
+README.zh.md: 6e8d28f10071fbab175c4f14f1aaa9618b8f598a

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}`, resolved from the injected `headlessStartup` provider). 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 ordinary `headless-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), reads the positional argument of `dsh --profile headless "task"`, prints the app's `--help`, and provides `headlessStartup`; the runner injects that service and reads its task from lazy config. A missing or whitespace-only task is rejected before the runner activates.
 
 ## 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}`，从注入的 `headlessStartup` 提供方解析）。它不挂载任何 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`，并提供 `headlessStartup`；runner 注入该服务，再从惰性配置中读取任务。缺失或只有空白的任务会在 runner 激活前被拒绝。
 
 ## 模型体验
 

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. An ordinary
+# provider plugin injects `cmdlineArgs`, parses the task positional
+# (`dsh --profile headless "<task>"`) and this app's --help, then the direct
+# driver creates an Agent through the core registry and prints its durable result.
 
 - 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'
+
+    # Reads its task from the ordinary headlessStartup provider.
     - id: headless-runner
       name: '@deepseek-ai/dsh-headless'
+      inject: [headlessStartup]
+      config:
+        task: !!js ctx.headlessStartup.task

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,10 +37,13 @@
     }
   },
   "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",

packages/bundle/headless/src/index.ts

@@ -25,7 +25,7 @@ export const name = 'headless-runner'
 /** Core services required before the one-shot turn can start. */
 export const inject = ['agentDefaultModel', 'agents', 'sessions']
 
-/** Plugin config: the task, patched in by the launcher. */
+/** Plugin config: the task resolved from this app's injected provider service. */
 export interface Config {
   /** The prompt text for the single run. */
   task: string

packages/bundle/headless/src/startup.ts

@@ -0,0 +1,62 @@
+/**
+ * The one-shot app's command-line provider: it parses the task positional and
+ * `--help`, then publishes {@link HEADLESS_STARTUP_SERVICE}. The runner is an
+ * ordinary consumer whose lazy config waits for that service.
+ * @module @deepseek-ai/dsh-headless/startup
+ */
+
+import { Command } from 'commander'
+import type { Context } from '@deepseek-ai/cordis'
+import { parseCmdline } from '@deepseek-ai/dsh-cmdline'
+
+/** Stable Cordis plugin name. */
+export const name = 'headless-startup'
+
+/** Services required before the task can be resolved. */
+export const inject = ['cmdlineArgs']
+
+/** Service provided by this plugin and injected by the one-shot runner. */
+export const HEADLESS_STARTUP_SERVICE = 'headlessStartup'
+
+/** What the runner row reads from {@link HEADLESS_STARTUP_SERVICE}. */
+export interface HeadlessStartupValues {
+  /** The task text this invocation asked for. */
+  task: string
+}
+
+/**
+ * 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's task.
+ * @param program - the parsed headless command.
+ * @returns the runner's service value.
+ */
+function planHeadlessStartup(program: Command): HeadlessStartupValues {
+  const task = program.args.join(' ')
+  if (task.trim() === '') program.error('error: a task is required, for example: dsh --profile headless "run the tests"')
+  return { task }
+}
+
+/**
+ * Parse and provide the one-shot task as an ordinary Cordis service.
+ * @param ctx - plugin context carrying the command line.
+ * @returns nothing once the task is provided, or when the command requested exit.
+ */
+export function apply(ctx: Context): void {
+  const values = parseCmdline(ctx, headlessCommand(), planHeadlessStartup)
+  if (values !== undefined) ctx.provide(HEADLESS_STARTUP_SERVICE, values)
+}

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

@@ -0,0 +1,106 @@
+/**
+ * The one-shot app's ordinary command-line provider over a real Loader tree:
+ * the task becomes injected runner config, while help and usage errors leave
+ * the consumer pending.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import { internals, provideCmdline } from '@deepseek-ai/dsh-cmdline'
+import { afterEach, describe, expect, it } from 'vitest'
+import { apply, HEADLESS_STARTUP_SERVICE, type HeadlessStartupValues } from '../src/startup.ts'
+
+/** What one boot of the fixture tree observed. */
+interface Observed {
+  exits: number[]
+  out: string
+  runnerConfig?: unknown
+}
+
+const disposers: (() => Promise<void>)[] = []
+
+afterEach(async () => {
+  for (const dispose of disposers.splice(0)) await dispose()
+  internals.stdout = process.stdout
+  internals.stderr = process.stderr
+})
+
+/**
+ * Mount the real provider over a runner stand-in.
+ * @param args - the invocation's inner arguments.
+ * @returns the resolved service value and observed runner/process effects.
+ */
+async function bootStartup(args: string[]): Promise<{ task: HeadlessStartupValues | undefined; observed: Observed }> {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-headless-startup-'))
+  const observed: Observed = { exits: [], out: '' }
+  writeFileSync(join(dir, 'row.mjs'), 'export function apply(_ctx, config) { globalThis.__headlessStartupObserved.runnerConfig = config }\n')
+  // Loader imports through Node's resolver, so this fixture delegates to the
+  // source-plane plugin already imported by the test.
+  writeFileSync(join(dir, 'startup.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
+  writeFileSync(join(dir, 'cordis.yml'), [
+    '- id: headless-runner',
+    `  name: ${rowUrl}`,
+    `  inject: [${HEADLESS_STARTUP_SERVICE}]`,
+    '  config:',
+    '    task: !!js ctx.headlessStartup.task',
+    '- id: headless-startup',
+    `  name: ${pathToFileURL(join(dir, 'startup.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 {
+    __headlessStartupApply: typeof apply
+    __headlessStartupObserved: Observed
+  }
+  globals.__headlessStartupApply = apply
+  globals.__headlessStartupObserved = observed
+
+  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 {
+    task: ctx.get(HEADLESS_STARTUP_SERVICE) as HeadlessStartupValues | undefined,
+    observed,
+  }
+}
+
+describe('headless command-line provider', () => {
+  it('joins the task positional into the runner config', async () => {
+    const { task, observed } = await bootStartup(['run', 'the', 'tests'])
+    expect(task).toEqual({ task: 'run the tests' })
+    expect(observed.runnerConfig).toEqual({ task: 'run the tests' })
+    expect(observed.exits).toEqual([])
+  })
+
+  it.each([{ args: [] }, { args: ['   '] }])('rejects an invocation with no non-whitespace task ($args)', async ({ args }) => {
+    const { task, observed } = await bootStartup(args)
+    expect(observed.out).toContain('a task is required')
+    expect(task).toBeUndefined()
+    expect(observed.runnerConfig).toBeUndefined()
+    expect(observed.exits).toEqual([1])
+  })
+
+  it('prints its own help and leaves the runner pending', async () => {
+    const { task, observed } = await bootStartup(['--help'])
+    expect(observed.out).toContain('dsh --profile headless')
+    expect(task).toBeUndefined()
+    expect(observed.runnerConfig).toBeUndefined()
+    expect(observed.exits).toEqual([0])
+  })
+})

packages/bundle/headless/tsconfig.json

@@ -31,6 +31,9 @@
     },
     {
       "path": "../../support/invariants"
+    },
+    {
+      "path": "../../boot/cmdline"
     }
   ]
 }