# Keep Root CLI Machine Failures Parseable

## Traceability

- Spec ID: `root-cli-machine-failure-contract`
- Status: Implemented

## Intent

Keep automation able to classify failures that occur at the root CLI's
delegated-process boundary. After the root recognizes machine mode, a child
spawn failure or signal termination must produce one existing versioned error
envelope with a stable code and safe recovery hint. Human invocations should
retain short diagnostics, while successfully started child commands continue
to own their normal output bytes and exit status.

## Acceptance Scenarios

- **RCM-AC-1 (spawn failure):** when a pre-passthrough `--json` token selects
  machine mode and the delegated process cannot start, stdout contains exactly
  one parseable `format_version: "1.0"` error document with code
  `DELEGATED_COMMAND_SPAWN_FAILED`, stderr contains no second envelope, and the
  process exits with status 1.
- **RCM-AC-2 (signal termination):** when a delegated process terminates by
  signal in machine mode, any incomplete child stdout or stderr is not relayed;
  stdout instead contains exactly one parseable `format_version: "1.0"` error
  document with code `DELEGATED_COMMAND_SIGNAL_TERMINATED`, a safe next step,
  and exit status 1.
- **RCM-AC-3 (human diagnostics):** the same two failures without recognized
  machine mode write no stdout and emit one concise diagnostic on stderr. A
  spawn diagnostic may retain the operating-system error detail; a signal
  diagnostic names the terminating signal.
- **RCM-AC-4 (normal child ownership):** delegated commands that return a
  numeric status keep that status, stdout, and stderr byte-for-byte. The root
  CLI adds no success or child-business-failure envelope.
- **RCM-AC-5 (output overflow):** when a delegated process starts, runs, and
  exceeds the machine-mode output buffer, stdout contains exactly one parseable
  `format_version: "1.0"` error document with code
  `DELEGATED_COMMAND_OUTPUT_OVERFLOW` and a hint that narrows scope or drops
  `--json`. Truncated child bytes and the raw `ENOBUFS` diagnostic are not
  relayed, and the envelope is never confused with a start failure.

## Non-goals

- Changing capability-owned output schemas, messages, or business-failure
  exit codes.
- Replacing synchronous argv-array dispatch, changing the command registry, or
  adding shell-string execution.
- Activating the ADR's proposed `command-contract.v1` shape beyond the root
  CLI's existing `format_version: "1.0"` envelope.
- Normalizing malformed argument bytes or redesigning all global-option
  parsing.

## Plan and Tasks

1. Keep dispatch resolution in `scripts/better-harness-cli/cli.mjs`, and add a
   single result-normalization path that receives the already-recognized
   machine-mode state.
2. In machine mode, capture delegated stdout and stderr until `spawnSync`
   returns. Relay both unchanged for numeric child statuses, but replace
   incomplete output with the root error envelope for spawn and signal
   failures.
3. Reuse the root `errorPayload`/`jsonDocument` writer for versioning and add a
   narrow process-runner/output-writer seam so focused tests can deterministically
   supply cross-platform spawn and signal results.
4. Add focused root CLI tests for spawn failure, signal termination, human
   diagnostics, absence of a stderr envelope, and normal byte preservation.

## Test and Review Evidence

- **RCM-AC-1/RCM-AC-2:** run
  `node --test test/better-harness-cli.test.mjs`; focused injected-result tests
  must parse all of machine stdout with `JSON.parse`, assert the stable error
  code and hint, and assert empty stderr even when the simulated child result
  contains partial output.
- **RCM-AC-3:** the same focused tests assert empty stdout and bounded stderr in
  human mode for spawn and signal failures.
- **RCM-AC-4:** compare delegated root CLI output with direct capability output
  and assert identical stdout, stderr, and numeric exit status.
- **RCM-AC-5:** drive a real `spawnSync` overflow with a small `maxBuffer`, then
  assert the resulting `ENOBUFS` shape produces the overflow envelope instead of
  the spawn-failure envelope in machine mode and a bounded stderr diagnostic in
  human mode.
- **Documentation integrity:** run
  `node scripts/doc-link-graph/cli.mjs skills/better-harness` and
  `node --test test/doc-link-graph.test.mjs` after adding this Markdown file.
- **Review readiness:** run `git diff --check` and inspect staged and unstaged
  changes separately.
- **Risk:** machine-mode buffering delays delegated output until the child
  exits and is bounded by Node's synchronous child-process buffer. Keep the
  buffer explicit and large enough for current machine documents; buffer
  exhaustion stays a stable machine envelope with its own overflow code rather
  than leaking a raw diagnostic or truncated child bytes into machine stdout.

## Observed Validation Evidence

- `node --test test/better-harness-cli.test.mjs` passed 36 tests with one
  pre-existing Windows symlink-permission skip. The focused injected-result
  tests parse the complete spawn/signal stdout as one JSON document, assert
  empty machine stderr, and prove partial child envelopes are discarded.
- The combined CLI, report, Skill, renderer, and compatibility run retained all
  upstream leaf-command behavior and passed every root CLI and
  `scripts-refactor-contract` assertion.
- The full repository run reached 1,044 passes and 6 supported skips. Its four
  failures were pre-existing Windows `EPERM` symlink-creation cases; the same
  failure was reproduced from the unchanged baseline and does not execute the
  changed CLI normalization path.
- `npm run pack:verify`, the six doc-link tests, and `git diff --check` passed.