[GH-ISSUE #3052] [Docs] process-capture.md: final capture progress line has no `disposition` field; the values are in `message` #1067

New issue

Closed

opened 2026-10-15 18:30:48 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:30:48 +00:00

Owner

Originally created by @coygeek on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3052

Before submitting

I searched the existing issues for a related documentation report.
I removed credentials, tokens, private paths, and sensitive target data.

Documentation location

docs/process-capture.md#progress (lines 161-164; lines 72-75 at the rea-agents-6.4.0 tag, same wording)

Problem

The Progress section says the final rea_progress line from capture-process "uses phase cleanup, sets terminal to true, and adds disposition (exited, timeout, idle_timeout, cancelled, or failed) plus the owned-process, renderer, and temporary-root cleanup states." Read beside the phase, completed, total, and terminal keys the same paragraph documents, this reads as added keys on the final line. The preceding sentence says only that "message reports elapsed time and those counts".

The emitted final line has no disposition key and no cleanup-state keys. Its keys are phase, completed, total, message, terminal, and sequence; the disposition and cleanup states appear only as key=value text inside message. A JSON consumer that follows the doc and reads rea_progress.disposition gets nothing. Capture, cleanup, and stdout output are unaffected.

Tested with rea-agents 6.4.0 from npm (latest dist-tag, commit a56f7bb668ab23fec8d33f7af353ac7ed2fe1895) on macOS 27.0 arm64, Node 26.10.0, npm 12.2.0. main at e049ef70f71aeb9965e9d75d4d4a84ea02eaee11 has the same doc wording and the same message formatting in source (inspected, not run).

Expected content

The documented final-line shape should match the emitted line: either the doc says that message on the final line also carries disposition=<value> and the owned_process_group, terminal_renderer, and temporary_root cleanup states, or the final line carries them as keys. docs/mcp-contracts.md already describes the MCP form of this progress as putting "the lifecycle phase, elapsed time, and final cleanup status in message".

Supporting evidence

Reproduction:

Save this scenario as scenario.json: {"executable":"/bin/sleep","arguments":["1"],"timeout_ms":10000}.
Run npx -y rea-agents@6.4.0 capture-process "$PWD/scenario.json" --json 2> progress.ndjson > result.json.
Read the last rea_progress line of progress.ndjson.
For a cancelled run, in a new directory run npm install --no-save --no-package-lock rea-agents@6.4.0, save {"executable":"/bin/sleep","arguments":["10"],"timeout_ms":30000} as scenario.json, then run ./node_modules/.bin/rea capture-process "$PWD/scenario.json" --json 2> progress.ndjson > result.json & P=$!; sleep 3; kill -INT $P; wait $P; echo $? and read the last line of progress.ndjson.

Step 2 exited 0 and ended with:

{"rea_progress":{"phase":"cleanup","completed":0,"total":null,"message":"elapsed_ms=2180 frames=0 samples=0 interactions=0 disposition=exited owned_process_group=cleaned terminal_renderer=cleaned temporary_root=cleaned","terminal":true,"sequence":13}}

Step 4 exited 130, wrote a cancelled error to stdout, and ended with:

{"rea_progress":{"phase":"cleanup","completed":1,"total":null,"message":"elapsed_ms=2625 frames=0 samples=1 interactions=0 disposition=cancelled owned_process_group=cleaned terminal_renderer=cleaned temporary_root=cleaned","terminal":true,"sequence":20}}

Source at the rea-agents-6.4.0 tag and on main:

formatProgressMessage in src/process/capture/ProcessCaptureProgress.ts appends disposition=… and the three cleanup states to the message string.
The shared ProgressUpdate in src/application/ProgressReporter.ts has only phase, completed, total, message, and terminal.
tests/boundary/process/processCaptureProgress.test.ts parses disposition= and the cleanup states out of message, so the tests pin the message-text form.

Workaround: parse disposition= and the cleanup states from the final line's message.

Additional context

Related: #1252 (the feature request) and #1483 (the PR that added capture progress). I found no existing issue or PR about this wording.

Originally created by @coygeek on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3052 ### Before submitting - [x] I searched the existing issues for a related documentation report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Documentation location [docs/process-capture.md#progress](https://github.com/morluto/rea/blob/e049ef70f71aeb9965e9d75d4d4a84ea02eaee11/docs/process-capture.md#L158-L167) (lines 161-164; lines 72-75 at the `rea-agents-6.4.0` tag, same wording) ### Problem The Progress section says the final `rea_progress` line from `capture-process` "uses `phase` `cleanup`, sets `terminal` to true, and adds `disposition` (`exited`, `timeout`, `idle_timeout`, `cancelled`, or `failed`) plus the owned-process, renderer, and temporary-root cleanup states." Read beside the `phase`, `completed`, `total`, and `terminal` keys the same paragraph documents, this reads as added keys on the final line. The preceding sentence says only that "`message` reports elapsed time and those counts". The emitted final line has no `disposition` key and no cleanup-state keys. Its keys are `phase`, `completed`, `total`, `message`, `terminal`, and `sequence`; the disposition and cleanup states appear only as `key=value` text inside `message`. A JSON consumer that follows the doc and reads `rea_progress.disposition` gets nothing. Capture, cleanup, and stdout output are unaffected. Tested with `rea-agents` 6.4.0 from npm (latest dist-tag, commit `a56f7bb668ab23fec8d33f7af353ac7ed2fe1895`) on macOS 27.0 arm64, Node 26.10.0, npm 12.2.0. `main` at `e049ef70f71aeb9965e9d75d4d4a84ea02eaee11` has the same doc wording and the same message formatting in source (inspected, not run). ### Expected content The documented final-line shape should match the emitted line: either the doc says that `message` on the final line also carries `disposition=<value>` and the `owned_process_group`, `terminal_renderer`, and `temporary_root` cleanup states, or the final line carries them as keys. `docs/mcp-contracts.md` already describes the MCP form of this progress as putting "the lifecycle phase, elapsed time, and final cleanup status in `message`". ### Supporting evidence Reproduction: 1. Save this scenario as `scenario.json`: `{"executable":"/bin/sleep","arguments":["1"],"timeout_ms":10000}`. 2. Run `npx -y rea-agents@6.4.0 capture-process "$PWD/scenario.json" --json 2> progress.ndjson > result.json`. 3. Read the last `rea_progress` line of `progress.ndjson`. 4. For a cancelled run, in a new directory run `npm install --no-save --no-package-lock rea-agents@6.4.0`, save `{"executable":"/bin/sleep","arguments":["10"],"timeout_ms":30000}` as `scenario.json`, then run `./node_modules/.bin/rea capture-process "$PWD/scenario.json" --json 2> progress.ndjson > result.json & P=$!; sleep 3; kill -INT $P; wait $P; echo $?` and read the last line of `progress.ndjson`. Step 2 exited 0 and ended with: ```json {"rea_progress":{"phase":"cleanup","completed":0,"total":null,"message":"elapsed_ms=2180 frames=0 samples=0 interactions=0 disposition=exited owned_process_group=cleaned terminal_renderer=cleaned temporary_root=cleaned","terminal":true,"sequence":13}} ``` Step 4 exited 130, wrote a `cancelled` error to stdout, and ended with: ```json {"rea_progress":{"phase":"cleanup","completed":1,"total":null,"message":"elapsed_ms=2625 frames=0 samples=1 interactions=0 disposition=cancelled owned_process_group=cleaned terminal_renderer=cleaned temporary_root=cleaned","terminal":true,"sequence":20}} ``` Source at the `rea-agents-6.4.0` tag and on `main`: - `formatProgressMessage` in `src/process/capture/ProcessCaptureProgress.ts` appends ` disposition=…` and the three cleanup states to the `message` string. - The shared `ProgressUpdate` in `src/application/ProgressReporter.ts` has only `phase`, `completed`, `total`, `message`, and `terminal`. - `tests/boundary/process/processCaptureProgress.test.ts` parses `disposition=` and the cleanup states out of `message`, so the tests pin the message-text form. Workaround: parse `disposition=` and the cleanup states from the final line's `message`. ### Additional context Related: #1252 (the feature request) and #1483 (the PR that added capture progress). I found no existing issue or PR about this wording.

bsakaguchi

2026-10-15 18:30:48 +00:00