[aaltshuler]

What & why

CLI handlers currently terminate the process, the query family lives in the main dispatcher, and successful reads reload operator preferences after execution. This change makes the application callable without process exit, gives query / mutate / alias their own argument and execution module, and captures read presentation with the configuration used for execution.

The one intentional presentation change is that captured operator/alias JSON or JSONL defaults now apply to structured execution errors too. Explicit formats still win; errors before successful configuration/alias capture use argv preferences, mutations still require explicit --json, and unstructured read transport errors stay on stderr. Query and mutation renderers use fallible writers, and output/flush failures retain the original mutation evidence.

Backing issue / RFC

• Implements and preserves the current operator contracts in RFC 0007 and RFC 0011.
• RFC 0059 (rfc: named targets and CLI coherency #675) is design context, still draft. This does not introduce its proposed targeting grammar.

Checklist

• Focused application/query-family boundary; no new CLI flags or dependencies.
• Existing config-swap regressions extended; application re-entry, typed preparation and fallible presentation tested.
• Public/developer docs and permanent changelog note updated.
• Reviewed against architectural invariants; no engine, publication, credential-custody or substrate contract changed.

Local verification

Cargo commands ran inside the checkout with the existing shared target directory. CLI integration tests used the matching prebuilt omnigraph-server through CARGO_BIN_EXE_omnigraph-server.

• Clean combined-prerequisite baseline: cargo test -p omnigraph-cli --bin omnigraph --locked — 171 passed, 9 ignored; query/data integration selection — 120 passed.
• Extended config-swap and configured-error-format owners failed before the presentation fix (three expected failures), then passed in the full suite.
• cargo test -p omnigraph-cli --locked — 181 library tests and 326 integration tests passed; 19 explicitly ignored. Environment-gated cloud/predecessor cases may return early when their prerequisites are absent; this is not live-cloud or release-upgrade qualification.
• cargo clippy -p omnigraph-cli --all-targets --locked -- -D warnings -W clippy::dbg_macro — passed.
• cargo fmt --all --check, python scripts/check-docs.py, bash scripts/check-agents-md.sh, typos, git diff --check — passed.
• Saved-baseline executable comparison: all 91 command/group help pages plus 15 representative argument/version/error invocations — identical stdout, stderr and exit status across 106 invocations with identical argv[0].

Full workspace, cloud and GQT gates are left to CI. The GQT semantic corpus is unchanged; CLI and parity tests own this transport/presentation change. The existing macOS linker unwind-size warning appeared in baseline and final builds.

Notes for reviewers

This branch combines the still-open prerequisites #1037, #1038, #1039 and #1040, so the main-based diff currently includes them. They are followed by four commits for this change:

1. Separate application completion from process startup/exit.
2. Extract query arguments, execution and typed preparation.
3. Capture presentation and preserve output-delivery outcomes.
4. Qualify config-swap/error behavior and document the contract.

The extraction preserves source-loading/credential validation order, opaque forwarding of syntax the local parser cannot understand, omitted versus explicit temporal selectors, alias parameter precedence, destructive consent, and execution-owned CSV file opening. Managed acquisition remains with its existing owner. Streaming export/Blob output stays on its existing path.

[aaltshuler]

Superseded by #1047, which merged the complete CLI refactor, its delivery and configuration fixes, and the latest main integrations as 02026b5. Closing this incremental slice because its implementation is now on main.