Frontrunner Client

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

Distribution version 0.1.0a11 supports Python >=3.11,<3.13. Its immutable wave4-remote-client-mcp-stdio-v11 contract fingerprint is 792f68db385fec0eb7df97c4549a7b0be1b39584e0afed233580e5a5819595fd. 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 2026-07-28 stdio translator with newline-delimited bounded JSON-RPC, required per-request protocol metadata, server/discover, deterministic private tools/list, and remote-only tools/call. It has no initialize handshake, protocol session, 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.0a10 predecessor at commit acb8a3ec to 0.1.0a11. 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.0a10 removed the unmounted Darwin supervisor, worker, local IPC, and deadline-aware transport extension from 0.1.0a9. Version 0.1.0a11 keeps that reduced six-module boundary and adds only mcp_stdio.py, producing a seven-module wheel. The immediate-predecessor upgrade proof verifies the new module is installed while console ownership and the HTTPX/CLI contract remain stable.

The repository's local, non-executing release validator is artifact wave4-client-release-candidate-v1, fingerprint a1c9ad83d10dc6b875f0a102f39a43f560c7a90ac09f9eac8e6cd0375b3279ec. 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 future live publication/install bundle must satisfy wave4-client-publication-receipt-v1, fingerprint aa026ba1adebde008b96e0976c6a1611c53e9a748dab5981d7143454a1432b08. It requires separate index/authorization evidence, upload and independent download hash equality, non-yanked metadata, and fresh Python 3.11/3.12 install proof. No such live receipt exists yet.

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, publication, supported runtime installation, 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.