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/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)
+}