You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@maka.apache.org by wy...@apache.org on 2026/09/16 01:18:43 UTC

(maka) 24/29: feat(host): bridge native connections and repair explicit WSL remounts

This is an automated email from the ASF dual-hosted git repository.

M4n5ter pushed a commit to branch feat/runtime-host-rust
in repository https://gitbox.apache.org/repos/asf/maka.git

commit a41cb84e60c1a6e16f21ca2c3fa1f2229c9f62e4
Author: Wang <m4...@gmail.com>
AuthorDate: Tue Sep 15 23:29:39 2026 +0800

    feat(host): bridge native connections and repair explicit WSL remounts
    
    Generated-by: OpenAI Codex
---
 crates/cli/Cargo.toml                      |   2 +-
 crates/cli/src/args.rs                     |   3 +
 crates/cli/src/deployment.rs               |   2 +
 crates/cli/src/deployment/activation.rs    |  61 ++++++---
 crates/cli/src/deployment/connect.rs       | 192 +++++++++++++++++++++++++++++
 crates/cli/src/host_client.rs              |  50 +++++---
 crates/cli/src/main.rs                     |   1 +
 crates/cli/src/stdio.rs                    |  69 +++++++++++
 crates/cli/tests/integration/deployment.rs |  13 +-
 crates/event-log/src/root.rs               |  92 +++++++++++++-
 crates/event-log/tests/root_authority.rs   |  87 +++++++------
 crates/event-log/tests/root_lease.rs       |  65 ++++++++++
 docs/rust-runtime.md                       |   7 ++
 docs/rust-runtime.zh-CN.md                 |   7 +-
 tests/fixtures/client-bridge-entry.mjs     | 136 ++++++++++++++++++++
 tests/fixtures/client.mjs                  |   1 +
 16 files changed, 707 insertions(+), 81 deletions(-)

diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml
index 1899c46650..0ca19955ba 100644
--- a/crates/cli/Cargo.toml
+++ b/crates/cli/Cargo.toml
@@ -50,7 +50,7 @@ serde_json.workspace = true
 sha2.workspace = true
 sqlx.workspace = true
 tokio = { workspace = true, features = ["process"] }
-tokio-util.workspace = true
+tokio-util = { workspace = true, features = ["io-util"] }
 uuid.workspace = true
 tempfile.workspace = true
 
diff --git a/crates/cli/src/args.rs b/crates/cli/src/args.rs
index c3a46e826d..7b74506679 100644
--- a/crates/cli/src/args.rs
+++ b/crates/cli/src/args.rs
@@ -53,6 +53,8 @@ enum HostCommand {
     Install(crate::deployment::Install),
     /// Activate an installed Host and report its verified loopback endpoint.
     Activate(crate::deployment::Activate),
+    /// Connect an installed Host to stdin/stdout using the client wire protocol.
+    Connect(crate::deployment::Connect),
     /// Update a deployment to this executable at a safe boundary.
     Update(crate::deployment::Update),
     /// Finish an interrupted deployment update without choosing another target.
@@ -117,6 +119,7 @@ impl Cli {
             Command::Host(HostCommand::Candidate(args)) => args.run().await,
             Command::Host(HostCommand::Install(args)) => args.run().await,
             Command::Host(HostCommand::Activate(args)) => args.run().await,
+            Command::Host(HostCommand::Connect(args)) => args.run().await,
             Command::Host(HostCommand::Update(args)) => args.run(false).await,
             Command::Host(HostCommand::Reconcile(args)) => args.run(true).await,
             Command::Host(HostCommand::Stop(args)) => {
diff --git a/crates/cli/src/deployment.rs b/crates/cli/src/deployment.rs
index 7e4a9146e2..cf118f5570 100644
--- a/crates/cli/src/deployment.rs
+++ b/crates/cli/src/deployment.rs
@@ -18,6 +18,7 @@
  */
 
 mod activation;
+mod connect;
 mod control;
 mod entry;
 mod logs;
@@ -28,6 +29,7 @@ mod store;
 mod update;
 mod updates;
 pub(super) use activation::Activate;
+pub(super) use connect::Connect;
 pub(super) use control::{Control, ControlAction};
 pub(super) use entry::ServiceRun;
 pub(super) use logs::Logs;
diff --git a/crates/cli/src/deployment/activation.rs b/crates/cli/src/deployment/activation.rs
index 9933162d32..244f5e0971 100644
--- a/crates/cli/src/deployment/activation.rs
+++ b/crates/cli/src/deployment/activation.rs
@@ -40,6 +40,9 @@ pub(crate) struct Activate {
     root_id: RootId,
     #[arg(long)]
     framed: bool,
+    /// Confirm the same Linux filesystem was remounted, preserving root identity.
+    #[arg(long)]
+    repair_root_after_remount: bool,
 }
 
 #[derive(Serialize)]
@@ -102,22 +105,7 @@ impl Activate {
     }
 
     async fn activate(&self) -> Result<(), HostError> {
-        let directory = directory(&self.root_id.0)?;
-        // Activation never creates a deployment database.
-        if !directory.is_dir() {
-            return Err("Host deployment is not installed".into());
-        }
-        let lease = Arc::new(FileLease::acquire(&directory.join("executor.lock"))?);
-        let store::Installation::Installed(deployment) = store::read(&directory).await? else {
-            return Err("Host deployment is absent or incomplete".into());
-        };
-        let root = root::resolve(&deployment.root_path)?;
-        if root.root_id() != self.root_id.0 {
-            return Err("deployment root identity changed".into());
-        }
-        deployment.validate(&root, &directory)?;
-        deployment.require_active()?;
-        lease.validate()?;
+        let (deployment, lease) = prepare(&self.root_id, self.repair_root_after_remount).await?;
         let (client, live) = connect_or_launch(&deployment, lease.clone()).await?;
         lease.validate()?;
         emit(
@@ -143,6 +131,47 @@ impl Activate {
     }
 }
 
+pub(super) async fn prepare(
+    root_id: &RootId,
+    repair: bool,
+) -> Result<(Deployment, Arc<FileLease>), HostError> {
+    let directory = directory(&root_id.0)?;
+    // Activation never creates a deployment database.
+    if !directory.is_dir() {
+        return Err("Host deployment is not installed".into());
+    }
+    let lease = Arc::new(FileLease::acquire(&directory.join("executor.lock"))?);
+    let store::Installation::Installed(deployment) = store::read(&directory).await? else {
+        return Err("Host deployment is absent or incomplete".into());
+    };
+    deployment.validate_record(&directory)?;
+    deployment.require_active()?;
+    if deployment.root_id != root_id.0 {
+        return Err("deployment root identity changed".into());
+    }
+    if repair {
+        let path = deployment.root_path.clone();
+        let expected = root_id.0.clone();
+        let lease = lease.clone();
+        tokio::task::spawn_blocking(move || {
+            lease.validate()?;
+            if path.canonicalize()? != path {
+                return Err(std::io::Error::other("deployment root path was rebound"));
+            }
+            root::repair_after_remount(&path, &expected, &RootNamespaces::for_current_account()?)?;
+            lease.validate()
+        })
+        .await??;
+    }
+    let root = root::resolve(&deployment.root_path)?;
+    if root.root_id() != root_id.0 {
+        return Err("deployment root identity changed".into());
+    }
+    deployment.validate(&root, &directory)?;
+    lease.validate()?;
+    Ok((deployment, lease))
+}
+
 pub(super) async fn connect_or_launch(
     deployment: &Deployment,
     lease: Arc<FileLease>,
diff --git a/crates/cli/src/deployment/connect.rs b/crates/cli/src/deployment/connect.rs
new file mode 100644
index 0000000000..1134abc951
--- /dev/null
+++ b/crates/cli/src/deployment/connect.rs
@@ -0,0 +1,192 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use super::{RootId, activation};
+use clap::Args;
+use maka_protocol::{
+    MAX_MESSAGE_BYTES,
+    handshake::{HostHandshake, decode_hello, decode_host_handshake},
+};
+use maka_runtime_host::server::HostError;
+use std::time::Duration;
+use tokio::io::{
+    AsyncBufRead, AsyncBufReadExt, AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt, BufReader,
+};
+use tokio_util::sync::CancellationToken;
+
+#[derive(Args)]
+pub(crate) struct Connect {
+    #[arg(long)]
+    root_id: RootId,
+    #[arg(long = "framed", required = true)]
+    _framed: bool,
+    /// Confirm the same Linux filesystem was remounted, preserving root identity.
+    #[arg(long)]
+    repair_root_after_remount: bool,
+}
+
+impl Connect {
+    pub async fn run(self) -> Result<(), HostError> {
+        let crate::stdio::Stdio {
+            input,
+            mut output,
+            mut output_done,
+        } = crate::stdio::Stdio::open()?;
+        let cancel = CancellationToken::new();
+        let _signals = crate::signals::watch(cancel.clone())?;
+        let result = tokio::select! {
+            result = self.bridge(BufReader::new(input), &mut output) => result,
+            _ = cancel.cancelled() => Ok(()),
+            result = &mut output_done => {
+                result??;
+                return Err("Host bridge output closed".into());
+            }
+        };
+        // Duplex shutdown alone only proves that bytes were queued. Wait for
+        // the stdout worker's final flush, bounded even if the consumer stalls.
+        drop(output);
+        let flushed = tokio::time::timeout(Duration::from_secs(5), output_done)
+            .await
+            .map_err(HostError::from)
+            .and_then(|result| result.map_err(HostError::from))
+            .and_then(|result| result.map_err(HostError::from));
+        result.and(flushed)
+    }
+
+    async fn bridge(
+        &self,
+        mut input: impl AsyncBufRead + Unpin,
+        output: &mut (impl AsyncWrite + Unpin),
+    ) -> Result<(), HostError> {
+        // A silent client must not reserve the deployment executor or start a Host.
+        let hello = tokio::time::timeout(Duration::from_secs(5), frame(&mut input)).await??;
+        decode_hello(&maka_protocol::decode_message(&hello)?)?;
+        let (deployment, lease) =
+            activation::prepare(&self.root_id, self.repair_root_after_remount).await?;
+        let (probe, live) = activation::connect_or_launch(&deployment, lease.clone()).await?;
+        let mut stream = probe.open_bridge().await?;
+        let mut stream = BufReader::new(&mut stream);
+        let accepted = tokio::time::timeout(Duration::from_secs(5), async {
+            stream.write_all(&hello).await?;
+            stream.write_all(b"\n").await?;
+            stream.flush().await?;
+            let reply = frame(&mut stream).await?;
+            let handshake = decode_host_handshake(&maka_protocol::decode_message(&reply)?)?;
+            if let HostHandshake::Accepted {
+                root_id,
+                host_epoch,
+                ..
+            } = &handshake
+                && (root_id != &deployment.root_id || host_epoch != &live.epoch)
+            {
+                return Err::<_, HostError>(
+                    "Host changed between activation and bridge handshake".into(),
+                );
+            }
+            Ok((reply, matches!(handshake, HostHandshake::Accepted { .. })))
+        })
+        .await??;
+        lease.validate()?;
+        drop(probe);
+        drop(lease);
+        output.write_all(&accepted.0).await?;
+        output.write_all(b"\n").await?;
+        output.flush().await?;
+        if !accepted.1 {
+            return Ok(());
+        }
+        // Keep both BufReaders: either may already own pipelined bytes beyond hello.
+        relay(&mut input, output, stream).await?;
+        Ok(())
+    }
+}
+
+async fn relay(
+    input: &mut (impl AsyncRead + Unpin),
+    output: &mut (impl AsyncWrite + Unpin),
+    stream: impl AsyncRead + AsyncWrite + Unpin,
+) -> std::io::Result<()> {
+    let (mut read, mut write) = tokio::io::split(stream);
+    let downstream = tokio::io::copy(&mut read, output);
+    tokio::pin!(downstream);
+    tokio::select! {
+        result = tokio::io::copy(input, &mut write) => {
+            result?;
+            #[cfg(unix)]
+            {
+                // Preserve this same copy future: it may own a partially
+                // written response buffer while stdout applies backpressure.
+                write.shutdown().await?;
+                downstream.await?;
+            }
+            // Windows named pipes cannot half-close. EOF disconnects the
+            // client without promising queued writes or final responses;
+            // it never retires the independently owned Host.
+        },
+        result = &mut downstream => { result?; },
+    }
+    Ok(())
+}
+
+async fn frame(reader: &mut (impl AsyncBufRead + Unpin)) -> Result<Vec<u8>, HostError> {
+    let mut bytes = Vec::new();
+    reader
+        .take(MAX_MESSAGE_BYTES as u64 + 2)
+        .read_until(b'\n', &mut bytes)
+        .await?;
+    if bytes.last() != Some(&b'\n') || bytes.len() > MAX_MESSAGE_BYTES + 1 {
+        return Err("Host bridge greeting is incomplete or too large".into());
+    }
+    bytes.pop();
+    Ok(bytes)
+}
+
+#[cfg(all(test, unix))]
+mod tests {
+    use super::*;
+
+    #[tokio::test]
+    async fn input_eof_preserves_a_response_already_blocked_on_output() {
+        tokio::time::timeout(Duration::from_secs(5), async {
+            let (mut sender, mut input) = tokio::io::duplex(16);
+            let (mut output, mut receiver) = tokio::io::duplex(1);
+            let (stream, server) = tokio::io::duplex(16 * 1024);
+            let bridge = tokio::spawn(async move { relay(&mut input, &mut output, stream).await });
+            let (mut server_read, mut server_write) = tokio::io::split(server);
+            let payload: Vec<_> = (0..128 * 1024).map(|index| (index % 251) as u8).collect();
+            let expected = payload.clone();
+            let server = tokio::spawn(async move {
+                server_write.write_all(&payload).await.unwrap();
+                server_write.shutdown().await.unwrap();
+            });
+            let first = receiver.read_u8().await.unwrap();
+            sender.shutdown().await.unwrap();
+            // This EOF proves the bridge handled input EOF while downstream
+            // was blocked, before allowing the output consumer to drain.
+            assert_eq!(server_read.read(&mut [0]).await.unwrap(), 0);
+            let mut actual = vec![first];
+            receiver.read_to_end(&mut actual).await.unwrap();
+            assert_eq!(actual, expected);
+            bridge.await.unwrap().unwrap();
+            server.await.unwrap();
+        })
+        .await
+        .unwrap();
+    }
+}
diff --git a/crates/cli/src/host_client.rs b/crates/cli/src/host_client.rs
index 7a9b6221ad..2916dbd4cd 100644
--- a/crates/cli/src/host_client.rs
+++ b/crates/cli/src/host_client.rs
@@ -37,9 +37,9 @@ use tokio::io::{ReadHalf, WriteHalf};
 use tokio_util::sync::CancellationToken;
 
 #[cfg(unix)]
-type Stream = tokio::net::UnixStream;
+pub(super) type Stream = tokio::net::UnixStream;
 #[cfg(windows)]
-type Stream = tokio::net::windows::named_pipe::NamedPipeClient;
+pub(super) type Stream = tokio::net::windows::named_pipe::NamedPipeClient;
 
 /// Discovery is only a hint. The live handshake must confirm both root and epoch.
 #[derive(Deserialize)]
@@ -72,22 +72,7 @@ impl HostClient {
         let root = root.to_owned();
         tokio::time::timeout(Duration::from_secs(5), async move {
             let discovery = tokio::task::spawn_blocking(move || read_discovery(&root)).await??;
-            #[cfg(unix)]
-            let stream = Stream::connect(&discovery.endpoint).await?;
-            #[cfg(windows)]
-            let stream = {
-                use tokio::net::windows::named_pipe::ClientOptions;
-                loop {
-                    match ClientOptions::new().open(&discovery.endpoint) {
-                        Ok(stream) => break stream,
-                        // An existing pipe instance may be between accepts.
-                        Err(error) if error.raw_os_error() == Some(231) => {
-                            tokio::time::sleep(Duration::from_millis(10)).await
-                        }
-                        Err(error) => return Err(error.into()),
-                    }
-                }
-            };
+            let stream = open_stream(&discovery.endpoint).await?;
             let (mut reader, mut writer) =
                 maka_transport::ndjson::split(stream, CancellationToken::new());
             writer
@@ -128,6 +113,16 @@ impl HostClient {
         .await?
     }
 
+    /// A fresh connection to this verified epoch, not a second discovery lookup.
+    /// The bridge must still check its own handshake before forwarding requests.
+    pub async fn open_bridge(&self) -> Result<Stream, HostError> {
+        tokio::time::timeout(
+            Duration::from_secs(5),
+            open_stream(&self.discovery.endpoint),
+        )
+        .await?
+    }
+
     pub async fn status(&mut self) -> Result<Value, HostError> {
         let result = self.request(Operation::HostStatus, json!({})).await?;
         if result["hostEpoch"] != self.discovery.host_epoch {
@@ -235,6 +230,25 @@ impl HostClient {
     }
 }
 
+async fn open_stream(endpoint: &Path) -> Result<Stream, HostError> {
+    #[cfg(unix)]
+    return Ok(Stream::connect(endpoint).await?);
+    #[cfg(windows)]
+    {
+        use tokio::net::windows::named_pipe::ClientOptions;
+        loop {
+            match ClientOptions::new().open(endpoint) {
+                Ok(stream) => return Ok(stream),
+                // An existing pipe instance may be between accepts.
+                Err(error) if error.raw_os_error() == Some(231) => {
+                    tokio::time::sleep(Duration::from_millis(10)).await;
+                }
+                Err(error) => return Err(error.into()),
+            }
+        }
+    }
+}
+
 fn read_discovery(path: &Path) -> Result<Discovery, HostError> {
     let root = root::resolve(path)?;
     let path = RootNamespaces::for_current_account()?
diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs
index d50ec1fc8b..54565ddcad 100644
--- a/crates/cli/src/main.rs
+++ b/crates/cli/src/main.rs
@@ -26,6 +26,7 @@ mod endpoint;
 mod host_client;
 mod serve;
 mod signals;
+mod stdio;
 #[cfg(windows)]
 mod windows;
 
diff --git a/crates/cli/src/stdio.rs b/crates/cli/src/stdio.rs
new file mode 100644
index 0000000000..76f6cd587f
--- /dev/null
+++ b/crates/cli/src/stdio.rs
@@ -0,0 +1,69 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+use std::io::{self, Read, Write};
+use tokio::{io::DuplexStream, sync::oneshot};
+use tokio_util::io::SyncIoBridge;
+
+/// Process-lifetime stdio workers own no Host, deployment or effect leases.
+/// An open input pipe or blocked output must not hold Tokio shutdown hostage.
+pub(super) struct Stdio {
+    pub input: DuplexStream,
+    pub output: DuplexStream,
+    pub output_done: oneshot::Receiver<io::Result<()>>,
+}
+
+impl Stdio {
+    pub fn open() -> io::Result<Self> {
+        let (input, writer) = tokio::io::duplex(32 * 1024);
+        let (output, reader) = tokio::io::duplex(32 * 1024);
+        let mut writer = SyncIoBridge::new(writer);
+        let mut reader = SyncIoBridge::new(reader);
+        let (done, output_done) = oneshot::channel();
+        std::thread::Builder::new()
+            .name("bridge-stdin".into())
+            .spawn(move || {
+                // EOF drops the duplex writer. The async caller also checks for
+                // a partial greeting before allowing any Host activation.
+                let _ = io::copy(&mut io::stdin().lock(), &mut writer);
+            })?;
+        std::thread::Builder::new()
+            .name("bridge-stdout".into())
+            .spawn(move || {
+                let result = (|| {
+                    let mut stdout = io::stdout().lock();
+                    let mut bytes = [0; 16 * 1024];
+                    loop {
+                        let count = reader.read(&mut bytes)?;
+                        if count == 0 {
+                            return stdout.flush();
+                        }
+                        stdout.write_all(&bytes[..count])?;
+                        stdout.flush()?;
+                    }
+                })();
+                let _ = done.send(result);
+            })?;
+        Ok(Self {
+            input,
+            output,
+            output_done,
+        })
+    }
+}
diff --git a/crates/cli/tests/integration/deployment.rs b/crates/cli/tests/integration/deployment.rs
index 49c2cee458..bcd8baa928 100644
--- a/crates/cli/tests/integration/deployment.rs
+++ b/crates/cli/tests/integration/deployment.rs
@@ -242,9 +242,16 @@ fn managed_installation_pins_code_before_migration_and_preserves_live_authority(
         assert_eq!(observed["host"]["identity"]["pid"], registration["pid"]);
         assert_eq!(observed["host"]["activity"]["state"], "ready");
         assert!(RootOwner::open(&fixture.root, &namespaces).is_err());
-        let retired = Command::new(env!("CARGO_BIN_EXE_maka"))
-            .args(["host", "retire", "--root"])
-            .arg(&fixture.root)
+        let retired = Command::new("node")
+            .arg(Path::new(env!("CARGO_MANIFEST_DIR")).join("../../tests/fixtures/client.mjs"))
+            .args([
+                "--bridge",
+                env!("CARGO_BIN_EXE_maka"),
+                "--root-id",
+                &fixture.root_id,
+                "--host-epoch",
+                registration["hostEpoch"].as_str().unwrap(),
+            ])
             .output()
             .unwrap();
         assert!(
diff --git a/crates/event-log/src/root.rs b/crates/event-log/src/root.rs
index 29d23ae572..afb5d74bc8 100644
--- a/crates/event-log/src/root.rs
+++ b/crates/event-log/src/root.rs
@@ -38,6 +38,7 @@ pub const ROOT_MARKER: &str = ".maka-storage-root.json";
 pub const RUST_ROOT_MARKER: &str = ".maka-rust-runtime.json";
 pub const ROOT_DATABASE: &str = "runtime-rust.sqlite";
 const PROTOTYPE: &[u8] = b"{\"schemaVersion\":1,\"runtime\":\"rust-prototype\"}\n";
+const REMOUNT_STAGING: &str = ".maka-storage-root.next";
 
 #[derive(Debug, Clone)]
 pub struct RootNamespaces {
@@ -66,7 +67,7 @@ impl RootNamespaces {
     }
 }
 
-#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
 #[serde(rename_all = "camelCase")]
 struct Marker {
     schema_version: u8,
@@ -75,7 +76,7 @@ struct Marker {
     root_identity: Identity,
 }
 
-#[derive(Debug, Serialize, Deserialize, PartialEq, Eq)]
+#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq)]
 struct Identity {
     dev: String,
     ino: String,
@@ -117,6 +118,72 @@ pub fn resolve(path: &Path) -> io::Result<RootLocation> {
     })
 }
 
+/// Explicitly confirm an unchanged Linux directory after its filesystem was
+/// remounted. Equal inode numbers alone do not establish identity across volumes.
+/// A matching root is a read-only no-op, including while its Host is running.
+pub fn repair_after_remount(
+    path: &Path,
+    expected_root_id: &str,
+    namespaces: &RootNamespaces,
+) -> io::Result<()> {
+    let canonical_path = path.canonicalize()?;
+    let identity = directory_identity(&canonical_path)?;
+    check_layout(&canonical_path)?;
+    let previous = read_marker(&canonical_path)?;
+    if previous.root_id != expected_root_id
+        || directory_identity(&canonical_path)? != identity
+        || canonical_path.canonicalize()? != canonical_path
+    {
+        return Err(io::Error::other("root changed before remount confirmation"));
+    }
+    if previous.root_identity == identity {
+        return Ok(());
+    }
+    if !cfg!(target_os = "linux") || previous.root_identity.ino != identity.ino {
+        return Err(io::Error::other("root is not an unchanged Linux remount"));
+    }
+    let mut next = previous.clone();
+    next.root_identity = identity;
+    // Use the same two ownership locks as normal Host startup, not executor.lock
+    // or FileLease: Linux's TS-compatible OFD locks are distinct from flock.
+    let owner = RootOwner::acquire(canonical_path, next, namespaces)?;
+    let validate = || {
+        owner.check_directory()?;
+        owner.validate_leases()?;
+        if read_marker(&owner.canonical_path)? != previous {
+            return Err(io::Error::other(
+                "root marker changed during remount confirmation",
+            ));
+        }
+        owner.check_directory()
+    };
+    validate()?;
+    let staging = owner.canonical_path.join(REMOUNT_STAGING);
+    match staging.symlink_metadata() {
+        Ok(metadata) if metadata.is_file() => fs::remove_file(&staging)?,
+        Ok(_) => return Err(io::Error::other("remount staging is not a regular file")),
+        Err(error) if error.kind() == io::ErrorKind::NotFound => {}
+        Err(error) => return Err(error),
+    }
+    let mut options = fs::OpenOptions::new();
+    options.write(true).create_new(true);
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::OpenOptionsExt;
+        options.mode(0o600);
+    }
+    let mut file = options.open(&staging)?;
+    file.write_all(&serde_json::to_vec(&owner.marker)?)?;
+    file.sync_all()?;
+    lock::stable(&file, &staging)?;
+    validate()?;
+    fs::rename(&staging, owner.canonical_path.join(ROOT_MARKER))?;
+    // On an uncertain rename/fsync result, stop. The next call re-reads the
+    // official marker; it never promotes or trusts an abandoned staging file.
+    File::open(&owner.canonical_path)?.sync_all()?;
+    owner.validate_current()
+}
+
 fn inspect(path: &Path) -> io::Result<(PathBuf, Marker)> {
     let canonical_path = path.canonicalize()?;
     let identity = directory_identity(&canonical_path)?;
@@ -170,6 +237,16 @@ impl RootOwner {
     /// Open only a marked Rust prototype root, rejecting legacy layouts before database access.
     pub fn open(path: &Path, namespaces: &RootNamespaces) -> io::Result<Self> {
         let (canonical_path, marker) = inspect(path)?;
+        let owner = Self::acquire(canonical_path, marker, namespaces)?;
+        owner.validate_current()?;
+        Ok(owner)
+    }
+
+    fn acquire(
+        canonical_path: PathBuf,
+        marker: Marker,
+        namespaces: &RootNamespaces,
+    ) -> io::Result<Self> {
         lock::private_directory(&namespaces.ownership)?;
         let lock_path = namespaces
             .ownership
@@ -179,16 +256,14 @@ impl RootOwner {
         let control_directory = namespaces.control.join(&marker.root_id);
         lock::private_directory(&control_directory)?;
         let compatibility_lease = lock::acquire(&control_directory.join("owner.lock"))?;
-        let owner = Self {
+        Ok(Self {
             canonical_path,
             marker,
             control_directory,
             lock_path,
             durable_lease,
             compatibility_lease,
-        };
-        owner.validate_current()?;
-        Ok(owner)
+        })
     }
 
     pub fn canonical_path(&self) -> &Path {
@@ -215,6 +290,10 @@ impl RootOwner {
         if marker != self.marker {
             return Err(io::Error::other("root marker identity changed"));
         }
+        self.validate_leases()
+    }
+
+    fn validate_leases(&self) -> io::Result<()> {
         lock::stable(&self.durable_lease, &self.lock_path)?;
         lock::stable(
             &self.compatibility_lease,
@@ -306,6 +385,7 @@ fn check_layout(path: &Path) -> io::Result<()> {
             name.to_str(),
             Some(
                 ROOT_MARKER
+                    | REMOUNT_STAGING
                     | RUST_ROOT_MARKER
                     | ROOT_DATABASE
                     | "runtime-rust.sqlite-wal"
diff --git a/crates/event-log/tests/root_authority.rs b/crates/event-log/tests/root_authority.rs
index 2c8b448af8..5121d35320 100644
--- a/crates/event-log/tests/root_authority.rs
+++ b/crates/event-log/tests/root_authority.rs
@@ -18,7 +18,7 @@
  */
 
 use maka_event_log::root::{ROOT_MARKER, RUST_ROOT_MARKER, RootNamespaces, RootOwner};
-use std::{fs, path::Path, process::Command};
+use std::{fs, path::Path};
 
 fn namespaces(base: &Path) -> RootNamespaces {
     RootNamespaces {
@@ -64,17 +64,67 @@ fn copied_marker_and_rebound_path_cannot_reuse_identity() {
     let path = temp.path().join("root");
     let owner = RootOwner::create(&path, &ns).unwrap();
     let copy = temp.path().join("copy");
+    maka_event_log::root::repair_after_remount(&path, owner.root_id(), &ns).unwrap();
+    assert!(maka_event_log::root::repair_after_remount(&path, &"0".repeat(64), &ns).is_err());
     fs::create_dir(&copy).unwrap();
     for name in [ROOT_MARKER, RUST_ROOT_MARKER] {
         fs::copy(path.join(name), copy.join(name)).unwrap();
     }
     assert!(RootOwner::open(&copy, &ns).is_err());
     assert!(maka_event_log::root::resolve(&copy).is_err());
+    assert!(maka_event_log::root::repair_after_remount(&copy, owner.root_id(), &ns).is_err());
     fs::rename(&path, temp.path().join("moved")).unwrap();
     fs::rename(&copy, &path).unwrap();
     assert!(owner.validate_current().is_err());
 }
 
+#[test]
+#[cfg(target_os = "linux")]
+fn explicit_remount_preserves_authority_and_recovers_only_its_staging_file() {
+    use maka_event_log::root::{repair_after_remount, resolve};
+    let temp = tempfile::tempdir().unwrap();
+    let ns = namespaces(temp.path());
+    let path = temp.path().join("root");
+    let owner = RootOwner::create(&path, &ns).unwrap();
+    let id = owner.root_id().to_owned();
+    let marker = path.join(ROOT_MARKER);
+    let original: serde_json::Value = serde_json::from_slice(&fs::read(&marker).unwrap()).unwrap();
+    let mut stale = original.clone();
+    stale["rootIdentity"]["dev"] = serde_json::json!("0");
+    fs::write(&marker, serde_json::to_vec(&stale).unwrap()).unwrap();
+    assert!(resolve(&path).is_err());
+    assert!(
+        repair_after_remount(&path, &id, &ns).is_err(),
+        "repair bypassed the live owner lease"
+    );
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(&fs::read(&marker).unwrap()).unwrap(),
+        stale
+    );
+    drop(owner);
+    let staging = path.join(".maka-storage-root.next");
+    fs::write(&staging, b"abandoned partial write").unwrap();
+    repair_after_remount(&path, &id, &ns).unwrap();
+    assert!(!staging.exists());
+    assert_eq!(
+        serde_json::from_slice::<serde_json::Value>(&fs::read(&marker).unwrap()).unwrap(),
+        original
+    );
+    let owner = RootOwner::open(&path, &ns).unwrap();
+    fs::write(&staging, b"never promote this").unwrap();
+    repair_after_remount(&path, &id, &ns).unwrap();
+    assert!(
+        staging.exists(),
+        "no-op must not acquire leases just to clean staging"
+    );
+    owner.validate_current().unwrap();
+    drop(owner);
+    stale["rootIdentity"]["ino"] = serde_json::json!("0");
+    fs::write(&marker, serde_json::to_vec(&stale).unwrap()).unwrap();
+    assert!(repair_after_remount(&path, &id, &ns).is_err());
+    assert_eq!(fs::read(staging).unwrap(), b"never promote this");
+}
+
 #[test]
 #[cfg(unix)]
 fn legacy_and_unsafe_markers_fail_closed() {
@@ -104,38 +154,3 @@ fn legacy_and_unsafe_markers_fail_closed() {
     fs::write(path.join(ROOT_MARKER), vec![b' '; 1025]).unwrap();
     assert!(owner.validate_current().is_err());
 }
-
-#[test]
-fn durable_lease_blocks_other_process_even_after_cache_removal() {
-    if let Some(base) = std::env::var_os("MAKA_ROOT_AUTHORITY_TEST_BASE") {
-        let base = Path::new(&base);
-        let error = RootOwner::open(&base.join("root"), &namespaces(base))
-            .err()
-            .unwrap();
-        assert_eq!(error.kind(), std::io::ErrorKind::WouldBlock);
-        return;
-    }
-    let temp = tempfile::tempdir().unwrap();
-    let ns = namespaces(temp.path());
-    let path = temp.path().join("root");
-    let owner = RootOwner::create(&path, &ns).unwrap();
-    fs::create_dir(path.join("skills")).unwrap();
-    assert_eq!(
-        maka_event_log::root::initialize(&path, &ns).unwrap(),
-        owner.root_id()
-    );
-    fs::remove_dir_all(&ns.control).unwrap();
-    let status = Command::new(std::env::current_exe().unwrap())
-        .args([
-            "--exact",
-            "durable_lease_blocks_other_process_even_after_cache_removal",
-            "--nocapture",
-        ])
-        .env("MAKA_ROOT_AUTHORITY_TEST_BASE", temp.path())
-        .status()
-        .unwrap();
-    assert!(status.success());
-    assert!(owner.validate_current().is_err());
-    drop(owner);
-    RootOwner::open(&path, &ns).unwrap();
-}
diff --git a/crates/event-log/tests/root_lease.rs b/crates/event-log/tests/root_lease.rs
new file mode 100644
index 0000000000..5051c77305
--- /dev/null
+++ b/crates/event-log/tests/root_lease.rs
@@ -0,0 +1,65 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+// Keep this process-spawning check in its own binary: fork temporarily inherits
+// other test threads' OFD leases even when their files are close-on-exec.
+use maka_event_log::root::{RootNamespaces, RootOwner};
+use std::{fs, path::Path, process::Command};
+
+fn namespaces(base: &Path) -> RootNamespaces {
+    RootNamespaces {
+        ownership: base.join("owners"),
+        control: base.join("control"),
+    }
+}
+
+#[test]
+fn durable_lease_blocks_other_process_even_after_cache_removal() {
+    if let Some(base) = std::env::var_os("MAKA_ROOT_AUTHORITY_TEST_BASE") {
+        let base = Path::new(&base);
+        let error = RootOwner::open(&base.join("root"), &namespaces(base))
+            .err()
+            .unwrap();
+        assert_eq!(error.kind(), std::io::ErrorKind::WouldBlock);
+        return;
+    }
+    let temp = tempfile::tempdir().unwrap();
+    let ns = namespaces(temp.path());
+    let path = temp.path().join("root");
+    let owner = RootOwner::create(&path, &ns).unwrap();
+    fs::create_dir(path.join("skills")).unwrap();
+    assert_eq!(
+        maka_event_log::root::initialize(&path, &ns).unwrap(),
+        owner.root_id()
+    );
+    fs::remove_dir_all(&ns.control).unwrap();
+    let status = Command::new(std::env::current_exe().unwrap())
+        .args([
+            "--exact",
+            "durable_lease_blocks_other_process_even_after_cache_removal",
+            "--nocapture",
+        ])
+        .env("MAKA_ROOT_AUTHORITY_TEST_BASE", temp.path())
+        .status()
+        .unwrap();
+    assert!(status.success());
+    assert!(owner.validate_current().is_err());
+    drop(owner);
+    RootOwner::open(&path, &ns).unwrap();
+}
diff --git a/docs/rust-runtime.md b/docs/rust-runtime.md
index cbbf61e1fa..db9af85680 100644
--- a/docs/rust-runtime.md
+++ b/docs/rust-runtime.md
@@ -58,6 +58,13 @@ Windows MSVC builds use the static CRT required by the official V8 archive.
 The two vendored Deno TypeScript files must match `deno_telemetry` exactly;
 update them together when upgrading that dependency. They avoid a build-time V8.
 
+`host connect --root-id <rootId> --framed` activates that deployment and bridges the
+client protocol over stdin/stdout; diagnostics use stderr. Linux/macOS input EOF
+half-closes the connection and drains responses. Windows pipe EOF disconnects;
+clients must receive their responses before closing stdin. WSL passes
+`--repair-root-after-remount`: this explicitly confirms an unchanged Linux inode
+after remount, preserving Root ID. Do not use it to adopt copied or legacy roots.
+
 `host install --root <directory>` pins the current executable and on-demand policy;
 `--mode supervised` selects persistent serving. Only the returned `executable`
 may start that managed root. `host activate --root-id <rootId> --framed` reuses a ready
diff --git a/docs/rust-runtime.zh-CN.md b/docs/rust-runtime.zh-CN.md
index 74b138f3ba..1e87f813a6 100644
--- a/docs/rust-runtime.zh-CN.md
+++ b/docs/rust-runtime.zh-CN.md
@@ -53,8 +53,13 @@ Windows MSVC 构建使用与官方 V8 静态库一致的静态 CRT。
 两份随仓库保存的 Deno TypeScript 须与 `deno_telemetry` 完全一致,升级依赖时须同步;
 构建直接转译它们,不再加载构建期 V8。
 
+`host connect --root-id <rootId> --framed` 激活该部署,通过 stdin/stdout 桥接客户端协议,
+诊断写入 stderr。Linux/macOS 的输入 EOF 半关闭连接并排空响应;Windows 管道 EOF 表示断连,
+客户端须先收完响应再关闭 stdin。WSL 传入 `--repair-root-after-remount`,显式确认重挂载后
+Linux inode 未变并保留 Root ID。不要用它接管复制的根或旧版数据。
+
 `host install --root <目录>` 固定当前可执行文件和按需策略;`--mode supervised` 选择持续运行。
-此后只有返回的 `executable` 可以启动该托管根。`host activate --root-id <rootId> --framed`
+只有返回的 `executable` 可以启动该托管根。`host activate --root-id <rootId> --framed`
 复用就绪 Host,或启动固定版本;supervised 模式会注册并启动账户级 systemd 服务、LaunchAgent
 或 Windows 计划任务。Linux 要求用户服务管理器已运行且启用 linger;macOS 要求 Aqua 登录,
 Windows 要求交互式用户会话。单独安装不会启动服务或修改账户策略。
diff --git a/tests/fixtures/client-bridge-entry.mjs b/tests/fixtures/client-bridge-entry.mjs
new file mode 100644
index 0000000000..d578320190
--- /dev/null
+++ b/tests/fixtures/client-bridge-entry.mjs
@@ -0,0 +1,136 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { parseArgs } from 'node:util';
+import { connectRuntimeHostWslEnvironment } from '../../packages/runtime-host/src/client/wsl-environment.js';
+import { RUNTIME_HOST_COMPATIBILITY_EPOCH } from '../../packages/runtime-host/src/protocol/index.js';
+
+const { values } = parseArgs({
+  options: {
+    bridge: { type: 'string' },
+    'root-id': { type: 'string' },
+    'host-epoch': { type: 'string' },
+  },
+});
+const children = [];
+const args = ['host', 'connect', '--framed', '--root-id', values['root-id']];
+function launch(input = args) {
+  const child = spawn(values.bridge, input, { stdio: 'pipe', timeout: 8_000 });
+  child.stderr.pipe(process.stderr, { end: false });
+  const exited = new Promise((resolve) => {
+    child.once('exit', (code, signal) => resolve({ code, signal }));
+    child.once('error', (error) => resolve({ error }));
+  });
+  children.push({ child, exited });
+  return { child, exited };
+}
+const hello = {
+  kind: 'hello',
+  clientInstanceId: 'native-bridge-fixture',
+  protocolMin: 0,
+  protocolMax: 0,
+  compatibilityEpoch: RUNTIME_HOST_COMPATIBILITY_EPOCH,
+  compositionId: 'maka.interactive',
+};
+const line = (frame) => JSON.stringify(frame) + '\n';
+const request = (operation, input, id = 'bridge-request') => ({
+  requestId: id,
+  operation,
+  input,
+});
+
+try {
+  // Exercise the real WSL client and its unchanged launch arguments/transport.
+  // Only the OS process factory is replaced for ordinary three-platform tests.
+  const connection = await connectRuntimeHostWslEnvironment(
+    {
+      distribution: 'Maka-Test',
+      operator: { kind: 'native', platform: 'posix', executablePath: '/maka' },
+      rootId: values['root-id'],
+      clientInstanceId: 'original-wsl-client',
+    },
+    {
+      wslExecutable: 'fixture-wsl',
+      processFactory: (executable, input) => {
+        assert.equal(executable, 'fixture-wsl');
+        assert.deepEqual(input.slice(0, 4), ['--distribution', 'Maka-Test', '--exec', '/maka']);
+        assert(input.includes('--repair-root-after-remount'));
+        return launch(input.slice(4)).child;
+      },
+    },
+  );
+  try {
+    assert.equal(connection.rootId, values['root-id']);
+    assert.equal(connection.hostEpoch, values['host-epoch']);
+    assert.equal(
+      (await connection.request('host.diagnostics.query', {})).hostEpoch,
+      values['host-epoch'],
+    );
+  } finally {
+    await connection.close();
+  }
+
+  if (process.platform !== 'win32') {
+    const { child, exited } = launch();
+    // One write pipelines the request beyond hello; EOF must not discard either
+    // the input prefetch or the Host's final response.
+    child.stdin.end(line(hello) + line(request('host.diagnostics.query', {})));
+    let response;
+    for await (const text of createInterface({ input: child.stdout })) {
+      const frame = JSON.parse(text);
+      if (frame.requestId === 'bridge-request') response = frame;
+    }
+    assert.deepEqual(await exited, { code: 0, signal: null });
+    assert.equal(response?.ok, true, JSON.stringify(response));
+    assert.equal(response.result.hostEpoch, values['host-epoch']);
+  }
+
+  const { child, exited } = launch();
+  child.stdin.write(line(hello));
+  let prepared;
+  for await (const text of createInterface({ input: child.stdout })) {
+    const frame = JSON.parse(text);
+    if (frame.kind === 'accepted') {
+      assert.equal(frame.rootId, values['root-id']);
+      assert.equal(frame.hostEpoch, values['host-epoch']);
+      child.stdin.write(
+        line(
+          request('host.upgrade.prepare', {
+            expectedHostEpoch: values['host-epoch'],
+            allowInterruptActiveTasks: false,
+            allowCooperativeHandoff: true,
+          }),
+        ),
+      );
+    }
+    if (frame.requestId === 'bridge-request') prepared = frame;
+  }
+  // stdin was never ended: a process-lifetime stdio read must not prevent exit.
+  assert.deepEqual(await exited, { code: 0, signal: null });
+  assert.equal(prepared?.ok, true, JSON.stringify(prepared));
+  assert.equal(prepared.result.kind, 'prepared', JSON.stringify(prepared));
+} finally {
+  for (const { child, exited } of children) {
+    if (child.exitCode === null && child.signalCode === null) child.kill();
+    await exited;
+  }
+}
diff --git a/tests/fixtures/client.mjs b/tests/fixtures/client.mjs
index 9afe61c4a5..5fbf98bab4 100644
--- a/tests/fixtures/client.mjs
+++ b/tests/fixtures/client.mjs
@@ -36,6 +36,7 @@ const entries = [
   ['--project-workspace', 'client-project-entry.mjs'],
   ['--native-candidate', 'client-candidate-entry.mjs'],
   ['--activation-frame', 'client-activation-entry.mjs'],
+  ['--bridge', 'client-bridge-entry.mjs'],
   ['--system-prompt-workspace', 'client-system-prompt-entry.mjs'],
   ['--model-overrides-workspace', 'client-model-overrides-entry.mjs'],
   ['--runtime-policy-workspace', 'client-runtime-policy-entry.mjs'],


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@maka.apache.org
For additional commands, e-mail: commits-help@maka.apache.org