Frontrunner Client

This is the isolated, remote-only foundation for the future customer frontrunner CLI and local stdio bridge.

Distribution version 0.1.0a12 supports Python >=3.11,<3.13. Its immutable wave4-remote-client-mcp-stdio-v12 contract fingerprint is fd19264152e2fd36daadfa9959dcf1064d78cd5f3c26e85c4c1e2f9c11799f4e. The standalone requirements.lock has SHA-256 e1a6163e5146830afa1cd71ec95c5009f42f8a5a4dba195fc40cc4ebebdc39f0 and pins the reviewed direct certifi==2026.7.22 and httpx==0.28.1 requirements plus their transitive graph with artifact hashes and no extras.

The current package provides:

• explicit canonical HTTPS origin and exact Wave 3 afc1.<22-character locator>.<43-character secret> canonical base64url PAT configuration;
• canonical capability catalog and invocation request serialization;
• bounded, strict JSON-object response decoding;
• a caller-injected synchronous transport protocol;
• one validated, non-regressing monotonic whole-call acceptance deadline that starts before request validation and serialization, passes only its decreasing remaining budget into transport, expires at the exact boundary, rejects late transport returns and decoded results, and reports invalid or regressing clocks through the fixed clock_failure transport taxonomy;
• a concrete synchronous HTTPX adapter with a reviewed explicit TLS context, environment/proxy/key-log isolation, scoped HTTPX/HTTP Core log suppression, no redirects or retries, fresh-client cookie isolation, finite phase timeouts, raw streaming bounds, compression rejection, and late cleanup rejection; and
• a deterministic JSON CLI registered only as frontrunner = frontrunner_client.cli:main, whose only configuration inputs are FRONTRUNNER_API_ORIGIN and FRONTRUNNER_ACCESS_TOKEN; and
• an exact MCP 2025-06-18 stdio translator with newline-delimited bounded JSON-RPC, the standard initialize / notifications/initialized lifecycle, deterministic authority-filtered tools/list, and remote-only tools/call. It has no SDK dependency, database path, subprocess supervisor, custom IPC, or hosted listener.

The unmounted CLI contract is:

frontrunner capability catalog --json
frontrunner capability invoke evidence.search \
  --major 1 --arguments-json '{"query":"chip supply"}' --json
frontrunner mcp stdio

python -m frontrunner_client remains an equivalent module invocation. The root application owns no console command; the separate frontrunner-admin wheel owns the privileged operator command, and the client wheel is the sole owner of the bare customer command. Fresh-venv tests prove disjoint three-wheel console and RECORD ownership, representative clean install orders and uninstall directions, and the upgrade from the sealed 0.1.0a11 predecessor at commit b48d59336cba0ff7ce0170a22fd3a47eaaa6cf44 to 0.1.0a12. That interoperability proof is not permission to install the client into the shared application environment: customer use requires a fresh client-only environment, and co-installation with a historical root release that still owns bare frontrunner is unsupported.

Version 0.1.0a11 added mcp_stdio.py but deliberately omitted the MCP initialization lifecycle; current Codex therefore could not load it as an MCP server. Version 0.1.0a12 keeps the same seven-module, dependency, console, HTTPX, and remote API boundaries while replacing that incompatible protocol shape with the standard 2025-06-18 lifecycle used by the current Codex CLI.

The repository's local, non-executing release validator is artifact wave4-client-release-candidate-v2, fingerprint 0fcc271af6abdf86325c254d010272f4c4c34d59702cfd0eaaa14d3ebe3661aa. It content-addresses the exact wheel, reviewed source modules, lock, metadata, entry point, and every RECORD row. It does not select or upload to a package index and cannot replace independent registry-download or Python 3.11/3.12 fresh-install evidence.

The A12 live publication/install bundle must satisfy wave4-client-publication-receipt-v2, fingerprint d0f18cd62a800e5c74d01e9a489c04d0fbbc052995a2532b52477fa0b8d76118. It requires separate index/authorization evidence, upload and independent download hash equality, non-yanked metadata, and fresh Python 3.11/3.12 install proof. The historical A11 production receipt 5c4df75d92aea899df32cf78c11dcd84332fdc09965d5ebe78f1b7d7b59e2621 records the one 0.1.0a11 wheel published at 2026-08-15T15:23:50Z, wheel SHA-256 289105b2c60f93612dcdab1a5762e9edfa23f05d3a78c69c2e7ba4f85aa8b45b, non-yanked metadata, and successful fresh installs on Python 3.11 and 3.12.

The local publication operator consumes the candidate's exact hash-locked dependency file and runs fresh Python 3.11 and 3.12 local-wheel preflights before any production PyPI upload. Each preflight verifies the candidate, lock, runtime graph, console ownership, and module/CLI version surfaces while explicitly keeping publication and supported installation false. The operator hashes a separately retained owner-authorization file, binds the exact local publisher executable, accepts a PyPI token only through UV_PUBLISH_TOKEN, and never records it. Independent production-index downloads and fresh installs still run after upload and remain the only inputs to the live publication receipt. GitHub remains only the Git remote. See docs/local-ci-and-publication.md.

This package also has no default endpoint, token argument, config/token file, stdin or file configuration, local database mode, OAuth flow, hosted transport, application/provider integration, deployment, or activation. The stdio command is an unmounted local translator and is not a customer-ready connection by itself. Later authorized slices must supply the mounted endpoint and scoped PAT lifecycle, then complete production evidence for the separately packaged admin release, hosted MCP/OAuth surfaces, hard end-to-end completion/preemption, supported installation, and golden live query. The first secret-free pre-activation Codex configuration recipe and config-only probe live in docs/codex-mcp-setup.md; their parser acceptance is not a mounted protocol or live-query proof. The current deadline is an acceptance bound; hard completion and preemption remain false. Phase timeouts are defense-in-depth, arbitrary synchronous injected transports and blocking cleanup are not forcibly interrupted, and the package intentionally contains no process supervisor, worker, local IPC, or platform-specific lifecycle code. Hard completion/preemption is not claimed.