Read the result, including its evidence
One check command, six statuses and explicit exit codes. A synthetic ready result is never live readiness.
Command and flags
castles check [--json] [--fixture <case.json>]The syntax above describes the CLI entrypoint. From a source checkout, run it through corepack pnpm check; the package does not define an installed castles binary.
| Flag | Behavior |
|---|---|
--json | Emit the bounded castles.preflight.v1 result rather than human-readable text. |
--fixture <case.json> | Read the complete synthetic binding and response from one fixture. Output is marked fixture. |
Statuses
| Status | Meaning |
|---|---|
ready | The evaluated input is running and matches the profile. Check the evidence before treating it as readiness. |
stopped | The evaluated sandbox matches but is stopped or archived. Castles does not wake it. |
unavailable | Not configured, not found, unreachable, not settled, or the upstream seam is missing. |
incompatible | Unknown profile, unsafe policy, public exposure or missing metadata. |
unauthorized | The owner refused access or its record binds a different sandbox. |
reconciliation-required | Stale generation, ambiguous lookup, different returned ID or an unresolved prior attempt. |
Read reasons for the specific code and optional field. For example, a configured non-fixture check currently reports upstream_seam_missing. Reason codes are defined in src/preflight.ts.
Exit codes
| Code | Meaning |
|---|---|
0 | ready with live-provider evidence. Unreachable with the current CLI. |
1 | Any status other than ready. |
2 | Usage error or unreadable fixture. |
3 | A fixture reported ready. Synthetic input, never readiness. |
Nonzero exit codes in the fixture quickstart are intentional. Do not rewrite a fixture result to exit zero to satisfy a readiness gate.
JSON fields
| Field | Meaning |
|---|---|
schema | castles.preflight.v1. |
status / reasons | Evaluation outcome and bounded reason codes. |
evidence | fixture, live-provider or none. No live client currently exists. |
target | Profile, expected generation and redacted owner/sandbox aliases. |
sourcePolicy | Policy and exact source pins; these are not observed provider facts. |
observed | Sanitized metadata, or null when unavailable or withheld at the binding boundary. |
providerCalls.inspect | Inspection calls through the supplied client. Fixture-client calls are synthetic, not live provider reads. |
Rendered JSON is bounded to 16,384 bytes. Provider text is mapped to fixed vocabularies, bounded forms or null rather than printed directly.
The consumer gate
result.status === "ready" &&
result.evidence === "live-provider"The library exposes isLiveReady(result) for this condition. A green fixture test, a source pin, a merged pull request or a ready status alone does not satisfy it.