AGENTS.md

Better Codex runtime invariants

• The local Runtime is the only owner of the Better Codex business database. Its runtime lock and published identity must agree on PID, process start time, instance ID, port, version, and profile.

• Codex token activity is collected by one Runtime-owned resident watcher with incremental rollout reads and periodic reconciliation. Output speed is the weighted last_token_usage.output_tokens rate across completed model-output streaming intervals, while request count includes every completed output-bearing model request in the rolling window. Browser and Relay consumers read the cached rolling snapshot and must never create per-client filesystem scanners.

• A Session Host is single-instance within one profile. Runtime connections are authenticated before replacement and fenced by connection epoch. The Host owns one catalog-only App Server and one disposable App Server worker for each Better Codex-owned thread. Host status must continuously identify the Host PID, process start time, Host instance, Runtime instance, catalog App Server, every thread worker, and command state. A thread worker must exit after terminal turn delivery is durably queued or before native Codex resumes that thread; active threads reject handoff instead of sharing a writer.

• Native-thread handoff releases Session Host writer ownership while retaining the Issue-to-thread binding. Card commands for a handed-off thread remain durable Runtime commands and are consumed only by the authenticated native-session proxy in the Codex host; the Session Host must not claim them. Native turns are reconciled from the Runtime-owned rollout watcher so start, completion, interruption, restart recovery, archive protection, and local/Relay projections stay synchronized without a second writer resuming the handed-off thread.

• Runtime rollout reconciliation covers every unarchived Issue-to-thread binding, including idle owned sessions. Persisted active-turn and handoff flags must never exclude a binding from watcher-driven or periodic reconciliation. Reconciliation observes execution without changing writer ownership and records discovered turns with their previous session state and terminal turns with their completion state.

• Stable and development Session Hosts may use separate profile homes, but every detected Host must be represented by a fresh status record. untracked Hosts are operational drift and must never be killed without verifying their exact PID, start time, profile lock, and active work.

• Relay accepts one active Runtime connection. Connection-wide closure is reserved for authentication, identity, epoch, or protocol failures. Request sequence and channel state failures terminate only the affected channel and emit structured diagnostics.

• /livez proves only that the process can answer. /readyz proves that required dependencies can serve traffic. Docker uses /livez; external monitoring and remote-access acceptance use /readyz.

• Desktop integration is reported separately as ready, waiting for a main window, disabled, or failed. Its evidence is scoped to Runtime instance and generation, compatibility package, profile, and renderer document. Auxiliary windows and loading renderers never establish incompatibility. Compatibility probes do not modify version pointers, and a closed Codex window does not block a service update.

• Standalone VPS mode activates the Compose standalone profile and bundled Caddy. Existing-proxy mode starts only hub and requires bundled Caddy to be stopped.

• Storage below the 2 GiB critical reserve makes Runtime or Relay not ready and blocks updates before staging. Storage below the fixed 5 GiB warning reserve is reported as degraded and requires cleanup before routine upgrades; free-space percentage is diagnostic only and never an admission gate. Updates also reserve capacity for their staged artifacts.

• Errors on Runtime, Session Host, Relay, update, database, and deployment paths must include structured identity and state fields. Do not convert a failed dependency into a successful health response.

• New Issues persist their input before allocating a Codex thread. The first durable start command creates the thread and submits the original input in the same worker; creation alone never proves persistence. Legacy bind commands retain their worker until the returned rollout is materialized. Once a turn has started, the Issue keeps that canonical thread. Agent Issues remain queued until turn start; generated titles use a durable, idempotent owner-routed command.

• Provider, process, and transport failures remain visible on the Run, Reply, and Session records and return the Issue to blocked. Failed execution takes precedence over scheduler decisions; in_review is reserved for successful execution awaiting review or an unavailable semantic decision. A terminal execution interruption returns the Issue to blocked, while a superseded turn remains in_progress under its replacement turn.

• Runtime updates must drain new dispatch without interrupting active turns. A compatible Session Host, its catalog App Server, and active thread workers remain alive across Runtime generations, deliveries are acknowledged only after the business transaction commits, and update success or rollback is terminal only after handoff replay, reconciliation, and /readyz recovery.

• Update operation IDs bind an immutable request, signed manifest, source pointers, and target artifacts. Status reads never recover or mutate pointers. Only the update coordinator activates staged artifacts or restores pointers under the matching operation and Runtime generation; rollback intent is durable before target shutdown. A committed operation rejects late failures, and failed recovery retains its journal instead of starting another activation loop. Rollback never restores a business database snapshot.

• The activator persists a commit decision before the business terminal state. Interrupted committing and committing_rollback phases finish their original decision instead of reversing it. Recovery has one process-start-fenced owner, includes Runtime bootstrap failures before HTTP starts, and stops automatic activation after two interrupted recovery attempts.

• Local Mockup is an isolated renderer simulation backed only by temporary local state. It runs only in a local development MCP App with an isolated simulation service; production Runtime dispatch, Session Host, App Server, local WebUI, Relay WebUI, remote access, updates, and business data must never read or depend on Mockup lifecycle state.

• Frontend design values are registered only in src/ui/design/registry.ts and its layer modules. Feature styles consume canonical --bc-* semantic tokens directly; legacy and --web-* aliases are not permitted.

• Local WebUI, Relay WebUI, the MCP App, and development Mockup consume the same generated browser entry. Hosts own only mount, theme input, transport, routing, and capability differences.

• Shared UI follows core -> primitives -> components -> patterns -> features -> hosts. Components expose update and destroy lifecycles, feature code owns product state and API intent, and host code must not contain product rendering rules.

• Settings, Projects, Agents, and Board each have controller.ts, model.ts, and view.ts boundaries under src/ui/features. Features must not import another feature's internal controller, model, or view.

• Project management is a Release feature in the feature manifest and shared UI.

• Structured composer input is persisted as ordered InputDocumentV2 and compiled only through src/codex-input-document.ts. Semantic discovery and execution-time validation use the active Session Host's catalog App Server; Runtime must not start another catalog scanner or use a thread worker for discovery. Relay-visible candidates contain opaque expiring handles and safe display fields only, never local locators or absolute paths.

• Session command admission is bounded across Issues and serialized within one Issue and worker. Global polling must not await unrelated long-running command execution. Missing thread history is a visible terminal dependency failure, not a rename retry condition.

• Model discovery uses the Session Host catalog App Server. Runtime caches and normalizes results, with explicit unavailable state; only Mockup uses static model fixtures.

• Browser, Runtime, and Relay share src/web-command-policy.ts for durable command routes, body limits, and response classification. Browser acceptance requires a committed local queue entry or a durable remote acknowledgement.

• Desktop, local Web, and Relay Web use the same update observer. Receipt loss, reloads, and other windows retain the original idempotency key and operation ID. Each window independently observes a verified terminal result; transport timeouts mean an unknown outcome. Detailed upgrade error reports open only on user action and retain operation identity, actual version, phase, desktop evidence, and recovery result.

• Build and verification never refresh an installed Runtime or desktop bridge. Local refresh is explicit. Preview and Release consume the same reusable CI and signed Host capability requirements.

• Architecture ownership, migration limits, and verification entrypoints are defined in docs/adr/execution-and-delivery-boundaries.md.

• System services, desktop launchers, and MCP registrations share one stable installation command, never a version-directory core. Service environments preserve that base entrypoint across updates and rollback; only the base launcher selects the active core. Legacy service configuration is migrated on start only after Runtime and service processes have stopped, with structured before/after diagnostics. Launcher failures must also be visible in a native dialog.

• Relay automatic updates run in one resident scheduler and use the signed channel feed plus the host updater queue. Compose defaults to stable automatic updates; verified installers persist preview for a selected Beta and stable for a selected release when no explicit channel exists. Existing channel and automatic-update settings survive installation, and rollback restores the saved deployment environment. Failed installations pause automatic retries, storage warning reserves block staging, and successful upgrades require target-version /readyz recovery. Health status reports actual updater capability rather than fixed update flags. Desktop and both Web hosts display the VPS channel and cached detection result; authenticated remote update actions remain on the Relay.

• The VPS queue persists operation IDs, request fingerprints, pinned signed manifests, phase timings, and recovery outcomes across executor restarts. Unknown operation IDs return 404. The executor retains source image digests and resolved Compose configuration before building or switching, resumes interrupted work under its original ID, and verifies internal and public readiness before a terminal outcome. Installers never run a second rollback after a Runtime operation commits.

• Signed channel manifests include the release source commit. The VPS executor checks that pin before checkout, preserves its execution lock in the deployment child across supervisor death, and uses group-inheriting state directories so the Relay can read host-written progress. Rollback restores retained Hub and Caddy images and configuration without rebuilding or replacing business data.

• The Better Codex MCP App renders the complete shared product UI against the local Runtime. It is the only Better Codex product surface inside Codex; page injection and sidebar recovery routes are retired. App transport keeps Runtime credentials server-side, preserves durable command IDs, and consumes the existing Runtime event stream without additional filesystem scanners. A separate non-rendering desktop bridge owns native-session commands and catalog synchronization; its lifecycle is independent of the plugin UI and Mockup.

• The standard MCP server delegates business reads and bounded task-content writes to the authenticated Runtime. External observations remain separate from owned Issues and never gain worker ownership.

• Runtime semantic evaluation uses the versioned schema and prompt at the standard service tier with the user-configured scheduler model. An unset model prefers an available catalog model whose ID or display name contains luna (case insensitive), otherwise the user default model; the catalog default resolves an unspecified user default. No evaluator model is hard-coded. The evaluator has no board-write authority. A model completion decision maps to review, while manual acceptance remains a separate persisted user action.

• Completed Issue thread archive, unarchive, and delete actions durably queue a desktop catalog notification in the same Runtime transaction. The authenticated native proxy updates the Codex catalog and renderer cache before acknowledging that notification; unavailable desktop services retain a visible retryable error. Backend completion never implies desktop sidebar synchronization.