From af1c660326200a437564948b472c6b659cbd238c Mon Sep 17 00:00:00 2001 From: rain Date: Thu, 12 Nov 2026 11:32:00 +0800 Subject: [PATCH] fix(sandbox): carry a full-pool capacity notice into sandbox.get (#649) `sandbox.get`'s `daemon_capacity` model is absent exactly when the daemon pool is full: the capacity read needs the same slot, so the only source of the counts is the pre-handshake `LAYERFS-CAPACITY` notice. `direct::unanswered` re-coded every refusal that was not `Busy`/`StaleSandbox` to `Unavailable` and dropped the notice's `detail`, so the get could only show prose in `down_reason`. Keep the `Capacity` detail (tagged with its code) through `unanswered`, and surface it from `sandbox.get` as a new explicit, **partial** `down` field: down: { code, resource, pool_vacant, reserved_vacant, retained } It is not mapped into `daemon_capacity` (`CapacityModel::parse` would fill missing fields with zero). It is absent when the refusal had no counts: a legacy bare EOF, a malformed record, or a remote refusal collapsed to `{phase}` by `values::refusal`. `Capacity` still does not pass through `unanswered` as `Capacity`, so the get keeps answering with `down_reason`. Tests (layerfs-api/tests/sandbox_capacity.rs, 8/8): - full pool -> get shows `down` with the notice counts, after the measured 60 s admission window, and no `daemon_capacity`; - legacy EOF -> `down_reason`, no `down`; - normal get -> no `down`, `daemon_capacity` intact; - collapsed remote refusal `{phase}` -> `Down::of` is `None`. Docs: sandbox/get.md, sandbox/README.md, daemon-channel.md. --- api/crates/layerfs-api/src/sandbox/get.rs | 12 +- .../layerfs-api/tests/sandbox_capacity.rs | 120 +++++++++++++++++- control/crates/layerfs-sandbox/src/direct.rs | 37 ++++-- control/crates/layerfs-sandbox/src/family.rs | 2 +- control/crates/layerfs-sandbox/src/get.rs | 67 +++++++++- docs/architecture/api/sdk/sandbox/README.md | 7 +- docs/architecture/api/sdk/sandbox/get.md | 12 +- .../control/routing/daemon-channel.md | 2 +- 8 files changed, 231 insertions(+), 28 deletions(-) diff --git a/api/crates/layerfs-api/src/sandbox/get.rs b/api/crates/layerfs-api/src/sandbox/get.rs index 2839ca84b8..958fb5a075 100644 --- a/api/crates/layerfs-api/src/sandbox/get.rs +++ b/api/crates/layerfs-api/src/sandbox/get.rs @@ -19,9 +19,11 @@ pub(crate) const CALL: Call = call( /// Runs `sandbox.get`: its record with its derived `state`, one page of its /// `workspaces` (each with its `path`, `name` and `ws`), why its machine did -/// not answer (`down_reason`), the daemon's `daemon_capacity` read model when -/// the Sandbox answered it (#540), and `next_page_pos`. The library reads it -/// best effort and bounded, so this layer only shows what it got. +/// not answer (`down_reason`, with the partial `down` counts when the +/// daemon's capacity notice carried them, #649), the daemon's +/// `daemon_capacity` read model when the Sandbox answered it (#540), and +/// `next_page_pos`. The library reads it best effort and bounded, so this +/// layer only shows what it got. fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { let request = GetRequest { name: args.get_text("name").unwrap_or("").to_owned(), @@ -36,6 +38,7 @@ fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { state, workspaces, down_reason, + down, next, daemon_capacity, } = get(home, events, &request)?; @@ -50,6 +53,9 @@ fn run(context: &mut Context<'_>, args: &SdkValue) -> Outcome { if let Some(why) = down_reason { shown = with_field(shown, "down_reason", SdkValue::Text(why)); } + if let Some(down) = down { + shown = with_field(shown, "down", down.to_sdk()); + } if let Some(model) = daemon_capacity { shown = with_field(shown, "daemon_capacity", model.to_sdk()); } diff --git a/api/crates/layerfs-api/tests/sandbox_capacity.rs b/api/crates/layerfs-api/tests/sandbox_capacity.rs index b802f060c0..869aa37dc5 100644 --- a/api/crates/layerfs-api/tests/sandbox_capacity.rs +++ b/api/crates/layerfs-api/tests/sandbox_capacity.rs @@ -1,17 +1,20 @@ -//! `sandbox.get`'s `daemon_capacity` (#540, #543): the daemon's +//! `sandbox.get`'s daemon fields (#540, #543, #649): the //! `backend.daemon.connection_failures` read model, shown best-effort and //! bounded on the connection the Workspace list lent from this process's -//! pool. Nothing runs: a stand-in daemon answers the Sandbox's Workspace list -//! and its capacity model on the same connection, a second one answers the -//! list and then says nothing, and a Sandbox whose machine or forward is -//! already down is not dialed at all. +//! pool, and the partial `down` counts a full-pool refusal carries. Nothing +//! runs: a stand-in daemon answers the Sandbox's Workspace list and its +//! capacity model on the same connection, a second one answers the list and +//! then says nothing, a third refuses every connection with the +//! pre-handshake capacity notice (or a legacy bare close), and a Sandbox +//! whose machine or forward is already down is not dialed at all. #![cfg(unix)] use layerfs_api::home::{self, paths, write_record}; use layerfs_bridge::control::{ AdmissionModel, Answer, Call, DaemonPhase, DaemonStatus, Reply, Request, RetainedModel, - SdkValue, OPERATION, + SdkRefusal, SdkValue, OPERATION, }; use layerfs_bridge::duplex; +use layerfs_bridge::duplex::admission::{self, AdmissionNotice, AdmissionReason}; use std::net::{SocketAddr, TcpListener}; use std::os::unix::fs::PermissionsExt; use std::path::{Path, PathBuf}; @@ -281,6 +284,8 @@ fn a_running_sandbox_s_get_shows_its_daemon_capacity() { ); assert_eq!(failures[0].get_int("generation"), Some(6)); assert_eq!(failures[0].get_text("request"), Some("unmount")); + // a daemon that answered carries no down counts (#649) + assert!(got.get("down").is_none(), "{got:?}"); // the Workspace list and the capacity read share the one pooled // connection (#543): a get takes no second control slot of its own assert_eq!(served.load(Ordering::SeqCst), 1, "{got:?}"); @@ -363,3 +368,106 @@ fn a_sandbox_with_no_id_is_never_dialed() { assert_eq!(served.load(Ordering::SeqCst), 0, "{got:?}"); std::fs::remove_dir_all(home).unwrap(); } + +/// A stand-in daemon that refuses every connection the way an accept loop +/// does when its pool is full: with `notice` before any handshake, or, for a +/// daemon that predates the notice, with a bare close (#540). It drains what +/// the client sent and counts the connections it refused. +fn refusing(notice: Option) -> (SocketAddr, Arc) { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let endpoint = listener.local_addr().unwrap(); + let served = Arc::new(AtomicUsize::new(0)); + let counted = served.clone(); + std::thread::spawn(move || { + for stream in listener.incoming() { + let Ok(mut stream) = stream else { return }; + counted.fetch_add(1, Ordering::SeqCst); + let _ = stream.set_write_timeout(Some(Duration::from_millis(100))); + let _ = stream.set_read_timeout(Some(Duration::from_millis(50))); + if let Some(notice) = notice { + if admission::write(&mut stream, ¬ice).is_err() { + continue; + } + } + let mut sink = [0u8; 512]; + let _ = std::io::Read::read(&mut stream, &mut sink); + } + }); + (endpoint, served) +} + +#[test] +fn a_full_daemon_pool_shows_the_partial_down_counts() { + let (endpoint, served) = refusing(Some(AdmissionNotice::new( + AdmissionReason::NoPoolSlot, + 3, + 0, + 1, + ))); + let home = tempdir("full-pool"); + home::open(&home).unwrap(); + home_records(&home, true); + sandbox_record(&home, endpoint, Some("s-1"), None); + let at = Instant::now(); + let got = call(&home, "sandbox.get", &[("name", t("s1"))]).unwrap(); + let elapsed = at.elapsed(); + // This is the measured behaviour (#649): a full pool is not visible to + // the get before the whole admission window has passed. + assert!( + elapsed >= Duration::from_secs(55), + "the get answered before the admission window: {elapsed:?}" + ); + assert!(served.load(Ordering::SeqCst) > 0, "{got:?}"); + assert_eq!(got.get_text("state"), Some("running"), "{got:?}"); + assert!(got.get_text("down_reason").is_some(), "{got:?}"); + let down = got.get("down").unwrap_or_else(|| panic!("{got:?}")); + assert_eq!(down.get_text("code"), Some("Capacity"), "{down:?}"); + assert_eq!( + down.get_text("resource"), + Some("daemon_control_slot"), + "{down:?}" + ); + assert_eq!(down.get_int("pool_vacant"), Some(0), "{down:?}"); + assert_eq!(down.get_int("reserved_vacant"), Some(1), "{down:?}"); + assert_eq!(down.get_int("retained"), Some(3), "{down:?}"); + // the notice is partial: it is never dressed up as the full model + assert!(got.get("daemon_capacity").is_none(), "{got:?}"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn a_legacy_eof_has_no_down_counts() { + // a daemon that closes the connection without the capacity notice: the + // refusal says only what was observed, so the get shows down_reason and + // no `down` counts (#649) + let (endpoint, served) = refusing(None); + let home = tempdir("legacy-eof"); + home::open(&home).unwrap(); + home_records(&home, true); + sandbox_record(&home, endpoint, Some("s-1"), None); + let at = Instant::now(); + let got = call(&home, "sandbox.get", &[("name", t("s1"))]).unwrap(); + assert!( + at.elapsed() >= Duration::from_secs(55), + "a legacy EOF is retried for the admission window: {:?}", + at.elapsed() + ); + assert!(served.load(Ordering::SeqCst) > 0, "{got:?}"); + assert!(got.get_text("down_reason").is_some(), "{got:?}"); + assert!(got.get("down").is_none(), "{got:?}"); + assert!(got.get("daemon_capacity").is_none(), "{got:?}"); + std::fs::remove_dir_all(home).unwrap(); +} + +#[test] +fn a_collapsed_remote_refusal_has_no_down_counts() { + // A refusal forwarded from a machine's worker is collapsed to + // `{phase}` by `values::refusal` (#547 slice 6): it carries no counts, + // so the get must omit `down` rather than fill zeros. + let refusal = SdkRefusal { + code: "Unavailable".to_owned(), + message: "the Sandbox's daemon ended this connection before it answered".to_owned(), + detail: SdkValue::map([("phase", SdkValue::text("receive"))]), + }; + assert!(layerfs_sandbox::family::Down::of(&refusal).is_none()); +} diff --git a/control/crates/layerfs-sandbox/src/direct.rs b/control/crates/layerfs-sandbox/src/direct.rs index f6188b3306..5f702985a8 100644 --- a/control/crates/layerfs-sandbox/src/direct.rs +++ b/control/crates/layerfs-sandbox/src/direct.rs @@ -90,6 +90,13 @@ pub fn live(state: &SandboxState) -> Result<()> { /// The refusal of a forwarded Sandbox `id` whose daemon did not answer a /// new connection: `Unavailable`, naming the calls that say why. A busy /// daemon's `Busy` and a restarted one's `StaleSandbox` stay as they are. +/// +/// A `Capacity` refusal keeps its structured `detail` (#649): the +/// pre-handshake `LAYERFS-CAPACITY` notice is the only place the counts +/// exist while the pool is full, and `sandbox.get` shows them as its +/// partial `down` model. The surviving `Unavailable` detail carries the +/// underlying `code` so the get can tell it from a refusal that never had +/// counts. pub fn unanswered(id: &str, daemon: &DaemonRecord, refusal: SdkRefusal) -> SdkRefusal { if matches!(refusal.code.as_str(), "Busy" | "StaleSandbox") { return refusal; @@ -97,14 +104,28 @@ pub fn unanswered(id: &str, daemon: &DaemonRecord, refusal: SdkRefusal) -> SdkRe let at = forward_of(daemon) .map(|a| a.to_string()) .unwrap_or_default(); - refused( - "Unavailable", - format!( - "Sandbox {id}'s daemon does not answer at {at}: {}; `layerfs sandbox get {id}` \ - shows whether it runs, `layerfs sandbox close {id}` closes it", - refusal.message - ), - ) + let message = format!( + "Sandbox {id}'s daemon does not answer at {at}: {}; `layerfs sandbox get {id}` \ + shows whether it runs, `layerfs sandbox close {id}` closes it", + refusal.message + ); + SdkRefusal { + code: "Unavailable".to_owned(), + message, + detail: down_detail(refusal.code.as_str(), refusal.detail), + } +} + +/// The detail an unanswered get keeps from the refusal that made it +/// (#649): a `Capacity` refusal's notice counts, tagged with the refusal +/// code it came from. Every other refusal keeps nothing: a legacy EOF, a +/// malformed record, or a remote refusal collapsed to `{phase}` has no +/// counts, and inventing zeros would be false. +fn down_detail(code: &str, detail: SdkValue) -> SdkValue { + match code { + "Capacity" => home::with_field(detail, "code", SdkValue::text("Capacity")), + _ => SdkValue::Null, + } } /// A worker's `sandbox.create` answer `out` for Sandbox `name` under its diff --git a/control/crates/layerfs-sandbox/src/family.rs b/control/crates/layerfs-sandbox/src/family.rs index c1e01a5b55..4c0c32ea09 100644 --- a/control/crates/layerfs-sandbox/src/family.rs +++ b/control/crates/layerfs-sandbox/src/family.rs @@ -19,7 +19,7 @@ //! `route.rs`, and the `workspace` calls in `workspace/calls.rs`. pub use super::close::{close, CloseRequest, Closed}; pub use super::create::{create, CreateRequest, Created}; -pub use super::get::{get, GetRequest, Got, ListedWorkspace}; +pub use super::get::{get, Down, GetRequest, Got, ListedWorkspace}; pub use super::list::{list, ListRequest, Listed}; use super::record::SandboxRecord; use layerfs_bridge::control::SdkRefusal; diff --git a/control/crates/layerfs-sandbox/src/get.rs b/control/crates/layerfs-sandbox/src/get.rs index cb8485bd77..b80783f976 100644 --- a/control/crates/layerfs-sandbox/src/get.rs +++ b/control/crates/layerfs-sandbox/src/get.rs @@ -31,6 +31,53 @@ pub struct ListedWorkspace { pub ws: String, } +/// Why a get's daemon was not reached, as far as the refused connection +/// said (#649): a **partial** model, filled only from the daemon's +/// pre-handshake `LAYERFS-CAPACITY` notice. It is not +/// [`CapacityModel`]: that model's missing fields would read as zero, so a +/// notice is never mapped into `daemon_capacity`. +#[derive(Clone, Debug, Eq, PartialEq)] +pub struct Down { + /// The refusal the notice produced: `Capacity`. + pub code: String, + /// The exhausted resource, e.g. `daemon_control_slot`. + pub resource: String, + /// Pool slots vacant when the daemon refused. + pub pool_vacant: i64, + /// Reserved slots vacant when the daemon refused. + pub reserved_vacant: i64, + /// Retained failure records visible when the daemon refused. + pub retained: i64, +} + +impl Down { + /// The partial model a refusal's detail carries, when it carries every + /// count. A detail without the capacity fields (a legacy EOF, or a + /// remote refusal collapsed to `{phase}`) has none, and `None` is + /// returned rather than zeros. + pub fn of(refusal: &SdkRefusal) -> Option { + let detail = &refusal.detail; + Some(Self { + code: detail.get_text("code")?.to_owned(), + resource: detail.get_text("resource")?.to_owned(), + pool_vacant: detail.get_int("pool_vacant")?, + reserved_vacant: detail.get_int("reserved_vacant")?, + retained: detail.get_int("retained")?, + }) + } + + /// The SDK value `sandbox.get` shows as `down`. + pub fn to_sdk(&self) -> SdkValue { + SdkValue::map([ + ("code", SdkValue::text(self.code.as_str())), + ("resource", SdkValue::text(self.resource.as_str())), + ("pool_vacant", SdkValue::Int(self.pool_vacant)), + ("reserved_vacant", SdkValue::Int(self.reserved_vacant)), + ("retained", SdkValue::Int(self.retained)), + ]) + } +} + /// A Sandbox's record with its derived state and one page of its /// Workspaces. pub struct Got { @@ -42,6 +89,9 @@ pub struct Got { pub workspaces: Vec, /// Why its machine did not answer, when it did not. pub down_reason: Option, + /// The structured counts behind `down_reason`, when the refusing + /// daemon's capacity notice carried them (#649). + pub down: Option, /// The next page's position; `None` after the last. pub next: Option, /// Its daemon's control-capacity read model (#540), when a running @@ -70,29 +120,34 @@ pub fn get(home: &Path, events: &mut Events<'_>, request: &GetRequest) -> Result ), None => Ok(Ok(SdkValue::Null)), }; - let (all, down_reason, gone) = match listed { - Ok(Err(refusal)) if refusal.code == "NoSuchSandbox" => (Vec::new(), None, true), + let (all, down_reason, down, gone) = match listed { + Ok(Err(refusal)) if refusal.code == "NoSuchSandbox" => (Vec::new(), None, None, true), Ok(workspaces) => match workspaces?.get("workspaces") { Some(SdkValue::List(items)) => ( items.iter().map(|i| listed_workspace(name, i)).collect(), None, + None, false, ), - _ => (Vec::new(), None, false), + _ => (Vec::new(), None, None, false), }, - Err(Unreached(why)) => (Vec::new(), Some(why.message), false), + Err(Unreached(why)) => { + let down = Down::of(&why); + (Vec::new(), Some(why.message), down, false) + } }; let (workspaces, next) = page(all, request.page); let state = record.state(gone); // best effort, bounded, and only for a Sandbox its daemon still serves: // this read never fails a get (#540, #543) - let down = down_reason.is_some(); - let daemon_capacity = capacity(&home, events, &record, gone, state, down); + let unreachable = down_reason.is_some(); + let daemon_capacity = capacity(&home, events, &record, gone, state, unreachable); Ok(Got { state, record, workspaces, down_reason, + down, next, daemon_capacity, }) diff --git a/docs/architecture/api/sdk/sandbox/README.md b/docs/architecture/api/sdk/sandbox/README.md index d1724454f6..f4218f8a58 100644 --- a/docs/architecture/api/sdk/sandbox/README.md +++ b/docs/architecture/api/sdk/sandbox/README.md @@ -36,7 +36,7 @@ unique across the home. | --- | --- | --- | --- | --- | | [`create`](create.md) | `project` (Project), `name` (Name), `machine?` (Name) | `image` (Text) | the Sandbox record with `state`; `forward_failed` when a direct daemon forward did not open | its machine: here or `sandbox.host` in the worker | | [`list`](list.md) | `project?` (Project) | `page_size`, `page_pos` (Int) | `{ items: [record], next_page_pos }` | caller's process, home records only | -| [`get`](get.md) | `name` (Name) | `page_size`, `page_pos` | the record with `state`, `workspaces`, `next_page_pos`, `down_reason` when its machine is down, and `daemon_capacity` when its daemon answers the bounded capacity read | its machine or its daemon; starts nothing | +| [`get`](get.md) | `name` (Name) | `page_size`, `page_pos` | the record with `state`, `workspaces`, `next_page_pos`, `down_reason` when its machine is down, `down` (partial capacity counts) when the refusal carried the daemon's notice, and `daemon_capacity` when its daemon answers the bounded capacity read | its machine or its daemon; starts nothing | | [`close`](close.md) | `name` (Name) | `force` (Bool) | `{ kind: "Closed", sandbox, unknown, closed }`, or `{ closed, was_gone: true }`, or `{ closed, was, left? }` for a record with no id | its machine: here or `sandbox.host` in the worker | The record is `SandboxRecord::to_sdk` @@ -52,6 +52,11 @@ its `daemon_capacity` is the daemon's `backend.daemon.connection_failures` read model, read best effort and bounded to 2 s on the connection the Workspace list already lent ([`daemon/capacity.rs`](../../../../../control/crates/layerfs-sandbox/src/daemon/capacity.rs)). +When the Workspace list is refused at a full pool, `down` carries the +partial counts from the daemon's pre-handshake capacity notice: `code`, +`resource`, `pool_vacant`, `reserved_vacant` and `retained`, and no +`daemon_capacity`, whose missing fields would read as zero +(#649). ## Arguments and options diff --git a/docs/architecture/api/sdk/sandbox/get.md b/docs/architecture/api/sdk/sandbox/get.md index accb9c91d5..a87bb90b7b 100644 --- a/docs/architecture/api/sdk/sandbox/get.md +++ b/docs/architecture/api/sdk/sandbox/get.md @@ -59,6 +59,7 @@ layerfs sandbox get [--page-size ] [--page-pos ] pending_merge, revision } ], next_page_pos: int | null, down_reason?: text, + down?: { code, resource, pool_vacant, reserved_vacant, retained }, daemon_capacity?: { admission: { pool_vacant, pool_running, reserved_vacant, reserved_running }, retained: { limit, ttl_ms, count, dropped, recorded, @@ -78,6 +79,7 @@ layerfs sandbox get [--page-size ] [--page-pos ] | `workspaces[].*` | | the daemon's read model per Workspace: id, namespace, Branch, base Commit and Layer, root, `activity`, dirty counts ([`operator/inspect.rs`](../../../../../engine/crates/layerfs-store-service/src/operator/inspect.rs) `workspace_value`) | | `next_page_pos` | int or null | next page of `workspaces` | | `down_reason` | text | the machine's worker or the forwarded daemon was not reached; `workspaces` is then `[]` | +| `down` | record | the structured counts behind a `down_reason`, when the refused connection carried the daemon's pre-handshake `LAYERFS-CAPACITY` notice (#649): `code` is the refusal the notice made (`Capacity`), `resource` the exhausted resource (`daemon_control_slot`), and `pool_vacant`, `reserved_vacant` and `retained` its counts. It is a **partial** model, never `daemon_capacity`: the field is absent when the refusal had no counts — a legacy bare EOF, a malformed record, or a remote refusal collapsed to `{phase}` ([`direct.rs`](../../../../../control/crates/layerfs-sandbox/src/direct.rs) `unanswered`, [`get.rs`](../../../../../control/crates/layerfs-sandbox/src/get.rs) `Down`) | | `daemon_capacity` | record | the daemon's `backend.daemon.connection_failures` read model (#540): control admission by slot class and the bounded retained connection failures that used to hold a slot ([`control_capacity.rs`](../../../../../engine/crates/layerfs-bridge/src/control_capacity.rs)). It is read once, best effort, and only for a Sandbox that is `running` and whose machine and forward were reached; nothing is started and no second control slot is taken, so the field is simply absent when the daemon refuses, does not answer within 2 s, or was not asked ([`daemon/capacity.rs`](../../../../../control/crates/layerfs-sandbox/src/daemon/capacity.rs)) | ## Where it runs @@ -94,6 +96,8 @@ layerfs sandbox get [--page-size ] [--page-pos ] | v Unreached / Unavailable --> record + workspaces [] + down_reason + | a Capacity refusal keeps its notice detail --> down (partial counts) + | any other refusal (legacy EOF, {phase}) --> no down NoSuchSandbox --> state "lost", workspaces [] running and not down, same route and the same pooled connection: @@ -101,8 +105,12 @@ layerfs sandbox get [--page-size ] [--page-pos ] ``` `get` starts no machine and loads no image (#535 P4); reading never clears -an intent. The capacity read is a second host operation on the connection -the Workspace list lent from the Sandbox's pool +an intent. At a full daemon pool a forwarded Sandbox's list is refused +`Capacity` after the whole 60 s admission window; the get still answers, +with `down_reason` and — when the daemon wrote its capacity notice — the +partial `down` counts the capacity read itself cannot fetch in that state, +because it would need the same slot (#649). The capacity read is a second +host operation on the connection the Workspace list lent from the Sandbox's pool ([`daemon/pool.rs`](../../../../../control/crates/layerfs-sandbox/src/daemon/pool.rs)), bounded to 2 s for admission and for the exchange and fenced at that deadline ([`daemon/fence.rs`](../../../../../control/crates/layerfs-sandbox/src/daemon/fence.rs)), diff --git a/docs/architecture/control/routing/daemon-channel.md b/docs/architecture/control/routing/daemon-channel.md index 67bd11168d..5a6eced07b 100644 --- a/docs/architecture/control/routing/daemon-channel.md +++ b/docs/architecture/control/routing/daemon-channel.md @@ -82,7 +82,7 @@ opening a connection sends only Hello, so it attempts no operation. | `workspace.commit` | `Commit` | `values::commit`: Committed, Merged (with `merged`), or `Conflict` | [`daemon/workspace/commit.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/workspace/commit.rs), [`daemon/values.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/values.rs) | | `workspace.unmount` | `Unmount{token, discard}`, or `ForceUnmount` with `force` | `values::unmounted` (`Dirty` refusal) or `force_unmounted` | [`daemon/workspace/unmount.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/workspace/unmount.rs) | | `workspace.status` | `Status(token)`; the Branch head is read separately on the Store's route | `values::status` | [`daemon/workspace/status.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/workspace/status.rs) | -| `sandbox.get` | SDK method `sandbox.list_workspaces`, then, on the same pooled connection and for a running Sandbox its machine still reaches, `backend.daemon.connection_failures` (`daemon_capacity`, bounded to 2 s: admission and the exchange share one deadline, fenced by [`daemon/fence.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/fence.rs); a window admission used up refuses the read, and a connection the fence ends is not lent again) | `sandbox/dispatch.rs` (both through `daemon/operator.rs`) | [`daemon/operator.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/operator.rs), [`daemon/capacity.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/capacity.rs) | +| `sandbox.get` | SDK method `sandbox.list_workspaces`, then, on the same pooled connection and for a running Sandbox its machine still reaches, `backend.daemon.connection_failures` (`daemon_capacity`, bounded to 2 s: admission and the exchange share one deadline, fenced by [`daemon/fence.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/fence.rs); a window admission used up refuses the read, and a connection the fence ends is not lent again); a full pool's pre-handshake `LAYERFS-CAPACITY` notice survives the failed open as the partial `down` counts (#649) | `sandbox/dispatch.rs` (both through `daemon/operator.rs`) | [`daemon/operator.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/operator.rs), [`daemon/capacity.rs`](../../../../control/crates/layerfs-sandbox/src/daemon/capacity.rs) | | `workspace.exec` | none on this channel: `bash -c` runs through the Sandbox's runtime | — | [`exec/run.rs`](../../../../control/crates/layerfs-sandbox/src/exec/run.rs) | `Locate` and `Cleanup` are read-only observations for a caller whose