feat(sandbox): add canonical main process

[drew]

🏗️ build-from-issue-agent

Summary

Add one canonical main process to every sandbox and make it the process observed by sandbox connect. The supervisor retains and multiplexes its session across reconnects, while sandbox exec remains an independent process path. Any unexpected canonical-process exit, including exit code 0, is persisted and transitions the sandbox to Error; intentional stop/start teardown is exempt.

Related Issue

Closes #2710

Changes

• Add public and compute-driver protobuf contracts for the canonical process, exit result, driver capability, and durable exit acknowledgement.
• Persist and validate exact argv, environment, working directory, terminal mode, and initial terminal size.
• Launch the canonical process directly in Docker, Podman, Kubernetes, and VM runtimes without an idle sleep/tail entrypoint.
• Add a supervisor-owned PTY/pipe session multiplexer with bounded replay, live fanout, one stdin owner, read-only readers, resize, signals, and disconnect-safe process ownership.
• Route sandbox connect through the dedicated openshell-main SSH subsystem; preserve independent shell, exec, SFTP, editor, and forwarding behavior.
• Make trailing sandbox create argv the persisted main process, attach interactively by default, and add --detach.
• Record unexpected main-process exits as terminal sandbox errors and suppress automatic relaunch while preserving intentional stop/start lifecycle transitions.
• Update Rust, Python, and Go SDKs, architecture docs, published docs, driver READMEs, E2E coverage, and the OpenShell CLI skill.

Deviations from Plan

Per the agreed scope, checkpoint/restore and lifecycle hook APIs are excluded. The implementation is limited to the new canonical entrypoint, retained attachment, and terminal exit semantics.

Testing

• mise run pre-commit
• Go build, format, lint, docs, proto drift, and feature-relevant converter tests
• Focused Rust core/server/supervisor/driver/SDK tests
• CLI lifecycle integration: 22 passed, 2 known flaky forwarding tests ignored
• Docker-backed Rust E2E coverage, including connect, reconnect, fast exit, terminal status, no relaunch, and --no-keep
• Principal engineer review: no release blockers

mise run pre-commit and the relevant Rust suites pass. Full local Go and CLI aggregate suites each encounter unrelated environment-isolation tests that inspect this host's registered system gateway under /etc/openshell; build, lint, docs, proto drift, converter coverage, and the feature-relevant tests pass.

Tests added/updated:

• Unit: protobuf conversion, validation, driver rendering/capabilities, terminal state persistence, durable acknowledgement, replay/fanout/ownership, and disconnect cleanup.
• Integration: CLI request persistence, attach/detach, no duplicate exec, and no-keep cleanup.
• E2E: canonical process connect/reconnect, lifecycle exit semantics, local-driver no-relaunch behavior, provider creation, labels, and upload harness compatibility.

Checklist

• Follows Conventional Commits
• Commit is signed off (DCO)
• User-facing and architecture documentation updated
• Related agent skill 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-2726.docs.buildwithfern.com/openshell

[drew]

🏗️ build-from-issue-agent

E2E Test Attestation

Local E2E smoke passed against the exact pushed commit. CI does not currently run this Docker E2E lane, so this comment serves as the verification record.

Field	Value
Commit	f192d21
Command	mise run e2e:docker
Gateway mode	Docker
Result	✅ All passed

Test Summary

1 passed; 0 failed; 0 ignored; finished in 0.72s

Tests Executed

• smoke::gateway_smoke — PASSED

The broader canonical-process lifecycle and reconnect cases were also exercised during implementation; this attestation records the final-commit smoke lane specifically.

[drew]

🏗️ build-from-issue-agent

Principal Review Findings Addressed

Rebased onto current main and fixed all findings from the principal-engineer review:

• Exact supervisor exit results now enrich an earlier backend-only terminal snapshot instead of being discarded as duplicates.
• Intentional Stopping, Stopped, and Deleting teardown ignores the canonical-process exit report; unexpected exits still transition to Error.
• Direct and Kubernetes-sidecar exit reporting now retries until the gateway durably acknowledges the result, without the previous 15-second cutoff.
• openshell-main attachment applies the client's initial PTY dimensions before the channel is accepted.
• VM recovery preserves distinct durable tombstones for intentionally stopped and unexpectedly exited workloads.

Regression tests cover backend-terminal-first ordering, stop/exit races, and initial PTY sizing.

Verification

Field	Value
Commit	5981a52e
Rebased onto	current main
Pre-commit	✅ Passed
Supervisor	✅ 230 tests
Server	✅ 1,328 passed, 8 ignored
CLI lifecycle integration	✅ 22 passed, 2 ignored
Driver/sandbox packages	✅ Docker, Podman, Kubernetes, VM, and sandbox suites
Docker E2E	✅ gateway_smoke: 1 passed
Go	Build, format, lint, docs, proto drift, and relevant converter packages pass

The full Go race suite reaches three unrelated gateway-list tests that inspect this host's real /etc/openshell registration; this is the same environment-isolation class as the pre-existing CLI completer failure.