morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[GH-ISSUE #3053] [Docs] CLI exit-status table does not say which commands exit 130 or 143 after a reported cancellation #1068

New issue

Closed

opened 2026-10-15 18:30:48 +00:00 by bsakaguchi · 2 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/3053

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/cli.md#output-and-exit-status (the exit-status table, lines 304-308 on main; lines 211-215 in the 6.4.0 release)

Problem

The "Output and exit status" table names cancellation only under status 1 and describes 128 + N as "Signal N ended the process". It does not say that some commands handle SIGINT and SIGTERM, print a complete structured result with code: "cancelled", finish cleanup, and then exit 130 or 143 on purpose, as the acceptance tests pin. It also does not say that the status after a handled cancellation depends on the command: analyze-javascript-application and analyze exit 130 or 143, while inspect-artifact reports the same cancelled result and exits 1. A script written from the table cannot predict which status a handled cancellation produces, and can read 130 or 143 as the process being killed without a result.

Expected content

The section already lists per-command exceptions below the table (for example, a cancelled setup exits 0). It should equally let a reader predict the status after a handled SIGINT or SIGTERM: that some commands print a complete cancelled result and then exit with a 128 + N status, and which status each kind of command returns. Whatever status the project chooses for commands such as inspect-artifact, the documentation should match what they return.

The table currently reads:

| `1`       | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. |
| `128 + N` | Signal `N` ended the process, where the shell or runtime preserves the conventional signal-derived status.                                           |

Supporting evidence

Runtime or environment

rea-agents 6.4.0 from npm, the current latest dist-tag (tag rea-agents-6.4.0, commit a56f7bb668ab23fec8d33f7af353ac7ed2fe1895)
Current main at e049ef70f71aeb9965e9d75d4d4a84ea02eaee11: the table and src/cli/commandCancellation.ts are unchanged from the release (source read; the main build was not executed)
macOS 27.0 arm64, Node 26.10.0, npm 12.2.0

Steps to reproduce

Install the release into an empty directory: npm install --no-save rea-agents@6.4.0.
Create a directory of 3000 small JavaScript files. In my run, progress showed 36 of 3000 files parsed when the signal arrived at 3 s, so the signal lands mid-run.
Send SIGINT to analyze-javascript-application 3 s into the run and print the exit status; then read the code and details.cleanup fields of out.json.
Repeat step 3 with SIGTERM, and repeat both with rea analyze ./js.
Control: send SIGINT, then SIGTERM, to inspect-artifact on a large app bundle 3 s into the run. Any bundle works if its inspection runs longer than 3 s; a full inspection of /System/Applications/Mail.app finished in under 1 s, too fast for this step.

npm install --no-save rea-agents@6.4.0
mkdir js && for i in $(seq 1 3000); do printf 'export const v%s = %s;\n' $i $i > js/m$i.js; done

# steps 3 and 4 (replace INT with TERM, and analyze-javascript-application with analyze)
./node_modules/.bin/rea analyze-javascript-application ./js --json > out.json & pid=$!
sleep 3; kill -INT $pid; wait $pid; echo "exit=$?"

# step 5
./node_modules/.bin/rea inspect-artifact /Applications/Xcode.app --json > out.json & pid=$!
sleep 3; kill -INT $pid; wait $pid; echo "exit=$?"

Actual behavior

analyze-javascript-application  SIGINT  exit=130  "code":"cancelled", details.cleanup "complete"
analyze-javascript-application  SIGTERM exit=143  "code":"cancelled", details.cleanup "complete"
analyze ./js                    SIGINT  exit=130  "code":"cancelled", details.cleanup "complete"
analyze ./js                    SIGTERM exit=143  "code":"cancelled", details.cleanup "complete"
inspect-artifact Xcode.app      SIGINT  exit=1    "code":"cancelled", details.reason "cancelled"
inspect-artifact Xcode.app      SIGTERM exit=1    "code":"cancelled", details.reason "cancelled"

In an earlier run with the same release and environment, capture-process and observe-web-execution (headless Chrome on a loopback CDP port) also exited 130 for SIGINT and 143 for SIGTERM after a cancelled result; those two were not rerun for this report, and the report does not depend on them.

The 130/143 path is intended, not a crash:

withCommandCancellation in src/cli/commandCancellation.ts (lines 16 and 20, unchanged on main) sets exit code 130 for SIGINT and 143 for SIGTERM after the operation settles.
tests/acceptance/applications/javascriptCancellationCli.test.ts expects exit code 130 with a cancelled result (lines 42 and 87 in the release; lines 61 and 110 on main, where the test now covers more cancellation phases).
inspect-artifact also handles both signals, through withProcessCancellation in src/application/DirectAnalysis.ts (lines 420-436 in the release), which does not set an exit status.

None of this split appears in docs/cli.md.

Restoration check

Failing now: from docs/cli.md alone, a reader cannot predict that steps 3 and 4 return 130 and 143 after a complete cancelled result while step 5 returns 1 after the same kind of result. Restored: docs/cli.md lets a reader predict, for each command in steps 3-5, the exit status after a handled SIGINT or SIGTERM that prints a cancelled result, and states that a 128 + N status can accompany a complete structured result. Step 5 remains the control: whatever status the project chooses for it, the documentation matches what it returns.

Additional context

Impact: low. Every observed case prints a complete structured result with code: "cancelled", and no operation result or cleanup changes. Scripts can treat 130 and 143 as possible cancellation statuses and read the result's code field.
Related: #1126 made observe-web-execution and inspect-web-event-listeners keep the 130/143 status, and open PR #2879 extends the same boundary to more browser and JavaScript-runtime commands. Neither changes docs/cli.md.

Originally created by @coygeek on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3053 ### 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/cli.md#output-and-exit-status (the exit-status table, lines 304-308 on `main`; lines 211-215 in the 6.4.0 release) ### Problem The "Output and exit status" table names cancellation only under status `1` and describes `128 + N` as "Signal `N` ended the process". It does not say that some commands handle SIGINT and SIGTERM, print a complete structured result with `code: "cancelled"`, finish cleanup, and then exit 130 or 143 on purpose, as the acceptance tests pin. It also does not say that the status after a handled cancellation depends on the command: `analyze-javascript-application` and `analyze` exit 130 or 143, while `inspect-artifact` reports the same `cancelled` result and exits 1. A script written from the table cannot predict which status a handled cancellation produces, and can read 130 or 143 as the process being killed without a result. ### Expected content The section already lists per-command exceptions below the table (for example, a cancelled setup exits `0`). It should equally let a reader predict the status after a handled SIGINT or SIGTERM: that some commands print a complete `cancelled` result and then exit with a `128 + N` status, and which status each kind of command returns. Whatever status the project chooses for commands such as `inspect-artifact`, the documentation should match what they return. The table currently reads: ```text | `1` | The operation could not complete. Structured output identifies invalid input, permissions, cancellation, timeouts or another failure when available. | | `128 + N` | Signal `N` ended the process, where the shell or runtime preserves the conventional signal-derived status. | ``` ### Supporting evidence #### Runtime or environment - `rea-agents` 6.4.0 from npm, the current `latest` dist-tag (tag `rea-agents-6.4.0`, commit `a56f7bb668ab23fec8d33f7af353ac7ed2fe1895`) - Current `main` at `e049ef70f71aeb9965e9d75d4d4a84ea02eaee11`: the table and `src/cli/commandCancellation.ts` are unchanged from the release (source read; the `main` build was not executed) - macOS 27.0 arm64, Node 26.10.0, npm 12.2.0 #### Steps to reproduce 1. Install the release into an empty directory: `npm install --no-save rea-agents@6.4.0`. 2. Create a directory of 3000 small JavaScript files. In my run, progress showed 36 of 3000 files parsed when the signal arrived at 3 s, so the signal lands mid-run. 3. Send SIGINT to `analyze-javascript-application` 3 s into the run and print the exit status; then read the `code` and `details.cleanup` fields of `out.json`. 4. Repeat step 3 with SIGTERM, and repeat both with `rea analyze ./js`. 5. Control: send SIGINT, then SIGTERM, to `inspect-artifact` on a large app bundle 3 s into the run. Any bundle works if its inspection runs longer than 3 s; a full inspection of `/System/Applications/Mail.app` finished in under 1 s, too fast for this step. ```bash npm install --no-save rea-agents@6.4.0 mkdir js && for i in $(seq 1 3000); do printf 'export const v%s = %s;\n' $i $i > js/m$i.js; done # steps 3 and 4 (replace INT with TERM, and analyze-javascript-application with analyze) ./node_modules/.bin/rea analyze-javascript-application ./js --json > out.json & pid=$! sleep 3; kill -INT $pid; wait $pid; echo "exit=$?" # step 5 ./node_modules/.bin/rea inspect-artifact /Applications/Xcode.app --json > out.json & pid=$! sleep 3; kill -INT $pid; wait $pid; echo "exit=$?" ``` #### Actual behavior ```text analyze-javascript-application SIGINT exit=130 "code":"cancelled", details.cleanup "complete" analyze-javascript-application SIGTERM exit=143 "code":"cancelled", details.cleanup "complete" analyze ./js SIGINT exit=130 "code":"cancelled", details.cleanup "complete" analyze ./js SIGTERM exit=143 "code":"cancelled", details.cleanup "complete" inspect-artifact Xcode.app SIGINT exit=1 "code":"cancelled", details.reason "cancelled" inspect-artifact Xcode.app SIGTERM exit=1 "code":"cancelled", details.reason "cancelled" ``` In an earlier run with the same release and environment, `capture-process` and `observe-web-execution` (headless Chrome on a loopback CDP port) also exited 130 for SIGINT and 143 for SIGTERM after a `cancelled` result; those two were not rerun for this report, and the report does not depend on them. The 130/143 path is intended, not a crash: - `withCommandCancellation` in `src/cli/commandCancellation.ts` (lines 16 and 20, unchanged on `main`) sets exit code 130 for SIGINT and 143 for SIGTERM after the operation settles. - `tests/acceptance/applications/javascriptCancellationCli.test.ts` expects exit code 130 with a `cancelled` result (lines 42 and 87 in the release; lines 61 and 110 on `main`, where the test now covers more cancellation phases). - `inspect-artifact` also handles both signals, through `withProcessCancellation` in `src/application/DirectAnalysis.ts` (lines 420-436 in the release), which does not set an exit status. None of this split appears in `docs/cli.md`. #### Restoration check Failing now: from `docs/cli.md` alone, a reader cannot predict that steps 3 and 4 return 130 and 143 after a complete `cancelled` result while step 5 returns 1 after the same kind of result. Restored: `docs/cli.md` lets a reader predict, for each command in steps 3-5, the exit status after a handled SIGINT or SIGTERM that prints a `cancelled` result, and states that a `128 + N` status can accompany a complete structured result. Step 5 remains the control: whatever status the project chooses for it, the documentation matches what it returns. ### Additional context - Impact: low. Every observed case prints a complete structured result with `code: "cancelled"`, and no operation result or cleanup changes. Scripts can treat 130 and 143 as possible cancellation statuses and read the result's `code` field. - Related: #1126 made `observe-web-execution` and `inspect-web-event-listeners` keep the 130/143 status, and open PR #2879 extends the same boundary to more browser and JavaScript-runtime commands. Neither changes `docs/cli.md`.

bsakaguchi

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

closed this issue
added the
bug

documentation
labels

bsakaguchi commented

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

Author

Owner

@IvenKooLab commented on GitHub (Oct 14, 2026):

I'd like to take this one. The behavior is reproducible on current main: analyze ./js exits 130 after SIGINT and 143 after SIGTERM with a complete code: "cancelled" result and completed cleanup, while inspect-artifact reports code: "cancelled" as a structured failure and exits 1. Plan: extend the 128 + N row for handled signals and add the per-command cancellation statuses next to the existing setup/doctor exceptions.

@IvenKooLab commented on GitHub (Oct 14, 2026): I'd like to take this one. The behavior is reproducible on current main: `analyze ./js` exits 130 after SIGINT and 143 after SIGTERM with a complete `code: "cancelled"` result and completed cleanup, while `inspect-artifact` reports `code: "cancelled"` as a structured failure and exits 1. Plan: extend the `128 + N` row for handled signals and add the per-command cancellation statuses next to the existing setup/doctor exceptions.

bsakaguchi commented

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

Author

Owner

@morluto commented on GitHub (Oct 14, 2026):

Delivered on main in fffb07419.

CLI status documentation conflated signal termination with completed structured cancellation. It now describes command-specific completed cancellation statuses and inspect-artifact behavior.

Validation: Documentation consistency checks and CLI cancellation workflows. Full exact-revision qualification passed.

@morluto commented on GitHub (Oct 14, 2026): Delivered on main in [fffb07419](https://github.com/morluto/rea/commit/fffb0741936067530d1ce9777461cd53e87398c2). CLI status documentation conflated signal termination with completed structured cancellation. It now describes command-specific completed cancellation statuses and inspect-artifact behavior. Validation: Documentation consistency checks and CLI cancellation workflows. Full exact-revision [qualification](https://github.com/morluto/rea/actions/runs/38629313022) passed.

bsakaguchi referenced this issue

2026-10-17 21:08:16 +00:00

[PR #1068] [MERGED] fix(cli): preserve blank JSON paths for input validation #2617

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#1068

No description provided.

Rows
Columns