* feat(diagnostics): report a byte entropy profile for one local file
The diff adds the MCP tool inspect_byte_entropy and the CLI command
inspect-byte-entropy, both implemented by ByteEntropyService. One
absolute regular file is read offline into observed Evidence: file-wide
SHA-256 and Shannon entropy, then fixed blocks and adjacent runs for an
optional window, using a power-of-two block size from 256 to 65536
(default 4096), with high at 7.2 or above and low at 1.0 or below. A
window past EOF, a missing path, or a non-file is an input error; a size
or identity change during the read is an artifact-changed error; empty
input reports entropy 0; cancellation is honored before and during the
read. Summary detail retains the complete series and returns file
entropy, counts, and the ten longest runs for inspect_analysis_view,
while the registered effect remains read-only Evidence and the
diagnostics docs record the operation and its errors.
* fix(diagnostics): flag zero-size files as not shown empty
Generated files such as Linux /proc entries report size 0 while holding
content, so inspect_byte_entropy read nothing and returned an empty-looking
report. A file that reports size 0 now carries a limitation that the result
does not show the file is empty. The result stays a success because the
tool reads the declared size, which the file-stability checks depend on.
* fix(mcp): reject unsupported diagnostic summaries before inspection
* fix(ci): repair integrated checks and Hopper test baseline
* test(entropy): use shared MCP schema verification after merge
* fix(catalog): list inspect_byte_entropy under its own provider
Adding inspect_byte_entropy to BINARY_DIAGNOSTICS_TOOL_CONTRACTS put it
under pwntools-elf in the generated product catalog, because the
pwntools group took every binary diagnostics tool except
inspect_pe_resources. The service reports provider byte-entropy.
Add a BYTE_ENTROPY_PROVIDER identity beside PE_RESOURCES_PROVIDER, use
it in ByteEntropyService, give it its own catalog group, and name the
pwntools tools (inspect_binary_layout, inspect_recorded_crash)
explicitly so a new diagnostics tool is not attributed to pwntools by
default. The catalog test pins both groups.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KFTE4BHbGYzgf8Uhzcppdh
* fix(cli): resolve the byte-entropy path with absoluteCallerPath
main replaced the node:path resolve import in binaryDiagnosticsCommands.ts
with absoluteCallerPath (#4067), so the byte-entropy command's
resolve(args.path) no longer type-checks once the PR is merged with main.
Use absoluteCallerPath like the other commands, and add
src/filesystem/callerPath.ts matching main so the branch builds on its own.
* fix(diagnostics): retain entropy read cleanup ownership
* docs(diagnostics): explain entropy output capacity
* fix(diagnostics): preserve entropy cancellation outcomes
* fix(diagnostics): close the entropy input and warn on large reports
Public inspect_byte_entropy input now uses publicInputStrictObject before
detail is added, so unknown keys stay rejected on the advertised schema.
The tool description warns that complete output can become very large and
points callers to a shorter length or a larger block_size.
Co-authored-by: morluto <morluto@users.noreply.github.com>
* fix(diagnostics): keep byte-entropy registration mergeable with main
Register inspect_byte_entropy beside layout inspection and reject
unretained summaries before the file read, without editing workflows.
Co-authored-by: morluto <morluto@users.noreply.github.com>
* fix(diagnostics): register byte entropy with the shared tool options
Use toolRegistrationOptions so the handler typechecks on this branch and
on main, and still refuse unretained summaries before the file read.
Co-authored-by: morluto <morluto@users.noreply.github.com>
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: morluto <morluto@users.noreply.github.com>
Teach client deadline recovery before REA results can be discarded, distinguish
producer-owned server budgets, and preserve Evidence/cleanup uncertainty.
Include actual Codex CLI recovery probes and CLI/MCP regression coverage.
Fixes#5598
Assisted-by: Kogasa (gensokyo-skills:kogasa-surprise-testing)
Replace the superseded fixed 64 MiB process-input refusal with the shared reader diagnostic and recovery text. Restore CSV field boundaries in the adjacent import-limit catalogue entry.
Refs #5077. Verification is source consistency and CSV parsing, without a new large-file runtime claim.
Add shared, typed input-contract and timeout-state recovery guidance. Normalize SDK input failures within the actual MCP wire budget, preserve full diagnostics and protocol metadata, and retain original Evidence when normalized delivery would exceed the budget.
Fixes#5431.
* feat(native): search analyzed memory for masked byte patterns
The diff adds search_bytes to the CLI, the shared MCP contract, Ghidra
inventory, and the headless bridge, and advertises the same operation on
Hopper as unavailable until that provider is verified. Patterns are
hexadecimal byte pairs with optional ?? wildcards and an optional
equal-length bit mask; the TypeScript boundary and the bridge both
require a nonempty pattern, equal lengths, and at least one constrained
bit. Ghidra walks initialized blocks in address order within inclusive
bounds, keeps overlapping matches inside a single block, and returns
each hit with its segment, unique source file offset, and containing
procedure, continuing through a cursor bound to the target, profile,
pattern, mask, and bounds. Each page reports the inclusive ranges
examined and the skipped uninitialized blocks; cancellation returns a
typed error and discards the active Ghidra database.
address_to_file_offset now uses the same unique-offset helper, which
rejects a mapping that is missing, ambiguous, or larger than a safe
integer.
* fix(native): limit unbounded byte search to loaded memory
Without start or end, search_bytes walked every Ghidra block, including
non-loaded file parts such as .symtab and overlay blocks, which the docs
call out of scope. Unbounded searches now skip those blocks and list them
in searched.skipped_not_loaded; explicit bounds in their address space
still search them. Document that a match must end at or before end.
* fix(native): preserve implicit address spaces in range consumers
* fix(native): reject present malformed byte search state
---------
Co-authored-by: Matt Van Horn <455140+mvanhorn@users.noreply.github.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
* fix(scripts): defer dist/ imports in verifier helpers so test:fast runs without build
Two helpers under scripts/lib/ reached into ../../dist/ at module load even
though the top-level import was only needed by one of their exports. That
turned mocked, dist-free tests into failing tests under `npm run test:fast`,
which docs/testing.md § test scripts explicitly promises runs "without build":
- tests/conformance/providers/hopper/realHopperSemantic.test.ts only calls
requireCurrentDocument and resolveFixtureProcedure (both mock-only), but
scripts/lib/real-hopper-semantic.mjs eagerly imported
requireFunctionDossierOracle from dist/application/RealHopperAssertions.js.
Moved the dist-dependent dossier oracle into a lazy loader called from
verifyRealHopperFixture, which is where it is actually used (against the
real Hopper bridge, after build:cached).
- tests/evaluation/package/packagePlatformDiagnostics.test.ts only uses
assertLinuxPackageProviderFailure, which depends on `json`, but
scripts/lib/verify-package-core.mjs eagerly re-exported helpers from
mcp-verifier-results.mjs, which in turn pulls four dist/ modules. Moved
that import into verifyCompleteToolCatalog (the only consumer in this
file). Downstream scripts (verify-recorded-crash.mjs, verify-package-mcp.mjs,
verify-windows-package.mjs) are unaffected because they already run after
build:cached.
Reproduction before fix:
rm -rf dist && npm run test:fast → 2 failed (both import-time errors)
Reproduction after fix:
rm -rf dist && npm run test:fast → 388 passed, 4924 tests, 0 failed
npm run build:cached && npm run test:fast → 388 passed, 4924 tests, 0 failed
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
* fix(install): orient Node.js version mismatch failures with actionable remediation
install.sh previously told operators "use Node.js 22.x (>=22.19), 24.x (>=24.11),
or 26+" without saying how to install one. The curl|bash onboarding path then
left the operator to guess between nvm, fnm, n, Volta, system packages, or
nodejs.org — a lookup that bounces across search engines for a first-time user.
Replace the one-line failure with a block that:
- Names the detected Node.js version (so the operator confirms it is theirs).
- Shows the three most common install paths (nvm, fnm, direct tarball).
- Pins the Node.js release line (24) that satisfies the engine, so copy-paste
commands produce a supported runtime instead of whichever "latest" is on top.
- Maps uname -m / uname -s to the Node.js tarball label pair for this host
(e.g. darwin/arm64, linux/x64), so the operator can grab the right archive
from https://nodejs.org/dist/latest-v24.x/ without a second lookup.
Verified with four Node.js versions (24.18 compatible, 25.9/20.11 outside the
supported ranges, 22.18 below the minor floor) that remediation triggers only
on real mismatches and names the host labels correctly. shellcheck install.sh
and npm run check:fast remain clean.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
* fix(errors): stop recommending retries for non-retryable failures
Unreadable output and provider adapter failures project retryable=false,
but their standard message and remediation said "Retry once", so a
firmware run whose expected report was never published told callers to
repeat a non-retryable operation. Point those failures at `rea doctor`
and the reported details instead, leaving retryability decided once by
the projected error code.
Fixes#1855
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(errors): align Hopper remote failure guidance with retryability
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Align the documented tool inventory, setup client matrix, supported hosts, installation behavior, and roadmap with the 1.6.0 implementation.
Record Ghidra as the accepted next read-only provider direction without claiming shipped support, and refresh the provider admission criteria around evidence fidelity and local diagnostics.
Regenerate the committed TypeDoc site from current sources so package metadata and Process Capture v4 contracts replace the stale 1.1.0/v3 output. Add localized README coverage for every detected setup client.
