Cas

CAS

Mission

Use CAS as the single local Codex control-plane product. Its primary runtime boundary is the Codex app-server protocol. Automation is a direct adapter over the existing local Codex database and files because app-server has no automation CRUD or scheduler API.

CAS owns route execution and facts it directly observes. It does not decide Goal semantics, review credit, finding truth, repairs, mutation, publication, closure, what an automation ought to do, or whether its result is correct.

Require installed CAS 0.6.0 or newer. There is no standalone automation product, compatibility skill, or legacy command route.

Native surface

cas capabilities
cas app-server <preflight|schema|session|daemon>
cas account status
cas automation <doctor|list|show|create|update|enable|disable|run-now|delete|run-due|scheduler>
cas goal <resolve|get|set|clear|status|wait>
cas smoke_check
cas instance_runner
cas review <run|start|wait>
cas session_inquiry <preflight|run|start|status|wait|interrupt|receipt|cleanup>
cas conformance

Underscore/hyphen spelling conveniences already shown by cas --help may be used. They do not create another product identity.

Runtime compatibility gate

Before an app-server-backed route whose compatibility has not already been established for the exact resolved Codex executable and current schema cache, run:

cas app-server preflight \
  --cwd <repo> \
  --profile <core|review|session-inquiry|full> \
  --app-server-transport <selected-transport> \
  --json

Use these profiles:

Require status == "compatible", the intended resolved Codex path, contract ID codex-app-server-capabilities-v2, no missing required methods or handlers, and all required selected-profile probes passed. Codex version and release channel are diagnostic only. degraded is not compatible proof for a required route behavior.

CAS 0.6.0 is qualified against released Codex 0.151.0. That version is an evidence baseline, not a runtime pin or upper bound: admit later released runtimes when the selected capability profile and probes pass. Do not use an unreleased or prerelease build as qualification evidence unless the caller explicitly requests prerelease testing.

For review and session inquiry, also require the preflight receipt's transport.selected == "managed-ws"; a compatible stdio receipt is not equivalent proof. CAS 0.6.0 review runs this gate internally before starting and reports the realized connection as selectedTransport == "websocket". Session inquiry additionally receives --transport managed-ws on execution.

Compile-time capabilities report what CAS implements. They do not prove that the resolved runtime implements it. For review, require both the compatible review preflight and cas_capabilities.features.cas_structured_review_v1 == true.

See codex_app_server_contract.md and codex-app-server-capability-matrix.md.

Route guidance

App-server, smoke, and instances

Use cas app-server schema --json for a non-mutating schema/cache report and cas app-server preflight --json for the structural and behavioral verdict. Use cas app-server session for a raw stateful app-server stream and cas app-server daemon for released daemon lifecycle commands. Both delegate to the selected Codex executable, preserve its raw bytes and exit status, and accept --codex-path; they do not impose a version gate. Use cas smoke_check for bounded handshake and reachability observations. Use cas instance_runner for bounded raw requests or fanout. Preserve additive response, notification, and item data rather than projecting it away.

Explicit transport or remote Code Mode host selection is fail-closed. The outbound Code Mode host is distinct from the inbound app-server endpoint and uses the released HTTP(S) root-endpoint form. Authenticated WebSocket listener flags belong to the delegated app-server session surface.

Automation

Use cas automation for every automation operation. When store or scheduler compatibility is uncertain, and before troubleshooting or mutation that relies on it, run:

cas automation doctor --json

Do not perform row or file mutations when safeToMutate is false. The only narrow remediation exception is the doctor-directed same-label scheduler adoption documented below. Use --db only when deliberately selecting a non-default database; automation files still belong to the existing Codex automation root. See automation.md and automation-db.md.

Review

Use run for a standalone one-off review. Use one owner-lived start --wait process for workflow-bound or Actuating review. Use wait only to recover or inspect an already-started admissible attempt.

cas app-server preflight --cwd <repo> --profile review \
  --app-server-transport managed-ws --json

cas review run --cwd <repo> --base <base> \
  --custom-instructions @<instructions> \
  --timeout-ms 2700000 --json

cas review start --wait --cwd <repo> --base <base> \
  --custom-instructions @<instructions> \
  --workflow-binding-json @<binding.json> \
  --timeout-ms 2700000 --json

A process is not a review. An attempt exists only after reviewThreadId; a semantic verdict exists only when the structured verdict binds the exact target tuple. CAS reports the backend. The caller decides credit and finding disposition. See review-proof-boundary.md.

When the caller admits a new same-target attempt after terminal evidence, pass --fresh-attempt <source-bound-reason>. CAS records the reason; it does not decide whether the new attempt is permitted.

Session inquiry

Use the session-inquiry preflight profile before execution. A paginated source is admissible when the exact runtime probe passes. Fork boundary and anchor digest verification remain mandatory. A successful paginated fork is not proof of historical workspace reconstruction.

Pass --transport managed-ws to session_inquiry run|start; do not let the execution fall back to its auto default after proving a selected transport.

Validate Retrace inputs with their owner definitions and validate the returned FIR with CAS's passive definition before interpreting it. See retrace-session-inquiry.md.

Account and goals

cas account status reports account facts and preserves plan values as data. cas goal resolves, observes, mutates, or waits for native CAS goal state only when the caller authorizes that route. Neither command creates semantic Goal Contract authority.

Hard rules

• Treat the installed Codex executable and its generated stable and experimental schemas as the runtime source.
• Version strings and schema digests alone are not compatibility proof.
• Unknown server requests get an immediate unsupported response and never deadlock a request loop.
• Never synthesize credentials, attestations, elicitation consent, plugin trust, or publication authority.
• Never log or persist secret server-request response bodies.
• Preserve additive non-control data; reject unknown control flow explicitly.
• Explicit transports and Code Mode hosts never silently fall back.
• Automation keeps the existing Codex rows, files, RRULEs, run records, memories, scheduler label, and log paths.
• CAS reports owner facts; callers retain semantic decisions and authority.