[GH-ISSUE #1165] [Bug] `doctor`, documented as strictly read-only, writes Homebrew caches #410

New issue

Closed

opened 2026-10-15 18:24:50 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:24:50 +00:00

Owner

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

Before submitting

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

Area

Setup, packaging, or upgrade

Observed behavior

docs/installation.md calls rea doctor --json "strictly read-only". On a macOS host without Hopper installed, even a client-scoped rea doctor --client codex --json runs brew --prefix --cask hopper-disassembler as a discovery fallback, and that creates hundreds of files in the user's Homebrew cache. In a fresh trial home the run created 626 files totalling about 36 MB under Library/Caches/Homebrew. No client configuration changed, so this is a mismatch between the read-only promise and observed side effects rather than damage to user settings.

Before doctor: 0 files. After doctor: 626 files, 36,102,869 bytes, for example Library/Caches/Homebrew/api/internal/packages.arm64_golden_gate.jws.json and Homebrew bootsnap files. Doctor itself exits 1 because the trial home has no Codex configuration, which is expected. Reproduced in two fresh trial homes on the npm release and once on the main build, with the same counts. File counts and sizes depend on the host's Homebrew version and cache state.

Reproduction

TRIAL_HOME="$(mktemp -d)"
NPM_CACHE="$(mktemp -d)"
rea_trial() { env -u CLAUDE_CONFIG_DIR -u CODEX_HOME -u COPILOT_HOME -u OPENCODE_CONFIG -u XDG_CONFIG_HOME -u GROK_HOME -u SAND_DATA_ROOT HOME="$TRIAL_HOME" npm_config_cache="$NPM_CACHE" npx -y rea-agents@6.1.0 "$@"; }
rea_trial --version                 # control: creates nothing in TRIAL_HOME
find "$TRIAL_HOME" -type f | wc -l  # 0
rea_trial doctor --client codex --json > /dev/null
find "$TRIAL_HOME" -type f | wc -l
find "$TRIAL_HOME" -type f | head -3

Expected behavior

docs/installation.md says "rea doctor --json is strictly read-only", and its readiness section says doctor "reads host prerequisites and agent configuration without changing them". Under that wording, running doctor should leave no new files in the home directory (npm's runner cache is isolated above).

Impact and scope

The writes are disposable Homebrew caches; client configuration, user data, and doctor's diagnostic result are unaffected, so the defect is an inaccurate read-only claim with no consequential behavior change.

Workaround: No option or environment setting was found that keeps doctor from triggering the Homebrew lookup; deleting the cache files afterwards is a mitigation, not a way to get the promised read-only run.

REA version

rea-agents@6.1.0 from npm, and main at 089bbf58f3 built locally with npm ci && npm run build:cached.

Runtime and platform

Node v24.21.0, macOS 27.0.1 (26A434), arm64, Homebrew installed at /opt/homebrew, Hopper not installed.

Target and artifact context

Not applicable (host diagnostics)

Interface

Package or setup

Earliest failure stage

Setup or provider admission

Relevant output or evidence

Expected source: docs/installation.md, the "strictly read-only" sentence and the readiness section (unchanged on the main build).
Failure source: the before/after file counts quoted under Observed behavior.
Evidence provenance: observed
Local verification: reproduced
Reproduction completeness: complete

Typed outcome or recovery expected

Failing now: the find "$TRIAL_HOME" -type f | wc -l count after doctor is in the hundreds. Restored: the count stays 0 after doctor. Control: doctor still finds a Hopper installed through the Homebrew cask when one exists.

Analysis or suspected cause

Source-derived, not verified by a patch: src/application/DoctorDiagnostics.ts findHopper falls back to a Homebrew lookup, and src/application/Doctor.ts runs brew --prefix --cask hopper-disassembler. The files are written by Homebrew, not by REA's own code.

Additional context

Found while exercising typical REA workflows on macOS with rea-agents@6.1.0; each case was reproduced on the npm release and on a local build of main, and re-checked on main at 6a1e558db3 just before filing.

Originally created by @coygeek on GitHub (Oct 9, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/1165 ### Before submitting - [x] I searched the open and closed issues for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Area Setup, packaging, or upgrade ### Observed behavior `docs/installation.md` calls `rea doctor --json` "strictly read-only". On a macOS host without Hopper installed, even a client-scoped `rea doctor --client codex --json` runs `brew --prefix --cask hopper-disassembler` as a discovery fallback, and that creates hundreds of files in the user's Homebrew cache. In a fresh trial home the run created 626 files totalling about 36 MB under `Library/Caches/Homebrew`. No client configuration changed, so this is a mismatch between the read-only promise and observed side effects rather than damage to user settings. Before doctor: 0 files. After doctor: 626 files, 36,102,869 bytes, for example `Library/Caches/Homebrew/api/internal/packages.arm64_golden_gate.jws.json` and Homebrew bootsnap files. Doctor itself exits 1 because the trial home has no Codex configuration, which is expected. Reproduced in two fresh trial homes on the npm release and once on the `main` build, with the same counts. File counts and sizes depend on the host's Homebrew version and cache state. ### Reproduction ```sh TRIAL_HOME="$(mktemp -d)" NPM_CACHE="$(mktemp -d)" rea_trial() { env -u CLAUDE_CONFIG_DIR -u CODEX_HOME -u COPILOT_HOME -u OPENCODE_CONFIG -u XDG_CONFIG_HOME -u GROK_HOME -u SAND_DATA_ROOT HOME="$TRIAL_HOME" npm_config_cache="$NPM_CACHE" npx -y rea-agents@6.1.0 "$@"; } rea_trial --version # control: creates nothing in TRIAL_HOME find "$TRIAL_HOME" -type f | wc -l # 0 rea_trial doctor --client codex --json > /dev/null find "$TRIAL_HOME" -type f | wc -l find "$TRIAL_HOME" -type f | head -3 ``` ### Expected behavior `docs/installation.md` says "`rea doctor --json` is strictly read-only", and its readiness section says doctor "reads host prerequisites and agent configuration without changing them". Under that wording, running doctor should leave no new files in the home directory (npm's runner cache is isolated above). ### Impact and scope The writes are disposable Homebrew caches; client configuration, user data, and doctor's diagnostic result are unaffected, so the defect is an inaccurate read-only claim with no consequential behavior change. Workaround: No option or environment setting was found that keeps doctor from triggering the Homebrew lookup; deleting the cache files afterwards is a mitigation, not a way to get the promised read-only run. ### REA version `rea-agents@6.1.0` from npm, and `main` at 089bbf58f3561e3f465c544bbcf8c307287b1256 built locally with `npm ci && npm run build:cached`. ### Runtime and platform Node v24.21.0, macOS 27.0.1 (26A434), arm64, Homebrew installed at `/opt/homebrew`, Hopper not installed. ### Target and artifact context Not applicable (host diagnostics) ### Interface Package or setup ### Earliest failure stage Setup or provider admission ### Relevant output or evidence - Expected source: `docs/installation.md`, the "strictly read-only" sentence and the readiness section (unchanged on the `main` build). - Failure source: the before/after file counts quoted under Observed behavior. - Evidence provenance: observed - Local verification: reproduced - Reproduction completeness: complete ### Typed outcome or recovery expected Failing now: the `find "$TRIAL_HOME" -type f | wc -l` count after doctor is in the hundreds. Restored: the count stays 0 after doctor. Control: doctor still finds a Hopper installed through the Homebrew cask when one exists. ### Analysis or suspected cause Source-derived, not verified by a patch: `src/application/DoctorDiagnostics.ts` `findHopper` falls back to a Homebrew lookup, and `src/application/Doctor.ts` runs `brew --prefix --cask hopper-disassembler`. The files are written by Homebrew, not by REA's own code. ### Additional context Found while exercising typical REA workflows on macOS with `rea-agents@6.1.0`; each case was reproduced on the npm release and on a local build of `main`, and re-checked on `main` at 6a1e558db3ec2b69561e91ea817f1c2065dfc676 just before filing.

bsakaguchi

2026-10-15 18:24:50 +00:00