feat(sandbox): add canonical main process

.agents/skills/openshell-cli/SKILL.md

@@ -70,7 +70,9 @@ The simplest way to get a sandbox running:
 openshell sandbox create
 ```
 
-This creates a sandbox with defaults and drops you into an interactive shell.
+This creates a sandbox whose canonical main process is `/bin/bash -l` and
+attaches your terminal to that retained process. Add `--detach` to return after
+the sandbox becomes ready without attaching.
 
 When supplying `--name`, use a portable DNS-1123 label: at most 63 lowercase alphanumeric or `-` characters, beginning and ending with an alphanumeric character. The Kubernetes driver rejects uppercase letters, underscores, dots, and other names that cannot become Kubernetes resource labels.
 
@@ -230,13 +232,19 @@ Key flags:
 - `--driver-config-json`: Pass experimental driver-specific sandbox configuration
 - `--label KEY=VALUE`: Add labels for later selection (repeatable)
 - `--env KEY=VALUE`: Set non-secret sandbox environment variables (repeatable); use `--provider` for credentials
+- `--tty`: Allocate a retained PTY for the canonical main process
 - `--approval-mode manual|auto`: Control handling of agent-authored policy proposals; `manual` is the default
 - `--upload <PATH>[:<DEST>]`: Upload local files into the container working directory or an explicit destination
 - `--no-git-ignore`: Disable `.gitignore` filtering for uploads
 - `--no-keep`: Delete the sandbox after the initial command or shell exits
+- `--detach`: Start the canonical main process without attaching
 - `--forward [BIND_ADDRESS:]PORT`: Forward a local port and keep the sandbox alive
 - `--editor vscode|cursor`: Open a remote editor after creation and keep the sandbox alive
 
+Do not combine `--upload` with a trailing main command. Uploads currently finish
+after the canonical process starts; create a scratch sandbox and use
+`sandbox exec`, or build the files into the image.
+
 ### List and inspect sandboxes
 
 ```bash
@@ -254,7 +262,12 @@ openshell sandbox connect my-sandbox
 openshell sandbox connect my-sandbox --editor vscode
 ```
 
-Opens an interactive SSH shell. To configure VS Code Remote-SSH:
+Attaches to the sandbox's existing canonical main process. Disconnecting leaves
+that process running; reconnecting targets the same process instance and replays
+recent output. Use `sandbox exec --tty -- /bin/bash -l` for a new shell. Press
+`Ctrl-P`, then `Ctrl-Q` to disconnect without terminating main. `Ctrl-C` retains
+its normal terminal behavior and interrupts the foreground process. Configure
+VS Code Remote-SSH with:
 
 ```bash
 openshell sandbox ssh-config my-sandbox >> ~/.ssh/config
@@ -287,7 +300,9 @@ openshell sandbox exec --name my-sandbox --workdir /workspace -- ls -la
 openshell sandbox exec --name my-sandbox --env MODE=test -- cargo test
 ```
 
-`sandbox exec` streams output and exits with the remote command's exit code. Use `sandbox connect` for an interactive shell.
+`sandbox exec` starts an independent sibling process, streams output, and exits
+with the remote command's exit code. Use `sandbox connect` to attach to the
+canonical main process.
 Use `--env` only for non-secret values. Attach credentials to the sandbox with a
 provider instead of passing API keys, tokens, or other secrets to `sandbox exec`.
 

.agents/skills/openshell-cli/cli-reference.md

@@ -204,13 +204,17 @@ identity provider. Requires an authenticated gateway connection.
 
 ### `openshell sandbox create [OPTIONS] [-- COMMAND...]`
 
-Create a sandbox through the selected gateway, wait for readiness, then connect, open an editor, or execute the trailing command.
+Create a sandbox through the selected gateway and launch its canonical main
+process. By default, the CLI attaches to that retained process after the
+sandbox becomes ready. A trailing command defines the canonical main process;
+without one, the default is `/bin/bash -l` with a PTY.
 
 | Flag | Description |
 |------|-------------|
 | `--name <NAME>` | Sandbox name (auto-generated if omitted) |
 | `--from <SOURCE>` | Community name, Dockerfile path, directory, or image reference (BYOC) |
 | `--no-keep` | Delete the sandbox after the initial command or shell exits |
+| `--detach` | Start the canonical main process without attaching |
 | `--editor vscode|cursor` | Launch a remote editor and keep the sandbox alive |
 | `--gpu [COUNT]` | Request the driver's default GPU selection or a specific count |
 | `--cpu <QUANTITY>` | CPU limit (for example: `500m`, `1`, `2.5`) |
@@ -227,7 +231,12 @@ Create a sandbox through the selected gateway, wait for readiness, then connect,
 | `--approval-mode manual|auto` | Handle agent-authored policy proposals; default: `manual` |
 | `--upload <PATH>[:<DEST>]` | Upload local files to the working directory or an explicit destination (repeatable) |
 | `--no-git-ignore` | Disable `.gitignore` filtering for `--upload` |
-| `[-- COMMAND...]` | Initial command (defaults to an interactive shell) |
+| `[-- COMMAND...]` | Canonical main command (defaults to `/bin/bash -l`) |
+
+`--upload` cannot be combined with a trailing main command because uploads
+currently complete after the canonical process starts. Create the default
+scratch sandbox, upload files, then use `sandbox exec`, or build the files into
+the image.
 
 ### `openshell sandbox get [name]`
 
@@ -277,7 +286,13 @@ Execute a command through the gRPC exec endpoint, stream its output, and exit wi
 
 ### `openshell sandbox connect [name]`
 
-Open an interactive SSH shell. The name defaults to the last-used sandbox. `--editor vscode|cursor` launches a supported remote editor instead.
+Attach to the sandbox's retained canonical main process. Disconnecting leaves
+the process running. Reconnecting targets the same process instance and
+replays recent output. Use `sandbox exec --tty -- /bin/bash -l` when you need a
+new shell. The name defaults to the last-used sandbox.
+
+`--editor vscode|cursor` launches a supported remote editor instead of
+attaching to the canonical main process.
 
 ### `openshell sandbox upload <name> <path> [dest]`
 

architecture/compute-runtimes.md

@@ -13,6 +13,9 @@ Each runtime receives a sandbox spec from the gateway and is responsible for:
 - Injecting sandbox identity and gateway callback configuration.
 - Supplying TLS or secret material for supervisor callbacks.
 - Providing the supervisor binary or image in the workload.
+- Forwarding the exact canonical main-process argv and TTY mode without shell
+ reconstruction. The sandbox-level environment and policy workspace apply to
+ the main process.
 - Reporting lifecycle and platform events back to the gateway.
 - Cleaning up runtime-owned resources.
 
@@ -30,6 +33,10 @@ Process-identity omissions are preserved across this boundary so every driver
 can apply its native image or runtime defaults. Driver-requested listeners are
 structurally validated and remain restricted to sandbox callback RPCs.
 
+Canonical main-process support is part of the `ComputeDriver` contract. Every
+in-tree and extension driver must forward the exact specification; it is not an
+optional capability that drivers can omit or negotiate.
+
 Drivers own runtime-specific platform event interpretation. When an event should
 drive client provisioning UI, the driver attaches the shared
 `openshell.progress.*` metadata defined in `openshell-core` instead of requiring

architecture/gateway.md

@@ -15,11 +15,19 @@ workloads.
 - Resolve provider credentials and inference bundles for sandbox supervisors.
 - Coordinate supervisor relay sessions for connect, exec, file sync, and
  service forwarding.
+- Persist the canonical main-process instance ID and normalized exit code on
+ sandbox status. Any main process exit transitions the sandbox to `Error`,
+ including exit code zero.
 
 The gateway does not enforce agent network policy at request time. That happens
 inside each sandbox, where the supervisor and proxy can observe local process
 identity.
 
+The live supervisor session is the readiness authority for its main-process
+instance. The supervisor reports its normalized result through the
+sandbox-authenticated `ReportMainProcessExit` RPC, and the gateway rejects
+results from stale instance IDs.
+
 ## Protocol and Auth
 
 The gateway listens on one service port and multiplexes gRPC and HTTP traffic.

architecture/sandbox.md

@@ -29,10 +29,11 @@ only when the set is already empty; any other outcome fails the spawn.
  gateway, depending on mode.
 3. It prepares filesystem access, process restrictions, network namespace
  routing, trust stores, provider credential resolution, and inference routes.
-4. It starts the policy proxy and local SSH server.
-5. It opens a supervisor session back to the gateway for connect, exec, file
+4. It launches the persisted canonical main-process argv and retains its PTY
+ or pipes in the main-session multiplexer.
+5. It starts the policy proxy and local SSH server.
+6. It opens a supervisor session back to the gateway for connect, exec, file
  sync, config polling, and log push.
-6. It launches the agent command as the resolved restricted identity.
 
 ## Isolation Layers
 
@@ -359,8 +360,10 @@ The supervisor runs an SSH server on a Unix socket inside the sandbox. The
 gateway reaches it through the outbound supervisor relay, not by dialing the
 sandbox workload directly. The relay supports:
 
-- Interactive shell sessions.
-- Command execution.
+- Attachment to the canonical main process through the `openshell-main` SSH
+ subsystem. The supervisor owns its retained PTY or pipes, a 1 MiB replay
+ buffer, and a single stdin lease across client disconnects.
+- Independent shell and command execution sessions.
 - Tar-based file sync.
 - Port forwarding where supported by the CLI/TUI surface.
 
@@ -436,3 +439,7 @@ engine with a gateway policy revision.
  re-evaluate.
 - If the supervisor relay drops, the sandbox can keep running, but connect and
  exec operations fail until the supervisor registers again.
+- If the canonical main process exits, including with code 0, the supervisor
+ reports its normalized exit code before shutdown. The gateway persists the
+ code on sandbox status, records `MainProcessExited`, and makes the sandbox
+ terminal `Error`; runtime restart policies must not replace the process.

crates/openshell-cli/src/main.rs

@@ -1351,7 +1351,12 @@ enum SandboxCommands {
  /// working directory.
  /// `.gitignore` rules are applied by default; use `--no-git-ignore` to
  /// upload everything.
- #[arg(long, value_hint = ValueHint::AnyPath, help_heading = "UPLOAD FLAGS")]
+ #[arg(
+ long,
+ value_hint = ValueHint::AnyPath,
+ help_heading = "UPLOAD FLAGS",
+ conflicts_with = "command"
+ )]
  upload: Vec<String>,
 
  /// Disable `.gitignore` filtering for `--upload`.
@@ -1421,6 +1426,10 @@ enum SandboxCommands {
  #[arg(long, overrides_with = "tty")]
  no_tty: bool,
 
+ /// Start the canonical main process without attaching to it.
+ #[arg(long, conflicts_with_all = ["editor", "no_keep"])]
+ detach: bool,
+
  /// Auto-create missing providers from local credentials.
  ///
  /// Without this flag, an interactive prompt asks per-provider;
@@ -1594,6 +1603,7 @@ enum SandboxCommands {
  /// Connect to a sandbox.
  ///
  /// When no name is given, reconnects to the last-used sandbox.
+ /// Press Ctrl-P Ctrl-Q to disconnect without terminating the main process.
  #[command(help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")]
  Connect {
  /// Sandbox name (defaults to last-used sandbox).
@@ -2980,6 +2990,7 @@ async fn run_async() -> Result<()> {
  forward,
  tty,
  no_tty,
+ detach,
  auto_providers,
  no_auto_providers,
  labels,
@@ -3075,6 +3086,7 @@ async fn run_async() -> Result<()> {
  environment: env_map,
  approval_mode: &approval_mode,
  output: output.as_str(),
+ detach,
  },
  &cli.workspace,
  &tls,
@@ -5128,6 +5140,55 @@ mod tests {
  }
  }
 
+ #[test]
+ fn sandbox_create_detach_parses_with_main_command() {
+ let cli = Cli::try_parse_from([
+ "openshell",
+ "sandbox",
+ "create",
+ "--detach",
+ "--",
+ "worker",
+ "--serve",
+ ])
+ .expect("sandbox create --detach should parse");
+
+ match cli.command {
+ Some(Commands::Sandbox {
+ command:
+ Some(SandboxCommands::Create {
+ detach, command, ..
+ }),
+ ..
+ }) => {
+ assert!(detach);
+ assert_eq!(command, ["worker", "--serve"]);
+ }
+ other => panic!("expected SandboxCommands::Create, got: {other:?}"),
+ }
+ }
+
+ #[test]
+ fn sandbox_create_detach_rejects_ephemeral_sandbox() {
+ let result =
+ Cli::try_parse_from(["openshell", "sandbox", "create", "--detach", "--no-keep"]);
+ assert!(result.is_err());
+ }
+
+ #[test]
+ fn sandbox_create_rejects_upload_with_main_command() {
+ let result = Cli::try_parse_from([
+ "openshell",
+ "sandbox",
+ "create",
+ "--upload",
+ ".",
+ "--",
+ "./run-uploaded-app",
+ ]);
+ assert!(result.is_err());
+ }
+
  /// `sandbox create` defaults `--approval-mode` to `"manual"`. The CLI
  /// always sends an explicit value so the wire form is human-readable
  /// (the gateway treats `""` as `"manual"` too, but the CLI's job is to