docs(batch): name the step shape and the accepted commands in help and refusals

`batch` accepts one step shape and `help batch` documented none of it: the
usage line, one sentence, and the flags. Every refusal named only what was
wrong. A caller reaching for `press` through `batch` therefore saw
"Invalid batch step 1." for `["press @E12"]` and "unknown field(s): args" for
`{"command":"press","args":[...]}`, and reasonably concluded the mutating verbs
were excluded (#2062).

They are not, and never were: `press`, `click`, `fill`, `longpress`, `scroll`
and `back` all carry `batchable: true` in the command-descriptor registry,
including at 0.20.10. The exclusions are `batch`/`replay` (which never nest) and
the session/daemon/connection/host-tooling commands. Nothing about the
allowlist changes here; what changes is that it is stated.

- `help batch` documents the step shape, serial semantics, and RENDERS the
  accepted commands from the registry's `batchable` trait, so the listing cannot
  drift from the runtime allowlist.
- The step-shape refusals (non-object step, unknown field, non-object input)
  share one hint naming `{"command":"<name>","input":{...}}`, owned by
  `batch-contract.ts` next to the checks that raise them.
- The non-batchable-command refusal points at that listing and says which
  families are excluded and why.
- `assertAllowedKeys` takes an optional hint so the batch call sites can attach
  theirs without a second unknown-key check.

Closes #2062

Author: NicolasBataille

packages/contracts/src/batch-contract.ts

@@ -14,9 +14,22 @@ export function assertBatchStepCount(stepCount: number, maxSteps: number): void
   }
 }
 
+/**
+ * The one sentence every batch-step shape refusal owes the caller. `batch` accepts a single step
+ * shape, and none of its refusals named it: a string step answered "Invalid batch step 1." and an
+ * `args`/`target`/`argv` step answered "unknown field(s)", neither of which says what a step
+ * looks like or where to find a command's input keys (#2062).
+ */
+export const BATCH_STEP_SHAPE_HINT =
+  'Each batch step is {"command":"<name>","input":{...}} — the same input object that command ' +
+  'takes on its own. There is no positional step form: run agent-device help <command> for its ' +
+  'arguments, and agent-device help batch for the commands batch accepts.';
+
 export function readBatchStepRecord(step: unknown, stepNumber: number): Record<string, unknown> {
   if (!isRecord(step)) {
-    throw new AppError('INVALID_ARGS', `Invalid batch step ${stepNumber}.`);
+    throw new AppError('INVALID_ARGS', `Invalid batch step ${stepNumber}.`, {
+      hint: BATCH_STEP_SHAPE_HINT,
+    });
   }
   return step;
 }
@@ -27,7 +40,9 @@ export function readBatchStepInputObject(
 ): Record<string, unknown> {
   const input = record.input;
   if (!isRecord(input)) {
-    throw new AppError('INVALID_ARGS', `Batch step ${stepNumber} input must be an object.`);
+    throw new AppError('INVALID_ARGS', `Batch step ${stepNumber} input must be an object.`, {
+      hint: BATCH_STEP_SHAPE_HINT,
+    });
   }
   return input;
 }

packages/contracts/src/facades/command.ts

@@ -1,4 +1,5 @@
 export {
+  BATCH_STEP_SHAPE_HINT,
   DEFAULT_BATCH_MAX_STEPS,
   assertBatchStepCount,
   isValidBatchMaxSteps,

src/cli-schema/cli-help-topics.test.ts

@@ -37,6 +37,22 @@ test('gesture help documents selectors and pinned refs for both drag endpoints',
   assert.match(help, /drag <source-selector\|pinned-ref> <destination-selector\|pinned-ref>/);
 });
 
+// `help batch` documented neither the step shape nor which commands batch accepts, so both were
+// only reachable by trial (#2062). The accepted list is rendered from the registry, so this asserts
+// membership rather than an exact roster.
+test('batch help documents the step shape and the commands batch accepts', async () => {
+  const help = await usageForCommand('batch');
+  if (help === null) throw new Error('Expected batch help text');
+
+  assert.match(help, /\{"command":"<name>","input":\{\.\.\.\}\}/);
+  assert.match(help, /no positional step form/);
+  assert.match(help, /Available through batch:/);
+  for (const command of ['press', 'click', 'fill', 'longpress', 'scroll', 'back']) {
+    assert.match(help, new RegExp(`\\b${command}\\b`), `expected ${command} in batch help`);
+  }
+  assert.match(help, /batch and replay never nest/);
+});
+
 test('commands topic includes only global flags in its global flags section', async () => {
   const usageText = await usageForCommand('commands');
   if (usageText === null) throw new Error('Expected commands help text');

src/cli/batch-steps.ts

@@ -1,5 +1,6 @@
 import type { BatchStep } from '@agent-device/contracts/client';
 import {
+  BATCH_STEP_SHAPE_HINT,
   parseBatchStepRuntime,
   readBatchStepInputObject,
   readBatchStepRecord,
@@ -31,7 +32,12 @@ function readCliBatchStep(step: unknown, stepNumber: number): BatchStep {
       `Batch step ${stepNumber} uses removed field(s): ${fields}. Use {"command":"...","input":{...}}. Example: {"command":"open","input":{"app":"settings","platform":"ios"}}.`,
     );
   }
-  assertAllowedKeys(record, ['command', 'input', 'runtime'], `Batch step ${stepNumber}`);
+  assertAllowedKeys(
+    record,
+    ['command', 'input', 'runtime'],
+    `Batch step ${stepNumber}`,
+    BATCH_STEP_SHAPE_HINT,
+  );
   const runtime = parseBatchStepRuntime(record.runtime, stepNumber);
   return {
     command: readStructuredBatchCommandName(record.command, stepNumber),

src/commands/batch/cli.test.ts

@@ -120,6 +120,55 @@ test('batch rejects structured replay steps before daemon dispatch', async () =>
   assert.match(result.stderr, /not available through command batch/);
 });
 
+// Every step-shape refusal used to name only what was wrong, never what a step looks like, and
+// `help batch` documented no shape and no exclusions — so the boundary was reachable only by
+// trial (#2062). Each refusal now carries the missing half.
+
+test('a non-object step names the step shape', async () => {
+  const result = await runCliCapture(['batch', '--steps', '["press @e12"]']);
+
+  assert.equal(result.code, 1);
+  assert.equal(result.calls.length, 0);
+  assert.match(result.stderr, /Invalid batch step 1/);
+  assert.match(result.stderr, /\{"command":"<name>","input":\{\.\.\.\}\}/);
+  assert.match(result.stderr, /no positional step form/);
+});
+
+test('an args/target step names the step shape instead of only the unknown field', async () => {
+  const result = await runCliCapture(['batch', '--steps', '[{"command":"press","args":["@e12"]}]']);
+
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /has unknown field\(s\): args/);
+  assert.match(result.stderr, /\{"command":"<name>","input":\{\.\.\.\}\}/);
+});
+
+test('a non-batchable command points at the listing of the ones that are', async () => {
+  const result = await runCliCapture(['batch', '--steps', '[{"command":"session","input":{}}]']);
+
+  assert.equal(result.code, 1);
+  assert.match(result.stderr, /not available through command batch: session/);
+  assert.match(result.stderr, /help batch/);
+});
+
+// The reported blocker (#2062) was the step shape, not the verb: press/click/fill were never
+// excluded from batch. Pin that so a future exclusion has to be a deliberate registry change.
+test('mutating UI verbs reach daemon dispatch through batch', async () => {
+  const result = await runCliCapture([
+    'batch',
+    '--steps',
+    '[{"command":"press","input":{"target":{"kind":"ref","ref":"@e12"}}},{"command":"fill","input":{"target":{"kind":"ref","ref":"@e13"},"text":"x"}}]',
+    '--json',
+  ]);
+
+  assert.equal(result.code, null);
+  assert.equal(result.calls.length, 1);
+  const steps = result.calls[0]?.flags?.batchSteps ?? [];
+  assert.deepEqual(
+    steps.map((step) => step.command),
+    ['press', 'fill'],
+  );
+});
+
 test('batch rejects invalid structured runtime', async () => {
   const result = await runCliCapture([
     'batch',

src/commands/batch/index.ts

@@ -7,6 +7,7 @@ import { defineExecutableCommand } from '../command-contract.ts';
 import { commonToClientOptions } from '../command-input.ts';
 import { batchCliOutputFormatters } from './output.ts';
 import { createBatchCommandMetadata, type BatchInput } from './metadata.ts';
+import { STRUCTURED_BATCH_COMMAND_NAMES } from '../../core/batch-policy.ts';
 import { createBatchDaemonWriter } from './projection.ts';
 
 const batchCommandMetadata = createBatchCommandMetadata();
@@ -29,10 +30,26 @@ const batchCliReader: CliReader = (_positionals, flags) => ({
   out: flags.out,
 });
 
+/**
+ * `help batch` documented neither the step shape nor which commands batch accepts, so an agent
+ * discovered both by trial: `["press @e12"]` and `{"command":"press","args":[...]}` were refused
+ * without either being named (#2062). The accepted set is RENDERED from the command-descriptor
+ * registry's `batchable` trait, so it cannot drift from what the runtime allowlist enforces.
+ */
+function buildBatchCliDetail(): string {
+  return [
+    'Each step is {"command":"<name>","input":{...}}: the same input object that command takes on its own — run agent-device help <command> for its arguments. There is no positional step form; args, target, and argv are not step fields.',
+    'Steps run serially in one daemon request against the same session, in order. Mutating UI verbs are included (press, click, fill, longpress, scroll, back), which is where the round-trip saving is; --on-error stop halts at the first failing step.',
+    `Available through batch: ${[...STRUCTURED_BATCH_COMMAND_NAMES].sort().join(', ')}.`,
+    'Every other command is excluded: batch and replay never nest, and session, daemon, connection, and host tooling commands own lifecycle a batch request cannot carry. Run those on their own.',
+  ].join(' ');
+}
+
 const batchCommandFacet = defineCommandFacet({
   name: 'batch',
   text: {
     summary: 'Run multiple commands',
+    cliDetail: buildBatchCliDetail(),
   },
   metadata: batchCommandMetadata,
   definition: batchCommandDefinition,

src/commands/batch/metadata.ts

@@ -1,4 +1,5 @@
 import {
+  BATCH_STEP_SHAPE_HINT,
   DEFAULT_BATCH_MAX_STEPS,
   assertBatchStepCount,
   isValidBatchMaxSteps,
@@ -49,7 +50,7 @@ export function createBatchCommandMetadata(
   const fields = batchFields(nestedCommands);
   return defineCommandMetadata({
     name: 'batch',
-    description: 'Execute multiple commands in one daemon request',
+    description: 'Execute multiple commands in one daemon request.',
     inputSchema: fieldsInputSchema(fields),
     readInput: (input) => readBatchInput(input, fields),
   });
@@ -128,7 +129,12 @@ function readBatchStep(
   nestedCommands: readonly string[],
 ): BatchCommandStep {
   const record = readBatchStepRecord(step, stepNumber);
-  assertAllowedKeys(record, ['command', 'input', 'runtime'], `Batch step ${stepNumber}`);
+  assertAllowedKeys(
+    record,
+    ['command', 'input', 'runtime'],
+    `Batch step ${stepNumber}`,
+    BATCH_STEP_SHAPE_HINT,
+  );
   return {
     command: readBatchStepCommand(record, stepNumber, nestedCommands),
     input: readBatchStepInputObject(record, stepNumber),

src/commands/cli-grammar/flag-definitions-workflow.ts

@@ -135,7 +135,7 @@ export const WORKFLOW_FLAG_DEFINITIONS: readonly FlagDefinition[] = [
     names: ['--steps'],
     type: 'string',
     usageLabel: '--steps <json>',
-    usageDescription: 'Batch: JSON array of steps',
+    usageDescription: 'Batch: JSON array of {"command","input"} steps',
   },
   {
     key: 'stepsFile',

src/commands/command-input.ts

@@ -529,11 +529,16 @@ export function assertAllowedKeys(
   record: Record<string, unknown>,
   allowedKeys: readonly string[],
   label: string,
+  hint?: string,
 ): void {
   const allowed = new Set(allowedKeys);
   const unknownKeys = Object.keys(record).filter((key) => !allowed.has(key));
   if (unknownKeys.length > 0) {
-    throw new AppError('INVALID_ARGS', `${label} has unknown field(s): ${unknownKeys.join(', ')}.`);
+    throw new AppError(
+      'INVALID_ARGS',
+      `${label} has unknown field(s): ${unknownKeys.join(', ')}.`,
+      hint === undefined ? undefined : { hint },
+    );
   }
 }
 

src/core/batch-policy.ts

@@ -49,6 +49,17 @@ export const INHERITED_PARENT_FLAG_KEYS = [
   'out',
 ] as const;
 
+/**
+ * The refusal above names the rejected command but never named the accepted set, and `help batch`
+ * documented no exclusions either, so the boundary was only discoverable by trial (#2062). Point at
+ * the one derived listing rather than restating it: `help batch` renders
+ * {@link STRUCTURED_BATCH_COMMAND_NAMES} itself, so a registry change cannot leave prose behind.
+ */
+const BATCH_AVAILABLE_COMMANDS_HINT =
+  'Run agent-device help batch for the commands available through batch. Session, daemon, ' +
+  'connection, and host tooling commands are excluded — they own lifecycle a batch cannot ' +
+  'carry — and batch and replay never nest. Run an excluded command on its own.';
+
 const structuredBatchCommandNames = new Set<string>(STRUCTURED_BATCH_COMMAND_NAMES);
 
 function isStructuredBatchCommandName(command: string): command is StructuredBatchCommandName {
@@ -68,6 +79,7 @@ export function readStructuredBatchCommandName(
   throw new AppError(
     'INVALID_ARGS',
     `Batch step ${stepNumber} command is not available through command batch: ${String(command)}`,
+    { hint: BATCH_AVAILABLE_COMMANDS_HINT },
   );
 }