Repository navigation
Introduce the task-first Observer CLI v3 - #143
Merged
Merged
Conversation
Changes: - Specify the five command families, stateless target selection, and 15-second default check. - Define stable measurements, the v2 response, finding exit policy, and explicit escalation boundaries. - Record migration mappings, acceptance stories, and deferred scope without claiming implementation or release. Validation: - Rechecked the clean 9682931 worktree baseline and existing runtime/toolchain configuration. - Ran git diff --check successfully. - Runtime verification is deferred until the v3 implementation is available; this commit changes documentation only.
Changes: - Replace the public command inventory with check, inspect, trace, tui and incremental offline discovery. - Resolve atomic targets from explicit options or process environments without shipping saved-context operations. - Reuse bounded capture workers with focused 15-second observations, stable current/change/rate semantics and typed follow-up selectors. - Publish the v2 response, separate findings from execution exits, require state/trace/code-loading consent and preserve redaction boundaries. - Update the bundle and target protocol to 3.0.0 and 2, generate public schemas from capture facts and registry definitions, and migrate regression tests. Validation: - Passed 875 EUnit tests on OTP 29 and the latest 16 focused public-contract/report tests. - Passed compile, lint, xref and Dialyzer with the CI profile before the final presentation-only unit-label adjustment. - Passed isolated Rebar and Mix agent workflows, including default/focused checks, selectors, state, supervision, ports, tracing and log safety. - Validated 47 actual responses plus 97 capture fixtures with negative and schema-unit mutation checks. - Built OTP 26-29 escripts; OTP 26 remote text/term and JSON preflight and OTP 27-29 JSON workflows passed. - Ran formatting and git diff --check successfully; production deployment, release publication and first-time-human usability testing were not performed.
Changes: - Describe timeout margins, state/trace minima, schema-export format requirements and conditional application-observation risk in offline discovery. - Show accepted timing bounds in generated command help without adding another command definition source. - Verify fixed byte-rate presentation and preserve explicit redaction in recommended follow-up arguments. Validation: - Passed 18 focused parser, target, result and terminal-report tests. - Passed CI-profile compile, lint, xref and Dialyzer. - Verified schema generation has no drift against the public registry. - Ran formatting and git diff --check successfully.
Changes: - Render normalized MFA metadata as module:function/arity rather than escaped Erlang map dumps. - Give selected process and port details a focused summary instead of the list-command description. - Preserve the validated data, identifiers, redaction policy and evidence envelope. Validation: - Inspected the owned-node terminal walkthrough for help, overview, process detail and scheduler evidence. - Passed 18 focused contract/report tests and CI-profile compile, lint, xref and Dialyzer. - Rebuilt the escript and confirmed generated schemas have no drift.
Changes: - Replace session-oriented guides with check-to-inspect recipes, fixed measurement meanings and explicit target/consent boundaries. - Document the unreleased 3.0.0 migration, v2 envelopes, finding exits, sharing policy and unchanged TUI pages. - Exercise owned EPMD/nodes, Unicode cookies, 15-second checks, focused evidence, typed selectors, logs, state, supervision, ports and tracing. - Upgrade schema fixtures, negative checks, packaging assertions and CI schema-drift validation; ignore local validation artifacts. - Keep release and installer metadata ready for a future versioned publication without publishing or deploying anything. Validation: - Passed the isolated Rebar and Mix workflows and terminal walkthrough using generated test credentials and owned local nodes. - Validated 97 fixture responses and 47 actual agent responses, rejecting 1096 and 516 negative cases plus schema-unit mutations. - Passed escript help/error/consent smoke and TUI stdin-EOF cleanup. - Built OTP 26-29 escripts; validated OTP 26 remote text/term and preflight rejection and OTP 27-29 JSON workflows. - Built the OTP 29 / Elixir 1.20.4 Mix escript and release; verified schema packaging, bundle 3.0.0 and crypto startup. - Passed shell syntax, Python syntax, formatting, generated-schema drift and git diff checks. - Hosted CI, publication, production access and a first-time-human usability study were not performed.
Changes: - Apply canonical target-local PID validation to trace call before credential or connection work. - Reject redacted aliases, registered names, nonlocal PIDs, and malformed selectors without weakening target-side authorization. Validation: - mise exec -- rebar3 as test eunit --module=observer_cli_input_test: 9 tests passed. - mise exec -- rebar3 fmt --check: passed.
Changes: - Use the two inventory start timestamps for network and socket rate denominators. - Exclude the extra trailing scan time that understated observed counter rates. - Add a deterministic scan-cost regression with a 6-second counter interval. Validation: - rebar3 as test eunit --module=observer_cli_socket_test,observer_cli_inet_test: 64 tests passed. - rebar3 fmt --check and git diff --check passed.
Changes: - Accept the normal interactive quit result and propagate connection failures. - Treat unexpected TUI return values as internal errors instead of exit-zero success. Validation: - Ran rebar3 fmt successfully. - Ran the focused tui_result_preserves_failures_test: 1 test, 0 failures. - Ran git diff --check successfully.
Changes: - Render leaf, family, and full describe results through the existing complete text encoder. - Preserve all registry constraints, authorization, and risk metadata while keeping the default index concise. Validation: - Ran mise exec -- rebar3 fmt successfully. - Ran focused observer_cli_result_test EUnit: 8 tests, 0 failures. - Ran git diff --check for the changed files successfully.
Changes: - Run owned smoke nodes and commands with temporary HOME, configuration, and crash-dump paths. - Clear inherited Erlang VM flags, library paths, and default target credentials while retaining the explicit binary override. Validation: - sh -n scripts/escript-smoke.sh and git diff --check passed. - All 17 existing shell smoke cases passed against the built escript, including TUI EOF cleanup. - An adversarial wrapper injected invalid VM flags, target settings, and an invalid outer cookie; smoke passed and outer HOME/configuration sentinels remained unchanged. - The wrapper stubbed only rebar3 escriptize to avoid concurrent shared build writes; this commit does not change Erlang source.
Changes: - Share a ten-second deadline across connection, capability probes, and explicit remote module loading. - Replace unbounded loading calls with timeout-aware code loading and preserve runtime failure classification. - Bound the network tick-time setup probe to five seconds while retaining unlimited interactive duration. - Remove a stale cross-OTP assertion that exercised the removed distributed-controller path rather than loading consent. Validation: - Ran rebar3 fmt and git diff --check successfully. - Ran three focused EUnit tests with an owned EPMD and disposable peer nodes: 3 tests, 0 failures. - Verified a suspended remote code server cannot hang setup, explicit remote loading still succeeds, and TUI failures remain failures.
Changes: - Validate help and version options instead of silently emitting successful text for JSON requests or invalid formats. - Reject ignored target and execution options on help routes and direct machine clients to describe. - Document the text-only offline helper contract and preserve ordinary help and version invocations. Validation: - mise exec -- rebar3 fmt: passed. - mise exec -- rebar3 as test eunit --module=observer_cli_input_test: 10 tests passed. - git diff --check: passed.
Changes: - Validate target-local PID and port selectors with runtime round trips before target access. - Reject leading-zero spellings and numeric components outside runtime representation without hardcoding OTP bounds. - Cover process details, state reads, tracing, and port details with canonical selector regressions. Validation: - mise exec -- rebar3 fmt: passed. - mise exec -- rebar3 as test eunit --module=observer_cli_input_test,observer_cli_target_test: 14 tests passed. - git diff --check: passed.
Changes: - Recognize trace call help after a supplied MFA instead of treating the MFA as part of the command path. - Cover both the help flag and the help subcommand without requiring trace authorization. Validation: - mise exec -- rebar3 fmt --check: passed. - mise exec -- rebar3 as test eunit --module=observer_cli_input_test,observer_cli_target_test: 15 tests passed. - git diff --check: passed.
Changes: - Project executable PID selectors for current process, activity, and binary-holder check evidence. - Project selectors in VM process and port inventories, with null selectors under redaction. - Extend public evidence schema definitions without changing the private target wire format. Validation: - Ran mise exec -- rebar3 fmt successfully. - Ran focused observer_cli_result_test EUnit: 9 tests, 0 failures. - Passed schema generator drift, Python syntax, and changed-file diff checks.
Changes: - Avoid allocator attribution suggestions when no current memory evidence exists. - Suggest peer and network follow-up only when their source context was measured, preserving valid empty and zero observations. - Keep missing-evidence partial results explicit instead of supplying a generic investigation checklist. Validation: - Ran mise exec -- rebar3 fmt successfully after correcting a local compile typo. - Ran focused observer_cli_result_test EUnit: 10 tests, 0 failures. - Ran changed-file git diff --check successfully.
Changes: - Split overlong unbroken words on Unicode codepoint boundaries before applying the 24-line check-report limit. - Preserve full target identifiers while ensuring long ASCII node names do not overflow an 80-column report. - Add dedicated ASCII, multibyte UTF-8, and crowded-report regressions without adding a display-width dependency. Validation: - Compiled the presenter and dedicated test module into memory in an isolated Erlang VM; both EUnit tests passed without shared build writes. - mise exec -- rebar3 fmt --check and scoped git diff --check passed. - Terminal-cell width for wide Unicode glyphs is not claimed; the wrapper preserves Unicode codepoints.
Changes: - Delete the TEST-only context file reader, writer, migration helpers, and connect/status/disconnect executor. - Remove obsolete saved-context text rendering while preserving live cookie and connection error safeguards. - Exercise v3 offline discovery and legacy-file noninterference directly, retaining credential file and collector coverage. Validation: - Formatted the four changed Erlang files with rebar3 fmt. - Ran focused capture and escriptize EUnit suites: 146 tests passed, 0 failures. - Ran git diff --check successfully. - Full-suite and packaging verification are deferred to the coordinated integration pass.
Changes: - Count non-ASCII codepoints as two terminal columns for wrapping and long-token splitting without a new dependency. - Document that this is a safe width bound rather than exact wcwidth, so accents and combining sequences may wrap early. - Extend screen-budget regressions with wide CJK and combining-character tokens while preserving all codepoints. Validation: - Compiled the presenter and width-test module into memory in an isolated Erlang VM; all 3 focused EUnit tests passed. - Scoped rebar3 fmt --check and git diff --check passed; a whole-tree format check encountered an unrelated concurrent edit in observer_cli_diagnostic_test.erl. - Tests verify the conservative 80-column bound, the 24-line limit, valid UTF-8, and lossless long-token reconstruction.
Changes: - Render port memory, queue size, input, and output with existing byte formatting. - Preserve unavailable readings and keep process identifiers and count fields unitless. - Leave inventory output and nested evidence unchanged. Validation: - Formatted both changed files with the existing erlfmt API and passed git diff --check. - Compiled changed source/tests in memory and ran result plus width EUnit suites: 14 tests passed. - Did not rebuild shared artifacts to avoid other agents concurrent build work.
Changes: - Evaluate calibrated rules from their valid evidence rather than suppressing every finding after an unrelated sample or memory failure. - Keep execution partial and retain original sample indices while pointing into the compacted evidence array. - Add sampling-gap, memory-failure and evidence-pointer regressions. Validation: - Focused diagnostic, snapshot, socket, inet and scan-budget EUnit suites passed: 171 tests, 0 failures. - rebar3 fmt --check and git diff --check passed. - Full integration validation remains assigned to the parent review task.
Changes: - Recheck process and counter inventory counts before every sample, including the second window endpoint. - Cap process iteration callbacks and reject oversized network or socket enumerations before querying resources. - Derive retained-series limits from existing scan and working-set budgets and preserve structured budget refusals. - Add regressions for count growth, enumeration races and callback limits without introducing a scan framework. Validation: - Focused diagnostic, snapshot, socket, inet and scan-budget EUnit suites passed: 171 tests, 0 failures. - rebar3 fmt --check and git diff --check passed. - Enumeration APIs can still allocate their identifier list before rejection; worker heap and deadline limits remain the backstop.
Changes: - Record monotonic start and finish timestamps around the memory probe. - Use the existing inventory midpoint logic instead of timestamps from earlier VM-limit probes for memory rates. - Add producer audit and delayed-memory interval regression coverage without expanding the public schema. Validation: - Focused diagnostic, snapshot, socket, inet and scan-budget EUnit suites passed: 171 tests, 0 failures. - rebar3 fmt --check and git diff --check passed.
Changes: - Classify exceptions after trace dispatch as cleanup uncertainty instead of ordinary runtime failure. - Preserve ordinary runtime classification for read-only dispatch failures and retain pre-dispatch timeout behavior. - Add an isolated peer regression for a dispatcher that fails without a cleanup acknowledgement. Validation: - Ran rebar3 fmt and git diff --check successfully. - Ran observer_cli_lifecycle_test with an owned EPMD and disposable peer: 1 test, 0 failures. - Verified trace uncertainty produces exit code 4 while read-only dispatch failure keeps its existing classification.
Changes: - Align the shared process-inventory audit enum with the actual bounded fallback emitted on OTP 26 and 27. - Remove the obsolete processes_list value rather than retaining an unused compatibility alias. - Regenerate the standalone public schema from the corrected private fact schema. Validation: - Built commit a5870c5 in an isolated OTP 27.3.4.2-4 scratch archive and passed the full required-JSON agent workflow. - Validated all 47 emitted OTP 27 responses against the corrected public schema and rejected 516 negative cases plus 14 schema-unit mutations. - Schema generation drift check and scoped git diff --check passed. - Packaging revalidation awaits rebuilding the escript with the corrected embedded schema.
Changes: - Declare the normal local TUI completion as quit instead of excluding all successful returns. - Describe remote-capable start overloads as RPC result boundaries so callers can reject unexpected replies. - Preserve fail-closed TUI outcome validation without suppressing static analysis warnings. Validation: - Full CI-profile compile, lint, xref, and Dialyzer passed after the specification correction. - Full EUnit reported 891 tests with 0 failures, including the cross-OTP 26 check; this specification-only edit does not alter runtime behavior. - Ran formatting and git diff --check successfully.
Changes: - Raise and narrowly catch tagged scan-budget errors without changing public refusal semantics. - Update budget regressions and avoid an ambiguous boolean comparison in the TUI test adapter. Validation: - Full isolated OTP 29 EUnit with an owned OTP 26 cross-version peer: 891 tests passed. - rebar3 as ci do compile, lint, xref, dialyzer passed. - rebar3 fmt and git diff --check passed.
Changes: - Run response-schema and Rebar packaging acceptance on OTP 27 and 28 as well as OTP 29. - Keep OTP 26 excluded because JSON output is intentionally unsupported there. - Exercise producer fixtures and real isolated agent responses on each JSON-capable runtime to catch version-specific inventory metadata drift. Validation: - On isolated OTP 27.3.4.2-4, producer-fixture generation passed and all 97 responses validated; 1096 negative cases and 14 schema-unit mutations were rejected. - The OTP 27 full JSON agent workflow passed; all 47 responses validated, rejecting 516 negative cases. - Scoped git diff --check passed. Hosted GitHub Actions has not been run.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Changes: - Register the migration guide as an ExDoc extra and group it with the CLI documentation. - Preserve warnings-as-errors so unresolved documentation links still fail CI. Validation: - mise exec -- rebar3 as ci check passed, including HTML, Markdown and EPUB generation. - Confirmed the migration HTML page exists and README/CLI links resolve to it. - rebar3 fmt --check and git diff --check passed. - EUnit was not rerun for this documentation-configuration-only change; hosted CI will run the full matrix.
Changes: - Keep the README focused on getting started and replace repeated contract prose with reference links. - Shorten design, concepts, agent and migration guides while preserving examples, safety boundaries and acceptance criteria. - Mark only the generated public schema for GitHub review folding; leave its bytes and validation rules unchanged. Validation: - mise exec -- rebar3 as ci check passed, including ExDoc with warnings-as-errors. - Verified 16 local document targets and syntax-checked 9 shell examples. - Generated-schema drift check, rebar3 fmt --check and git diff --check passed. - Confirmed the generated attribute applies only to the public schema. - EUnit was not rerun because only documentation and GitHub presentation attributes changed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Replace the implementation-oriented command inventory with a bounded workflow for people and agents:
check -> inspect -> explicit escalation.check [cpu|memory|mailbox|connections]: 15-second overview, supported findings, evidence, coverage and next steps.inspect RESOURCE: consistent list/detail paths, fixed current/change/rate meanings and typed selectors.trace,tui, offlinedescribe: explicit escalation, unchanged TUI pages, incremental discovery.Breaking changes
observer_cli.cli/v2; controller/target capabilities must match.context.etfaccess. Old paths return migration hints, not compatibility execution.--redact, with non-executable selectors. Logs are not reliably redacted.0unless--fail-onrequests a threshold failure; partial/error/uncertain cleanup takes precedence.--load-codeand the same OTP major.CLI reference · Migration · Agent workflow
Implementation and review
Reuse collectors, validation, budgets, deadlines and cleanup; separate public parsing, target resolution and presentation. Checks share one sampling plan; suggestions are closed argument arrays, never automatic actions. Default checks do not read business contents, logs, state or trace events.
Six adversarial review tracks and cross-review fixed selector preflight, TUI failures/timeouts, trace cleanup uncertainty, sampling time denominators, partial findings/evidence pointers, growing scan budgets, nested selectors, grounded suggestions and cross-OTP schema handling. Obsolete context execution/persistence was removed.
Most added lines are the standalone public schema generated from shared capture definitions, not prose. It is marked generated for review folding, without changing its validation rules. Documentation now assigns exact rules to the CLI reference instead of repeating them across guides.
Validation
303ad10: OTP 26–29 and Mix passed, including ExDoc, EUnit, smoke and applicable schema/packaging checks.rebar3 as ci checkpassed; 16 local link targets and 9 shell blocks verified; schema drift check passed. No behavior, schema or test changes; EUnit was not rerun for this docs/attributes-only edit. Latest-head CI runs independently.Boundaries
Older enumeration APIs may allocate identifier lists before a post-enumeration cap; per-resource work, retained samples and worker heap/deadline remain bounded. Unicode wrapping is conservative and may wrap early. Tests are not production-load benchmarks, new-user studies or proof of zero defects.
Deferred: TUI redesign, named targets, daemon/MCP, automatic actions, aggregate concurrency limiting, new root-cause rules and business-content collection. No merge, release publication or deployment is included.