feat(config)!: add durable configuration completion

[pimlock]

Summary

Add durable completion tracking for sandbox policy and settings updates. Desired state and its operation commit together; callers can return after commit or use WAIT_FOR_COMPLETION to wait for a terminal outcome. A timeout leaves the committed operation running, and completion distinguishes application, degradation, failure, supersession, inactivity and cancellation.

Architecture diagrams and interaction flows — includes request sequencing, operation states, recovery, and a standalone HTML diagram page.

Related Issue

Part of #1731. Stacked on #3265.

Changes

• Atomically persist desired state, sandbox metadata/resource-version checks and completion operations in SQLite and PostgreSQL. Unchanged updates track existing revisions and obtain a fresh acknowledgement when needed.
• Match completion to the exact streamed revision, with indexed recovery, conditional state transitions and durable operation lookup. Record request replay before waiting so retries can recover the committed operation after a timeout.
• Integrate with feat(supervisor)!: apply streamed configuration snapshots #3265's supervisor admission, runtime readiness, provider receipts and protobuf time contracts. Require supervisor protocol revision 3.
• Update CLI, Go and TypeScript contracts and documentation. Rename WAIT_FOR_APPLY to WAIT_FOR_COMPLETION and expose degraded outcomes separately from operation state.

Testing

Live-testing report covers the earlier #3265 fleet tests—up to 128 running sandboxes, 15,360 policy submissions, and restart/reconnect checks—with observed failures and limitations. It separately records the passing live-policy and lifecycle checks on the current #3273 head (262be8a9e); the fleet benchmark was not rerun on this head.

Review follow-up validation at 40518cc7f:

• mise run pre-commit passed.
• Focused durable-operation, idempotency, readiness, and dimension-matching tests passed.
• The ignored PostgreSQL transaction suite passed all three tests against a disposable postgres:16-alpine instance with OPENSHELL_TEST_POSTGRES_URL=postgres://postgres:openshell-test@127.0.0.1:55432/openshell_test mise exec -- cargo test -p openshell-server 'persistence::tests::postgres_' -- --ignored --test-threads=1.

Checklist

• Conventional Commits and DCO sign-off requirements followed.
• Architecture and user-facing documentation updated.
• SDK contracts updated.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-3273.docs.buildwithfern.com/openshell

[pimlock]

gator-agent

PR Review Status

Thanks @pimlock. I reviewed the latest author delta that allows the startup-rejection E2E to accept either ordering of the fail-closed transition while still requiring exactly one configuration-error event. All prior Gator findings remain resolved, and the bounded critical-only review found no newly introduced Critical defect.

Blocking findings:

• No blocking findings remain

Carried findings:

• None

Gator metadata

• Validation: Project-valid because this implements the accepted stage of #1731 on the declared #3265 stack.
• Docs: Fern policy documentation and related architecture guidance are updated.
• Checks: Current-head Branch Checks and required E2E are running; Helm Lint and Trivy Changes are green.
• E2E: test:e2e and test:e2e-kubernetes are applied, and the current-head workflows are running.
• Head SHA: ef321d52e572cceb8307aeba722a066f078bf870
• Base SHA: f5601252ba2dc68677ffe6fc4955802e7ed54128
• Merge base SHA: f5601252ba2dc68677ffe6fc4955802e7ed54128
• Patch ID: ab3ec9e885ca8117973618e9df94b12c009cbb8e
• Gator payload: 9
• Review mode: critical_only
• Previous reviewed SHA: dbc0eda816097eb303801776547598cdae040a3f
• Review budget exhausted: yes
• Maintainer decision required: no
• Next state: gator:watch-pipeline

[politerealism]

Hey @sjenning @mrunalp @derekwaynecarr — this one's been open a bit and is part of the #1731 staged rollout (this is stage 3 of 3). Any chance you have bandwidth for a review pass in the near term? Happy to help unblock if there's anything I can clarify in the meantime.

[pimlock]

Hey @sjenning @mrunalp @derekwaynecarr — this one's been open a bit and is part of the #1731 staged rollout (this is stage 3 of 3). Any chance you have bandwidth for a review pass in the near term? Happy to help unblock if there's anything I can clarify in the meantime.

Thanks @politerealism! Just FYI this won't make it into the 0.1.0 and we will try to land it soon after. It will need some tweaks to land it in one of the patch releases, as this is a breaking change, but shouldn't be too much (this version was made with the assumption we can make breaking changes).