feat(host): expose platform shell selection through the bus

crates/tinybox-bus/src/lib.rs

@@ -21,6 +21,11 @@ pub use grants::{LocalGrantConfig, LocalGrants, ProtectedPaths, ResolveLocalGran
 mod jail;
 pub use jail::{JailEnforcement, NativeJailConfig};
 
+mod shell_execution;
+mod shell_selection;
+pub use shell_execution::ShellExecRequest;
+pub use shell_selection::{SelectShellRequest, ShellFlavor, ShellInvocation};
+
 mod shell;
 pub use shell::{CommandAnalysis, CommandClass, CommandSegment};
 mod files;
@@ -42,8 +47,10 @@ pub use files::{
 /// bounded, module-owned one-shot Docker operation. 1.9 adds bounded Docker
 /// daemon status and label-scoped cleanup operations. 1.10 adds a bounded
 /// Docker command that does not mount a host workspace. 1.11 adds local grant
-/// discovery.
-pub const CONTRACT_VERSION: (u32, u32) = (1, 11);
+/// discovery. 1.12 adds platform shell selection. 1.13 adds supervised native
+/// shell execution on local passthrough resources.
+/// 1.14 adds native shell execution with owned scratch, timeout and optional jail.
+pub const CONTRACT_VERSION: (u32, u32) = (1, 14);
 
 /// Whether this host vocabulary can bind to a module's advertised version.
 /// The major must match and the module's minor must include every host member.
@@ -117,6 +124,9 @@ pub const METHODS: &[&str] = &[
     "CleanupDocker",
     "RunDockerWithoutWorkspace",
     "ResolveLocalGrants",
+    "SelectShell",
+    "StartShellExec",
+    "StartNativeShellExec",
 ];
 
 /// Facts about the detected native directory-jail backend.
@@ -554,3 +564,6 @@ mod tests;
 
 mod output;
 pub use output::{ExecutionFailure, ExecutionState, OutputBatch, OutputChunk, OutputStream};
+
+/// Invalid native shell execution inputs.
+pub const INVALID_SHELL_EXEC: &str = "ai.tinyhumans.tinybox.Error.InvalidShellExec";

crates/tinybox-bus/src/lib_tests.rs

@@ -46,15 +46,12 @@ fn docker_run_vocabulary_is_typed_bounded_and_additive() -> Result<(), serde_jso
         label: Some("openhuman.sandbox=true".into()),
         timeout_ms: 120_000,
     };
-    assert!(METHODS.contains(&"RunDocker"));
-    assert_eq!(METHODS.get(METHODS.len() - 3), Some(&"CleanupDocker"));
-    assert_eq!(
-        METHODS.get(METHODS.len() - 2),
-        Some(&"RunDockerWithoutWorkspace")
-    );
-    assert_eq!(METHODS.last(), Some(&"ResolveLocalGrants"));
-    assert!(METHODS.contains(&"RunDockerWithoutWorkspace"));
-    assert_eq!(CONTRACT_VERSION, (1, 11));
+    assert_eq!(METHODS[27], "RunDocker");
+    assert_eq!(METHODS[28], "DockerStatus");
+    assert_eq!(METHODS[29], "CleanupDocker");
+    assert_eq!(METHODS[30], "RunDockerWithoutWorkspace");
+    assert_eq!(METHODS.last(), Some(&"StartNativeShellExec"));
+    assert_eq!(CONTRACT_VERSION, (1, 14));
     assert_eq!(MAX_DOCKER_RUN_TIMEOUT_MS, 86_400_000);
     let serialized = serde_json::to_value(&request)?;
     assert_eq!(serialized["read_only_rootfs"], false);
@@ -132,7 +129,7 @@ fn host_gateway_and_docker_facts_are_additive_and_default_safely() -> Result<(),
 #[test]
 fn version_and_capability_wire_snapshot_preserve_contract_compatibility()
 -> Result<(), serde_json::Error> {
-    assert_eq!(CONTRACT_VERSION, (1, 11));
+    assert_eq!(CONTRACT_VERSION, (1, 14));
     assert!(is_compatible(CONTRACT_VERSION));
     assert!(!is_compatible((1, 8)));
     assert!(!is_compatible((1, 7)));
@@ -150,7 +147,7 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility()
         exec_backends: Vec::new(),
         spawn_backends: Vec::new(),
     };
-    let snapshot = serde_json::json!({"contract_version":[1,11],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]});
+    let snapshot = serde_json::json!({"contract_version":[1,14],"create_backends":["passthrough"],"exec_backends":[],"spawn_backends":[]});
     assert_eq!(serde_json::to_value(&capabilities)?, snapshot);
     assert_eq!(
         serde_json::from_value::<ModuleCapabilities>(snapshot)?,
@@ -161,18 +158,15 @@ fn version_and_capability_wire_snapshot_preserve_contract_compatibility()
 
 #[test]
 fn no_workspace_docker_operation_is_present_in_the_contract() {
-    assert_eq!(
-        METHODS.get(METHODS.len() - 2),
-        Some(&"RunDockerWithoutWorkspace")
-    );
+    assert_eq!(METHODS.get(30), Some(&"RunDockerWithoutWorkspace"));
     assert_eq!(
         METHODS
             .iter()
             .filter(|method| **method == "RunDockerWithoutWorkspace")
             .count(),
         1
     );
-    assert_eq!(CONTRACT_VERSION, (1, 11));
+    assert_eq!(CONTRACT_VERSION, (1, 14));
 }
 
 #[test]
@@ -278,3 +272,60 @@ fn local_grant_configuration_defaults_and_floor_round_trip() -> Result<(), serde
     );
     Ok(())
 }
+
+#[test]
+fn shell_selection_wire_defaults_preserve_safe_pipeline_behavior() -> Result<(), serde_json::Error>
+{
+    let request: SelectShellRequest =
+        serde_json::from_value(serde_json::json!({"command":"false | true"}))?;
+    assert!(!request.preserve_pipeline_status);
+    let invocation = ShellInvocation {
+        flavor: ShellFlavor::Cmd,
+        program: "cmd".into(),
+        arguments: vec!["/C".into()],
+        raw_arguments: Some(r#"echo "quoted payload""#.into()),
+        bootstrap_environment: vec!["SystemRoot".into()],
+        remove_environment: Vec::new(),
+    };
+    let value = serde_json::to_value(&invocation)?;
+    assert_eq!(value["flavor"], "cmd");
+    assert_eq!(value["raw_arguments"], r#"echo "quoted payload""#);
+    assert_eq!(
+        serde_json::from_value::<ShellInvocation>(value)?,
+        invocation
+    );
+    assert_eq!(METHODS[31], "ResolveLocalGrants");
+    assert_eq!(METHODS[32], "SelectShell");
+    assert!(!is_compatible((1, 9)));
+    Ok(())
+}
+
+#[test]
+fn older_shell_invocations_default_the_startup_removal_vocabulary() -> Result<(), serde_json::Error>
+{
+    let invocation: ShellInvocation = serde_json::from_value(serde_json::json!({
+        "flavor":"posix", "program":"sh", "arguments":["-c","true"],
+        "raw_arguments":null, "bootstrap_environment":[]
+    }))?;
+    assert_eq!(invocation.remove_environment, Vec::<String>::new());
+    Ok(())
+}
+
+#[test]
+fn native_shell_wire_defaults_close_stdin_and_keep_a_bounded_runtime()
+-> Result<(), serde_json::Error> {
+    let request: ShellExecRequest = serde_json::from_value(serde_json::json!({
+        "process":"process", "resource":"resource", "shell":{"command":"true"},
+        "state_dir":"/state"
+    }))?;
+    assert_eq!(request.timeout_ms, 30_000);
+    assert_eq!(request.stdin, None);
+    assert_eq!(request.cwd, None);
+    assert_eq!(request.jail, None);
+    assert_eq!(request.extra_env, std::collections::BTreeMap::new());
+    assert_eq!(METHODS[33], "StartShellExec");
+    assert_eq!(METHODS[34], "StartNativeShellExec");
+    assert!(!is_compatible((1, 13)));
+    assert!(!is_compatible((1, 10)));
+    Ok(())
+}

crates/tinybox-bus/src/output.rs

@@ -27,6 +27,8 @@ pub struct OutputChunk {
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(rename_all = "snake_case")]
 pub enum ExecutionFailure {
+    /// The runtime budget elapsed; supervised native cleanup is acknowledged.
+    TimedOut,
     /// The native operation could not start.
     StartFailed,
     /// Combined output exceeded the execution budget.

crates/tinybox-bus/src/shell_execution.rs

@@ -0,0 +1,35 @@
+//! Reserved native shell execution; authorization remains caller-owned.
+use crate::{NativeJailConfig, ResourceId, SelectShellRequest};
+use serde::{Deserialize, Serialize};
+use std::collections::BTreeMap;
+
+/// Start a local shell under module-owned supervision and output replay.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ShellExecRequest {
+    /// Caller-known process reservation.
+    pub process: ResourceId,
+    /// Existing local passthrough resource.
+    pub resource: ResourceId,
+    /// Shell payload and pipeline-status convention.
+    pub shell: SelectShellRequest,
+    /// Working directory inside the resource; absent means its root.
+    #[serde(default)]
+    pub cwd: Option<String>,
+    /// Approved overrides on the module's safe parent environment snapshot.
+    #[serde(default)]
+    pub extra_env: BTreeMap<String, String>,
+    /// Approved existing absolute private state directory for owned scratch.
+    pub state_dir: String,
+    /// Positive runtime budget, default thirty seconds, at most twenty-four hours.
+    #[serde(default = "default_timeout")]
+    pub timeout_ms: u64,
+    /// Binary input; absent closes stdin.
+    #[serde(default)]
+    pub stdin: Option<Vec<u8>>,
+    /// Explicit native confinement; absent is ordinary local execution.
+    #[serde(default)]
+    pub jail: Option<NativeJailConfig>,
+}
+const fn default_timeout() -> u64 {
+    30_000
+}

crates/tinybox-bus/src/shell_selection.rs

@@ -0,0 +1,45 @@
+//! Platform shell invocation vocabulary; selecting a shell grants no execution access.
+
+use serde::{Deserialize, Serialize};
+
+/// Command text and the desired pipeline exit-status convention.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct SelectShellRequest {
+    /// Text interpreted by the platform shell.
+    pub command: String,
+    /// Preserve the shell's ordinary last-stage pipeline status rather than
+    /// enabling Bash pipefail. Windows cmd has no pipefail mode.
+    #[serde(default)]
+    pub preserve_pipeline_status: bool,
+}
+
+/// Shell syntax used by the module machine.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "snake_case")]
+pub enum ShellFlavor {
+    /// Windows cmd syntax, including percent-variable expansion.
+    Cmd,
+    /// POSIX shell syntax, using Bash when available.
+    Posix,
+}
+
+/// Selected invocation, returned for discovery and consumed inside `TinyBox`.
+/// Hosts execute commands through the module rather than spawning this plan.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ShellInvocation {
+    /// Syntax understood by the selected shell.
+    pub flavor: ShellFlavor,
+    /// Shell executable on the module machine.
+    pub program: String,
+    /// Ordinary process arguments, excluding the executable.
+    pub arguments: Vec<String>,
+    /// Windows command payload appended verbatim after ordinary arguments.
+    /// Rust's ordinary argument escaping is incompatible with cmd quotes.
+    pub raw_arguments: Option<String>,
+    /// Parent environment names needed to bootstrap Windows child tools.
+    /// Values are never returned by shell discovery.
+    pub bootstrap_environment: Vec<String>,
+    /// Remove these startup-hook variables after applying the approved environment.
+    #[serde(default)]
+    pub remove_environment: Vec<String>,
+}

crates/tinybox-host/Cargo.toml

@@ -14,6 +14,8 @@ publish = false
 
 [dependencies]
 tinybox-core.workspace = true
+# Shell selection shares the module's serialized invocation vocabulary.
+tinybox-bus.workspace = true
 tinybox-jail.workspace = true
 async-trait.workspace = true
 # `Dir` keeps workspace file handles beneath the approved root without
@@ -25,8 +27,8 @@ cap-std = "4"
 tokio = { workspace = true, features = ["process", "io-util", "sync"] }
 
 [target.'cfg(unix)'.dependencies]
-# Safe process-group signalling keeps shell descendants within supervised cleanup.
-nix = { version = "0.30", default-features = false, features = ["signal", "process"] }
+# Safe process-group signalling supervises descendants; access checks select executable shells.
+nix = { version = "0.30", default-features = false, features = ["signal", "process", "fs"] }
 
 [target.'cfg(windows)'.dependencies]
 # Job Objects keep supervised Windows descendants inside one killable process tree.

crates/tinybox-host/src/lib.rs

@@ -48,3 +48,6 @@ mod local;
 pub use limited::{JailLocalHost, LimitedLocalHost, ManagedProcess};
 
 pub use local::{LocalHost, NAME as LOCAL};
+
+/// Platform shell discovery and command construction owned by the local host.
+pub use local::shell::{build_shell_command, select_shell};

crates/tinybox-host/src/limited/jailed.rs

@@ -171,6 +171,34 @@ impl JailLocalHost {
         let mut command = crate::LocalHost::command(request)?.into_std();
         // The host explicitly supplies the approved environment for jailed code.
         command.env_clear().envs(&request.env);
+        self.collect_command(command, request.stdin.clone(), observer)
+            .await
+    }
+
+    /// Collect a prepared shell inside this host's explicit native jail.
+    /// The caller clears and supplies the approved environment before invocation.
+    /// # Errors
+    /// Reports unavailable spawn, output bounds and retained kill/reap failures.
+    pub async fn run_command_observed(
+        &self,
+        mut command: std::process::Command,
+        payload: Option<Vec<u8>>,
+        observer: Arc<dyn ExecutionObserver>,
+    ) -> Result<ExecOutput> {
+        command.stdin(if payload.is_some() {
+            std::process::Stdio::piped()
+        } else {
+            std::process::Stdio::null()
+        });
+        self.collect_command(command, payload, Some(observer)).await
+    }
+
+    async fn collect_command(
+        &self,
+        mut command: std::process::Command,
+        payload: Option<Vec<u8>>,
+        observer: Option<Arc<dyn ExecutionObserver>>,
+    ) -> Result<ExecOutput> {
         #[cfg(unix)]
         {
             use std::os::unix::process::CommandExt;
@@ -181,7 +209,6 @@ impl JailLocalHost {
             .stderr(std::process::Stdio::piped());
         let jail = self.jail.clone();
         let backend = self.backend.clone();
-        let payload = request.stdin.clone();
         let state = self.state.clone();
         let limit = self.limit;
         let runtime = tokio::runtime::Handle::try_current()