A global flag placed before the subcommand makes the error's suggested example name the flag's VALUE as the command #984

Reproduced on 2026.8.7 and 2026.8.11.

Reproduction

Same failing command, same working directory — only the position of --pm-path differs:

$ pm plan show --pm-path /tmp/w/.agents/pm --json | jq .examples
[
  "pm plan --help",                                    # correct
  "pm contracts --command <command> --flags-only --json"
]

$ pm --pm-path /tmp/w/.agents/pm plan show --json | jq .examples
[
  "pm /tmp/w/.agents/pm --help",                       # the VALUE, as the command
  "pm contracts --command <command> --flags-only --json"
]

The detail (pm plan show requires a plan id) and recovery.attempted_command are correct in both. Only the examples array changes.

What appears to happen

The example builder derives the command path by taking the first non-flag token after pm. With --pm-path before the subcommand, that token is the flag's value, so the suggestion becomes pm <path> --help — a command that cannot work, and whose first argument is an absolute filesystem path.

Both orderings are valid: --pm-path is a documented host-owned global flag, and putting global flags before the subcommand is the conventional shape.

Why it matters more than a cosmetic error

examples is the field an agent reads to recover, and this is the failure path where recovery matters — a missing required argument. The suggestion is not merely unhelpful, it is confidently wrong: an agent that follows it runs a command whose first token is a path, gets a different error, and is now two steps from the actual problem. Nothing in the payload marks the example as derived rather than verified.

The version an agent sees depends on argument ordering it chose for unrelated reasons, so the same mistake produces good guidance or bad guidance arbitrarily.

How I found it, in case the shape recurs

Not by testing pm directly — by running pm ts-starter plan-demo, which shells out as pm --pm-path <path> plan show --depth standard --json and surfaces the nested error. Any extension that builds its argv with global flags first hits this on every usage error it forwards, which makes it more visible from extensions than from the CLI.

Suggested fix

Derive the command path from the parsed command rather than from raw argv position — recovery.attempted_command and normalized_args already have the correct structure in the same payload, so the information is present. Failing that, omit the <command> --help example when the path cannot be derived confidently, since a missing suggestion costs less than a wrong one.

Environment

@unbrained/pm-cli 2026.8.7 and 2026.8.11, Node 22/26, Linux.