feat: add a command to check a policy file before creating a sandbox #4035

User Story

As someone writing a sandbox policy,
I want a command that tells me whether the file is valid,
so that I can fix mistakes before I try to create a sandbox with it.

Problem Statement

There's no command that checks a policy file on its own. openshell policy has set, update, get, list, and delete, and sandbox create has no dry run.

From reading the code, the CLI only parses the file, and the gateway does the remaining checks, such as rejecting a root run_as_user. So full validation needs a reachable gateway. sandbox create also connects before it reads the file, so with the gateway down, openshell sandbox create --policy bad.yaml fails with a connection error and never mentions the file.

Reproduction Steps

1. Write policy.yaml with no version:

   process:
     run_as_user: "1000"
     run_as_group: "1000"

2. openshell --gateway-endpoint http://127.0.0.1:1 sandbox create --policy policy.yaml, where nothing is listening on that port. It fails with failed to connect to gateway and doesn't mention the file.
3. openshell-prover check --boundary policy.yaml policy.yaml correctly fails with missing field: version.
4. Add version: 1 and change both IDs to "0". The same prover command prints result: within_boundary and exits 0.

Impact / Why This Matters

My first policy was missing version: 1. I couldn't tell whether the file was right without a running gateway and a sandbox create, which also pulls the image. And yes I should have read the documentation!

The workaround is openshell-prover check --boundary policy.yaml policy.yaml, with the same file as both arguments. The prover is meant for comparing two policies, not for validating one. On 0.1.2 it catches a missing version and unknown fields, but it accepts run_as_user: "0", which the schema reference says OpenShell rejects. It's also a separate binary that nothing points you to for this.

Proposed Design

A CLI command that takes a policy file, for example:

openshell policy check policy.yaml

It runs locally and doesn't need a gateway. It applies the same validation to the file as sandbox create --policy. A valid file exits 0. An invalid one exits non-zero and prints the same errors that creating a sandbox with it would. Alternative names for the subcommand: lint or validate. This is the same idea as terraform validate, helm lint, or opa check.

A pass means the file is valid, not that a sandbox will start. Checks that depend on the gateway or the image stay where they are, such as registered middleware, attached providers, or the image's USER. The command could also ask a running gateway to run its checks, the way kubectl has --dry-run=client and --dry-run=server. That could be done in follow-up work.

Acceptance Criteria

• The command works with no gateway configured or running.
• It rejects everything sandbox create --policy rejects in the file itself, including a missing version, unknown fields, and a root run_as_user.
• When the file parses, it reports every validation problem in one run, not just the first.
• The exit code is 0 for a valid file and non-zero otherwise.
• The policy docs mention it where they describe writing a policy.

Alternatives Considered

• The prover, as above. It doesn't apply all the validation and isn't meant for this.
• policy update --dry-run. It previews a merge into a live sandbox's policy. It doesn't take a file, and it needs a sandbox.
• A gateway-side check only, such as sandbox create --dry-run. The gateway can see more, such as registered middleware and attached providers. But it doesn't work before a gateway is up, or in CI or an editor, and it ties a file check to create's other flags.

Agent Investigation

Used the create-spike skill to check feasibility against main at 021400be8.

Feasible, medium complexity. Most of the file-only validation is already a pure function in openshell-policy, which the CLI already depends on. The work is a subcommand that skips gateway resolution, plus moving a few pure checks out of the gateway so both sides share them.

What validates a policy file today:

The CLI runs only the first two rows. The rest run in the gateway on CreateSandbox (grpc/sandbox.rs:548-565 and 620).

What would change:

• openshell-cli: a new PolicyCommands variant (main.rs:2100) with its own dispatch arm. The shared policy arm calls resolve_gateway and apply_auth at main.rs:3021 before it matches the subcommand. doctor check (main.rs:2715) is the existing pattern for a command that runs without a gateway.
• openshell-policy: one shared function for file-only validation. None exists today. The gateway chains the checks itself on create and repeats the chain on the policy update paths (grpc/policy.rs:3606 and 3997).
• openshell-server: the reserved-name, credential_binding, and size checks move into openshell-policy, and the gateway calls the shared function. Otherwise the command and the gateway only match by convention.
• Docs and skills: docs/how-it-works/policies/manage-policies.mdx, a cross-reference from prover.mdx, and the openshell-cli and generate-sandbox-policy skills.

That's roughly 9 to 13 files. It doesn't touch gateway configuration or anything sensitive to SELinux or AppArmor.

Decisions for a maintainer:

• Name. doctor check runs locally and profile lint goes through the gateway, so lint would end up meaning two things.
• Exit codes and output. Plain exit 1, or the prover's split of 1 for an invalid policy and 2 for usage or I/O errors. Also whether to offer --output json.
• Reporting every problem. The checks that stop at the first failure would need to return lists. The parse stage stopping early is consistent with the acceptance criterion.
• Built-in middleware config. Checking it locally adds a CLI dependency on the builtins crate. External middleware can only be skipped with a note.
• Reserved _provider_ names. If they're an error locally, the output of policy get --full fails the check and the output of --base passes.
• No path argument. Require it, or fall back to OPENSHELL_SANDBOX_POLICY as sandbox create does.
• Version skew. The result reflects the CLI's rules, which can differ from an older or newer gateway.

Tests:

• Unit tests on the shared function, including a file with several violations.
• CLI tests with no gateway configured, using run_isolated in crates/openshell-cli/tests/common/mod.rs.
• A parity test against the gateway is practical. policy_only_process_identity_integration.rs already runs an in-process gateway.

Checklist

• I've reviewed existing issues and the published docs
• This is a design proposal, not a "please build this" request