# Local Codex component research

The localhost server calls the installed Codex CLI for a selected uncertain BOM component. This is a real subprocess using the current local Codex account and configured model. It can consume account usage. No credential is requested in the browser. A single-component lookup presents a report for manual application. The authorized research-and-run flow can apply supported findings with high confidence, then resolve the BOM again before starting. Unresolved mappings remain visible and cannot silently pass as verified.

The bridge uses `codex exec --ephemeral --sandbox read-only --json --output-schema ...` with live web search. It sends the component record as delimited, untrusted JSON on stdin. Shell tools, connectors, plugins and subagents are disabled for this invocation; configured MCP servers are individually disabled using process-local overrides. Local configuration and credentials are not changed. Authentication-status output, model reasoning, command output and raw process diagnostics are never returned to the browser or saved in reports. A bounded, redacted CLI startup error can be shown to help fix configuration incompatibilities.

Codex is asked to open manufacturer datasheets and other primary sources, identify the exact part variant, and explain missing information. Maximum ratings and typical specifications do not silently become operating settings. For example, a DAC settling specification does not overwrite the selected scan delay. A generic custom filament or slit cannot acquire invented dimensions. Unresolved details remain visible, and the previous simulation settings remain usable.

There is one running process and at most twelve queued requests. Duplicate active requests for a component share the same job. Each job is limited to three minutes and 2 MiB of stdout; stderr storage is bounded and private. Jobs can be cancelled. Completed public reports are saved beneath the server's data directory in `research-jobs/`; they contain source citations and findings, not authentication or raw tool output. At most sixty jobs are held in memory; saved reports are local evidence, not an automatic cache of component truth.

## Configuration

Start the simulator with `npm start --prefix simulator`. It discovers the desktop app's CLI installation or `codex` on PATH. `CODEX_RESEARCH_BIN` can select a different local executable. The existing model is preserved unless `CODEX_RESEARCH_MODEL` is explicitly set. Run `codex login` locally if the status says authentication is missing. Offline research, a model without web-search support, account limits, or process permission failures show an actionable message; the previous parameters can still run.

`createResearchService({ cwd, dataDir, parameterRules })` exports `getStatus()`, `start(component)`, `get(id)`, `cancel(id)` and `close()`. Jobs progress through `queued`, `running` and `completed`, `failed` or `cancelled`. A completed report can still have `ready: false` and unresolved details. `parameterRules` is the server's shared `PARAMETER_SCHEMA`; the bridge rejects unsupported units, out-of-range values, duplicate/conflicting mappings and missing citations. High confidence and source links are evidence for human review, not an independent certification of a datasheet or hardware compatibility. The service cannot apply hardware changes.

## Verification and references

Run `node --test simulator/research.test.mjs`. Tests inject subprocesses and perform no paid model calls. They cover strict report validation, source URLs, bounds, serialized work, unavailable authentication, diagnostic redaction, cancellation and timeout. A live smoke report, when generated, is separate from the deterministic tests and does not modify the BOM.

The initial live lookup exposed a CLI configuration detail: `-c` dotted paths do not unquote a quoted server-name segment. Quoting `node_repl` created an invalid extra MCP entry and the process stopped before research. The bridge now validates server names and passes the unquoted `mcp_servers.node_repl.enabled=false` override. A CLI configuration probe confirmed that the existing server is disabled, and regression tests protect that exact argument. Unusual names fail closed with an explanation.

A real lookup subsequently completed through the localhost browser interface on 2026-09-11. Codex consulted the Spellman UM datasheet (revision R) and UMMAN manual, identifying the UM6N4 as a negative-output 0–6 kV, 4 W supply. It distinguished those ratings from the simulator's selected 3 kV operating voltage and left that value unchanged. The exact B/T option ordering code and selected operating settings remained unresolved, so the report correctly returned `findings: []` and `ready: false`. No BOM or hardware parameters were altered by this verification. The simulator review record and screenshots capture the report.

The implementation follows the official [Codex non-interactive guide](https://developers.openai.com/codex/noninteractive): JSONL events expose progress, a JSON schema defines the final report, ephemeral mode avoids saved session rollouts, and CLI authentication is reused. Tool switches and live web search are documented in the official [configuration reference](https://developers.openai.com/codex/config-reference). Flag availability was also checked against the installed `codex exec --help` (version 0.153.4).