feat(sandbox): add canonical main process

[drew]

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 on the sandbox and transitions it to Error; intentional stop/start teardown is exempt.

Related Issue

Closes #2710

Changes

• Add command and tty directly to the public and compute-driver sandbox specs, with sandbox-owned main instance and exit status.
• Normalize omitted and pre-upgrade persisted driver specs to the default /bin/bash -l TTY main process.
• Launch the canonical process in Docker, Podman, Kubernetes, and VM runtimes with exact argv transport and native runtime restart disabled.
• 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 retained main session while preserving independent 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 preserve intentional stop/start lifecycle transitions.
• Update SDKs, architecture and published docs, driver references, CLI agent guidance, and E2E coverage.

Testing

• mise run pre-commit
• mise run test with an isolated system-gateway directory
• Focused core, server, supervisor, VM driver, SDK, and CLI lifecycle tests
• Docker sandbox lifecycle E2E, including competing attachments, disconnect/reconnect, same PID, PTY history replay, exit status, and --no-keep
• Pre-upgrade VM driver-spec compatibility regression coverage

Checklist

• Follows Conventional Commits
• Commits are 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.