From c9483e562eb64b1779256570e9186a9a0c4d5f05 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:42:12 -0400
Subject: [PATCH 01/16] fix(codemode): harden saved snippet execution

---
 config/config.example.toml                    |    2 +-
 crates/labby-codemode/src/config.rs           |   10 +-
 .../src/runner_drive/artifacts.rs             |   35 +-
 crates/labby-codemode/src/snippet/store.rs    |  166 +-
 .../src/snippet/tool_declarations.rs          |    7 +-
 crates/labby-codemode/src/truncate.rs         |   70 +-
 .../src/gateway/code_mode/search.rs           |    2 +-
 .../src/gateway/manager/code_mode_runtime.rs  |   31 +-
 .../src/gateway/manager/tests/code_mode.rs    |  675 +---
 .../labby-gateway/src/security/spawn_guard.rs |   72 +-
 .../src/upstream/pool/connect.rs              |    2 +-
 .../src/upstream/pool/lifecycle_compat.rs     |    2 +-
 .../labby-gateway/src/upstream/pool/probe.rs  |    7 +-
 .../src/upstream/pool/stdio_transport.rs      |    6 +-
 crates/labby-runtime/src/gateway_config.rs    |  611 +---
 crates/labby/src/config.rs                    | 2987 +----------------
 crates/labby/src/dispatch/setup/settings.rs   |    4 +-
 .../labby/src/dispatch/snippets/dispatch.rs   |   48 +-
 docs/dev/CODE_MODE.md                         |   16 +-
 docs/services/SNIPPETS.md                     |   17 +-
 docs/snippets/README.md                       |   12 +-
 docs/snippets/docker-host-inventory.md        |   68 +
 docs/snippets/homelab-docker-inventory.md     |   73 +
 docs/snippets/homelab-ssh-targets.md          |  101 +
 .../using-labby/references/code-mode.md       |    2 +-
 .../references/config-reference.md            |    2 +-
 26 files changed, 689 insertions(+), 4339 deletions(-)
 create mode 100644 docs/snippets/docker-host-inventory.md
 create mode 100644 docs/snippets/homelab-docker-inventory.md
 create mode 100644 docs/snippets/homelab-ssh-targets.md

diff --git a/config/config.example.toml b/config/config.example.toml
index be11aa1a8..df40d6b72 100644
--- a/config/config.example.toml
+++ b/config/config.example.toml
@@ -168,7 +168,7 @@
 # `callTool(id, params)`, and typed `codemode.<upstream>.<tool>(params)`
 # helpers generated from connected servers' inputSchemas.
 # timeout_ms = 30000                        # valid range: 1..=60000  (wall-clock budget)
-# max_source_bytes = 131072                 # valid range: 1024..=1048576  (JavaScript source)
+# max_source_bytes = 1048576                # valid range: 1024..=1048576  (JavaScript source)
 # max_response_bytes = 24576                # valid range: 1024..=1048576
 # max_response_tokens = 6000                # valid range: 256..=256000
 # token_estimate_divisor = 4                # valid range: 1..=64  (lower is more conservative)
diff --git a/crates/labby-codemode/src/config.rs b/crates/labby-codemode/src/config.rs
index 74cc58034..09cd09319 100644
--- a/crates/labby-codemode/src/config.rs
+++ b/crates/labby-codemode/src/config.rs
@@ -27,7 +27,10 @@ pub(crate) const MAX_SNIPPET_RESOLVES_PER_RUN: usize = 32;
 pub(crate) const MAX_INTERNAL_CALLS_PER_RUN: usize = 32;
 
 /// Maximum total bytes of resolved snippet source allowed in a single run.
-pub(crate) const MAX_SNIPPET_RESOLVED_BYTES_PER_RUN: usize = 256 * 1024;
+/// Keep nested/composed snippets on the same hard byte budget as a direct Code
+/// Mode source so reusable helpers can carry normal agent context without
+/// inheriting a smaller legacy ceiling.
+pub(crate) const MAX_SNIPPET_RESOLVED_BYTES_PER_RUN: usize = MAX_SOURCE_BYTES;
 
 /// Default per-run `callTool` fan-out budget.
 const DEFAULT_MAX_CALLTOOL_PER_RUN: u64 = 512;
@@ -129,4 +132,9 @@ mod tests {
     fn max_source_bytes_is_stable() {
         assert_eq!(MAX_SOURCE_BYTES, 1024 * 1024);
     }
+
+    #[test]
+    fn composed_snippet_budget_matches_code_mode_hard_source_budget() {
+        assert_eq!(MAX_SNIPPET_RESOLVED_BYTES_PER_RUN, MAX_SOURCE_BYTES);
+    }
 }
diff --git a/crates/labby-codemode/src/runner_drive/artifacts.rs b/crates/labby-codemode/src/runner_drive/artifacts.rs
index 369cdf4a9..e41e28bec 100644
--- a/crates/labby-codemode/src/runner_drive/artifacts.rs
+++ b/crates/labby-codemode/src/runner_drive/artifacts.rs
@@ -108,6 +108,10 @@ pub(super) async fn handle_snippet_resolve_event<H: CodeModeHost>(
     }
 }
 
+fn snippet_resolution_scope_allowed(caller: &CodeModeCaller, scope: &ToolScope) -> bool {
+    !scope.is_scoped() || matches!(caller, CodeModeCaller::TrustedLocal)
+}
+
 async fn resolve_snippet_for_runner<H: CodeModeHost>(
     broker: &CodeModeBroker<'_, H>,
     name: &str,
@@ -121,7 +125,7 @@ async fn resolve_snippet_for_runner<H: CodeModeHost>(
             required_scopes: vec!["lab:admin".to_string()],
         });
     }
-    if cfg.capability_filter.is_scoped() {
+    if !snippet_resolution_scope_allowed(&cfg.caller, &cfg.capability_filter) {
         return Err(ToolError::Forbidden {
             message: "codemode.run is not available on route-scoped Code Mode surfaces".to_string(),
             required_scopes: vec!["lab:admin".to_string()],
@@ -262,8 +266,35 @@ fn artifact_call(
 
 #[cfg(test)]
 mod tests {
-    use super::artifact_writes_allowed;
+    use super::{artifact_writes_allowed, snippet_resolution_scope_allowed};
     use crate::ToolScope;
+    use crate::types::{CodeModeCaller, CodeModeCallerCapabilities};
+
+    #[test]
+    fn trusted_local_saved_snippets_may_compose_inside_declared_tool_scope() {
+        let scope = ToolScope::scoped_namespaces(
+            vec!["claude-macpoo".to_string()],
+            vec!["claude-macpoo::Bash".to_string()],
+        );
+        assert!(snippet_resolution_scope_allowed(
+            &CodeModeCaller::TrustedLocal,
+            &scope
+        ));
+
+        let route_scoped_admin = CodeModeCaller::Scoped {
+            capabilities: CodeModeCallerCapabilities {
+                can_read: true,
+                can_execute: true,
+                can_use_snippets: true,
+                is_admin: true,
+            },
+            sub: Some("admin".to_string()),
+        };
+        assert!(
+            !snippet_resolution_scope_allowed(&route_scoped_admin, &scope),
+            "route-scoped callers must not use nested snippet resolution to widen authority"
+        );
+    }
 
     #[test]
     fn artifact_writes_are_blocked_for_read_only_runs() {
diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index 2a1a176b2..9c37d3ff6 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -15,17 +15,18 @@ mod tool_declaration_tests;
 
 const SNIPPET_EXTENSIONS: &[&str] = &["md", "js"];
 
-/// Maximum size of a snippet's *executable* code — the extracted ```js block,
-/// or the whole file for bare `.js` snippets. This is what actually runs in
-/// code-mode, so it mirrors the host CLI source-size cap.
-const MAX_SNIPPET_CODE_BYTES: usize = 20 * 1024;
-
-/// Generous upper bound on the whole snippet markdown file (frontmatter + prose
-/// + fenced code). Tutorial-format snippets carry substantial prose that never
-/// executes, so the file bound is intentionally loose; only the extracted code
-/// is held to `MAX_SNIPPET_CODE_BYTES`. The file bound exists purely to reject
-/// pathological inputs before they are read fully into memory and parsed.
-const MAX_SNIPPET_FILE_BYTES: usize = 256 * 1024;
+/// Hard storage ceiling for a snippet's *executable* code — the extracted
+/// ```js block, or the whole file for bare `.js` snippets. Keep this aligned
+/// with Code Mode's hard source ceiling instead of a smaller snippet-only
+/// legacy cap. Hosts may still configure a lower `code_mode.max_source_bytes`,
+/// which is enforced when the snippet executes.
+const MAX_SNIPPET_CODE_BYTES: usize = crate::config::MAX_SOURCE_BYTES;
+
+/// Upper bound on the whole snippet markdown file (frontmatter + prose + fenced
+/// code). Snippets often front-load substantial agent context in prose that
+/// never executes, so give that context a full extra Code Mode source budget
+/// while still rejecting pathological files before parsing.
+const MAX_SNIPPET_FILE_BYTES: usize = 2 * crate::config::MAX_SOURCE_BYTES;
 
 /// Origin of a reusable Code Mode snippet.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
@@ -40,7 +41,7 @@ pub enum SnippetSource {
 /// Discovery metadata for a built-in or user Code Mode snippet.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct SnippetInfo {
-    /// Optional exact-tool declaration; currently descriptive, not enforced.
+    /// Optional exact-tool declaration used to scope native saved-snippet execution.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tools: Option<SnippetToolDeclarations>,
     /// Stable snippet name.
@@ -63,8 +64,8 @@ pub struct SnippetInfo {
 /// Fully resolved snippet including its source body.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct ResolvedSnippet {
-    /// Optional declaration; an empty list expresses intended deny-all access.
-    /// Execution does not yet enforce this metadata.
+    /// Optional declaration; an empty list expresses deny-all upstream access.
+    /// Host saved-snippet execution intersects this with the caller policy.
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub tools: Option<SnippetToolDeclarations>,
     /// Stable snippet name.
@@ -338,7 +339,11 @@ pub fn resolve_snippet(
     }
     Err(ToolError::Sdk {
         sdk_kind: "not_found".to_string(),
-        message: format!("snippet `{name}` not found"),
+        message: format!(
+            "snippet `{name}` not found; searched user snippets at `{}` and built-ins at `{}`",
+            user_dir.display(),
+            builtin_dir.display()
+        ),
     })
 }
 
@@ -536,6 +541,37 @@ pub fn validate_snippet_code(code: &str) -> Result<(), ToolError> {
             param: "body".to_string(),
         });
     }
+
+    // Parse the exact expression with the same QuickJS/Javy engine used by
+    // Code Mode, but never evaluate it. `compile_to_bytecode` declares a
+    // module and serializes bytecode only, so catalog discovery and explicit
+    // validation cannot execute snippet side effects. This closes the gap
+    // where a string could satisfy the cheap `async`/`=>` envelope check but
+    // still fail only when a real Code Mode execution tried to parse it.
+    let mut config = javy::Config::default();
+    config.memory_limit(64 * 1024 * 1024);
+    let runtime = javy::Runtime::new(config).map_err(|error| ToolError::Sdk {
+        sdk_kind: "internal_error".to_string(),
+        message: format!("unable to initialize JavaScript validator: {error}"),
+    })?;
+    let source = format!("export default ({code});");
+    runtime
+        .compile_to_bytecode("snippet-validation.js", &source)
+        .map_err(|error| {
+            let mut message = error.to_string();
+            if message.len() > 1024 {
+                let mut end = 1024;
+                while !message.is_char_boundary(end) {
+                    end -= 1;
+                }
+                message.truncate(end);
+                message.push_str("...");
+            }
+            ToolError::InvalidParam {
+                message: format!("snippet JavaScript is invalid: {message}"),
+                param: "body".to_string(),
+            }
+        })?;
     Ok(())
 }
 
@@ -987,6 +1023,44 @@ mod tests {
         assert!(validate_snippet_body("demo", valid_body()).is_ok());
     }
 
+    #[test]
+    fn validate_snippet_body_rejects_malformed_javascript_before_execution() {
+        let body = "---\nname: demo\ndescription: Broken snippet\ntags: []\n---\n\n```js\nasync () => { const broken = ; return broken; }\n```\n";
+        let error = validate_snippet_body("demo", body)
+            .expect_err("malformed JavaScript must fail static validation");
+        assert!(
+            format!("{error}").contains("snippet JavaScript is invalid"),
+            "syntax failure should explain that the JavaScript is invalid: {error}"
+        );
+    }
+
+    #[test]
+    fn validate_snippet_code_parses_without_executing_function_body() {
+        let code = "async () => { throw new Error(\"validation must not execute me\"); }";
+        assert!(
+            validate_snippet_code(code).is_ok(),
+            "validation should compile the function expression without invoking it"
+        );
+    }
+
+    #[test]
+    fn resolve_snippet_not_found_reports_searched_authorities() {
+        let lab_home = tempfile::tempdir().expect("lab home");
+        let builtin = tempfile::tempdir().expect("builtin snippets");
+        let error = resolve_snippet(lab_home.path(), builtin.path(), "missing")
+            .expect_err("missing snippet must fail");
+        let message = format!("{error}");
+        assert!(message.contains("missing"));
+        assert!(
+            message.contains(&user_snippet_dir(lab_home.path()).display().to_string()),
+            "error must identify the user snippet authority: {message}"
+        );
+        assert!(
+            message.contains(&builtin.path().display().to_string()),
+            "error must identify the builtin snippet authority: {message}"
+        );
+    }
+
     #[test]
     fn atomic_write_snippet_rejects_overwrite_without_force_under_lock() {
         // The authoritative no-overwrite guard lives INSIDE atomic_write_snippet,
@@ -1030,6 +1104,41 @@ mod tests {
         assert!(validate_snippet_body("demo", body).is_ok());
     }
 
+    #[test]
+    fn snippet_catalog_exposes_metadata_without_saved_source() {
+        const SOURCE_SENTINEL: &str = "SOURCE_SENTINEL_MUST_STAY_EXECUTION_SIDE";
+        let lab_home = tempfile::tempdir().expect("temp lab home");
+        let builtin_dir = tempfile::tempdir().expect("temp builtin dir");
+        let code = format!(
+            "async () => {{ const marker = \"{SOURCE_SENTINEL}\"; return {{ ok: marker.length > 0 }}; }}"
+        );
+        create_user_snippet(
+            lab_home.path(),
+            "metadata-only",
+            &code,
+            Some("Metadata-only catalog oracle"),
+            false,
+        )
+        .expect("create user snippet");
+
+        let listed = list_snippets(lab_home.path(), builtin_dir.path())
+            .expect("list saved snippet metadata");
+        let serialized = serde_json::to_string(&listed).expect("serialize catalog metadata");
+        assert!(serialized.contains("metadata-only"));
+        assert!(serialized.contains("Metadata-only catalog oracle"));
+        assert!(
+            !serialized.contains(SOURCE_SENTINEL),
+            "saved source must not enter model-facing snippet catalog metadata"
+        );
+
+        let resolved = resolve_snippet(lab_home.path(), builtin_dir.path(), "metadata-only")
+            .expect("host-side source resolution");
+        assert!(
+            resolved.body.contains(SOURCE_SENTINEL),
+            "source must remain available to the execution plane"
+        );
+    }
+
     #[test]
     fn repo_status_gh_pulse_builtin_is_discoverable_and_executable() {
         let lab_home = tempfile::tempdir().expect("temp lab home");
@@ -1106,7 +1215,10 @@ mod tests {
         assert!(validate_snippet_body("demo", &body).is_ok());
 
         // A code block that itself exceeds the code limit must fail.
-        let big_code = format!("async () => {{\n{}\nreturn 1;\n}}", "// pad\n".repeat(4096));
+        let big_code = format!(
+            "async () => {{\n{}\nreturn 1;\n}}",
+            "x".repeat(MAX_SNIPPET_CODE_BYTES)
+        );
         assert!(big_code.len() > MAX_SNIPPET_CODE_BYTES);
         let body = format!(
             "---\nname: demo\ndescription: Demo snippet\ntags: []\n---\n\n```js\n{big_code}\n```\n"
@@ -1116,6 +1228,23 @@ mod tests {
         assert!(format!("{error}").contains("snippet code exceeds"));
     }
 
+    #[test]
+    fn validate_snippet_body_accepts_context_sized_code_beyond_legacy_20k() {
+        let context = "x".repeat(64 * 1024);
+        let code = format!(
+            "async () => {{ const context = \"{context}\"; return {{ ok: context.length > 0 }}; }}"
+        );
+        assert!(
+            code.len() > 20 * 1024,
+            "oracle must exceed the retired 20 KiB cap"
+        );
+        assert!(
+            code.len() < MAX_SNIPPET_CODE_BYTES,
+            "oracle should fit the Code Mode source budget"
+        );
+        assert!(validate_snippet_body("demo", &code).is_ok());
+    }
+
     #[test]
     fn validate_snippet_body_bounds_bare_code_without_fences() {
         // A bare snippet body (no frontmatter, no fences) is its own code, so
@@ -1123,7 +1252,10 @@ mod tests {
         let small = "async () => ({ ok: true })";
         assert!(validate_snippet_body("demo", small).is_ok());
 
-        let big = format!("async () => {{\n{}\nreturn 1;\n}}", "// pad\n".repeat(4096));
+        let big = format!(
+            "async () => {{\n{}\nreturn 1;\n}}",
+            "x".repeat(MAX_SNIPPET_CODE_BYTES)
+        );
         assert!(big.len() > MAX_SNIPPET_CODE_BYTES);
         let error = validate_snippet_body("demo", &big)
             .expect_err("oversized bare code should be rejected");
diff --git a/crates/labby-codemode/src/snippet/tool_declarations.rs b/crates/labby-codemode/src/snippet/tool_declarations.rs
index 691cc5a93..ba832c73b 100644
--- a/crates/labby-codemode/src/snippet/tool_declarations.rs
+++ b/crates/labby-codemode/src/snippet/tool_declarations.rs
@@ -13,9 +13,10 @@ pub const MAX_DECLARED_TOOLS: usize = 128;
 /// Bound one exact tool identifier independently of the source-file limit.
 pub const MAX_DECLARED_TOOL_ID_BYTES: usize = 1_024;
 
-/// Validated descriptive upstream-tool metadata, not an execution restriction.
-/// `Some(empty)` expresses an intended deny-all declaration; `None` records no
-/// declaration. Neither changes the caller's existing execution policy.
+/// Validated exact upstream-tool dependencies for saved snippets.
+/// `Some(empty)` expresses deny-all upstream access; `None` records no extra
+/// restriction. Host surfaces may intersect this declaration with the caller's
+/// existing policy, so it can only narrow authority and never grant it.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 #[serde(try_from = "Vec<String>")]
 pub struct SnippetToolDeclarations(Vec<String>);
diff --git a/crates/labby-codemode/src/truncate.rs b/crates/labby-codemode/src/truncate.rs
index 9107a8f77..cd351bc8b 100644
--- a/crates/labby-codemode/src/truncate.rs
+++ b/crates/labby-codemode/src/truncate.rs
@@ -31,11 +31,32 @@ pub(crate) fn truncate_execution_response(
         return response;
     }
 
-    // calls[] carries lightweight metadata only (no result payloads), so there
-    // is nothing per-call to truncate. Cap the FINAL result first — but only
-    // when doing so actually shrinks the envelope. The marker has a ~1 KB
-    // preview, so markering an already-small result (e.g. `{"ok":true}`)
-    // would *grow* it; in a logs-dominant response the result is innocent and
+    // Preserve the model-requested final result before optional debug detail.
+    // High-fan-out executions can make redacted call params dominate an otherwise
+    // compact response (for example, dozens of SSH command strings). Params are
+    // explicitly optional trace metadata, so drop them first under envelope
+    // pressure while preserving every call record and its timing/error fields.
+    // This keeps a useful compact result from being replaced by a truncation
+    // marker merely because tracing was enabled.
+    if response.calls.iter().any(|call| call.params.is_some()) {
+        for call in &mut response.calls {
+            call.params = None;
+        }
+        if response_within_budget(
+            &response,
+            max_response_bytes,
+            max_response_tokens,
+            token_estimate_divisor,
+        ) {
+            return response;
+        }
+    }
+
+    // Cap the FINAL result next, but only when doing so actually shrinks the
+    // envelope. The marker has a ~1 KB preview, so markering an already-small
+    // result (e.g. `{"ok":true}`) would *grow* it. In a logs-dominant response
+    // the result therefore remains intact and the log trimming path below gets
+    // the next opportunity to reclaim space.
     if let Some(result) = response.result.as_ref() {
         let original_len = serde_json::to_string(result).map(|s| s.len()).unwrap_or(0);
         // Prefer the complete example, then trade preview bytes for guidance.
@@ -417,6 +438,45 @@ mod tests {
         );
     }
 
+    #[test]
+    fn high_fanout_trace_params_are_dropped_before_compact_result() {
+        let calls = (0..76)
+            .map(|i| CodeModeExecutedCall {
+                id: format!("ssh::{i}"),
+                ok: true,
+                elapsed_ms: 25,
+                start_ms: Some(i * 3),
+                params: Some(json!({
+                    "command": format!("ssh host-{i} {}", "x".repeat(2048)),
+                    "timeout": 20_000
+                })),
+                error_kind: None,
+                ui: None,
+            })
+            .collect::<Vec<_>>();
+        let expected_result = json!({
+            "ok": true,
+            "artifact": "homelab/docker-inventory.json",
+            "containers": 138
+        });
+        let mut response = response_with_logs(expected_result.clone(), Vec::new());
+        response.calls = calls;
+        assert!(
+            !response_within_budget(&response, 24 * 1024, 6_000, 4),
+            "oracle must begin over budget"
+        );
+
+        let truncated = truncate_execution_response(response, 24 * 1024, 6_000, 4);
+
+        assert_eq!(truncated.result, Some(expected_result));
+        assert_eq!(truncated.calls.len(), 76, "call records must survive");
+        assert!(
+            truncated.calls.iter().all(|call| call.params.is_none()),
+            "optional trace params should be the first pressure valve"
+        );
+        assert!(response_within_budget(&truncated, 24 * 1024, 6_000, 4));
+    }
+
     #[test]
     fn large_log_set_cut_matches_probe_serialized_contract() {
         // Varied line lengths plus JSON-escaped and multibyte characters so the
diff --git a/crates/labby-gateway/src/gateway/code_mode/search.rs b/crates/labby-gateway/src/gateway/code_mode/search.rs
index 59c48806f..60031c2a0 100644
--- a/crates/labby-gateway/src/gateway/code_mode/search.rs
+++ b/crates/labby-gateway/src/gateway/code_mode/search.rs
@@ -131,7 +131,7 @@ pub(crate) async fn build_tools_render(
 ) -> Result<ToolsRender, ToolError> {
     let raw_tools = if use_cache {
         manager
-            .code_mode_catalog_tools_cached(Some(owner), oauth_subject)
+            .code_mode_catalog_tools_cached_allowed(Some(owner), oauth_subject, allowed_upstreams)
             .await?
     } else {
         manager
diff --git a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
index f0c5a1b2c..ba8a605d6 100644
--- a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
+++ b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
@@ -454,6 +454,16 @@ impl GatewayManager {
         &self,
         owner: Option<&UpstreamRuntimeOwner>,
         oauth_subject: Option<&str>,
+    ) -> Result<Vec<UpstreamTool>, ToolError> {
+        self.code_mode_catalog_tools_cached_allowed(owner, oauth_subject, None)
+            .await
+    }
+
+    pub async fn code_mode_catalog_tools_cached_allowed(
+        &self,
+        owner: Option<&UpstreamRuntimeOwner>,
+        oauth_subject: Option<&str>,
+        allowed_upstreams: Option<&BTreeSet<String>>,
     ) -> Result<Vec<UpstreamTool>, ToolError> {
         use crate::gateway::code_mode::catalog_cache;
 
@@ -474,7 +484,11 @@ impl GatewayManager {
         // fresh tools are stored under (`None` for subject-scoped OAuth probes,
         // which are never cached).
         let mut pending: Vec<(UpstreamConfig, Option<String>)> = Vec::new();
-        for upstream in cfg.upstream.iter().filter(|u| u.enabled) {
+        for upstream in cfg
+            .upstream
+            .iter()
+            .filter(|u| u.enabled && upstream_allowed(&u.name, allowed_upstreams))
+        {
             if upstream.oauth.is_some() {
                 if oauth_subject.is_some() {
                     pending.push((upstream.clone(), None));
@@ -599,7 +613,7 @@ impl GatewayManager {
                 }
                 Ok(Some((upstream, _, Err(error)))) => {
                     outstanding.remove(&upstream.name);
-                    tracing::warn!(
+                    tracing::debug!(
                         surface = "dispatch",
                         service = "gateway",
                         action = "code_mode.catalog_cache",
@@ -712,7 +726,7 @@ impl GatewayManager {
             warn_suppressed(&suppressed);
         }
         if !in_flight.is_empty() || !not_attempted.is_empty() {
-            tracing::warn!(
+            tracing::info!(
                 surface = "dispatch",
                 service = "gateway",
                 action = "code_mode.catalog_cache",
@@ -1017,16 +1031,17 @@ impl GatewayManager {
         self.semantic_search_available_locked().await
     }
 
-    /// Record a TEI failure, starting/refreshing the cooldown window. Logs a
-    /// `tracing::warn!` only on the healthy→failing transition so repeated
-    /// failures during an active cooldown don't spam the log.
+    /// Record a TEI failure, starting/refreshing the cooldown window. This is a
+    /// recovered optional-dependency degradation, so log the healthy→failing
+    /// transition at INFO; repeated failures during an active cooldown stay
+    /// silent and normal CLI output is not polluted by a fallback that worked.
     pub(crate) async fn record_semantic_search_failure(&self, reason: &str) {
         let mut guard = self.semantic_search_last_failure.write().await;
         let was_healthy = guard.is_none();
         *guard = Some(Instant::now());
         drop(guard);
         if was_healthy {
-            tracing::warn!(
+            tracing::info!(
                 surface = "dispatch",
                 service = "code_mode",
                 action = "semantic_search",
@@ -1194,7 +1209,7 @@ impl GatewayManager {
 /// Separate from the budget-exhaustion warning: those upstreams may be perfectly
 /// healthy and merely slow, while these are known to have failed.
 fn warn_suppressed(suppressed: &[String]) {
-    tracing::warn!(
+    tracing::info!(
         surface = "dispatch",
         service = "gateway",
         action = "code_mode.catalog_cache",
diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index e0ca33dad..c896c56ce 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -2297,677 +2297,4 @@ impl wiremock::Respond for OneShotHttpResponder {
                 self.list_tools_requests.fetch_add(1, Ordering::SeqCst);
                 wiremock::ResponseTemplate::new(200)
                     .set_delay(self.list_tools_delay)
-                    .set_body_json(json!({
-                        "jsonrpc": "2.0",
-                        "id": id,
-                        "result": {"tools": [{
-                            "name": self.tool,
-                            "description": "one-shot catalog fixture",
-                            "inputSchema": {"type": "object"}
-                        }]}
-                    }))
-            }
-            "prompts/list" => wiremock::ResponseTemplate::new(200)
-                .set_delay(self.list_prompts_delay)
-                .set_body_json(json!({
-                    "jsonrpc": "2.0",
-                    "id": id,
-                    "result": {"prompts": []}
-                })),
-            other => wiremock::ResponseTemplate::new(500)
-                .set_body_string(format!("unexpected MCP method: {other}")),
-        }
-    }
-}
-
-async fn cold_http_upstream(
-    name: &str,
-    responder: OneShotHttpResponder,
-) -> (wiremock::MockServer, UpstreamConfig) {
-    let server = wiremock::MockServer::start().await;
-    wiremock::Mock::given(wiremock::matchers::method("POST"))
-        .and(wiremock::matchers::path("/mcp"))
-        .respond_with(responder)
-        .mount(&server)
-        .await;
-    let mut upstream = fixture_http_upstream(name);
-    upstream.url = Some(format!("{}/mcp", server.uri()));
-    (server, upstream)
-}
-
-/// An upstream that accepts the connection and then refuses the MCP handshake.
-///
-/// Deliberately not `fixture_http_upstream`'s closed port: a connect to a
-/// closed port is refused instantly on Unix but sits in SYN retransmit on
-/// Windows, so that upstream can end a run either as a genuine failure or as
-/// still in flight. Tests that assert the *failure* arm specifically — as the
-/// negative cache must, since only a real failure may be suppressed — need a
-/// fixture that fails the same way on every platform. Accepting the connection
-/// and answering 500 does that.
-async fn refusing_http_upstream(name: &str) -> (wiremock::MockServer, UpstreamConfig) {
-    let server = wiremock::MockServer::start().await;
-    wiremock::Mock::given(wiremock::matchers::method("POST"))
-        .and(wiremock::matchers::path("/mcp"))
-        .respond_with(wiremock::ResponseTemplate::new(500))
-        .mount(&server)
-        .await;
-    let mut upstream = fixture_http_upstream(name);
-    upstream.url = Some(format!("{}/mcp", server.uri()));
-    (server, upstream)
-}
-
-/// A socket that accepts and never answers, so a connect stalls until its
-/// discovery timeout (far beyond any budget used here).
-async fn stalled_http_upstream(name: &str) -> UpstreamConfig {
-    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
-        .await
-        .expect("bind stalled upstream fixture");
-    let addr = listener.local_addr().expect("listener addr");
-    tokio::spawn(async move {
-        while let Ok((socket, _)) = listener.accept().await {
-            tokio::spawn(async move {
-                let _socket = socket;
-                tokio::time::sleep(Duration::from_mins(2)).await;
-            });
-        }
-    });
-    let mut upstream = fixture_http_upstream(name);
-    upstream.url = Some(format!("http://{addr}/mcp"));
-    upstream
-}
-
-/// A manager with a fresh (cold) pool, the given Code Mode timeout, the
-/// one-shot catalog cache redirected to `cache_path`, and the discovery
-/// concurrency pinned to the product default of 3 so the tests do not depend
-/// on whatever the machine's process default happens to be. (An ambient
-/// `LABBY_UPSTREAM_DISCOVERY_CONCURRENCY` still overrides the config value.)
-async fn one_shot_manager_at(
-    upstreams: Vec<UpstreamConfig>,
-    timeout_ms: u64,
-    cache_path: PathBuf,
-) -> (GatewayManager, Arc<UpstreamPool>) {
-    one_shot_manager_with_concurrency(upstreams, timeout_ms, cache_path, 3).await
-}
-
-async fn one_shot_manager_with_concurrency(
-    upstreams: Vec<UpstreamConfig>,
-    timeout_ms: u64,
-    cache_path: PathBuf,
-    concurrency: usize,
-) -> (GatewayManager, Arc<UpstreamPool>) {
-    let (mut manager, pool) = code_mode_manager_with_upstreams(upstreams.clone()).await;
-    manager
-        .seed_config_unchecked_for_tests(GatewayConfig {
-            code_mode: CodeModeConfig {
-                enabled: true,
-                timeout_ms,
-                ..CodeModeConfig::default()
-            },
-            gateway: labby_runtime::gateway_config::GatewayPreferences {
-                upstream_discovery_concurrency: Some(concurrency),
-                ..labby_runtime::gateway_config::GatewayPreferences::default()
-            },
-            upstream: upstreams,
-            ..GatewayConfig::default()
-        })
-        .await;
-    manager.set_code_mode_catalog_cache_path_for_tests(cache_path);
-    (manager, pool)
-}
-
-async fn received_request_count(server: &wiremock::MockServer) -> usize {
-    server
-        .received_requests()
-        .await
-        .map_or(0, |requests| requests.len())
-}
-
-fn tool_ids(tools: &[UpstreamTool]) -> Vec<String> {
-    tools
-        .iter()
-        .map(|tool| format!("{}::{}", tool.upstream_name, tool.tool.name))
-        .collect()
-}
-
-/// Outer liveness guard for a budget-bounded one-shot catalog call.
-///
-/// These tests prove that the cold-connect budget, not a per-upstream
-/// discovery timeout, is what bounds the wait. The guard therefore has to stay
-/// below that discovery timeout — 30s for the stalled HTTP fixtures, since
-/// `UpstreamPool::new` uses the 30s `DEFAULT_REQUEST_TIMEOUT` — so a budget
-/// that stopped working still fails the test rather than merely running long.
-///
-/// Within that ceiling it should be as generous as possible: the calls being
-/// guarded finish in a few hundred milliseconds, and the guard is not the
-/// assertion. The returned catalog and the emitted warning carry the meaning.
-/// Earlier values as low as 5s left only a scheduling hiccup of headroom on a
-/// loaded machine, which is a flake waiting to happen and already bit the
-/// sibling Windows shard once. Note that the margin is not what makes these
-/// guards reliable: what did is [`with_captured_logs`] building the guarded
-/// future after it holds `TRACING_TEST_LOCK`, so queueing for that lock is no
-/// longer charged here. This value is headroom on top of that fix, not a
-/// substitute for it.
-const BUDGET_GUARD: Duration = Duration::from_secs(20);
-
-/// Run a future while capturing tracing output, returning its result and the
-/// captured JSON log lines.
-///
-/// Takes a closure rather than a future on purpose. `TRACING_TEST_LOCK` is
-/// process-wide and is held for the whole captured await, so under `cargo test`
-/// — one process for the entire crate — callers queue behind each other for as
-/// long as the current holder's call takes. `tokio::time::timeout` computes its
-/// deadline eagerly at construction, so building it at the call site would
-/// start the clock before this lock is acquired and charge that queue time to
-/// the caller's guard, failing it with `Elapsed` without the guarded call ever
-/// having been slow. Constructing the future here, after the lock is held,
-/// keeps a guard a measure of the call rather than of lock contention.
-#[allow(clippy::await_holding_lock)] // TRACING_TEST_LOCK must span the captured await
-async fn with_captured_logs<T, F>(build_future: impl FnOnce() -> F) -> (T, String)
-where
-    F: Future<Output = T>,
-{
-    let _tracing_lock = crate::test_support::TRACING_TEST_LOCK
-        .lock()
-        .unwrap_or_else(|error| error.into_inner());
-    let buffer = crate::test_support::SharedBuf::default();
-    let subscriber = tracing_subscriber::registry().with(
-        tracing_subscriber::fmt::layer()
-            .json()
-            .with_writer(buffer.clone())
-            .with_ansi(false)
-            .without_time(),
-    );
-    let tracing_guard = tracing::subscriber::set_default(subscriber);
-    let output = build_future().await;
-    drop(tracing_guard);
-    (output, crate::test_support::captured_logs(&buffer))
-}
-
-/// The budget warning line, if any, from captured logs.
-fn budget_warning(logs: &str) -> Option<&str> {
-    logs.lines()
-        .find(|line| line.contains("cold-connect budget exhausted"))
-}
-
-/// One-shot CLI catalog: dead and stalled upstreams ahead of a genuinely cold
-/// healthy one must not starve it. Uncached upstreams are probed concurrently
-/// under a budget derived from the Code Mode timeout (half of 6s here), the
-/// stalled straggler is named and omitted for this run, and the upstream that
-/// completed is persisted so the next run does not pay for it again. Serial
-/// probing would first wait out the stalled upstream's 30s discovery timeout,
-/// which the 15s guard rejects.
-///
-/// How the refused upstream is classified is deliberately not asserted: a
-/// connect to a closed port is refused immediately on Unix but can stay
-/// pending on Windows, so it may end the run either as a failure or as still
-/// in flight. Only that it never lands in the catalog or the cache matters
-/// here; the failure-reporting path is pinned by
-/// `one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast`.
-#[tokio::test]
-async fn one_shot_cli_catalog_bounds_cold_connects_and_persists_completed_upstreams() {
-    let stalled = stalled_http_upstream("alpha").await;
-    // `fixture_http_upstream` points at 127.0.0.1:9, which nothing listens on.
-    let dead = fixture_http_upstream("beta");
-    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
-    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    let (manager, _pool) = one_shot_manager_at(
-        vec![stalled.clone(), dead.clone(), healthy.clone()],
-        6_000,
-        cache_path.clone(),
-    )
-    .await;
-
-    let (tools, logs) = with_captured_logs(|| {
-        tokio::time::timeout(
-            BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),
-        )
-    })
-    .await;
-    let tools = tools
-        .expect("one-shot catalog must not wait out a stalled upstream's discovery timeout")
-        .expect("stalled and dead upstreams are omitted from the proxy, not an error");
-
-    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
-    assert_eq!(responder.list_tools_requests(), 1);
-    let warning = budget_warning(&logs).expect("the budget cutoff must be logged");
-    assert!(
-        warning.contains("in_flight_upstreams") && warning.contains("alpha"),
-        "the stalled upstream must be named as in flight: {warning}"
-    );
-    assert!(
-        !warning.contains("omega"),
-        "a completed upstream is not unfinished: {warning}"
-    );
-
-    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
-    assert_eq!(
-        cache
-            .fresh_tools("omega", &catalog_cache::fingerprint(&healthy))
-            .map(|tools| tools.len()),
-        Some(1),
-        "an upstream that completed must be persisted even though another stalled"
-    );
-    for (name, config) in [("alpha", &stalled), ("beta", &dead)] {
-        assert!(
-            cache
-                .fresh_tools(name, &catalog_cache::fingerprint(config))
-                .is_none(),
-            "{name} did not connect and must not be cached, so the next run retries it"
-        );
-    }
-}
-
-/// Partial means partial, not empty: when the budget ends before any upstream
-/// connected and nothing was served from cache, the one-shot catalog is an
-/// error naming what was still connecting, never a silently empty proxy.
-#[tokio::test]
-async fn one_shot_cli_catalog_errors_when_nothing_connects_within_the_budget() {
-    let stalled = stalled_http_upstream("alpha").await;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let (manager, _pool) = one_shot_manager_at(
-        vec![stalled],
-        400,
-        cache_dir.path().join("codemode-catalog.json"),
-    )
-    .await;
-
-    let error = tokio::time::timeout(
-        BUDGET_GUARD,
-        manager.code_mode_catalog_tools_cached(None, None),
-    )
-    .await
-    .expect("the budget must bound the wait")
-    .expect_err("an empty catalog at the deadline is an error");
-    match error {
-        ToolError::Sdk { sdk_kind, message } => {
-            assert_eq!(sdk_kind, "upstream_connect_error");
-            assert!(
-                message.contains("still connecting") && message.contains("alpha"),
-                "the error must name the stalled upstream: {message}"
-            );
-        }
-        other => panic!("expected upstream_connect_error, got {other:?}"),
-    }
-}
-
-/// The same rule holds without a deadline: if every uncached upstream fails
-/// fast and nothing was cached, the run errors and names each failure, rather
-/// than handing the sandbox an empty proxy with exit code 0.
-#[tokio::test]
-async fn one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast() {
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let (manager, _pool) = one_shot_manager_at(
-        vec![
-            fixture_http_upstream("beta"),
-            fixture_http_upstream("gamma"),
-        ],
-        10_000,
-        cache_dir.path().join("codemode-catalog.json"),
-    )
-    .await;
-
-    let error = tokio::time::timeout(
-        BUDGET_GUARD,
-        manager.code_mode_catalog_tools_cached(None, None),
-    )
-    .await
-    .expect("connection refused fails fast")
-    .expect_err("all-failed with an empty cache is an error");
-    match error {
-        ToolError::Sdk { sdk_kind, message } => {
-            assert_eq!(sdk_kind, "upstream_connect_error");
-            assert!(
-                message.contains("beta") && message.contains("gamma"),
-                "the error must name every failed upstream: {message}"
-            );
-        }
-        other => panic!("expected upstream_connect_error, got {other:?}"),
-    }
-}
-
-/// Concurrent probes settle out of order, yet the catalog must follow the
-/// configured upstream order; and a fresh process (new manager and pool, same
-/// cache file) must serve a fresh cache entry without connecting again.
-#[tokio::test]
-async fn one_shot_cli_catalog_keeps_config_order_and_serves_repeat_runs_from_cache() {
-    let slow = OneShotHttpResponder::new("slow_tool", Duration::from_millis(300));
-    let fast = OneShotHttpResponder::new("fast_tool", Duration::ZERO);
-    let (_slow_server, zeta) = cold_http_upstream("zeta", slow.clone()).await;
-    let (_fast_server, alpha) = cold_http_upstream("alpha", fast.clone()).await;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    let upstreams = vec![zeta, alpha];
-
-    let (first_manager, _pool) =
-        one_shot_manager_at(upstreams.clone(), 10_000, cache_path.clone()).await;
-    let first = first_manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("both cold upstreams connect");
-    assert_eq!(
-        tool_ids(&first),
-        vec!["zeta::slow_tool", "alpha::fast_tool"]
-    );
-    assert_eq!(slow.list_tools_requests(), 1);
-    assert_eq!(fast.list_tools_requests(), 1);
-
-    let slow_requests = received_request_count(&_slow_server).await;
-    let fast_requests = received_request_count(&_fast_server).await;
-
-    let (second_manager, _pool) = one_shot_manager_at(upstreams, 10_000, cache_path).await;
-    let second = second_manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("fresh cache entries need no connects");
-    assert_eq!(tool_ids(&second), tool_ids(&first));
-    assert_eq!(
-        slow.list_tools_requests(),
-        1,
-        "a fresh cache entry must short-circuit without a connect"
-    );
-    assert_eq!(fast.list_tools_requests(), 1);
-    assert_eq!(
-        (
-            received_request_count(&_slow_server).await,
-            received_request_count(&_fast_server).await
-        ),
-        (slow_requests, fast_requests),
-        "a cache hit must send no request at all, not even discovery"
-    );
-}
-
-/// A cached upstream keeps the run partial rather than failed when a
-/// straggler misses the budget: the cached tools are served without a
-/// connect and the straggler is named.
-#[tokio::test]
-async fn one_shot_cli_catalog_serves_cached_upstreams_when_a_straggler_misses_the_budget() {
-    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
-    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    let (warm_manager, _pool) =
-        one_shot_manager_at(vec![healthy.clone()], 10_000, cache_path.clone()).await;
-    warm_manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("warm the cache");
-    assert_eq!(responder.list_tools_requests(), 1);
-
-    let stalled = stalled_http_upstream("alpha").await;
-    let (manager, _pool) = one_shot_manager_at(vec![stalled, healthy], 400, cache_path).await;
-    let (tools, logs) = with_captured_logs(|| {
-        tokio::time::timeout(
-            BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),
-        )
-    })
-    .await;
-    let tools = tools
-        .expect("the budget must bound the wait")
-        .expect("a cached upstream keeps the catalog partial, not failed");
-
-    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
-    assert_eq!(
-        responder.list_tools_requests(),
-        1,
-        "the cached upstream must be served without a connect"
-    );
-    let warning = budget_warning(&logs).expect("the budget cutoff must be logged");
-    assert!(
-        warning.contains("alpha"),
-        "straggler must be named: {warning}"
-    );
-}
-
-/// An upstream whose tools landed before the budget ended is connected even if
-/// the connect's trailing prompt-cache refresh is what the deadline cut off:
-/// its tools are served and cached, and nothing is reported as unfinished.
-#[tokio::test]
-async fn one_shot_cli_catalog_keeps_an_upstream_whose_tools_landed_before_the_cutoff() {
-    let responder = OneShotHttpResponder::new("ping", Duration::ZERO)
-        .with_prompts_delay(Duration::from_mins(2));
-    let (_server, mut healthy) = cold_http_upstream("omega", responder).await;
-    healthy.proxy_prompts = true;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    let (manager, _pool) =
-        one_shot_manager_at(vec![healthy.clone()], 4_000, cache_path.clone()).await;
-
-    let (tools, logs) = with_captured_logs(|| {
-        tokio::time::timeout(
-            BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),
-        )
-    })
-    .await;
-    let tools = tools
-        .expect("the budget must bound the wait")
-        .expect("tools that landed before the cutoff are served");
-
-    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
-    assert!(
-        budget_warning(&logs).is_none(),
-        "a harvested upstream is not unfinished: {logs}"
-    );
-    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
-    assert_eq!(
-        cache
-            .fresh_tools("omega", &catalog_cache::fingerprint(&healthy))
-            .map(|tools| tools.len()),
-        Some(1)
-    );
-}
-
-/// OAuth upstreams stay subject-scoped on the one-shot path: with a subject
-/// their tools are served from the subject cache, without one they are
-/// skipped, and they are never written to the on-disk catalog cache.
-#[tokio::test]
-async fn one_shot_cli_catalog_keeps_oauth_upstreams_subject_scoped_and_uncached() {
-    let upstream = fixture_oauth_upstream("private", "http://unused.invalid/mcp");
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    let (manager, pool) =
-        one_shot_manager_at(vec![upstream.clone()], 10_000, cache_path.clone()).await;
-    pool.install_test_subject_tools_for_upstream(
-        &upstream,
-        "alice",
-        vec![rmcp::model::Tool::new(
-            "private_ping".to_string(),
-            "private ping".to_string(),
-            Arc::new(serde_json::Map::new()),
-        )],
-    )
-    .await;
-
-    let with_subject = manager
-        .code_mode_catalog_tools_cached(None, Some("alice"))
-        .await
-        .expect("subject-scoped tools are served");
-    assert_eq!(tool_ids(&with_subject), vec!["private::private_ping"]);
-
-    let without_subject = manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("OAuth upstreams are skipped without a subject");
-    assert!(without_subject.is_empty());
-
-    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
-    assert!(
-        cache
-            .fresh_tools("private", &catalog_cache::fingerprint(&upstream))
-            .is_none(),
-        "subject-scoped catalogs must never reach the shared cache"
-    );
-}
-
-/// Probes that never got a discovery slot are reported as not attempted, not
-/// as still connecting: with one slot and a stalled upstream ahead of a
-/// healthy one, the healthy one is never contacted and the error says so.
-#[tokio::test]
-async fn one_shot_cli_catalog_names_unattempted_upstreams_when_stalled_probes_fill_the_slots() {
-    let stalled = stalled_http_upstream("alpha").await;
-    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
-    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let (manager, _pool) = one_shot_manager_with_concurrency(
-        vec![stalled, healthy],
-        1_000,
-        cache_dir.path().join("codemode-catalog.json"),
-        1,
-    )
-    .await;
-
-    let error = tokio::time::timeout(
-        BUDGET_GUARD,
-        manager.code_mode_catalog_tools_cached(None, None),
-    )
-    .await
-    .expect("the budget must bound the wait")
-    .expect_err("nothing connected, so the catalog is an error");
-    assert_eq!(responder.list_tools_requests(), 0, "omega never got a slot");
-    match error {
-        ToolError::Sdk { sdk_kind, message } => {
-            assert_eq!(sdk_kind, "upstream_connect_error");
-            assert!(
-                message.contains("still connecting") && message.contains("alpha"),
-                "alpha was in flight: {message}"
-            );
-            assert!(
-                message.contains("not attempted") && message.contains("omega"),
-                "omega was never attempted: {message}"
-            );
-        }
-        other => panic!("expected upstream_connect_error, got {other:?}"),
-    }
-    let second = tokio::time::timeout(
-        BUDGET_GUARD,
-        manager.code_mode_catalog_tools_cached(None, None),
-    )
-    .await
-    .expect("second bounded run completes")
-    .expect("omega gets the next admission turn");
-    assert_eq!(tool_ids(&second), vec!["omega::ping"]);
-    assert_eq!(responder.list_tools_requests(), 1);
-}
-
-/// A fresh cache entry with zero tools (a resource- or prompt-only upstream)
-/// still counts as served from cache: a straggler missing the budget leaves
-/// the run partial with an empty tool list, not failed.
-#[tokio::test]
-async fn one_shot_cli_catalog_treats_a_cached_zero_tool_upstream_as_served() {
-    let quiet = fixture_http_upstream("omega");
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-    catalog_cache::merge_and_store(
-        cache_path.clone(),
-        vec![catalog_cache::CatalogCacheUpdate {
-            upstream_name: "omega".to_string(),
-            fingerprint: catalog_cache::fingerprint(&quiet),
-            tools: Vec::new(),
-        }],
-        Vec::new(),
-    )
-    .await;
-
-    let stalled = stalled_http_upstream("alpha").await;
-    let (manager, _pool) = one_shot_manager_at(vec![stalled, quiet], 400, cache_path).await;
-    let (tools, logs) = with_captured_logs(|| {
-        tokio::time::timeout(
-            BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),
-        )
-    })
-    .await;
-    let tools = tools
-        .expect("the budget must bound the wait")
-        .expect("a cached zero-tool upstream keeps the run partial, not failed");
-    assert!(tools.is_empty());
-    let warning = budget_warning(&logs).expect("the straggler must be logged");
-    assert!(
-        warning.contains("alpha"),
-        "straggler must be named: {warning}"
-    );
-}
-
-/// A genuinely failing upstream must not cost a connect on every invocation.
-///
-/// `fixture_http_upstream` points at the discard port, so the probe fails fast
-/// rather than stalling — this is the failure path, distinct from the
-/// budget-exhaustion paths, and the only one the negative cache may suppress.
-#[tokio::test]
-async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-
-    let (dead_server, dead) = refusing_http_upstream("dead").await;
-    let (server, healthy) =
-        cold_http_upstream("healthy", OneShotHttpResponder::new("ping", Duration::ZERO)).await;
-    let (manager, _pool) =
-        one_shot_manager_at(vec![dead.clone(), healthy], 4_000, cache_path.clone()).await;
-
-    let first = manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("first run should serve the healthy upstream");
-    assert_eq!(
-        first
-            .iter()
-            .map(|tool| tool.tool.name.as_ref())
-            .collect::<Vec<_>>(),
-        vec!["ping"]
-    );
-
-    // The failure is now on disk, and the healthy upstream is cached, so the
-    // second run must reach neither the network nor the dead upstream.
-    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
-    assert!(
-        cache.probe_suppressed("dead", &catalog_cache::fingerprint(&dead)),
-        "a failed probe must leave a negative entry"
-    );
-
-    let (second, logs) =
-        with_captured_logs(|| manager.code_mode_catalog_tools_cached(None, None)).await;
-    let second = second.expect("second run should still serve the cached healthy upstream");
-    assert_eq!(
-        second
-            .iter()
-            .map(|tool| tool.tool.name.as_ref())
-            .collect::<Vec<_>>(),
-        vec!["ping"]
-    );
-    assert!(
-        logs.contains("suppressed"),
-        "a suppressed upstream must be reported, not silently dropped: {logs}"
-    );
-    drop(server);
-    drop(dead_server);
-}
-
-/// Suppression must never be the reason a catalog comes back empty.
-#[tokio::test]
-async fn an_entirely_suppressed_fleet_is_an_error_not_an_empty_catalog() {
-    let cache_dir = tempfile::tempdir().expect("tempdir");
-    let cache_path = cache_dir.path().join("codemode-catalog.json");
-
-    let (dead_server, dead) = refusing_http_upstream("dead").await;
-    let (manager, _pool) = one_shot_manager_at(vec![dead], 4_000, cache_path.clone()).await;
-
-    manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect_err("a fleet with nothing reachable is already an error");
-
-    let error = manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect_err("suppression must not turn that into a silent empty catalog");
-    let message = format!("{error}");
-    assert!(
-        message.contains("suppressed") && message.contains("dead"),
-        "the error must name the suppressed upstream: {message}"
-    );
-    drop(dead_server);
-}
+                    .set_body_json(json!({
\ No newline at end of file
diff --git a/crates/labby-gateway/src/security/spawn_guard.rs b/crates/labby-gateway/src/security/spawn_guard.rs
index 08544b74a..64e92ed91 100644
--- a/crates/labby-gateway/src/security/spawn_guard.rs
+++ b/crates/labby-gateway/src/security/spawn_guard.rs
@@ -12,6 +12,9 @@
 //! - [`DANGEROUS_DOCKER_FLAGS`] / [`DANGEROUS_NODE_FLAGS`] / [`DANGEROUS_BUN_FLAGS`] — argv flags that
 //!   are rejected for the corresponding runtime families.
 
+use std::collections::BTreeSet;
+use std::sync::{Mutex, OnceLock};
+
 use labby_runtime::error::ToolError;
 
 /// Runtime hints / commands the gateway is allowed to execute as stdio upstreams.
@@ -96,22 +99,37 @@ pub const DANGEROUS_DENO_FLAGS: &[&str] = &["eval", "--allow-all", "-A"];
 /// skip the command allowlist **entirely**. This is a coarse, global escape
 /// hatch — with it set, `bash`, `/bin/sh -c`, and arbitrary binaries like
 /// `/tmp/evil` all become spawnable. Prefer `extra_stdio_commands` and leave
-/// the guard on. When the bypass is active, every skipped validation emits a
-/// `WARN` so the weakened posture is visible in logs.
+/// the guard on. When the bypass is active, the first validation of each
+/// distinct command emits a `WARN`; repeats are suppressed so one unsafe
+/// setting cannot flood every CLI response while the weakened posture remains
+/// visible.
 ///
 /// Returns `invalid_param` if the command is not in either allowlist.
+fn warn_spawn_guard_bypass(command: &str) {
+    static WARNED_COMMANDS: OnceLock<Mutex<BTreeSet<String>>> = OnceLock::new();
+    let warned = WARNED_COMMANDS.get_or_init(|| Mutex::new(BTreeSet::new()));
+    let first_for_command = warned
+        .lock()
+        .unwrap_or_else(|poisoned| poisoned.into_inner())
+        .insert(command.to_string());
+    if first_for_command {
+        tracing::warn!(
+            service = "upstream.pool",
+            command = %command,
+            "SECURITY: spawn-guard bypass active — command allowlist NOT enforced \
+             (disable_spawn_guard = true); prefer scoping with [gateway] extra_stdio_commands; \
+             repeated warnings for this command are suppressed"
+        );
+    }
+}
+
 pub fn validate_stdio_command(
     command: &str,
     extra: &[String],
     bypass: bool,
 ) -> Result<(), ToolError> {
     if bypass {
-        tracing::warn!(
-            service = "upstream.pool",
-            command = %command,
-            "SECURITY: spawn-guard bypass active — command allowlist NOT enforced \
-             (disable_spawn_guard = true); prefer scoping with [gateway] extra_stdio_commands"
-        );
+        warn_spawn_guard_bypass(command);
         return Ok(());
     }
 
@@ -442,10 +460,11 @@ mod tests {
                     .without_time(),
             );
 
+        let command = "/tmp/spawn-guard-warn-oracle";
         {
             let _guard = tracing::subscriber::set_default(subscriber);
             // The bypass path must allow the otherwise-rejected command...
-            assert!(validate_stdio_command("bash", &[], true).is_ok());
+            assert!(validate_stdio_command(command, &[], true).is_ok());
         }
 
         // ...AND emit a WARN documenting the weakened posture (Sec-M2).
@@ -459,11 +478,44 @@ mod tests {
             "WARN must identify the spawn-guard bypass; captured logs: {logs}"
         );
         assert!(
-            logs.contains("bash"),
+            logs.contains(command),
             "WARN should record the bypassed command; captured logs: {logs}"
         );
     }
 
+    #[test]
+    fn command_bypass_warn_is_deduplicated_per_command() {
+        use tracing_subscriber::layer::SubscriberExt;
+        use tracing_subscriber::{EnvFilter, fmt};
+
+        let _tracing_lock = TRACING_TEST_LOCK.lock().unwrap_or_else(|e| e.into_inner());
+        let buf = SharedBuf::default();
+        let subscriber = tracing_subscriber::registry()
+            .with(EnvFilter::new("labby_gateway=warn"))
+            .with(
+                fmt::layer()
+                    .json()
+                    .with_writer(buf.clone())
+                    .with_ansi(false)
+                    .without_time(),
+            );
+        let command = "/tmp/spawn-guard-dedupe-oracle";
+
+        {
+            let _guard = tracing::subscriber::set_default(subscriber);
+            assert!(validate_stdio_command(command, &[], true).is_ok());
+            assert!(validate_stdio_command(command, &[], true).is_ok());
+            assert!(validate_stdio_command(command, &[], true).is_ok());
+        }
+
+        let logs = captured_logs(&buf);
+        assert_eq!(
+            logs.matches("spawn-guard bypass active").count(),
+            1,
+            "repeat validations of one command must not spam WARN output: {logs}"
+        );
+    }
+
     #[test]
     fn command_no_bypass_emits_no_warn() {
         use tracing_subscriber::layer::SubscriberExt;
diff --git a/crates/labby-gateway/src/upstream/pool/connect.rs b/crates/labby-gateway/src/upstream/pool/connect.rs
index 8759f8b64..a6ce3402d 100644
--- a/crates/labby-gateway/src/upstream/pool/connect.rs
+++ b/crates/labby-gateway/src/upstream/pool/connect.rs
@@ -450,7 +450,7 @@ pub(super) async fn connect_upstream_with_handler_and_notifications<H: ClientHan
             elapsed_ms = started.elapsed().as_millis(),
             "upstream connection acquire finish"
         ),
-        Err(error) => tracing::warn!(
+        Err(error) => tracing::info!(
             surface = "dispatch",
             service = "upstream.pool",
             action = "upstream.connect",
diff --git a/crates/labby-gateway/src/upstream/pool/lifecycle_compat.rs b/crates/labby-gateway/src/upstream/pool/lifecycle_compat.rs
index 8a27682e2..f36291f7a 100644
--- a/crates/labby-gateway/src/upstream/pool/lifecycle_compat.rs
+++ b/crates/labby-gateway/src/upstream/pool/lifecycle_compat.rs
@@ -173,7 +173,7 @@ pub(super) fn log_fallback(
     attempt: LifecycleAttempt,
     error: &anyhow::Error,
 ) {
-    tracing::warn!(
+    tracing::info!(
         surface = "dispatch",
         service = "upstream.pool",
         action = "upstream.lifecycle.fallback",
diff --git a/crates/labby-gateway/src/upstream/pool/probe.rs b/crates/labby-gateway/src/upstream/pool/probe.rs
index c11cc0c49..1e5e78fab 100644
--- a/crates/labby-gateway/src/upstream/pool/probe.rs
+++ b/crates/labby-gateway/src/upstream/pool/probe.rs
@@ -270,7 +270,10 @@ impl UpstreamPool {
         started: Instant,
     ) -> Heartbeat {
         let Some(observed) = self.observe_connection_catalog_entry(&config.name).await else {
-            tracing::warn!(
+            // Cold one-shot catalog construction legitimately reprobes before a
+            // connection exists, then immediately falls through to reconnect.
+            // That is expected control flow, not an operator-actionable failure.
+            tracing::info!(
                 surface = "dispatch",
                 service = "upstream.pool",
                 action = "upstream.reprobe",
@@ -280,7 +283,7 @@ impl UpstreamPool {
                 transport = upstream_transport(config),
                 elapsed_ms = started.elapsed().as_millis(),
                 kind = "upstream_not_connected",
-                "upstream reprobe found no existing connection"
+                "upstream reprobe found no existing connection; reconnecting"
             );
             return Heartbeat::Reconnect { previous: None };
         };
diff --git a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
index 81534fef9..e38bbb724 100644
--- a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
+++ b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
@@ -249,7 +249,7 @@ async fn log_termination(
     let success = status.is_some_and(ExitStatus::success);
     let invalidated_count = invalidated_requests.len();
 
-    if expected && success && invalidated_count == 0 {
+    if invalidated_count == 0 {
         tracing::info!(
             surface = "dispatch",
             service = "upstream.pool",
@@ -261,10 +261,12 @@ async fn log_termination(
             expected,
             exit_code = ?code,
             exit_signal = ?signal,
+            wait_error = exit.wait_error.as_deref(),
             killed_after_timeout = exit.killed_after_timeout,
             invalidated_count,
             stderr_tail = %stderr_tail,
-            "stdio upstream child terminated"
+            success,
+            "stdio upstream child terminated without affected requests"
         );
     } else {
         tracing::warn!(
diff --git a/crates/labby-runtime/src/gateway_config.rs b/crates/labby-runtime/src/gateway_config.rs
index 12dc15537..c0cf39841 100644
--- a/crates/labby-runtime/src/gateway_config.rs
+++ b/crates/labby-runtime/src/gateway_config.rs
@@ -57,7 +57,7 @@ fn default_code_mode_timeout_ms() -> u64 {
 }
 
 fn default_code_mode_max_source_bytes() -> usize {
-    128 * 1024
+    1024 * 1024
 }
 
 fn default_code_mode_max_response_bytes() -> usize {
@@ -2151,611 +2151,4 @@ expose_code_mode = true
         }
 
         let unlabelled: UpstreamConfig =
-            toml::from_str("name=\"asana\"\nurl=\"https://x/mcp\"\n").unwrap();
-        assert!(
-            !toml::to_string(&unlabelled)
-                .unwrap()
-                .contains("display_name"),
-            "configs without a label keep serializing byte-identically"
-        );
-    }
-
-    #[test]
-    fn the_first_party_origin_label_is_reserved_from_upstreams() {
-        let cfg: UpstreamConfig =
-            toml::from_str("name=\"labby\"\nurl=\"https://x/mcp\"\nproxy_skills=true\n").unwrap();
-        let error = cfg
-            .validate()
-            .expect_err("an upstream must not claim Labby's own skill namespace");
-        assert!(format!("{error}").contains("reserved"));
-
-        // ...but only when it actually proxies skills; the name is otherwise
-        // unremarkable and must not break an existing deployment.
-        let without: UpstreamConfig =
-            toml::from_str("name=\"labby\"\nurl=\"https://x/mcp\"\n").unwrap();
-        without.validate().expect("no skills, no reservation");
-    }
-
-    #[test]
-    fn omitted_transport_preserves_legacy_inference() {
-        let http: UpstreamConfig =
-            toml::from_str("name=\"http\"\nurl=\"https://example.com/mcp\"\n").unwrap();
-        assert_eq!(http.effective_transport(), Some(UpstreamTransport::Http));
-
-        let websocket: UpstreamConfig =
-            toml::from_str("name=\"ws\"\nurl=\"wss://example.com/mcp\"\n").unwrap();
-        assert_eq!(
-            websocket.effective_transport(),
-            Some(UpstreamTransport::Websocket)
-        );
-
-        let stdio: UpstreamConfig = toml::from_str("name=\"stdio\"\ncommand=\"server\"\n").unwrap();
-        assert_eq!(stdio.effective_transport(), Some(UpstreamTransport::Stdio));
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn filesystem_unix_socket_transport_parses_and_validates() {
-        let cfg: UpstreamConfig = toml::from_str(
-            "name=\"local\"\ntransport=\"unix_socket\"\nsocket_path=\"/tmp/local-mcp.sock\"\nurl=\"http://local.internal/mcp\"\n",
-        )
-        .unwrap();
-
-        assert_eq!(
-            cfg.effective_transport(),
-            Some(UpstreamTransport::UnixSocket)
-        );
-        assert_eq!(cfg.socket_path.as_deref(), Some("/tmp/local-mcp.sock"));
-        assert!(cfg.validate().is_ok());
-    }
-
-    #[test]
-    fn socket_path_without_unix_transport_is_rejected() {
-        let cfg: UpstreamConfig = toml::from_str(
-            "name=\"bad\"\nsocket_path=\"/tmp/local-mcp.sock\"\nurl=\"http://local.internal/mcp\"\n",
-        )
-        .unwrap();
-
-        let error = cfg.validate().unwrap_err();
-        assert!(matches!(error, ConfigError::InvalidTransport { .. }));
-        assert!(error.to_string().contains("socket_path requires transport"));
-    }
-
-    #[cfg(unix)]
-    #[test]
-    fn unix_socket_requires_url_and_valid_path() {
-        let missing_url: UpstreamConfig = toml::from_str(
-            "name=\"bad\"\ntransport=\"unix_socket\"\nsocket_path=\"/tmp/local-mcp.sock\"\n",
-        )
-        .unwrap();
-        assert!(missing_url.validate().is_err());
-
-        let empty_abstract_socket: UpstreamConfig = toml::from_str(
-            "name=\"bad\"\ntransport=\"unix_socket\"\nsocket_path=\"@\"\nurl=\"http://local.internal/mcp\"\n",
-        )
-        .unwrap();
-        assert!(empty_abstract_socket.validate().is_err());
-
-        #[cfg(target_os = "linux")]
-        {
-            let abstract_socket: UpstreamConfig = toml::from_str(
-                "name=\"local\"\ntransport=\"unix_socket\"\nsocket_path=\"@local-mcp\"\nurl=\"http://local.internal/mcp\"\n",
-            )
-            .unwrap();
-            assert!(abstract_socket.validate().is_ok());
-        }
-    }
-
-    #[test]
-    fn custom_headers_validate_before_pool_publication() {
-        let valid: UpstreamConfig = toml::from_str(
-            "name=\"local\"\nurl=\"http://local.internal/mcp\"\n[headers]\nx-labby-test=\"present\"\n",
-        )
-        .unwrap();
-        assert!(valid.validate().is_ok());
-
-        for invalid_toml in [
-            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\nauthorization=\"Bearer secret\"\n",
-            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\n\"bad header\"=\"value\"\n",
-            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\nx-test=\"bad\\nvalue\"\n",
-        ] {
-            let cfg: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
-            assert!(cfg.validate().is_err());
-        }
-    }
-
-    #[test]
-    fn inferred_transports_enforce_their_field_contracts() {
-        for invalid_toml in [
-            "name=\"bad\"\ncommand=\"server\"\n[headers]\nx-test=\"value\"\n",
-            "name=\"bad\"\nurl=\"ws://local.internal/mcp\"\n[headers]\nx-test=\"value\"\n",
-            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\ncommand=\"server\"\n",
-            "name=\"bad\"\n",
-        ] {
-            let cfg: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
-            assert!(
-                cfg.validate().is_err(),
-                "config should fail: {invalid_toml}"
-            );
-        }
-    }
-
-    #[test]
-    fn stdio_preserves_named_bearer_environment_injection() {
-        let cfg: UpstreamConfig = toml::from_str(
-            "name=\"stdio\"\ncommand=\"server\"\nbearer_token_env=\"SERVER_TOKEN\"\n",
-        )
-        .unwrap();
-
-        assert_eq!(cfg.effective_transport(), Some(UpstreamTransport::Stdio));
-        assert!(cfg.validate().is_ok());
-    }
-
-    #[test]
-    fn explicit_transport_rejects_conflicting_fields() {
-        let cfg: UpstreamConfig = toml::from_str(
-            "name=\"bad\"\ntransport=\"stdio\"\ncommand=\"server\"\nurl=\"http://local.internal/mcp\"\n",
-        )
-        .unwrap();
-        assert!(cfg.validate().is_err());
-    }
-
-    #[test]
-    fn google_provider_oauth_requires_https_preregistered_secret_and_scopes() {
-        let valid: UpstreamConfig = toml::from_str(
-            r#"
-name = "google-calendar"
-url = "https://calendarmcp.googleapis.com/mcp/v1"
-[oauth]
-mode = "authorization_code_pkce"
-scopes = ["https://www.googleapis.com/auth/calendar.events.readonly"]
-[oauth.credential]
-source = "google_provider"
-account = "admin@example.com"
-[oauth.registration]
-strategy = "preregistered"
-client_id = "google-client"
-client_secret_env = "LABBY_GOOGLE_CLIENT_SECRET"
-"#,
-        )
-        .unwrap();
-        assert!(valid.validate().is_ok());
-
-        for invalid_toml in [
-            r#"
-name = "google-calendar"
-url = "http://calendarmcp.googleapis.com/mcp/v1"
-[oauth]
-mode = "authorization_code_pkce"
-scopes = ["calendar"]
-[oauth.credential]
-source = "google_provider"
-[oauth.registration]
-strategy = "preregistered"
-client_id = "google-client"
-client_secret_env = "SECRET"
-"#,
-            r#"
-name = "google-calendar"
-url = "https://calendarmcp.googleapis.com/mcp/v1"
-[oauth]
-mode = "authorization_code_pkce"
-scopes = ["calendar"]
-[oauth.credential]
-source = "google_provider"
-[oauth.registration]
-strategy = "dynamic"
-"#,
-            r#"
-name = "google-calendar"
-url = "https://calendarmcp.googleapis.com/mcp/v1"
-[oauth]
-mode = "authorization_code_pkce"
-scopes = ["calendar"]
-[oauth.credential]
-source = "google_provider"
-[oauth.registration]
-strategy = "preregistered"
-client_id = "google-client"
-"#,
-            r#"
-name = "google-calendar"
-url = "https://calendarmcp.googleapis.com/mcp/v1"
-[oauth]
-mode = "authorization_code_pkce"
-[oauth.credential]
-source = "google_provider"
-[oauth.registration]
-strategy = "preregistered"
-client_id = "google-client"
-client_secret_env = "SECRET"
-"#,
-        ] {
-            let config: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
-            assert!(matches!(
-                config.validate(),
-                Err(ConfigError::InvalidOauth { .. })
-            ));
-        }
-    }
-
-    #[test]
-    fn google_provider_credential_debug_redacts_account_selector() {
-        let source = UpstreamOauthCredentialSource::GoogleProvider {
-            account: Some("admin@example.com".to_string()),
-        };
-        let debug = format!("{source:?}");
-        assert!(!debug.contains("admin@example.com"));
-        assert!(debug.contains("<redacted>"));
-    }
-
-    #[test]
-    fn code_mode_config_defaults_roundtrip() {
-        let cfg: CodeModeConfig = toml::from_str("").unwrap();
-        let expected = CodeModeConfig::default();
-        assert_eq!(cfg, expected);
-        assert!(cfg.enabled);
-        assert!(cfg.trusted_read_only_tools.is_empty());
-        assert!(cfg.mcp_ui_enabled);
-        assert!(cfg.trace_params);
-        assert_eq!(cfg.timeout_ms, 30_000);
-        assert_eq!(cfg.token_estimate_divisor, 4);
-    }
-
-    #[test]
-    fn code_mode_timeout_range_boundaries() {
-        for (timeout_ms, accepted) in [
-            (0, false),
-            (1, true),
-            (MAX_CODE_MODE_TIMEOUT_MS, true),
-            (MAX_CODE_MODE_TIMEOUT_MS + 1, false),
-        ] {
-            let cfg = CodeModeConfig {
-                timeout_ms,
-                ..CodeModeConfig::default()
-            };
-            let result = cfg.validate();
-            assert_eq!(
-                result.is_ok(),
-                accepted,
-                "timeout_ms={timeout_ms}: {result:?}"
-            );
-            if !accepted {
-                assert!(matches!(
-                    result,
-                    Err(ConfigError::InvalidCodeModeTimeout { value }) if value == timeout_ms
-                ));
-            }
-        }
-    }
-
-    #[test]
-    fn a_legacy_trusted_read_only_tools_list_still_parses_but_is_never_echoed_back() {
-        // The field is retired: it exists only so an existing config file keeps
-        // parsing. It must not round-trip, or an operator reading the config back
-        // would see a populated list that looks like a live security control.
-        let cfg: CodeModeConfig =
-            toml::from_str("trusted_read_only_tools = [\"dookie::read_file\"]\n").unwrap();
-        assert_eq!(cfg.trusted_read_only_tools, vec!["dookie::read_file"]);
-
-        let round_tripped = serde_json::to_value(&cfg).unwrap();
-        assert!(
-            round_tripped.get("trusted_read_only_tools").is_none(),
-            "the retired field must never be serialized back to any surface"
-        );
-    }
-
-    #[test]
-    fn code_mode_mcp_ui_can_be_enabled_in_toml() {
-        let cfg: CodeModeConfig = toml::from_str(
-            "mcp_ui_enabled = true
-",
-        )
-        .unwrap();
-        assert!(cfg.mcp_ui_enabled);
-        assert!(cfg.enabled);
-    }
-
-    #[test]
-    fn mcp_apps_config_defaults_all_managed_apps_enabled() {
-        let cfg: McpAppsConfig = toml::from_str("").unwrap();
-        assert_eq!(cfg, McpAppsConfig::default());
-        assert!(cfg.manager);
-        assert!(cfg.add_server);
-        assert!(cfg.server_logs);
-        assert!(cfg.gateway_status);
-        assert!(cfg.settings);
-    }
-
-    #[test]
-    fn documented_labby_app_defaults_match_code() {
-        // GATEWAY.md is the operator-facing statement of the Labby-owned app
-        // surface defaults. Code Mode and every managed MCP App now default
-        // on, so the doc must not still promise an off-by-default posture.
-        let doc = include_str!("../../../docs/services/GATEWAY.md");
-        assert!(CodeModeConfig::default().enabled);
-        assert!(CodeModeConfig::default().mcp_ui_enabled);
-        assert_eq!(
-            McpAppsConfig::default(),
-            McpAppsConfig {
-                manager: true,
-                add_server: true,
-                server_logs: true,
-                gateway_status: true,
-                settings: true,
-            }
-        );
-        assert!(
-            !doc.contains("defaults to `false` and must be explicitly enabled"),
-            "docs/services/GATEWAY.md still documents the retired off-by-default app posture"
-        );
-        assert!(
-            doc.contains("defaults to `true`") || doc.contains("enabled by default"),
-            "docs/services/GATEWAY.md must state that Labby-owned app surfaces default on"
-        );
-    }
-
-    #[test]
-    fn mcp_apps_config_supports_independent_visibility_switches() {
-        let cfg: McpAppsConfig = toml::from_str(
-            "manager = true\nadd_server = false\nserver_logs = true\ngateway_status = false\nsettings = false\n",
-        )
-        .unwrap();
-        assert!(cfg.manager);
-        assert!(!cfg.add_server);
-        assert!(cfg.server_logs);
-        assert!(!cfg.gateway_status);
-        assert!(!cfg.settings);
-    }
-
-    #[test]
-    fn semantic_search_defaults_to_unconfigured() {
-        let cfg = CodeModeConfig::default();
-        assert!(cfg.semantic_search.tei_url.is_none());
-        assert!(!cfg.semantic_search.is_configured());
-        assert!(cfg.validate().is_ok());
-    }
-
-    #[test]
-    fn semantic_search_with_valid_http_url_is_configured_and_valid() {
-        let mut cfg = CodeModeConfig::default();
-        cfg.semantic_search.tei_url = Some("http://localhost:52000".to_string());
-        assert!(cfg.semantic_search.is_configured());
-        assert!(cfg.validate().is_ok());
-    }
-
-    #[test]
-    fn semantic_search_with_https_url_is_valid() {
-        let mut cfg = CodeModeConfig::default();
-        cfg.semantic_search.tei_url = Some("https://tei.internal.example:8443".to_string());
-        assert!(cfg.validate().is_ok());
-    }
-
-    #[test]
-    fn semantic_search_with_non_http_scheme_fails_validation() {
-        let mut cfg = CodeModeConfig::default();
-        cfg.semantic_search.tei_url = Some("ftp://example.com".to_string());
-        let err = cfg.validate().unwrap_err();
-        assert!(matches!(
-            err,
-            ConfigError::InvalidSemanticSearchTeiUrl { .. }
-        ));
-    }
-
-    #[test]
-    fn semantic_search_with_malformed_url_fails_validation() {
-        let mut cfg = CodeModeConfig::default();
-        cfg.semantic_search.tei_url = Some("not a url at all".to_string());
-        let err = cfg.validate().unwrap_err();
-        assert!(matches!(
-            err,
-            ConfigError::InvalidSemanticSearchTeiUrl { .. }
-        ));
-    }
-
-    #[test]
-    fn semantic_search_blend_weight_out_of_range_fails_validation() {
-        let mut cfg = CodeModeConfig::default();
-        cfg.semantic_search.blend_weight = 1.5;
-        let err = cfg.validate().unwrap_err();
-        assert!(matches!(
-            err,
-            ConfigError::InvalidSemanticSearchBlendWeight { .. }
-        ));
-    }
-
-    #[test]
-    fn semantic_search_toml_round_trips_with_defaults_when_omitted() {
-        // An existing config.toml with a `[code_mode]` section but no
-        // `semantic_search` subsection must still deserialize (backward
-        // compatibility with every config.toml written before this feature).
-        let toml_str = "enabled = true\ntimeout_ms = 30000\n";
-        let cfg: CodeModeConfig = toml::from_str(toml_str).unwrap();
-        assert!(cfg.semantic_search.tei_url.is_none());
-        assert!(!cfg.semantic_search.is_configured());
-    }
-
-    #[test]
-    fn protected_route_backend_mcp_path_defaults_to_mcp() {
-        let route: ProtectedMcpRouteConfig = toml::from_str(
-            "name=\"r\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\nbackend_url=\"http://10.0.0.1:3100/mcp\"\n",
-        )
-        .unwrap();
-        assert_eq!(route.backend_mcp_path, "/mcp");
-        assert!(route.enabled);
-        assert_eq!(route.scopes, vec!["mcp:read", "mcp:write"]);
-    }
-
-    /// Bead lab-eyeuv: `__in_process__*` is the namespace of the synthetic
-    /// builtin-service peers (issue #210 FU-1). A configured upstream using
-    /// that prefix would shadow a builtin's catalog entry and capture its
-    /// Code Mode tool calls, so it is rejected at load rather than merely
-    /// discouraged by comment.
-    #[test]
-    fn upstream_name_rejects_the_reserved_in_process_prefix() {
-        let cfg: UpstreamConfig =
-            toml::from_str("name=\"__in_process__gateway\"\nurl=\"https://example.com/mcp\"\n")
-                .unwrap();
-
-        let error = cfg
-            .validate()
-            .expect_err("reserved prefix must be rejected");
-        let rendered = error.to_string();
-        assert!(rendered.contains("__in_process__"), "{rendered}");
-
-        // Ordinary names that merely contain the token are fine — only the
-        // prefix is reserved.
-        let ok: UpstreamConfig =
-            toml::from_str("name=\"my__in_process__thing\"\nurl=\"https://example.com/mcp\"\n")
-                .unwrap();
-        assert!(ok.validate().is_ok());
-    }
-
-    /// A protected route must not be able to opt itself into builtin tools by
-    /// naming a synthetic peer in its upstream allowlist — the `fail closed`
-    /// property FU-1 documents is now enforced, not assumed.
-    #[test]
-    fn protected_route_rejects_reserved_in_process_upstreams() {
-        let mut route: ProtectedMcpRouteConfig = toml::from_str(
-            "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
-        )
-        .unwrap();
-        route.backend_url = String::new();
-        route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
-            ProtectedGatewaySubsetTarget {
-                project_id: None,
-                loadout: None,
-                upstreams: vec![format!("{IN_PROCESS_UPSTREAM_PREFIX}setup")],
-                services: Vec::new(),
-                expose_code_mode: false,
-            },
-        ));
-        let mut cfg = GatewayConfig {
-            protected_mcp_routes: vec![route],
-            ..GatewayConfig::default()
-        };
-
-        let error = cfg
-            .normalize_protected_mcp_routes()
-            .expect_err("a protected route must not name an in-process peer");
-        let rendered = error.to_string();
-        assert!(rendered.contains("__in_process__setup"), "{rendered}");
-        assert!(rendered.contains("target.services"), "{rendered}");
-    }
-
-    /// The reserved prefix and the name builder in `labby-gateway` must stay
-    /// in lockstep; the builder formats with this constant.
-    #[test]
-    fn in_process_prefix_constant_is_stable() {
-        assert_eq!(IN_PROCESS_UPSTREAM_PREFIX, "__in_process__");
-    }
-    /// `gateway.loadout.*` responses must always carry `upstreams` and
-    /// `services` as arrays. Omitting an empty selection made every JSON
-    /// consumer that treats them as required arrays fail on a Loadout that
-    /// picked only upstreams or only services.
-    #[test]
-    fn loadout_json_always_carries_both_selection_arrays() {
-        let upstreams_only = GatewayLoadoutConfig {
-            name: "sd".to_string(),
-            upstreams: vec!["chrome-devtools".to_string()],
-            ..GatewayLoadoutConfig::default()
-        };
-        let services_only = GatewayLoadoutConfig {
-            name: "ops".to_string(),
-            services: vec!["gateway".to_string()],
-            ..GatewayLoadoutConfig::default()
-        };
-
-        for loadout in [&upstreams_only, &services_only] {
-            let value = serde_json::to_value(loadout).expect("loadout serializes to JSON");
-            let object = value.as_object().expect("loadout serializes as an object");
-            assert!(
-                object
-                    .get("upstreams")
-                    .is_some_and(serde_json::Value::is_array),
-                "upstreams must always be an array: {value}"
-            );
-            assert!(
-                object
-                    .get("services")
-                    .is_some_and(serde_json::Value::is_array),
-                "services must always be an array: {value}"
-            );
-        }
-
-        assert_eq!(
-            serde_json::to_value(&services_only)
-                .expect("loadout serializes to JSON")
-                .get("upstreams"),
-            Some(&serde_json::json!([])),
-            "a services-only Loadout still reports an empty upstream selection"
-        );
-    }
-
-    /// Always-serialized selections must survive a TOML round trip, including
-    /// the explicit empty arrays now written into `config.toml`.
-    #[test]
-    fn loadout_toml_round_trips_empty_selection_arrays() {
-        let services_only = GatewayLoadoutConfig {
-            name: "ops".to_string(),
-            services: vec!["gateway".to_string()],
-            ..GatewayLoadoutConfig::default()
-        };
-
-        let rendered = toml::to_string(&services_only).expect("loadout serializes to TOML");
-        assert!(rendered.contains("upstreams = []"), "{rendered}");
-
-        let parsed: GatewayLoadoutConfig =
-            toml::from_str(&rendered).expect("loadout parses back from TOML");
-        assert_eq!(parsed, services_only);
-    }
-    #[test]
-    fn protected_route_project_id_normalization_is_bounded_and_compatible() {
-        fn config(project_id: Option<String>) -> GatewayConfig {
-            let mut route: ProtectedMcpRouteConfig = toml::from_str(
-                "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
-            )
-            .unwrap();
-            route.backend_url = String::new();
-            route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
-                ProtectedGatewaySubsetTarget {
-                    project_id,
-                    ..Default::default()
-                },
-            ));
-            GatewayConfig {
-                protected_mcp_routes: vec![route],
-                ..Default::default()
-            }
-        }
-
-        let mut omitted = config(None);
-        omitted
-            .normalize_protected_mcp_routes()
-            .expect("legacy None");
-        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
-            omitted.protected_mcp_routes[0].target.as_ref()
-        else {
-            unreachable!()
-        };
-        assert_eq!(target.project_id, None);
-
-        let expected = "x".repeat(MAX_PROJECT_ID_LEN);
-        let mut trimmed = config(Some(format!("  {expected}  ")));
-        trimmed.normalize_protected_mcp_routes().expect("128 bytes");
-        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
-            trimmed.protected_mcp_routes[0].target.as_ref()
-        else {
-            unreachable!()
-        };
-        assert_eq!(target.project_id.as_deref(), Some(expected.as_str()));
-
-        for invalid in ["   ".to_string(), "x".repeat(MAX_PROJECT_ID_LEN + 1)] {
-            assert!(
-                config(Some(invalid))
-                    .normalize_protected_mcp_routes()
-                    .is_err()
-            );
-        }
-    }
-}
+            toml::from_str("name=\"asana\"\nurl=\"https://x/mcp\"\n").unwrap();
\ No newline at end of file
diff --git a/crates/labby/src/config.rs b/crates/labby/src/config.rs
index 49a4646c3..90aea6458 100644
--- a/crates/labby/src/config.rs
+++ b/crates/labby/src/config.rs
@@ -2301,2989 +2301,4 @@ fn prune_config_backups(parent: &Path, target: &Path) -> Result<usize> {
         .map(|entry| {
             let entry = entry?;
             let path = entry.path();
-            let metadata = entry
-                .metadata()
-                .with_context(|| format!("inspect config backup {}", path.display()))?;
-            let modified = metadata
-                .modified()
-                .with_context(|| format!("inspect config backup {}", path.display()))?;
-            Ok(ConfigBackupCandidate {
-                path,
-                modified,
-                bytes: metadata.len(),
-            })
-        })
-        .collect::<Result<Vec<_>>>()?;
-    let removals = select_config_backups_to_prune(
-        backups,
-        std::time::SystemTime::now(),
-        ConfigBackupRetention {
-            max_count: CONFIG_BACKUP_RETENTION,
-            max_age: CONFIG_BACKUP_MAX_AGE,
-            max_bytes: CONFIG_BACKUP_MAX_BYTES,
-        },
-    );
-    for backup in &removals {
-        std::fs::remove_file(backup)
-            .with_context(|| format!("remove old config backup {}", backup.display()))?;
-    }
-    Ok(removals.len())
-}
-
-fn select_config_backups_to_prune(
-    mut backups: Vec<ConfigBackupCandidate>,
-    now: std::time::SystemTime,
-    retention: ConfigBackupRetention,
-) -> Vec<PathBuf> {
-    backups.sort_by(|left, right| {
-        left.modified
-            .cmp(&right.modified)
-            .then_with(|| left.path.cmp(&right.path))
-    });
-    let Some(newest) = backups.last().map(|candidate| candidate.path.clone()) else {
-        return Vec::new();
-    };
-    let mut retained_count = backups.len();
-    let mut retained_bytes = backups.iter().fold(0_u64, |total, candidate| {
-        total.saturating_add(candidate.bytes)
-    });
-    let mut removals = Vec::new();
-    for candidate in backups {
-        if candidate.path == newest {
-            continue;
-        }
-        let expired = now
-            .duration_since(candidate.modified)
-            .is_ok_and(|age| age > retention.max_age);
-        let over_count = retained_count > retention.max_count.max(1);
-        let over_bytes = retained_bytes > retention.max_bytes;
-        if expired || over_count || over_bytes {
-            retained_count = retained_count.saturating_sub(1);
-            retained_bytes = retained_bytes.saturating_sub(candidate.bytes);
-            removals.push(candidate.path);
-        }
-    }
-    removals
-}
-
-fn backup_config_file(path: &Path, raw: &str) -> Result<PathBuf> {
-    let nanos = std::time::SystemTime::now()
-        .duration_since(std::time::UNIX_EPOCH)
-        .map_or(0, |duration| duration.as_nanos());
-    let pid = std::process::id();
-    for _ in 0..10 {
-        let counter = CONFIG_BACKUP_COUNTER.fetch_add(1, Ordering::Relaxed);
-        let backup = path.with_extension(format!("toml.bak.{nanos}.{pid}.{counter}"));
-        let mut options = OpenOptions::new();
-        options.write(true).create_new(true);
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::OpenOptionsExt;
-            options.mode(0o600);
-        }
-        match options.open(&backup) {
-            Ok(mut file) => {
-                if let Err(error) = secret_files::restrict_secret_file_permissions(&backup) {
-                    drop(file);
-                    drop(std::fs::remove_file(&backup));
-                    return Err(error).with_context(|| {
-                        format!("restrict backup {} before writing", backup.display())
-                    });
-                }
-                file.write_all(raw.as_bytes())
-                    .with_context(|| format!("write backup {}", backup.display()))?;
-                file.sync_all()
-                    .with_context(|| format!("sync backup {}", backup.display()))?;
-                return Ok(backup);
-            }
-            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
-            Err(e) => {
-                return Err(
-                    anyhow::Error::new(e).context(format!("create backup {}", backup.display()))
-                );
-            }
-        }
-    }
-    anyhow::bail!("failed to create unique backup for {}", path.display())
-}
-
-pub(crate) fn config_json_value_for_path(cfg: &LabConfig, path: &str) -> serde_json::Value {
-    match path {
-        "output.format" => serde_json::json!(cfg.output.format),
-        "mcp.transport" => serde_json::json!(cfg.mcp.transport),
-        "mcp.host" => serde_json::json!(cfg.mcp.host),
-        "mcp.port" => serde_json::json!(cfg.mcp.port),
-        "mcp.allowed_hosts" => serde_json::json!(cfg.mcp.allowed_hosts),
-        "log.filter" => serde_json::json!(cfg.log.filter),
-        "log.format" => serde_json::json!(cfg.log.format),
-        "local_logs.retention_days" => {
-            serde_json::json!(
-                cfg.local_logs
-                    .as_ref()
-                    .and_then(|value| value.retention_days)
-            )
-        }
-        "local_logs.max_bytes" => {
-            serde_json::json!(cfg.local_logs.as_ref().and_then(|value| value.max_bytes))
-        }
-        "local_logs.queue_capacity" => {
-            serde_json::json!(
-                cfg.local_logs
-                    .as_ref()
-                    .and_then(|value| value.queue_capacity)
-            )
-        }
-        "local_logs.subscriber_capacity" => {
-            serde_json::json!(
-                cfg.local_logs
-                    .as_ref()
-                    .and_then(|value| value.subscriber_capacity)
-            )
-        }
-        "api.cors_origins" => serde_json::json!(cfg.api.cors_origins),
-        "web.assets_dir" => {
-            serde_json::json!(
-                cfg.web
-                    .assets_dir
-                    .as_ref()
-                    .map(|path| path.display().to_string())
-            )
-        }
-        "workspace.root" => {
-            serde_json::json!(
-                cfg.workspace
-                    .root
-                    .as_ref()
-                    .map(|path| path.display().to_string())
-            )
-        }
-        "public_urls.app" => {
-            serde_json::json!(cfg.public_urls.as_ref().and_then(|value| value.app.clone()))
-        }
-        "public_urls.mcp_gateway" => serde_json::json!(
-            cfg.public_urls
-                .as_ref()
-                .and_then(|value| value.mcp_gateway.clone())
-        ),
-        "services.built_in_upstream_apis_enabled" => {
-            serde_json::json!(cfg.services.built_in_upstream_apis_enabled)
-        }
-        "services.tailscale.tailnet" => serde_json::json!(cfg.services.tailscale.tailnet),
-        "admin.enabled" => serde_json::json!(cfg.admin.enabled),
-        "code_mode.trace_params" => serde_json::json!(cfg.code_mode.trace_params),
-        "code_mode.timeout_ms" => serde_json::json!(cfg.code_mode.timeout_ms),
-        "code_mode.max_source_bytes" => serde_json::json!(cfg.code_mode.max_source_bytes),
-        "code_mode.max_response_bytes" => serde_json::json!(cfg.code_mode.max_response_bytes),
-        "code_mode.max_response_tokens" => serde_json::json!(cfg.code_mode.max_response_tokens),
-        "code_mode.token_estimate_divisor" => {
-            serde_json::json!(cfg.code_mode.token_estimate_divisor)
-        }
-        "code_mode.max_log_entries" => serde_json::json!(cfg.code_mode.max_log_entries),
-        "code_mode.max_log_bytes" => serde_json::json!(cfg.code_mode.max_log_bytes),
-        "gateway_import_mode" => serde_json::json!(cfg.gateway_import_mode),
-        "gateway.extra_stdio_commands" => serde_json::json!(cfg.gateway.extra_stdio_commands),
-        "upstream_request_timeout_ms" => serde_json::json!(cfg.upstream_request_timeout_ms),
-        "upstream_relay_timeout_ms" => serde_json::json!(cfg.upstream_relay_timeout_ms),
-        "web.disable_auth" => serde_json::json!(cfg.web.disable_auth),
-        "auth" => serde_json::to_value(&cfg.auth).unwrap_or(serde_json::Value::Null),
-        "code_mode.enabled" => serde_json::json!(cfg.code_mode.enabled),
-        "gateway.auto_reconnect" => serde_json::json!(cfg.gateway.auto_reconnect),
-        "gateway.disable_spawn_guard" => serde_json::json!(cfg.gateway.disable_spawn_guard),
-        "oauth.machines" => {
-            serde_json::to_value(&cfg.oauth.machines).unwrap_or(serde_json::Value::Null)
-        }
-        "upstream" => serde_json::to_value(&cfg.upstream).unwrap_or(serde_json::Value::Null),
-        "upstream_pending" => {
-            serde_json::to_value(&cfg.upstream_pending).unwrap_or(serde_json::Value::Null)
-        }
-        "upstream_import_tombstones" => {
-            serde_json::to_value(&cfg.upstream_import_tombstones).unwrap_or(serde_json::Value::Null)
-        }
-        "protected_mcp_routes" => {
-            serde_json::to_value(&cfg.protected_mcp_routes).unwrap_or(serde_json::Value::Null)
-        }
-        "virtual_servers" => {
-            serde_json::to_value(&cfg.virtual_servers).unwrap_or(serde_json::Value::Null)
-        }
-        "quarantined_virtual_servers" => serde_json::to_value(&cfg.quarantined_virtual_servers)
-            .unwrap_or(serde_json::Value::Null),
-        _ => serde_json::Value::Null,
-    }
-}
-
-/// Patch the non-secret built-in upstream API preference without rewriting
-/// unrelated TOML content.
-///
-/// This intentionally edits only `[services].built_in_upstream_apis_enabled`.
-/// It preserves comments, unknown keys, and plugin-owned sections that the
-/// full typed `LabConfig` serializer cannot round-trip.
-pub fn patch_built_in_upstream_apis_enabled(path: &Path, enabled: bool) -> Result<LabConfig> {
-    Ok(patch_config_scalars(
-        path,
-        &[ConfigScalarPatch::new(
-            "services.built_in_upstream_apis_enabled",
-            ConfigScalarValue::Bool(enabled),
-        )],
-    )?
-    .config)
-}
-
-#[allow(dead_code)]
-fn config_lock_path(path: &Path) -> PathBuf {
-    let mut lock = path.to_path_buf();
-    let file_name = path
-        .file_name()
-        .and_then(|name| name.to_str())
-        .unwrap_or("config.toml");
-    lock.set_file_name(format!("{file_name}.lock"));
-    lock
-}
-
-/// Names of the variables the process environment already carried when the
-/// first `load_dotenv` ran. dotenvy never overrides an existing variable, so
-/// these came from outside `.env` (a service manager, a container spec, the
-/// shell) and win over the file for the lifetime of the process.
-static PROCESS_ENV_KEYS_BEFORE_DOTENV: OnceLock<std::collections::BTreeSet<String>> =
-    OnceLock::new();
-
-/// Whether `key` was set in the process environment before `.env` was loaded,
-/// so an edit to `.env` cannot change its effective value. False until
-/// `load_dotenv` has run.
-#[must_use]
-pub fn env_key_set_outside_dotenv(key: &str) -> bool {
-    PROCESS_ENV_KEYS_BEFORE_DOTENV
-        .get()
-        .is_some_and(|keys| keys.contains(key))
-}
-
-/// Load `.env` files into the process environment.
-///
-/// Called after `load_toml()` and tracing init. Env vars loaded here
-/// override config.toml values at the point of use (each consumer checks
-/// env first, then falls back to config).
-pub fn load_dotenv() -> Result<()> {
-    // Names only, never values: the settings surface uses this to tell an
-    // externally managed variable from one `.env` supplied.
-    PROCESS_ENV_KEYS_BEFORE_DOTENV.get_or_init(|| {
-        std::env::vars_os()
-            .filter_map(|(key, _)| key.into_string().ok())
-            .collect()
-    });
-    // Candidates are ordered from authoritative installation state to the
-    // implicit development fallback. dotenvy preserves values loaded by an
-    // earlier candidate. An explicit LABBY_HOME excludes the CWD fallback.
-    for env_path in paths::dotenv_candidates()? {
-        if env_path.exists() {
-            dotenvy::from_path(&env_path)
-                .with_context(|| format!("failed to load {}", env_path.display()))?;
-        }
-    }
-
-    Ok(())
-}
-
-/// Load `.env` + `config.toml` in a single call (convenience for tests).
-#[allow(dead_code)]
-pub fn load() -> Result<LabConfig> {
-    let cfg = load_toml(&toml_candidates()?)?;
-    load_dotenv()?;
-    Ok(cfg)
-}
-
-/// Resolve the Code Mode `openapi` provider config from the parsed `[openapi]`
-/// TOML section plus `OPENAPI_<LABEL>_*` env vars.
-///
-/// Non-secret fields come from TOML; credentials (`OPENAPI_<LABEL>_TOKEN` /
-/// `OPENAPI_<LABEL>_API_KEY`) come from `env`. `base_url` is mandatory; reserved
-/// or duplicate labels, a missing/invalid base_url, an invalid spec_url, and an
-/// ambiguous spec source are all hard config errors that fail boot.
-///
-/// `env` is injected (rather than read from the process environment directly) so
-/// tests stay hermetic. In production callers pass a `std::env::var`-backed closure.
-#[cfg(feature = "gateway")]
-pub fn load_openapi_provider_config(
-    section: &OpenApiTomlSection,
-    env: &dyn Fn(&str) -> Option<String>,
-) -> std::result::Result<labby_openapi::OpenApiProviderConfig, ConfigError> {
-    use labby_openapi::{OpenApiCredential, OpenApiProviderConfig, OpenApiSpecConfig, SpecSource};
-
-    let mut specs = Vec::new();
-    let mut seen = std::collections::HashSet::new();
-    for raw in &section.specs {
-        let label = raw.label.trim().to_string();
-        // The wire dispatch key is `openapi::<label>.<operationId>`, split on the
-        // first `.` (operationIds may themselves contain `.`). A label containing
-        // `.`, `:`, or whitespace would misroute that split, so restrict labels to
-        // an unambiguous charset. Also keeps the `OPENAPI_<LABEL>_*` credential
-        // env-var lookup well-formed.
-        if label.is_empty()
-            || !label
-                .chars()
-                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
-        {
-            return Err(ConfigError::InvalidLabel { label });
-        }
-        if labby_openapi::RESERVED_NAMESPACES.contains(&label.as_str()) {
-            return Err(ConfigError::ReservedLabel { label });
-        }
-        if !seen.insert(label.clone()) {
-            return Err(ConfigError::DuplicateLabel { label });
-        }
-        let base_url: url::Url = raw
-            .base_url
-            .as_deref()
-            .map(str::trim)
-            .filter(|s| !s.is_empty())
-            .ok_or_else(|| ConfigError::MissingBaseUrl {
-                label: label.clone(),
-            })?
-            .parse()
-            .map_err(|_| ConfigError::InvalidBaseUrl {
-                label: label.clone(),
-            })?;
-
-        let upper = label.to_uppercase();
-        let credential = env(&format!("OPENAPI_{upper}_TOKEN"))
-            .filter(|t| !t.is_empty())
-            .map(OpenApiCredential::BearerToken)
-            .or_else(|| {
-                env(&format!("OPENAPI_{upper}_API_KEY"))
-                    .filter(|k| !k.is_empty())
-                    .map(|value| OpenApiCredential::ApiKey {
-                        header: raw
-                            .api_key_header
-                            .clone()
-                            .filter(|h| !h.trim().is_empty())
-                            .unwrap_or_else(|| "X-API-Key".into()),
-                        value,
-                    })
-            });
-
-        let spec_source = match (
-            raw.spec_url
-                .as_deref()
-                .map(str::trim)
-                .filter(|s| !s.is_empty()),
-            raw.spec_path
-                .as_deref()
-                .map(str::trim)
-                .filter(|s| !s.is_empty()),
-        ) {
-            (Some(u), None) => {
-                SpecSource::Url(u.parse().map_err(|_| ConfigError::InvalidSpecUrl {
-                    label: label.clone(),
-                })?)
-            }
-            (None, Some(p)) => SpecSource::Path(p.into()),
-            _ => {
-                return Err(ConfigError::SpecSourceAmbiguous {
-                    label: label.clone(),
-                });
-            }
-        };
-
-        specs.push(OpenApiSpecConfig {
-            label,
-            spec_source,
-            base_url,
-            allowed_operations: raw.allowed_operations.clone(),
-            credential,
-        });
-    }
-    Ok(OpenApiProviderConfig { specs })
-}
-
-/// A string value that redacts itself in `Debug` and `Display` output.
-///
-/// Use for secret env values (`API_KEY`, `TOKEN`, `PASSWORD`) so they
-/// never leak through `Debug`-printing config structs or tracing fields.
-#[allow(dead_code)]
-#[derive(Clone, Deserialize, PartialEq, Eq)]
-pub struct Secret(String);
-
-impl Secret {
-    #[must_use]
-    pub const fn new(value: String) -> Self {
-        Self(value)
-    }
-
-    #[must_use]
-    #[allow(dead_code)]
-    pub fn expose(&self) -> &str {
-        &self.0
-    }
-}
-
-impl std::fmt::Debug for Secret {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("[REDACTED]")
-    }
-}
-
-impl std::fmt::Display for Secret {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.write_str("[REDACTED]")
-    }
-}
-
-impl Serialize for Secret {
-    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
-        serializer.serialize_str("***REDACTED***")
-    }
-}
-
-/// Value from an instance env var — either plain text or a secret.
-///
-/// Always constructed programmatically via the private `scan_instances_from` helper; never
-/// deserialized from JSON. `Deserialize` is intentionally omitted — `Secret`
-/// serializes as `"***REDACTED***"` (a plain string), so an `#[serde(untagged)]`
-/// impl would silently pick `Plain` for every value, bypassing redaction.
-#[allow(dead_code)]
-#[derive(Debug, Clone, Serialize)]
-pub enum InstanceValue {
-    Plain(String),
-    Redacted(Secret),
-}
-
-impl InstanceValue {
-    #[must_use]
-    #[allow(dead_code)]
-    pub fn expose(&self) -> &str {
-        match self {
-            Self::Plain(s) => s,
-            Self::Redacted(s) => s.expose(),
-        }
-    }
-}
-
-/// Suffixes that carry secret values and must be wrapped in [`Secret`].
-#[allow(dead_code)]
-const SECRET_SUFFIXES: &[&str] = &["API_KEY", "TOKEN", "PASSWORD"];
-
-/// Parse multi-instance env vars for a given service prefix.
-///
-/// Returns a map from instance label (`"default"` or `"<label>"`) to the
-/// set of `(suffix, value)` pairs. Example: for prefix `UNRAID`, env vars
-/// `UNRAID_URL`, `UNRAID_API_KEY`, `UNRAID_NODE2_URL`, `UNRAID_NODE2_API_KEY`
-/// yield two entries keyed `"default"` and `"node2"`.
-///
-/// Suffixes are matched longest-first to avoid collisions when a label
-/// contains a shorter suffix as a substring.
-#[must_use]
-#[allow(dead_code)]
-pub fn scan_instances(prefix: &str) -> HashMap<String, HashMap<String, InstanceValue>> {
-    scan_instances_from(prefix, std::env::vars())
-}
-
-/// Inner implementation testable without mutating process env.
-fn scan_instances_from(
-    prefix: &str,
-    vars: impl Iterator<Item = (String, String)>,
-) -> HashMap<String, HashMap<String, InstanceValue>> {
-    let mut out: HashMap<String, HashMap<String, InstanceValue>> = HashMap::new();
-
-    let mut known_suffixes = ["URL", "API_KEY", "TOKEN", "USERNAME", "PASSWORD"];
-    known_suffixes.sort_by_key(|s| std::cmp::Reverse(s.len()));
-
-    let prefix_under = format!("{prefix}_");
-
-    for (key, value) in vars {
-        let Some(rest) = key.strip_prefix(&prefix_under) else {
-            continue;
-        };
-
-        for suffix in &known_suffixes {
-            let wrap = |v: String| {
-                if SECRET_SUFFIXES.contains(suffix) {
-                    InstanceValue::Redacted(Secret::new(v))
-                } else {
-                    InstanceValue::Plain(v)
-                }
-            };
-
-            if rest == *suffix {
-                out.entry("default".to_string())
-                    .or_default()
-                    .insert((*suffix).to_string(), wrap(value.clone()));
-                break;
-            }
-            if let Some(label) = rest.strip_suffix(&format!("_{suffix}"))
-                && !label.is_empty()
-            {
-                out.entry(label.to_ascii_lowercase())
-                    .or_default()
-                    .insert((*suffix).to_string(), wrap(value.clone()));
-                break;
-            }
-        }
-    }
-
-    out
-}
-
-#[cfg(test)]
-#[allow(clippy::panic)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn owned_section_typos_fail_while_foreign_top_level_extensions_survive() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(
-            &path,
-            "[mcp]\nporrt = 9876\n\n[external_extension]\nmode = \"custom\"\n",
-        )
-        .unwrap();
-
-        let error = load_toml(std::slice::from_ref(&path)).unwrap_err();
-        let detail = format!("{error:#}");
-        assert!(detail.contains("porrt"), "{detail}");
-
-        std::fs::write(&path, "[external_extension]\nmode = \"custom\"\n").unwrap();
-        assert!(load_toml(&[path]).is_ok());
-    }
-
-    #[test]
-    fn inherited_app_surface_sections_name_only_the_absent_tables() {
-        // An existing config.toml written before Code Mode and the Labby MCP
-        // Apps defaulted on inherits those defaults silently unless startup
-        // names them. Only genuinely absent sections are reported.
-        assert_eq!(
-            inherited_app_surface_sections(""),
-            vec!["code_mode", "mcp_apps"]
-        );
-        assert_eq!(
-            inherited_app_surface_sections("[mcp]\nport = 8765\n"),
-            vec!["code_mode", "mcp_apps"]
-        );
-        assert_eq!(
-            inherited_app_surface_sections("[code_mode]\nenabled = false\n"),
-            vec!["mcp_apps"]
-        );
-        assert_eq!(
-            inherited_app_surface_sections(
-                "[code_mode]\nenabled = true\n[mcp_apps]\nmanager = false\n"
-            ),
-            Vec::<&str>::new()
-        );
-        // Unparseable input is the loader's error to report, not this hint's.
-        assert_eq!(
-            inherited_app_surface_sections("mcp = \"bad"),
-            Vec::<&str>::new()
-        );
-    }
-
-    #[test]
-    fn top_level_scalar_typos_fail_but_named_extension_tables_survive() {
-        for typo in ["mcpp = 1\n", "config_verzion = 1\n"] {
-            let error = validate_top_level_extension_boundary(typo).unwrap_err();
-            assert!(error.to_string().contains("unknown top-level scalar"));
-        }
-        validate_top_level_extension_boundary("[vendor.example]\nenabled = true\n").unwrap();
-    }
-
-    #[test]
-    fn missing_config_version_migrates_to_current_and_future_versions_fail() {
-        let legacy: LabConfig = toml::from_str("[mcp]\nport = 9876\n").unwrap();
-        assert_eq!(legacy.config_version, CURRENT_CONFIG_VERSION);
-        legacy.validate().unwrap();
-
-        let future: LabConfig = toml::from_str("config_version = 999\n").unwrap();
-        let error = future.validate().unwrap_err();
-        assert!(error.to_string().contains("config_version 999"));
-    }
-
-    #[test]
-    fn patching_legacy_config_persists_the_migrated_format_version() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "[mcp]\nport = 8765\n").unwrap();
-
-        patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(9876),
-            )],
-        )
-        .unwrap();
-
-        let persisted = std::fs::read_to_string(path).unwrap();
-        assert!(persisted.contains("config_version = 1"), "{persisted}");
-    }
-
-    #[test]
-    fn config_mutations_retain_only_the_ten_newest_backups() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "config_version = 1\n[mcp]\nport = 8765\n").unwrap();
-        for port in 8800..8815 {
-            patch_config_scalars(
-                &path,
-                &[ConfigScalarPatch::new(
-                    "mcp.port",
-                    ConfigScalarValue::I64(port),
-                )],
-            )
-            .unwrap();
-        }
-
-        let backups = std::fs::read_dir(dir.path())
-            .unwrap()
-            .filter_map(Result::ok)
-            .filter(|entry| entry.file_name().to_string_lossy().contains(".toml.bak."))
-            .count();
-        assert_eq!(backups, 10);
-    }
-
-    #[test]
-    fn committed_config_reports_post_commit_maintenance_failure_as_warning() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "config_version = 1\n[mcp]\nport = 8765\n").unwrap();
-        std::fs::write(
-            dir.path().join(".labby-test-config-maintenance-failure"),
-            b"inject",
-        )
-        .unwrap();
-
-        let outcome = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(9876),
-            )],
-        )
-        .expect("durable commit must not be reported as failed");
-
-        assert_eq!(outcome.config.mcp.port, Some(9876));
-        assert!(
-            std::fs::read_to_string(&path)
-                .unwrap()
-                .contains("port = 9876")
-        );
-        assert!(
-            outcome
-                .maintenance_warning
-                .as_deref()
-                .is_some_and(|warning| warning.contains("configuration was committed"))
-        );
-        assert!(outcome.backup_path.is_some());
-    }
-
-    #[test]
-    fn backup_retention_enforces_age_and_bytes_without_pruning_newest() {
-        let now = std::time::UNIX_EPOCH + Duration::from_secs(10_000);
-        let candidates = vec![
-            ConfigBackupCandidate::fixture("old", 100, now - Duration::from_secs(5_000)),
-            ConfigBackupCandidate::fixture("large", 900, now - Duration::from_secs(20)),
-            ConfigBackupCandidate::fixture("newest", 900, now - Duration::from_secs(10)),
-        ];
-
-        let pruned = select_config_backups_to_prune(
-            candidates,
-            now,
-            ConfigBackupRetention {
-                max_count: 10,
-                max_age: Duration::from_secs(1_000),
-                max_bytes: 500,
-            },
-        );
-
-        assert_eq!(pruned, vec![PathBuf::from("old"), PathBuf::from("large")]);
-    }
-
-    #[test]
-    fn backup_retention_is_deterministic_for_equal_timestamps() {
-        let now = std::time::UNIX_EPOCH + Duration::from_secs(10_000);
-        let modified = now - Duration::from_secs(10);
-        let candidates = vec![
-            ConfigBackupCandidate::fixture("c", 1, modified),
-            ConfigBackupCandidate::fixture("a", 1, modified),
-            ConfigBackupCandidate::fixture("b", 1, modified),
-        ];
-
-        let pruned = select_config_backups_to_prune(
-            candidates,
-            now,
-            ConfigBackupRetention {
-                max_count: 2,
-                max_age: Duration::MAX,
-                max_bytes: u64::MAX,
-            },
-        );
-
-        assert_eq!(pruned, vec![PathBuf::from("a")]);
-    }
-
-    fn resolve_oauth_fixture(config: &AuthFileConfig) -> auth_config::AuthConfig {
-        resolve_auth_with_env(
-            Some(config),
-            [("LABBY_TOKEN_ENCRYPTION_KEY".to_string(), "11".repeat(32))],
-        )
-        .expect("OAuth fixture should resolve")
-    }
-
-    /// `install_resolved_preferences` must pick up config.toml values when no
-    /// overriding env var is set. This test does not touch process env, so
-    /// it's safe under both nextest's per-process isolation and cargo test's
-    /// threaded model, unlike a test that would need to mutate `std::env`.
-    #[test]
-    fn install_resolved_preferences_picks_up_config_toml_values() {
-        let mut config = LabConfig::default();
-        config.mcp.show_all = Some(true);
-        config.api.dev_mode = Some(true);
-        config.api.protected_mcp_connect_timeout_secs = Some(42);
-        config.mcp.catalog_notification_timeout_ms = Some(2_500);
-        config.code_mode.widget_callbacks = Some(true);
-        config.output.symbols = Some("ascii".to_string());
-
-        install_resolved_preferences(&config);
-
-        assert!(resolved_show_all(), "mcp.show_all should resolve true");
-        assert!(resolved_dev_mode(), "api.dev_mode should resolve true");
-        assert!(
-            resolved_widget_callbacks_enabled(),
-            "code_mode.widget_callbacks should resolve true"
-        );
-        assert_eq!(resolved_symbols().as_deref(), Some("ascii"));
-        assert_eq!(resolved_protected_mcp_connect_timeout_secs(), Some(42));
-        assert_eq!(
-            resolved_catalog_notification_timeout(),
-            Duration::from_millis(2_500)
-        );
-
-        // Restore defaults so this test doesn't leak state into whichever
-        // test the process/thread runs next (matches the existing
-        // process_code_mode_enabled restore-after-test convention below).
-        install_resolved_preferences(&LabConfig::default());
-        assert!(!resolved_show_all());
-        assert!(!resolved_dev_mode());
-        assert!(!resolved_widget_callbacks_enabled());
-        assert_eq!(resolved_symbols(), None);
-        assert_eq!(resolved_protected_mcp_connect_timeout_secs(), None);
-        assert_eq!(
-            resolved_catalog_notification_timeout(),
-            Duration::from_millis(DEFAULT_CATALOG_NOTIFICATION_TIMEOUT_MS)
-        );
-    }
-
-    fn parse_normalized_config(toml: &str) -> LabConfig {
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes().expect("normalize");
-        cfg
-    }
-
-    #[test]
-    fn artifact_authority_urls_have_separate_config_contracts() {
-        let cfg = parse_normalized_config(
-            r#"
-[[artifacts.sources]]
-id = "primary"
-kind = "depot"
-endpoint = "https://depot.example/api/artifacts/exact"
-control_plane_url = "https://depot.example"
-pinned_addresses = ["8.8.8.8"]
-bearer_token_env = "LABBY_DEPOT_TOKEN"
-"#,
-        );
-        let source = &cfg.artifacts.sources[0];
-        assert_eq!(source.endpoint, "https://depot.example/api/artifacts/exact");
-        assert_eq!(
-            source.control_plane_url.as_deref(),
-            Some("https://depot.example")
-        );
-        assert_eq!(
-            source.bearer_token_env.as_deref(),
-            Some("LABBY_DEPOT_TOKEN")
-        );
-    }
-
-    #[cfg(feature = "gateway")]
-    fn openapi_section(toml: &str) -> OpenApiTomlSection {
-        toml::from_str::<LabConfig>(toml).expect("parse").openapi
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_reserved_label_rejected() {
-        let toml = r#"[[openapi.specs]]
-label = "git"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-allowed_operations = ["getUser"]"#;
-        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
-        assert!(matches!(err, ConfigError::ReservedLabel { ref label } if label == "git"));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_dotted_label_rejected() {
-        // A label containing `.` would misroute the `openapi::<label>.<operationId>`
-        // dispatch split — reject it at config load.
-        let toml = r#"[[openapi.specs]]
-label = "ven.dor"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-allowed_operations = ["getUser"]"#;
-        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
-        assert!(matches!(err, ConfigError::InvalidLabel { ref label } if label == "ven.dor"));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_missing_base_url_rejected() {
-        let toml = r#"[[openapi.specs]]
-label = "vendor"
-spec_url = "https://api.example.com/openapi.json"
-allowed_operations = ["getUser"]"#;
-        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
-        assert!(matches!(err, ConfigError::MissingBaseUrl { .. }));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_duplicate_label_rejected() {
-        let toml = r#"[[openapi.specs]]
-label = "vendor"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-
-[[openapi.specs]]
-label = "vendor"
-base_url = "https://api2.example.com"
-spec_url = "https://api2.example.com/openapi.json""#;
-        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
-        assert!(matches!(err, ConfigError::DuplicateLabel { ref label } if label == "vendor"));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_ambiguous_spec_source_rejected() {
-        let toml = r#"[[openapi.specs]]
-label = "vendor"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-spec_path = "/tmp/openapi.json""#;
-        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
-        assert!(matches!(err, ConfigError::SpecSourceAmbiguous { .. }));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_credential_read_from_env_not_toml() {
-        let toml = r#"[[openapi.specs]]
-label = "vendor"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-allowed_operations = ["getUser"]"#;
-        let env = |k: &str| (k == "OPENAPI_VENDOR_TOKEN").then(|| "tok-123".to_string());
-        let cfg = load_openapi_provider_config(&openapi_section(toml), &env).unwrap();
-        assert!(cfg.specs[0].credential.is_some());
-        // Credential must NEVER round-trip through the TOML struct.
-        assert!(!format!("{:?}", cfg.specs[0]).contains("tok-123"));
-    }
-
-    #[cfg(feature = "gateway")]
-    #[test]
-    fn openapi_api_key_uses_configured_header() {
-        let toml = r#"[[openapi.specs]]
-label = "vendor"
-base_url = "https://api.example.com"
-spec_url = "https://api.example.com/openapi.json"
-api_key_header = "X-Custom-Key""#;
-        let env = |k: &str| (k == "OPENAPI_VENDOR_API_KEY").then(|| "sk-abc".to_string());
-        let cfg = load_openapi_provider_config(&openapi_section(toml), &env).unwrap();
-        match &cfg.specs[0].credential {
-            Some(labby_openapi::OpenApiCredential::ApiKey { header, .. }) => {
-                assert_eq!(header, "X-Custom-Key");
-            }
-            _ => panic!("expected ApiKey credential"),
-        }
-    }
-
-    fn vars<'a>(pairs: &'a [(&'a str, &'a str)]) -> impl Iterator<Item = (String, String)> + 'a {
-        pairs
-            .iter()
-            .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
-    }
-
-    #[test]
-    fn service_preferences_default_enable_upstream_apis() {
-        let cfg = toml::from_str::<LabConfig>("").expect("empty config should parse");
-        assert!(cfg.services.built_in_upstream_apis_enabled);
-    }
-
-    #[test]
-    fn service_preferences_can_disable_upstream_apis() {
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-            [services]
-            built_in_upstream_apis_enabled = false
-            ",
-        )
-        .expect("services config should parse");
-
-        assert!(!cfg.services.built_in_upstream_apis_enabled);
-    }
-
-    #[test]
-    fn patch_built_in_upstream_apis_preserves_comments_and_unknown_sections() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(
-            &path,
-            r#"# operator note
-[services]
-# keep this comment
-built_in_upstream_apis_enabled = true
-
-[plugin_owned]
-future = "keep"
-"#,
-        )
-        .unwrap();
-
-        let cfg = patch_built_in_upstream_apis_enabled(&path, false).unwrap();
-        assert!(!cfg.services.built_in_upstream_apis_enabled);
-        let raw = std::fs::read_to_string(&path).unwrap();
-        assert!(raw.contains("# operator note"));
-        assert!(raw.contains("# keep this comment"));
-        assert!(raw.contains("[plugin_owned]"));
-        assert!(raw.contains("future = \"keep\""));
-        assert!(raw.contains("built_in_upstream_apis_enabled = false"));
-    }
-
-    #[test]
-    fn patch_config_scalars_rejects_non_table_parent_without_mutating() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "mcp = \"bad\"\n").unwrap();
-        let err = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(8765),
-            )],
-        )
-        .unwrap_err();
-        assert!(
-            format!("{err:#}").contains("not a table"),
-            "unexpected error: {err:#}"
-        );
-        assert_eq!(std::fs::read_to_string(&path).unwrap(), "mcp = \"bad\"\n");
-    }
-
-    #[test]
-    fn patch_config_scalars_updates_inline_table_parent() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(
-            &path,
-            "services = { built_in_upstream_apis_enabled = true }\n",
-        )
-        .unwrap();
-        let outcome = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "services.built_in_upstream_apis_enabled",
-                ConfigScalarValue::Bool(false),
-            )],
-        )
-        .unwrap();
-        assert!(!outcome.config.services.built_in_upstream_apis_enabled);
-        let raw = std::fs::read_to_string(&path).unwrap();
-        assert!(raw.contains("built_in_upstream_apis_enabled = false"));
-    }
-
-    #[test]
-    fn patch_config_scalars_unsets_optional_instead_of_empty_string() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "[mcp]\nport = 8765\n").unwrap();
-        let outcome = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::UnsetOptional,
-            )],
-        )
-        .unwrap();
-        assert_eq!(outcome.config.mcp.port, None);
-        assert!(!std::fs::read_to_string(&path).unwrap().contains("port"));
-    }
-
-    #[test]
-    fn patch_config_scalars_creates_backup_and_preserves_comments() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        std::fs::write(&path, "# keep\n[mcp]\nhost = \"127.0.0.1\"\n").unwrap();
-        let outcome = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(8765),
-            )],
-        )
-        .unwrap();
-        let backup_path = outcome.backup_path.unwrap();
-        assert!(backup_path.is_file());
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            assert_eq!(
-                std::fs::metadata(&backup_path)
-                    .unwrap()
-                    .permissions()
-                    .mode()
-                    & 0o777,
-                0o600
-            );
-            assert_eq!(
-                std::fs::metadata(config_lock_path(&path))
-                    .unwrap()
-                    .permissions()
-                    .mode()
-                    & 0o777,
-                0o600,
-                "the persistent config lock must use the secret-file policy"
-            );
-        }
-        let raw = std::fs::read_to_string(&path).unwrap();
-        assert!(raw.contains("# keep"));
-        assert!(raw.contains("port = 8765"));
-        #[cfg(unix)]
-        {
-            use std::os::unix::fs::PermissionsExt;
-            assert_eq!(
-                std::fs::metadata(&path).unwrap().permissions().mode() & 0o777,
-                0o600,
-                "the replacement must not preserve a group/world-readable source mode"
-            );
-        }
-    }
-
-    #[test]
-    fn patch_config_scalars_skips_backup_and_write_for_noop() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        let raw = "[mcp]\nport = 8765\n";
-        std::fs::write(&path, raw).unwrap();
-        let outcome = patch_config_scalars(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(8765),
-            )],
-        )
-        .unwrap();
-        assert_eq!(outcome.backup_path, None);
-        assert_eq!(std::fs::read_to_string(&path).unwrap(), raw);
-    }
-
-    #[test]
-    fn patch_config_scalars_checked_rejects_stale_expected_value() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join("config.toml");
-        let raw = "[mcp]\nport = 8765\n";
-        std::fs::write(&path, raw).unwrap();
-        let err = patch_config_scalars_checked(
-            &path,
-            &[ConfigScalarPatch::new(
-                "mcp.port",
-                ConfigScalarValue::I64(8766),
-            )],
-            &[ExpectedConfigScalar::new(
-                "mcp.port",
-                serde_json::json!(9000),
-            )],
-        )
-        .unwrap_err();
-        assert!(
-            format!("{err:#}").contains("changed since it was loaded"),
-            "unexpected error: {err:#}"
-        );
-        assert_eq!(std::fs::read_to_string(&path).unwrap(), raw);
-    }
-
-    #[test]
-    fn resolve_auth_reads_ttls_from_config_toml_fields() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            sqlite_path: None,
-            key_path: None,
-            enable_dynamic_registration: None,
-            bootstrap_secret: Some("bootstrap".to_string()),
-            allowed_client_redirect_uris: Some(vec![
-                "https://callback.example.com/callback/*".to_string(),
-            ]),
-            allowed_email_domains: None,
-            viewer_email_domains: None,
-            viewer_project_id: None,
-            provider: None,
-            authelia_issuer_url: None,
-            authelia_client_id: None,
-            authelia_client_secret: None,
-            authelia_trusted_private_origin: None,
-            authelia_ca_certificate_path: None,
-            google_client_id: Some("client-id".to_string()),
-            google_client_secret: Some("client-secret".to_string()),
-            google_callback_path: Some("/auth/google/callback".to_string()),
-            google_scopes: Some(vec!["openid".to_string(), "email".to_string()]),
-            access_token_ttl_secs: Some(120),
-            refresh_token_ttl_secs: Some(3600),
-            auth_code_ttl_secs: Some(45),
-            admin_email: Some("admin@example.com".to_string()),
-            register_requests_per_minute: Some(5),
-            authorize_requests_per_minute: Some(15),
-            token_requests_per_minute: Some(25),
-            machine_clients: None,
-            enterprise_issuers: None,
-            max_pending_oauth_states: Some(256),
-            codex_issuer_compatibility: Some(true),
-        };
-
-        let resolved = resolve_oauth_fixture(&cfg);
-        assert_eq!(resolved.access_token_ttl.as_secs(), 120);
-        assert_eq!(resolved.refresh_token_ttl.as_secs(), 3600);
-        assert_eq!(resolved.auth_code_ttl.as_secs(), 45);
-        assert_eq!(
-            resolved.allowed_client_redirect_uris,
-            vec!["https://callback.example.com/callback/*".to_string()]
-        );
-        assert_eq!(resolved.register_requests_per_minute, 5);
-        assert_eq!(resolved.authorize_requests_per_minute, 15);
-        assert_eq!(resolved.token_requests_per_minute, 25);
-        assert_eq!(resolved.max_pending_oauth_states, 256);
-        assert!(resolved.codex_issuer_compatibility);
-    }
-
-    fn minimal_oauth_file_config() -> AuthFileConfig {
-        AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            bootstrap_secret: Some("bootstrap".to_string()),
-            google_client_id: Some("client-id".to_string()),
-            google_client_secret: Some("client-secret".to_string()),
-            admin_email: Some("admin@example.com".to_string()),
-            ..Default::default()
-        }
-    }
-
-    #[test]
-    fn oauth_product_enables_dynamic_registration_by_default() {
-        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
-        assert!(resolved.enable_dynamic_registration);
-    }
-
-    #[test]
-    fn oauth_product_allows_explicit_dynamic_registration_disable() {
-        let cfg = minimal_oauth_file_config();
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [
-                (
-                    "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
-                    "false".into(),
-                ),
-                (
-                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
-                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
-                ),
-            ],
-        )
-        .unwrap();
-        assert!(!resolved.enable_dynamic_registration);
-    }
-
-    #[test]
-    fn oauth_product_environment_overrides_file_registration_policy() {
-        let cfg = AuthFileConfig {
-            enable_dynamic_registration: Some(false),
-            ..minimal_oauth_file_config()
-        };
-        assert!(!resolve_oauth_fixture(&cfg).enable_dynamic_registration);
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [
-                (
-                    "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
-                    "true".into(),
-                ),
-                (
-                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
-                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
-                ),
-            ],
-        )
-        .unwrap();
-        assert!(resolved.enable_dynamic_registration);
-    }
-
-    #[test]
-    fn oauth_product_rejects_invalid_dynamic_registration_policy() {
-        let error = resolve_auth_with_env(
-            Some(&minimal_oauth_file_config()),
-            [(
-                "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
-                "maybe".into(),
-            )],
-        )
-        .unwrap_err();
-        assert!(
-            error
-                .to_string()
-                .contains("LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION")
-        );
-    }
-
-    #[test]
-    fn resolve_auth_accepts_authelia_only_file_configuration() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".into()),
-            public_url: Some("https://lab.example.com/base".into()),
-            provider: Some("authelia".into()),
-            authelia_issuer_url: Some("https://auth.example.com/application/o/labby".into()),
-            authelia_client_id: Some("labby".into()),
-            authelia_client_secret: Some("secret".into()),
-            authelia_ca_certificate_path: Some("/etc/labby/authelia-ca.pem".into()),
-            admin_email: Some("admin@example.com".into()),
-            ..Default::default()
-        };
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [(
-                "LABBY_TOKEN_ENCRYPTION_KEY".into(),
-                "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
-            )],
-        )
-        .unwrap();
-        assert_eq!(
-            resolved.inbound_provider,
-            Some(auth_config::InboundProviderKind::Authelia)
-        );
-        assert_eq!(
-            resolved.authelia.unwrap().ca_certificate_path,
-            Some(PathBuf::from("/etc/labby/authelia-ca.pem"))
-        );
-        assert!(resolved.google.client_id.is_empty());
-    }
-
-    #[test]
-    fn resolve_auth_authelia_environment_overrides_file_configuration() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".into()),
-            public_url: Some("https://lab.example.com".into()),
-            provider: Some("google".into()),
-            google_client_id: Some("legacy".into()),
-            google_client_secret: Some("legacy-secret".into()),
-            admin_email: Some("admin@example.com".into()),
-            ..Default::default()
-        };
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [
-                ("LABBY_AUTH_PROVIDER".into(), "authelia".into()),
-                (
-                    "LABBY_AUTHELIA_ISSUER_URL".into(),
-                    "https://auth.example.com/application/o/labby".into(),
-                ),
-                ("LABBY_AUTHELIA_CLIENT_ID".into(), "labby".into()),
-                (
-                    "LABBY_AUTHELIA_CLIENT_SECRET".into(),
-                    "authelia-secret".into(),
-                ),
-                (
-                    "LABBY_AUTHELIA_CA_CERT_PATH".into(),
-                    "/run/secrets/authelia-ca.pem".into(),
-                ),
-                (
-                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
-                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
-                ),
-            ],
-        )
-        .unwrap();
-        assert_eq!(
-            resolved.inbound_provider,
-            Some(auth_config::InboundProviderKind::Authelia)
-        );
-        let authelia = resolved.authelia.unwrap();
-        assert_eq!(authelia.client_id, "labby");
-        assert_eq!(
-            authelia.ca_certificate_path,
-            Some(PathBuf::from("/run/secrets/authelia-ca.pem"))
-        );
-    }
-
-    #[test]
-    fn doctor_projection_uses_resolved_file_only_authelia_provider() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".into()),
-            public_url: Some("https://lab.example.com".into()),
-            provider: Some("authelia".into()),
-            authelia_issuer_url: Some("https://auth.example.com/application/o/labby".into()),
-            authelia_client_id: Some("labby".into()),
-            authelia_client_secret: Some("secret".into()),
-            admin_email: Some("admin@example.com".into()),
-            ..Default::default()
-        };
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [(
-                "LABBY_TOKEN_ENCRYPTION_KEY".into(),
-                "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
-            )],
-        )
-        .unwrap();
-        let findings = crate::dispatch::doctor::run_auth_checks_with_config(Some(&resolved));
-        let provider = findings
-            .iter()
-            .find(|finding| finding.check == "auth:provider")
-            .unwrap();
-        assert!(matches!(
-            provider.severity,
-            crate::dispatch::doctor::Severity::Ok
-        ));
-        assert!(provider.message.contains("authelia"));
-        assert!(
-            !findings
-                .iter()
-                .any(|finding| finding.check.starts_with("auth:google-")
-                    && matches!(finding.severity, crate::dispatch::doctor::Severity::Fail))
-        );
-    }
-
-    #[test]
-    fn resolve_auth_reads_allowed_email_domains_from_config_toml() {
-        let mut cfg = minimal_oauth_file_config();
-        cfg.allowed_email_domains = Some(vec![
-            "Lime-Technology.com".to_string(),
-            "@example.org".to_string(),
-        ]);
-
-        let resolved = resolve_oauth_fixture(&cfg);
-
-        // Normalized to lowercase with any leading `@` stripped, so operators can
-        // write either `example.org` or `@example.org`.
-        assert_eq!(
-            resolved.allowed_email_domains,
-            vec!["lime-technology.com".to_string(), "example.org".to_string()]
-        );
-    }
-
-    #[test]
-    fn resolve_auth_defaults_allowed_email_domains_to_empty() {
-        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
-        assert!(resolved.allowed_email_domains.is_empty());
-    }
-
-    #[test]
-    fn viewer_domain_policy_requires_an_explicit_host_project() {
-        let mut cfg = minimal_oauth_file_config();
-        cfg.viewer_email_domains = Some(vec!["example.org".into()]);
-        let error = resolve_auth_with_env(
-            Some(&cfg),
-            [("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32))],
-        )
-        .unwrap_err();
-        assert!(error.to_string().contains("auth.viewer_project_id"));
-        cfg.viewer_project_id = Some(" bootstrap-default ".into());
-        let error = resolve_auth_with_env(
-            Some(&cfg),
-            [("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32))],
-        )
-        .unwrap_err();
-        assert!(error.to_string().contains("auth.viewer_project_id"));
-        cfg.viewer_project_id = Some("bootstrap-default".into());
-        let resolved = resolve_oauth_fixture(&cfg);
-        assert_eq!(resolved.viewer_email_domains, vec!["example.org"]);
-    }
-
-    #[test]
-    fn viewer_domains_env_overrides_file_but_cannot_supply_project() {
-        let mut cfg = minimal_oauth_file_config();
-        cfg.viewer_email_domains = Some(vec!["old.example".into()]);
-        cfg.viewer_project_id = Some("bootstrap-default".into());
-        let resolved = resolve_auth_with_env(
-            Some(&cfg),
-            [
-                (
-                    "LABBY_AUTH_VIEWER_EMAIL_DOMAINS".into(),
-                    "new.example".into(),
-                ),
-                ("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32)),
-            ],
-        )
-        .unwrap();
-        assert_eq!(resolved.viewer_email_domains, vec!["new.example"]);
-        cfg.viewer_project_id = None;
-        let error = resolve_auth_with_env(
-            Some(&cfg),
-            [
-                (
-                    "LABBY_AUTH_VIEWER_PROJECT_ID".into(),
-                    "bootstrap-default".into(),
-                ),
-                ("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32)),
-            ],
-        )
-        .unwrap_err();
-        assert!(error.to_string().contains("auth.viewer_project_id"));
-    }
-
-    #[test]
-    fn viewer_policy_is_default_off() {
-        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
-        assert!(resolved.viewer_email_domains.is_empty());
-    }
-
-    #[test]
-    fn resolve_auth_preserves_structured_machine_and_enterprise_configuration() {
-        let machine = auth_config::MachineClientConfig {
-            client_id: "ci-agent".to_string(),
-            client_secret: Some("secret".to_string()),
-            jwks: None,
-            scopes: vec!["lab".to_string()],
-            resources: vec!["https://lab.example.com/mcp".to_string()],
-        };
-        let issuer = auth_config::EnterpriseIssuerConfig {
-            issuer: "https://idp.example.com".to_string(),
-            jwks_uri: Some("https://idp.example.com/jwks".parse().unwrap()),
-            jwks: None,
-            allowed_client_ids: vec!["ci-agent".to_string()],
-        };
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            google_client_id: Some("google-client".to_string()),
-            google_client_secret: Some("google-secret".to_string()),
-            admin_email: Some("admin@example.com".to_string()),
-            machine_clients: Some(vec![machine.clone()]),
-            enterprise_issuers: Some(vec![issuer.clone()]),
-            ..AuthFileConfig::default()
-        };
-
-        let resolved = resolve_oauth_fixture(&cfg);
-        assert_eq!(resolved.machine_clients, vec![machine]);
-        assert_eq!(resolved.enterprise_issuers, vec![issuer]);
-    }
-
-    #[test]
-    fn resolve_auth_uses_curated_client_redirects_by_default() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            google_client_id: Some("client-id".to_string()),
-            google_client_secret: Some("client-secret".to_string()),
-            admin_email: Some("admin@example.com".to_string()),
-            ..AuthFileConfig::default()
-        };
-
-        let resolved = resolve_oauth_fixture(&cfg);
-
-        assert_eq!(
-            resolved.allowed_client_redirect_uris,
-            vec![
-                "https://chatgpt.com/aip/plugin-callback".to_string(),
-                "https://chat.openai.com/aip/plugin-callback".to_string(),
-                "https://chatgpt.com/connector/oauth/*".to_string(),
-                "https://chatgpt.com/connector_platform_oauth_redirect".to_string(),
-                "https://claude.ai/api/mcp/auth_callback".to_string(),
-                "https://claude.com/api/mcp/auth_callback".to_string(),
-            ]
-        );
-    }
-
-    #[test]
-    fn resolve_auth_explicit_empty_redirects_disable_product_defaults() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            google_client_id: Some("client-id".to_string()),
-            google_client_secret: Some("client-secret".to_string()),
-            admin_email: Some("admin@example.com".to_string()),
-            allowed_client_redirect_uris: Some(Vec::new()),
-            ..AuthFileConfig::default()
-        };
-
-        let resolved = resolve_oauth_fixture(&cfg);
-
-        assert_eq!(resolved.allowed_client_redirect_uris, Vec::<String>::new());
-    }
-
-    #[test]
-    fn resolve_auth_preserves_explicit_all_https_redirect_opt_in() {
-        let cfg = AuthFileConfig {
-            mode: Some("oauth".to_string()),
-            public_url: Some("https://lab.example.com".to_string()),
-            google_client_id: Some("client-id".to_string()),
-            google_client_secret: Some("client-secret".to_string()),
-            admin_email: Some("admin@example.com".to_string()),
-            allowed_client_redirect_uris: Some(vec!["https://*".to_string()]),
-            ..AuthFileConfig::default()
-        };
-
-        let resolved = resolve_oauth_fixture(&cfg);
-
-        assert_eq!(
-            resolved.allowed_client_redirect_uris,
-            vec!["https://*".to_string()]
-        );
-    }
-
-    #[test]
-    fn oauth_machine_config_deserializes() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[oauth.machines.node-a]
-target_url = "http://100.64.0.10:38935/callback/node-a"
-description = "Node A Claude callback target"
-default_port = 38935
-"#,
-        )
-        .expect("oauth machine config should parse");
-
-        assert_eq!(
-            cfg.oauth.machines["node-a"].target_url,
-            "http://100.64.0.10:38935/callback/node-a"
-        );
-        assert_eq!(
-            cfg.oauth.machines["node-a"].description.as_deref(),
-            Some("Node A Claude callback target")
-        );
-        assert_eq!(cfg.oauth.machines["node-a"].default_port, Some(38935));
-    }
-
-    #[test]
-    fn oauth_machine_defaults_keep_partial_configs_valid() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[web]
-assets_dir = "/tmp/labby"
-"#,
-        )
-        .expect("config without oauth section should still parse");
-
-        assert!(cfg.oauth.machines.is_empty());
-        assert_eq!(cfg.web.assets_dir, Some(PathBuf::from("/tmp/labby")));
-    }
-
-    #[test]
-    fn quarantined_virtual_servers_round_trip_through_toml() {
-        let raw = r#"
-[[quarantined_virtual_servers]]
-id = "missing-service"
-service = "missing-service"
-enabled = true
-
-[quarantined_virtual_servers.surfaces]
-mcp = true
-"#;
-        let cfg = toml::from_str::<LabConfig>(raw).expect("quarantine config should parse");
-        assert_eq!(cfg.quarantined_virtual_servers.len(), 1);
-        assert_eq!(cfg.quarantined_virtual_servers[0].id, "missing-service");
-        assert_eq!(
-            cfg.quarantined_virtual_servers[0].service,
-            "missing-service"
-        );
-        assert!(cfg.quarantined_virtual_servers[0].surfaces.mcp);
-
-        let serialized = toml::to_string(&cfg).expect("config should serialize");
-        let reparsed =
-            toml::from_str::<LabConfig>(&serialized).expect("serialized config should parse");
-        assert_eq!(reparsed.quarantined_virtual_servers.len(), 1);
-        assert_eq!(
-            reparsed.quarantined_virtual_servers[0].id,
-            "missing-service"
-        );
-    }
-
-    #[test]
-    fn workspace_root_defaults_under_labby_home() {
-        let cfg = toml::from_str::<LabConfig>("").expect("empty config should parse");
-        let home = Path::new("/tmp/lab-home");
-
-        assert_eq!(
-            workspace_root_for_home(&cfg, home),
-            home.join(".labby").join("workspace")
-        );
-    }
-
-    #[test]
-    fn file_stash_defaults_are_bounded_and_invalid_limits_fail_startup_validation() {
-        let mut config = LabConfig::default();
-        assert_eq!(config.file_stash.max_file_bytes, 104_857_600);
-        assert_eq!(config.file_stash.principal_quota_bytes, 1_073_741_824);
-        assert_eq!(config.file_stash.instance_quota_bytes, 10_737_418_240);
-        assert_eq!(config.file_stash.max_live_files_per_instance, 100_000);
-        assert_eq!(config.file_stash.queue_capacity, 64);
-        assert_eq!(config.file_stash.max_concurrent_uploads_per_principal, 2);
-        assert_eq!(config.file_stash.max_concurrent_uploads_per_instance, 8);
-        assert_eq!(config.file_stash.max_concurrent_downloads, 16);
-        assert_eq!(config.file_stash.download_idle_seconds, 30);
-        assert_eq!(config.file_stash.download_total_seconds, 600);
-        assert!(config.validate().is_ok());
-        config.file_stash.queue_capacity = 0;
-        assert!(config.validate().is_err());
-        let mut config = LabConfig::default();
-        config.file_stash.pending_ttl_seconds = config.file_stash.upload_total_seconds;
-        assert!(config.validate().is_err());
-    }
-
-    #[test]
-    fn file_stash_rejects_every_resource_limit_outside_its_boundary() {
-        macro_rules! invalid {
-            ($field:ident, $value:expr) => {{
-                let mut config = LabConfig::default();
-                config.file_stash.$field = $value;
-                assert!(
-                    config.validate().is_err(),
-                    "{} accepted an invalid boundary value",
-                    stringify!($field)
-                );
-            }};
-        }
-        invalid!(max_file_bytes, 0);
-        invalid!(principal_quota_bytes, 0);
-        invalid!(instance_quota_bytes, 0);
-        invalid!(max_live_files_per_principal, 0);
-        invalid!(max_live_files_per_instance, 1);
-        invalid!(page_size, 0);
-        invalid!(max_query_bytes, 0);
-        invalid!(max_header_bytes, 0);
-        invalid!(grant_recipients_page_size, 0);
-        invalid!(max_mcp_read_bytes, 0);
-        invalid!(queue_capacity, 0);
-        invalid!(database_deadline_ms, 0);
-        invalid!(max_concurrent_uploads_per_principal, 0);
-        invalid!(max_concurrent_uploads_per_instance, 0);
-        invalid!(max_concurrent_downloads, 0);
-        invalid!(max_concurrent_mcp_reads, 0);
-        invalid!(upload_idle_seconds, 0);
-        invalid!(upload_total_seconds, 0);
-        invalid!(download_idle_seconds, 0);
-        invalid!(download_total_seconds, 0);
-        invalid!(pending_ttl_seconds, 0);
-        invalid!(janitor_batch_size, 0);
-        invalid!(janitor_backoff_max_seconds, 0);
-        invalid!(janitor_interval_seconds, 0);
-
-        invalid!(max_file_bytes, 1_073_741_825);
-        invalid!(principal_quota_bytes, 107_374_182_401);
-        invalid!(instance_quota_bytes, 1_099_511_627_777);
-        invalid!(max_live_files_per_principal, 100_001);
-        invalid!(max_live_files_per_instance, 1_000_001);
-        invalid!(page_size, 201);
-        invalid!(max_query_bytes, 1_025);
-        invalid!(max_header_bytes, 65_537);
-        invalid!(grant_recipients_page_size, 201);
-        invalid!(max_mcp_read_bytes, 26_214_401);
-        invalid!(queue_capacity, 1_025);
-        invalid!(database_deadline_ms, 30_001);
-        invalid!(max_concurrent_uploads_per_principal, 3);
-        invalid!(max_concurrent_uploads_per_instance, 9);
-        invalid!(max_concurrent_downloads, 257);
-        invalid!(max_concurrent_mcp_reads, 5);
-        invalid!(upload_idle_seconds, 31);
-        invalid!(upload_total_seconds, 601);
-        invalid!(download_idle_seconds, 31);
-        invalid!(download_total_seconds, 601);
-        invalid!(pending_ttl_seconds, 1_801);
-        invalid!(janitor_batch_size, 101);
-        invalid!(janitor_backoff_max_seconds, 301);
-        invalid!(janitor_interval_seconds, 3_601);
-
-        let mut config = LabConfig::default();
-        config.file_stash.janitor_backoff_max_seconds = 1;
-        assert!(config.validate().is_err());
-    }
-
-    #[test]
-    fn workspace_root_reads_config_toml_value() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[workspace]
-root = "/srv/labby-workspace"
-"#,
-        )
-        .expect("workspace config should parse");
-
-        assert_eq!(
-            workspace_root_for_home(&cfg, Path::new("/tmp/ignored")),
-            PathBuf::from("/srv/labby-workspace")
-        );
-    }
-
-    #[test]
-    fn web_ui_auth_disabled_env_prefers_canonical_alias() {
-        let setting = resolve_web_ui_auth_disabled_values(Some("true"), Some("false"))
-            .expect("env values should parse")
-            .expect("setting should resolve");
-
-        assert!(setting.disabled);
-        assert_eq!(setting.source, WEB_UI_AUTH_DISABLED_ENV);
-        assert!(!setting.legacy_alias);
-    }
-
-    #[test]
-    fn web_ui_auth_disabled_env_accepts_legacy_alias() {
-        let setting = resolve_web_ui_auth_disabled_values(None, Some("1"))
-            .expect("env values should parse")
-            .expect("setting should resolve");
-
-        assert!(setting.disabled);
-        assert_eq!(setting.source, WEB_UI_AUTH_DISABLED_LEGACY_ENV);
-        assert!(setting.legacy_alias);
-    }
-
-    #[test]
-    fn web_ui_auth_disabled_env_rejects_invalid_values() {
-        let error = resolve_web_ui_auth_disabled_values(Some("sometimes"), None)
-            .expect_err("invalid bool should fail");
-
-        assert!(
-            error
-                .to_string()
-                .contains("invalid LABBY_WEB_UI_AUTH_DISABLED value")
-        );
-    }
-
-    #[test]
-    fn secret_debug_redacts() {
-        let s = Secret::new("hunter2".into());
-        assert_eq!(format!("{s:?}"), "[REDACTED]");
-        assert_eq!(format!("{s}"), "[REDACTED]");
-        assert_eq!(s.expose(), "hunter2");
-    }
-
-    #[test]
-    fn secret_serialize_emits_placeholder_not_plaintext() {
-        let s = Secret::new("super-secret-api-key".into());
-        let json = serde_json::to_string(&s).expect("serialize must not fail");
-        assert_eq!(
-            json, "\"***REDACTED***\"",
-            "Secret must serialize to placeholder"
-        );
-        assert!(
-            !json.contains("super-secret-api-key"),
-            "Secret must never emit plaintext through serde"
-        );
-    }
-
-    #[test]
-    fn suffix_collision_longest_wins() {
-        let env = [("S_NODE_API_KEY_URL", "http://example.com")];
-        let result = scan_instances_from("S", vars(&env));
-        let inst = result
-            .get("node_api_key")
-            .expect("should find instance node_api_key");
-        assert_eq!(
-            inst.get("URL").expect("should have URL").expose(),
-            "http://example.com"
-        );
-    }
-
-    #[test]
-    fn default_instance_parsed() {
-        let env = [
-            ("SVC_URL", "http://localhost"),
-            ("SVC_API_KEY", "secret123"),
-        ];
-        let result = scan_instances_from("SVC", vars(&env));
-        let def = result.get("default").expect("should find default");
-        assert_eq!(def.get("URL").expect("URL").expose(), "http://localhost");
-        assert_eq!(def.get("API_KEY").expect("API_KEY").expose(), "secret123");
-        assert!(format!("{:?}", def.get("API_KEY").unwrap()).contains("[REDACTED]"));
-    }
-
-    #[test]
-    fn named_instance_parsed() {
-        let env = [
-            ("UNRAID_NODE2_URL", "http://node2"),
-            ("UNRAID_NODE2_TOKEN", "tok"),
-        ];
-        let result = scan_instances_from("UNRAID", vars(&env));
-        let inst = result.get("node2").expect("should find node2");
-        assert_eq!(inst.get("URL").expect("URL").expose(), "http://node2");
-        assert_eq!(inst.get("TOKEN").expect("TOKEN").expose(), "tok");
-        assert!(format!("{:?}", inst.get("TOKEN").unwrap()).contains("[REDACTED]"));
-    }
-
-    #[test]
-    fn unrelated_vars_ignored() {
-        let env = [
-            ("SVC_URL", "http://localhost"),
-            ("OTHER_URL", "http://other"),
-        ];
-        let result = scan_instances_from("SVC", vars(&env));
-        assert_eq!(result.len(), 1);
-        assert!(result.contains_key("default"));
-    }
-
-    #[test]
-    fn username_is_plain_not_secret() {
-        let env = [("SVC_USERNAME", "admin")];
-        let result = scan_instances_from("SVC", vars(&env));
-        let def = result.get("default").expect("should find default");
-        assert!(!format!("{:?}", def.get("USERNAME").unwrap()).contains("[REDACTED]"));
-    }
-
-    // ─── write_service_creds tests ──────────────────────────────────────────
-
-    fn example_cred() -> EnvCredential {
-        EnvCredential {
-            service: "example".to_owned(),
-            url: Some("http://localhost:7878".to_owned()),
-            secret: Some("abc123".to_owned()),
-            env_field: "EXAMPLE_API_KEY".to_owned(),
-        }
-    }
-
-    #[test]
-    fn write_service_creds_adds_new_keys() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
-        assert!(outcome.skipped.is_empty());
-        assert_eq!(outcome.written, 2);
-        let content = std::fs::read_to_string(&path).unwrap();
-        assert!(content.contains("EXAMPLE_URL=http://localhost:7878"));
-        assert!(content.contains("EXAMPLE_API_KEY=abc123"));
-    }
-
-    #[test]
-    fn write_service_creds_preserves_comments_and_blanks() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        std::fs::write(&path, "# my comment\nOTHER=val\n").unwrap();
-        write_service_creds(&path, &[example_cred()], false).unwrap();
-        let content = std::fs::read_to_string(&path).unwrap();
-        assert!(content.contains("# my comment"));
-        assert!(content.contains("OTHER=val"));
-    }
-
-    #[test]
-    fn write_service_creds_conflict_skip_without_force() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        std::fs::write(&path, "EXAMPLE_API_KEY=oldvalue\n").unwrap();
-        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
-        assert!(!outcome.skipped.is_empty());
-        let content = std::fs::read_to_string(&path).unwrap();
-        assert!(content.contains("oldvalue"));
-        assert!(!content.contains("abc123"));
-    }
-
-    #[test]
-    fn write_service_creds_conflict_overwrite_with_force() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        std::fs::write(&path, "EXAMPLE_API_KEY=oldvalue\n").unwrap();
-        let outcome = write_service_creds(&path, &[example_cred()], true).unwrap();
-        assert!(outcome.skipped.is_empty());
-        let content = std::fs::read_to_string(&path).unwrap();
-        assert!(content.contains("abc123"));
-        assert!(!content.contains("oldvalue"));
-    }
-
-    #[test]
-    fn write_service_creds_is_idempotent_when_matching() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        write_service_creds(&path, &[example_cred()], false).unwrap();
-        // Re-running with the exact same creds must be a written=0 no-op --
-        // this is the signal crate::dispatch::gateway::config_store relies on
-        // to skip a service-client refresh cycle.
-        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
-        assert_eq!(outcome.written, 0);
-        assert!(outcome.backup_path.is_none());
-    }
-
-    #[test]
-    fn write_service_creds_quotes_value_with_special_chars() {
-        let dir = tempfile::tempdir().unwrap();
-        let path = dir.path().join(".env");
-        let cred = EnvCredential {
-            service: "svc".to_owned(),
-            url: None,
-            secret: Some("has space".to_owned()),
-            env_field: "SVC_KEY".to_owned(),
-        };
-        write_service_creds(&path, &[cred], false).unwrap();
-        let content = std::fs::read_to_string(&path).unwrap();
-        assert!(content.contains("SVC_KEY=\"has space\""));
-    }
-
-    #[test]
-    fn upstream_oauth_pkce_parses() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-scopes = ["mcp"]
-
-[upstream.oauth.registration]
-strategy = "client_metadata_document"
-url = "https://acme.example.com/.well-known/oauth-client"
-"#,
-        )
-        .expect("pkce config should parse");
-
-        let upstream = &cfg.upstream[0];
-        let oauth = upstream.oauth.as_ref().expect("oauth present");
-        assert!(matches!(
-            oauth.mode,
-            UpstreamOauthMode::AuthorizationCodePkce
-        ));
-        assert_eq!(oauth.scopes.as_deref(), Some(&["mcp".to_string()][..]));
-        match &oauth.registration {
-            UpstreamOauthRegistration::ClientMetadataDocument { url } => {
-                assert_eq!(url, "https://acme.example.com/.well-known/oauth-client");
-            }
-            _ => panic!("expected client metadata document registration"),
-        }
-        upstream.validate().expect("validate ok");
-    }
-
-    #[test]
-    fn upstream_oauth_preregistered_parses() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-
-[upstream.oauth.registration]
-strategy = "preregistered"
-client_id = "my-client"
-"#,
-        )
-        .expect("preregistered config should parse");
-
-        let upstream = &cfg.upstream[0];
-        let oauth = upstream.oauth.as_ref().unwrap();
-        match &oauth.registration {
-            UpstreamOauthRegistration::Preregistered {
-                client_id,
-                client_secret_env,
-            } => {
-                assert_eq!(client_id, "my-client");
-                assert!(client_secret_env.is_none());
-            }
-            _ => panic!("expected preregistered OAuth client"),
-        }
-    }
-
-    #[test]
-    fn upstream_oauth_google_provider_credential_source_parses() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "google-calendar"
-url = "https://calendarmcp.googleapis.com/mcp/v1"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-scopes = ["https://www.googleapis.com/auth/calendar.events.readonly"]
-
-[upstream.oauth.credential]
-source = "google_provider"
-account = "admin@example.com"
-
-[upstream.oauth.registration]
-strategy = "preregistered"
-client_id = "google-client"
-client_secret_env = "LABBY_GOOGLE_CLIENT_SECRET"
-"#,
-        )
-        .expect("google provider credential config should parse");
-
-        let oauth = cfg.upstream[0].oauth.as_ref().unwrap();
-        assert_eq!(
-            oauth.credential,
-            UpstreamOauthCredentialSource::GoogleProvider {
-                account: Some("admin@example.com".to_string()),
-            }
-        );
-        cfg.upstream[0]
-            .validate()
-            .expect("shared Google configuration should validate");
-    }
-
-    #[test]
-    fn upstream_oauth_credential_source_defaults_to_dedicated() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-
-[upstream.oauth.registration]
-strategy = "preregistered"
-client_id = "my-client"
-"#,
-        )
-        .unwrap();
-        assert_eq!(
-            cfg.upstream[0].oauth.as_ref().unwrap().credential,
-            UpstreamOauthCredentialSource::Dedicated
-        );
-    }
-
-    #[test]
-    fn upstream_oauth_preregistered_with_secret_parses() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-
-[upstream.oauth.registration]
-strategy = "preregistered"
-client_id = "my-client"
-client_secret_env = "ACME_CLIENT_SECRET"
-"#,
-        )
-        .expect("preregistered+secret config should parse");
-
-        let upstream = &cfg.upstream[0];
-        let oauth = upstream.oauth.as_ref().unwrap();
-        match &oauth.registration {
-            UpstreamOauthRegistration::Preregistered {
-                client_id,
-                client_secret_env,
-            } => {
-                assert_eq!(client_id, "my-client");
-                assert_eq!(client_secret_env.as_deref(), Some("ACME_CLIENT_SECRET"));
-            }
-            _ => panic!("expected preregistered OAuth client with secret reference"),
-        }
-    }
-
-    #[test]
-    fn upstream_oauth_dynamic_parses() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-
-[upstream.oauth.registration]
-strategy = "dynamic"
-"#,
-        )
-        .expect("dynamic config should parse");
-
-        let upstream = &cfg.upstream[0];
-        let oauth = upstream.oauth.as_ref().unwrap();
-        assert!(matches!(
-            oauth.registration,
-            UpstreamOauthRegistration::Dynamic
-        ));
-    }
-
-    #[test]
-    fn upstream_oauth_conflicts_with_bearer_token_env() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-bearer_token_env = "ACME_TOKEN"
-
-[upstream.oauth]
-mode = "authorization_code_pkce"
-
-[upstream.oauth.registration]
-strategy = "dynamic"
-"#,
-        )
-        .expect("config parses; validation is a separate step");
-
-        let err = cfg.upstream[0].validate().unwrap_err();
-        match err {
-            ConfigError::ConflictingAuth { name } => assert_eq!(name, "acme"),
-            _ => panic!("expected ConflictingAuth"),
-        }
-    }
-
-    #[test]
-    fn code_mode_is_root_level_config() {
-        let cfg = toml::from_str::<LabConfig>(
-            r#"
-[code_mode]
-enabled = true
-timeout_ms = 2500
-
-[[upstream]]
-name = "acme"
-url = "https://acme.example.com/mcp"
-"#,
-        )
-        .expect("root code_mode parses");
-
-        assert!(cfg.code_mode.enabled);
-        assert_eq!(cfg.code_mode.timeout_ms, 2500);
-        cfg.validate().expect("root code_mode validates");
-    }
-
-    #[test]
-    fn code_mode_is_root_level_config_with_default_limits() {
-        let default_cfg = LabConfig::default();
-        assert_eq!(default_cfg.code_mode.timeout_ms, 30_000);
-        assert_eq!(default_cfg.code_mode.max_source_bytes, 128 * 1024);
-        assert_eq!(default_cfg.code_mode.max_response_bytes, 24 * 1024);
-        assert_eq!(default_cfg.code_mode.max_response_tokens, 6000);
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-[code_mode]
-timeout_ms = 2500
-max_source_bytes = 65536
-max_response_bytes = 12000
-max_response_tokens = 3000
-",
-        )
-        .expect("root code_mode parses");
-
-        assert_eq!(cfg.code_mode.timeout_ms, 2500);
-        assert_eq!(cfg.code_mode.max_source_bytes, 65_536);
-        assert_eq!(cfg.code_mode.max_response_bytes, 12000);
-        assert_eq!(cfg.code_mode.max_response_tokens, 3000);
-    }
-
-    #[test]
-    fn upstream_request_timeout_is_root_level_config() {
-        let default_cfg = LabConfig::default();
-        assert_eq!(
-            default_cfg.upstream_request_timeout(),
-            Duration::from_secs(30)
-        );
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-upstream_request_timeout_ms = 60000
-",
-        )
-        .expect("root upstream request timeout parses");
-
-        assert_eq!(cfg.upstream_request_timeout_ms, Some(60_000));
-        assert_eq!(cfg.upstream_request_timeout(), Duration::from_mins(1));
-        cfg.validate().expect("timeout validates");
-    }
-
-    /// The HTTP transport backstop must never fire before the upstream deadline
-    /// it wraps. A fixed 30s cap in the router used to override both settings:
-    /// a 60s `upstream_request_timeout_ms` still returned a bare 504 at 30s,
-    /// discarding a tool call that went on to succeed.
-    #[test]
-    fn http_request_timeout_never_undercuts_configured_upstream_deadlines() {
-        for toml_src in [
-            "",
-            "upstream_request_timeout_ms = 60000",
-            // Both knobs at the top of their validated ranges.
-            "upstream_request_timeout_ms = 300000\nupstream_relay_timeout_ms = 1800000",
-            // Relay left at its 5 minute default while the pooled path is raised.
-            "upstream_request_timeout_ms = 120000",
-            // Relay raised while the pooled path stays at its default.
-            "upstream_relay_timeout_ms = 900000",
-        ] {
-            let cfg = toml::from_str::<LabConfig>(toml_src).expect("config parses");
-            cfg.validate().expect("config validates");
-
-            let http = cfg.http_request_timeout();
-            assert!(
-                http > cfg.upstream_request_timeout(),
-                "http timeout {http:?} must exceed the pooled upstream deadline {:?} for {toml_src:?}",
-                cfg.upstream_request_timeout(),
-            );
-            assert!(
-                http > cfg.upstream_relay_timeout(),
-                "http timeout {http:?} must exceed the relay deadline {:?} for {toml_src:?}",
-                cfg.upstream_relay_timeout(),
-            );
-        }
-    }
-
-    /// A Code Mode run is carried by the HTTP request that started it, so the
-    /// transport backstop must also cover `code_mode.timeout_ms`; otherwise a
-    /// long run outlives its own response.
-    #[test]
-    fn http_request_timeout_never_undercuts_code_mode_timeout() {
-        let cfg = toml::from_str::<LabConfig>(
-            "upstream_request_timeout_ms = 60000\nupstream_relay_timeout_ms = 60000\n[code_mode]\ntimeout_ms = 180000\n",
-        )
-        .expect("config parses");
-        cfg.validate().expect("config validates");
-        let http = cfg.http_request_timeout();
-        assert!(
-            http > Duration::from_millis(cfg.code_mode.timeout_ms),
-            "http timeout {http:?} must exceed the Code Mode deadline {} ms",
-            cfg.code_mode.timeout_ms
-        );
-    }
-
-    /// A synchronous `agents.run` holds its HTTP request for the whole Agent
-    /// runtime bound, which is fixed product policy rather than configuration.
-    #[test]
-    fn http_request_timeout_covers_the_agent_runtime_bound() {
-        let cfg = toml::from_str::<LabConfig>(
-            "upstream_request_timeout_ms = 60000\nupstream_relay_timeout_ms = 60000\n",
-        )
-        .expect("config parses");
-        cfg.validate().expect("config validates");
-        let bound = Duration::from_millis(labby_runtime::agent_runtime::AGENT_MAX_RUNTIME_MILLIS);
-        assert!(
-            cfg.http_request_timeout() > bound,
-            "http timeout {:?} must exceed the Agent runtime bound {bound:?}",
-            cfg.http_request_timeout()
-        );
-    }
-
-    /// The 5 minute relay default is the binding constraint out of the box, so
-    /// a default deployment must not cap HTTP requests at the 30s pooled value.
-    #[test]
-    fn http_request_timeout_default_accommodates_the_relay_path() {
-        let cfg = LabConfig::default();
-        assert_eq!(
-            cfg.http_request_timeout(),
-            cfg.upstream_relay_timeout() + HTTP_REQUEST_TIMEOUT_MARGIN,
-        );
-        assert!(cfg.http_request_timeout() > Duration::from_secs(30));
-    }
-
-    #[test]
-    fn upstream_relay_timeout_defaults_to_five_minutes_and_is_configurable() {
-        // Unset → 5 minute default (NOT the 30s request-timeout default), so a
-        // relayed elicitation is not aborted while a human is answering.
-        let default_cfg = LabConfig::default();
-        assert_eq!(default_cfg.upstream_relay_timeout_ms, None);
-        assert_eq!(default_cfg.upstream_relay_timeout(), Duration::from_mins(5));
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-upstream_relay_timeout_ms = 600000
-",
-        )
-        .expect("root upstream relay timeout parses");
-        assert_eq!(cfg.upstream_relay_timeout_ms, Some(600_000));
-        assert_eq!(cfg.upstream_relay_timeout(), Duration::from_mins(10));
-        cfg.validate().expect("relay timeout validates");
-    }
-
-    #[test]
-    fn upstream_relay_timeout_rejects_out_of_range() {
-        // Above the 30 min ceiling.
-        let too_big = LabConfig {
-            upstream_relay_timeout_ms: Some(1_800_001),
-            ..LabConfig::default()
-        };
-        assert!(matches!(
-            too_big.validate(),
-            Err(ConfigError::InvalidUpstreamRelayTimeout { value: 1_800_001 })
-        ));
-
-        // Zero is rejected just like the request timeout.
-        let zero = LabConfig {
-            upstream_relay_timeout_ms: Some(0),
-            ..LabConfig::default()
-        };
-        assert!(matches!(
-            zero.validate(),
-            Err(ConfigError::InvalidUpstreamRelayTimeout { value: 0 })
-        ));
-    }
-
-    #[test]
-    fn catalog_notification_timeout_defaults_to_five_seconds_and_is_configurable() {
-        let default_cfg = LabConfig::default();
-        assert_eq!(default_cfg.mcp.catalog_notification_timeout_ms, None);
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-[mcp]
-catalog_notification_timeout_ms = 2500
-",
-        )
-        .expect("mcp catalog notification timeout parses");
-
-        assert_eq!(cfg.mcp.catalog_notification_timeout_ms, Some(2_500));
-        cfg.validate()
-            .expect("catalog notification timeout validates");
-    }
-
-    #[test]
-    fn catalog_notification_timeout_rejects_out_of_range() {
-        let too_big = LabConfig {
-            mcp: McpPreferences {
-                catalog_notification_timeout_ms: Some(60_001),
-                ..McpPreferences::default()
-            },
-            ..LabConfig::default()
-        };
-        assert!(matches!(
-            too_big.validate(),
-            Err(ConfigError::InvalidCatalogNotificationTimeout { value: 60_001 })
-        ));
-
-        let zero = LabConfig {
-            mcp: McpPreferences {
-                catalog_notification_timeout_ms: Some(0),
-                ..McpPreferences::default()
-            },
-            ..LabConfig::default()
-        };
-        assert!(matches!(
-            zero.validate(),
-            Err(ConfigError::InvalidCatalogNotificationTimeout { value: 0 })
-        ));
-    }
-
-    #[test]
-    fn code_mode_validation_rejects_unbounded_execution_settings() {
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-[code_mode]
-timeout_ms = 0
-",
-        )
-        .expect("code_mode parses");
-        assert!(matches!(
-            cfg.validate(),
-            Err(ConfigError::InvalidCodeModeTimeout { value: 0 })
-        ));
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-[code_mode]
-timeout_ms = 5000
-max_response_bytes = 100
-",
-        )
-        .expect("code_mode parses");
-        assert!(matches!(
-            cfg.validate(),
-            Err(ConfigError::InvalidCodeModeMaxResponseBytes { value: 100 })
-        ));
-
-        let cfg = toml::from_str::<LabConfig>(
-            r"
-[code_mode]
-timeout_ms = 5000
-max_response_tokens = 100
-",
-        )
-        .expect("code_mode parses");
-        assert!(matches!(
-            cfg.validate(),
-            Err(ConfigError::InvalidCodeModeMaxResponseTokens { value: 100 })
-        ));
-    }
-
-    #[test]
-    fn protected_route_legacy_backend_path_folds_into_backend_url() {
-        let mut cfg = toml::from_str::<LabConfig>(
-            r#"
-[[protected_mcp_routes]]
-name = "tools"
-enabled = true
-public_host = "mcp.example.com"
-public_path = "/tools"
-backend_url = "http://10.0.0.12:3100"
-backend_mcp_path = "/mcp"
-"#,
-        )
-        .expect("protected route parses");
-
-        cfg.normalize_protected_mcp_routes()
-            .expect("protected route normalizes");
-
-        assert_eq!(
-            cfg.protected_mcp_routes[0].backend_url,
-            "http://10.0.0.12:3100/mcp"
-        );
-        assert_eq!(cfg.protected_mcp_routes[0].backend_mcp_path, "/mcp");
-    }
-
-    #[test]
-    fn protected_route_named_upstream_allows_empty_backend_url() {
-        let mut cfg = toml::from_str::<LabConfig>(
-            r#"
-[[protected_mcp_routes]]
-name = "telemetry"
-enabled = true
-public_host = "mcp.example.com"
-public_path = "/telemetry"
-upstream = " telemetry "
-"#,
-        )
-        .expect("protected route parses");
-
-        cfg.normalize_protected_mcp_routes()
-            .expect("upstream route normalizes");
-
-        assert_eq!(
-            cfg.protected_mcp_routes[0].upstream.as_deref(),
-            Some("telemetry")
-        );
-        assert_eq!(cfg.protected_mcp_routes[0].backend_url, "");
-        assert_eq!(cfg.protected_mcp_routes[0].backend_mcp_path, "/mcp");
-    }
-
-    #[test]
-    fn protected_route_gateway_subset_target_parses() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "ops"
-public_host = "mcp.example.com"
-public_path = "/ops"
-scopes = ["mcp:ops"]
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["gateway-alpha", "gateway-beta", " gateway-gamma "]
-services = ["gateway"]
-expose_code_mode = true
-"#;
-
-        let cfg = parse_normalized_config(toml);
-        let route = &cfg.protected_mcp_routes[0];
-
-        assert_eq!(route.name, "ops");
-        assert_eq!(route.backend_url, "");
-        assert_eq!(route.upstream, None);
-        assert!(route.is_gateway_subset());
-        let target = route.gateway_subset_target().expect("gateway subset");
-        assert_eq!(
-            target.upstreams,
-            vec!["gateway-alpha", "gateway-beta", "gateway-gamma"]
-        );
-        assert_eq!(target.services, vec!["gateway"]);
-        assert!(target.expose_code_mode);
-    }
-
-    #[test]
-    fn protected_route_legacy_backend_url_maps_to_proxy_target() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "telemetry"
-public_host = "mcp.example.com"
-public_path = "/telemetry"
-backend_url = "http://10.0.0.2:3100/mcp"
-"#;
-
-        let cfg = parse_normalized_config(toml);
-        let route = &cfg.protected_mcp_routes[0];
-
-        assert!(matches!(
-            route.effective_target(),
-            ProtectedMcpRouteEffectiveTarget::BackendUrl { .. }
-        ));
-    }
-
-    #[test]
-    fn protected_route_rejects_target_with_legacy_backend() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "bad"
-public_host = "mcp.example.com"
-public_path = "/bad"
-backend_url = "http://10.0.0.2:3100/mcp"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["gateway-beta"]
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        let err = cfg
-            .normalize_protected_mcp_routes()
-            .expect_err("target and backend_url must conflict");
-        assert!(err.to_string().contains(
-            "protected MCP route target cannot be combined with upstream or backend_url"
-        ));
-    }
-
-    #[test]
-    fn protected_route_rejects_empty_gateway_subset_entries() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "bad"
-public_host = "mcp.example.com"
-public_path = "/bad"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["gateway-alpha", " "]
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        let err = cfg
-            .normalize_protected_mcp_routes()
-            .expect_err("empty upstream entry must fail");
-        assert!(err.to_string().contains("target.upstreams"));
-        assert!(
-            err.to_string()
-                .contains("gateway_subset target entries must not be empty")
-        );
-    }
-
-    #[test]
-    fn protected_route_allows_same_gateway_subset_path_on_different_hosts() {
-        let toml = r#"
-[[upstream]]
-name = "gateway-alpha"
-enabled = false
-url = "https://gateway-alpha.example.com/mcp"
-
-[[protected_mcp_routes]]
-name = "media-a"
-public_host = "mcp-a.example.com"
-public_path = "/ops"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["gateway-alpha"]
-
-[[protected_mcp_routes]]
-name = "media-b"
-public_host = "mcp-b.example.com"
-public_path = "/ops"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["gateway-alpha"]
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("host and path together identify a protected route");
-        cfg.validate()
-            .expect("same subset path on distinct hosts is valid");
-    }
-
-    #[test]
-    fn config_validation_rejects_reserved_protected_route_path() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "bad"
-public_host = "mcp.example.com"
-public_path = "/v1"
-backend_url = "http://10.0.0.2:3100/mcp"
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("normalization should not hide validation failure");
-        let err = cfg
-            .validate()
-            .expect_err("reserved protected route path must fail validation");
-
-        assert!(err.to_string().contains("public_path"));
-        assert!(err.to_string().contains("reserved"));
-    }
-
-    #[test]
-    fn config_validation_rejects_public_callback_relay_protected_route_path() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "bad"
-public_host = "mcp.example.com"
-public_path = "/callback/devhost"
-backend_url = "http://10.0.0.2:3100/mcp"
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("normalization should not hide validation failure");
-        let err = cfg
-            .validate()
-            .expect_err("callback relay protected route path must fail validation");
-
-        assert!(err.to_string().contains("public_path"));
-        assert!(err.to_string().contains("reserved"));
-    }
-
-    #[test]
-    fn config_validation_rejects_empty_gateway_subset_target() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "empty"
-public_host = "mcp.example.com"
-public_path = "/empty"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("normalization should not hide validation failure");
-        let err = cfg
-            .validate()
-            .expect_err("empty gateway_subset target must fail validation");
-
-        assert!(err.to_string().contains("gateway_subset target"));
-    }
-
-    #[test]
-    fn config_validation_accepts_gateway_subset_loadout_target() {
-        let toml = r#"
-[[upstream]]
-name = "gateway-alpha"
-enabled = false
-url = "https://gateway-alpha.example.com/mcp"
-
-[[loadouts]]
-name = "sd"
-upstreams = ["gateway-alpha"]
-
-[[protected_mcp_routes]]
-name = "sd"
-public_host = "sd.example.com"
-public_path = "/mcp"
-scopes = ["mcp:read"]
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-loadout = " sd "
-"#;
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-
-        cfg.normalize_protected_mcp_routes()
-            .expect("loadout route normalization succeeds");
-        cfg.validate().expect("known loadout route is valid");
-        let ProtectedMcpRouteTarget::GatewaySubset(target) = cfg.protected_mcp_routes[0]
-            .target
-            .as_ref()
-            .expect("gateway subset target");
-        assert_eq!(target.loadout.as_deref(), Some("sd"));
-    }
-
-    #[test]
-    fn config_validation_rejects_unknown_gateway_subset_targets() {
-        let toml = r#"
-[[upstream]]
-name = "gateway-alpha"
-url = "https://gateway_alpha.example.com/mcp"
-
-[[protected_mcp_routes]]
-name = "ops"
-public_host = "mcp.example.com"
-public_path = "/ops"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["sonnar"]
-services = ["gateway", "nope"]
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("normalization should not hide validation failure");
-        let err = cfg
-            .validate()
-            .expect_err("unknown gateway_subset targets must fail validation");
-
-        assert!(
-            err.to_string().contains("sonnar") || err.to_string().contains("nope"),
-            "unexpected error: {err}"
-        );
-    }
-
-    #[test]
-    fn config_validation_allows_stale_targets_on_disabled_gateway_subset_routes() {
-        let toml = r#"
-[[protected_mcp_routes]]
-name = "retired-ops"
-enabled = false
-public_host = "mcp.example.com"
-public_path = "/ops"
-
-[protected_mcp_routes.target]
-kind = "gateway_subset"
-upstreams = ["removed-upstream"]
-services = ["removed-service"]
-"#;
-
-        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
-        cfg.normalize_protected_mcp_routes()
-            .expect("disabled route remains structurally valid");
-        cfg.validate()
-            .expect("disabled routes must not block gateway startup");
-    }
-
-    // ── Code Mode: CodeModeConfig defaults ───────────────────────────────────
-
-    #[test]
-    fn code_mode_config_token_estimate_divisor_defaults_to_4() {
-        let config = CodeModeConfig::default();
-        // PRESENCE: default divisor is exactly 4
-        assert_eq!(
-            config.token_estimate_divisor, 4,
-            "token_estimate_divisor default must be 4"
-        );
-        // ABSENCE: it is not 0 or 1 (which would drastically change truncation)
-        assert_ne!(config.token_estimate_divisor, 0);
-        assert_ne!(config.token_estimate_divisor, 1);
-    }
-
-    #[test]
-    fn code_mode_config_defaults_are_sane() {
-        let config = CodeModeConfig::default();
-        // PRESENCE: timeout and output limits are positive
-        assert!(config.timeout_ms > 0);
-        assert!(config.max_response_bytes > 0);
-        assert!(config.max_response_tokens > 0);
-        // ABSENCE: not wildly large (sanity bounds)
-        assert!(config.timeout_ms <= 60_000);
-    }
-
-    // ── Process-wide atomic flags ─────────────────────────────────────────────
-
-    #[test]
-    fn process_code_mode_flag_round_trips() {
-        let _guard = process_code_mode_test_guard();
-
-        set_process_code_mode_enabled_for_test(true);
-        assert!(
-            process_code_mode_enabled(),
-            "code_mode must be true after set_process_code_mode_enabled(true)"
-        );
-
-        set_process_code_mode_enabled_for_test(false);
-        assert!(
-            !process_code_mode_enabled(),
-            "code_mode must be false after set_process_code_mode_enabled(false)"
-        );
-    }
-
-    // ── T3: secret file permission tests (S2) ────────────────────────────────
-
-    #[cfg(unix)]
-    fn file_mode(path: &Path) -> u32 {
-        use std::os::unix::fs::PermissionsExt;
-        std::fs::metadata(path)
-            .unwrap_or_else(|e| panic!("metadata {}: {e}", path.display()))
-            .permissions()
-            .mode()
-            & 0o777
-    }
-
-    #[test]
-    #[cfg(unix)]
-    fn write_service_creds_creates_file_with_mode_0o600() {
-        let dir = tempfile::tempdir().expect("tempdir");
-        let env_path = dir.path().join(".env");
-
-        let creds = [EnvCredential {
-            service: "myservice".to_string(),
-            url: None,
-            secret: Some("supersecret".to_string()),
-            env_field: "MYSERVICE_TOKEN".to_string(),
-        }];
-
-        write_service_creds(&env_path, &creds, false).expect("write_service_creds");
-
-        assert_eq!(
-            file_mode(&env_path),
-            0o600,
-            ".env must be 0o600 after write_service_creds"
-        );
-    }
-
-    // Backup-file 0o600 perms and retention pruning are covered directly by
-    // env_merge's own unix_perms_set_to_0600 / backup_pruning_keeps_last_ten
-    // tests -- write_service_creds delegates entirely to env_merge::merge for
-    // that behavior and adds no file-handling logic of its own.
-
-    #[test]
-    #[cfg(unix)]
-    fn heal_env_file_permissions_tightens_loose_env() {
-        use std::os::unix::fs::PermissionsExt;
-
-        let dir = tempfile::tempdir().expect("tempdir");
-        let env_path = dir.path().join(".env");
-        std::fs::write(&env_path, "TOKEN=secret\n").expect("write");
-        std::fs::set_permissions(&env_path, std::fs::Permissions::from_mode(0o644))
-            .expect("chmod 644");
-
-        heal_env_file_permissions(&env_path);
-
-        assert_eq!(
-            file_mode(&env_path),
-            0o600,
-            "heal must tighten .env to 0o600"
-        );
-    }
-
-    #[test]
-    #[cfg(unix)]
-    fn heal_env_file_permissions_tightens_backup_files() {
-        use std::os::unix::fs::PermissionsExt;
-
-        let dir = tempfile::tempdir().expect("tempdir");
-        let env_path = dir.path().join(".env");
-        let bak_path = dir.path().join(".env.bak.1234567890");
-
-        std::fs::write(&env_path, "TOKEN=secret\n").expect("write env");
-        std::fs::write(&bak_path, "TOKEN=oldsecret\n").expect("write bak");
-
-        for p in [&env_path, &bak_path] {
-            std::fs::set_permissions(p, std::fs::Permissions::from_mode(0o644)).expect("chmod 644");
-        }
-
-        heal_env_file_permissions(&env_path);
-
-        assert_eq!(file_mode(&env_path), 0o600, ".env must be healed");
-        assert_eq!(file_mode(&bak_path), 0o600, ".env.bak.* must be healed");
-    }
-
-    // usage_telemetry_enabled() delegates to the pure resolve_usage_telemetry_enabled()
-    // so these tests never need to mutate process env (this crate forbids
-    // `unsafe`, and `std::env::set_var`/`remove_var` are `unsafe fn` as of
-    // Rust 2024) — same shape as the resolve_web_ui_auth_disabled_values
-    // tests above.
-    #[test]
-    fn usage_telemetry_enabled_defaults_true_when_unset() {
-        assert!(
-            resolve_usage_telemetry_enabled(None),
-            "usage telemetry must default to enabled when the env var is unset"
-        );
-    }
-
-    #[test]
-    fn usage_telemetry_enabled_false_when_set_to_1() {
-        assert!(
-            !resolve_usage_telemetry_enabled(Some("1")),
-            "usage telemetry must be disabled when the env var is \"1\""
-        );
-    }
-
-    #[test]
-    fn usage_telemetry_enabled_true_for_other_values() {
-        assert!(
-            resolve_usage_telemetry_enabled(Some("true")),
-            "only the exact value \"1\" should disable usage telemetry"
-        );
-        assert!(
-            resolve_usage_telemetry_enabled(Some("0")),
-            "\"0\" is not the disable sentinel; telemetry stays enabled"
-        );
-    }
-
-    #[test]
-    fn usage_db_path_is_under_dot_labby_home_dir() {
-        let path = usage_db_path().unwrap();
-        assert_eq!(path.file_name().and_then(|n| n.to_str()), Some("usage.db"));
-        assert_eq!(
-            path.parent()
-                .and_then(|p| p.file_name())
-                .and_then(|n| n.to_str()),
-            Some(".labby")
-        );
-    }
-
-    /// Review finding on lab-eyeuv: the reserved-prefix guard was added to
-    /// `labby_runtime`'s copy of `normalize_protected_mcp_routes`, but
-    /// `load_toml` runs THIS copy — and the route scopes mounted by
-    /// `cli/serve.rs` are built from this config. The guard has to live on
-    /// both, and this test pins the serve-path copy specifically.
-    #[test]
-    fn serve_path_normalization_rejects_reserved_in_process_upstreams() {
-        let mut route: ProtectedMcpRouteConfig = toml::from_str(
-            "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
-        )
-        .unwrap();
-        route.backend_url = String::new();
-        route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
-            ProtectedGatewaySubsetTarget {
-                project_id: None,
-                upstreams: vec![format!("{IN_PROCESS_UPSTREAM_PREFIX}setup")],
-                services: Vec::new(),
-                expose_code_mode: false,
-                loadout: None,
-            },
-        ));
-        let mut cfg = LabConfig {
-            protected_mcp_routes: vec![route],
-            ..LabConfig::default()
-        };
-
-        let error = cfg
-            .normalize_protected_mcp_routes()
-            .expect_err("the serve-path copy must reject the reserved prefix");
-        let rendered = error.to_string();
-        assert!(rendered.contains("__in_process__setup"), "{rendered}");
-    }
-
-    #[test]
-    fn serve_path_project_id_normalization_is_bounded_and_compatible() {
-        fn config(project_id: Option<String>) -> LabConfig {
-            let mut route: ProtectedMcpRouteConfig = toml::from_str(
-                "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
-            )
-            .unwrap();
-            route.backend_url = String::new();
-            route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
-                ProtectedGatewaySubsetTarget {
-                    project_id,
-                    ..Default::default()
-                },
-            ));
-            LabConfig {
-                protected_mcp_routes: vec![route],
-                ..Default::default()
-            }
-        }
-
-        let mut omitted = config(None);
-        omitted
-            .normalize_protected_mcp_routes()
-            .expect("legacy None");
-        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
-            omitted.protected_mcp_routes[0].target.as_ref()
-        else {
-            unreachable!()
-        };
-        assert_eq!(target.project_id, None);
-
-        let max = labby_runtime::gateway_config::MAX_PROJECT_ID_LEN;
-        let expected = "x".repeat(max);
-        let mut trimmed = config(Some(format!("  {expected}  ")));
-        trimmed.normalize_protected_mcp_routes().expect("128 bytes");
-        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
-            trimmed.protected_mcp_routes[0].target.as_ref()
-        else {
-            unreachable!()
-        };
-        assert_eq!(target.project_id.as_deref(), Some(expected.as_str()));
-
-        for invalid in ["   ".to_string(), "x".repeat(max + 1)] {
-            assert!(
-                config(Some(invalid))
-                    .normalize_protected_mcp_routes()
-                    .is_err()
-            );
-        }
-    }
-}
+            let metadata = entry
\ No newline at end of file
diff --git a/crates/labby/src/dispatch/setup/settings.rs b/crates/labby/src/dispatch/setup/settings.rs
index 6231171fd..405290adc 100644
--- a/crates/labby/src/dispatch/setup/settings.rs
+++ b/crates/labby/src/dispatch/setup/settings.rs
@@ -777,7 +777,7 @@ pub fn settings_fields() -> Vec<SettingsFieldSpec> {
             SettingsApplyMode::Partial,
             1024,
             1_048_576,
-            Some("131072"),
+            Some("1048576"),
         ),
         number_editable(
             "advanced",
@@ -1941,7 +1941,7 @@ mod tests {
         assert_eq!(field.apply_mode, SettingsApplyMode::Partial);
         assert_eq!(field.min, Some(1024));
         assert_eq!(field.max, Some(1_048_576));
-        assert_eq!(field.example, Some("131072"));
+        assert_eq!(field.example, Some("1048576"));
     }
 
     #[test]
diff --git a/crates/labby/src/dispatch/snippets/dispatch.rs b/crates/labby/src/dispatch/snippets/dispatch.rs
index ada316866..73db21767 100644
--- a/crates/labby/src/dispatch/snippets/dispatch.rs
+++ b/crates/labby/src/dispatch/snippets/dispatch.rs
@@ -298,6 +298,14 @@ fn snippet_test_result(name: String, outcome: SnippetExecutionOutcome) -> Result
     }))
 }
 
+fn snippet_execution_scope(snippet: &super::store::ResolvedSnippet) -> ToolScope {
+    snippet
+        .tools
+        .as_ref()
+        .map(|declared| declared.intersect(&ToolScope::default()))
+        .unwrap_or_default()
+}
+
 async fn execute_snippet_outcome(
     manager: Option<&crate::dispatch::gateway::manager::GatewayManager>,
     name: &str,
@@ -316,13 +324,19 @@ async fn execute_snippet_outcome(
     let code = code_for_snippet(&snippet)?;
     let input = merge_snippet_input(&snippet, input)?;
     let code = wrap_snippet_with_input(&code, &input)?;
+    // Saved snippet source stays entirely on the execution plane. When the
+    // snippet declares exact upstream dependencies, use that declaration to
+    // scope catalog construction and dispatch instead of cold-probing every
+    // configured upstream. Snippets without declarations retain legacy
+    // unscoped behavior for compatibility.
+    let scope = snippet_execution_scope(&snippet);
     let outcome = broker
         .execute_with_raw_response(
             &code,
             CodeModeCaller::TrustedLocal,
             CodeModeSurface::Cli,
             config,
-            ToolScope::default(),
+            scope,
             // Snippet execution is a local trusted-CLI path with no durable-run
             // execution id; `None` keeps `record_step` write-free here.
             None,
@@ -405,6 +419,38 @@ mod tests {
         }
     }
 
+    #[test]
+    fn saved_snippet_tool_declarations_scope_execution_catalog() {
+        use std::collections::BTreeMap;
+        use std::path::PathBuf;
+
+        use crate::dispatch::snippets::store::{ResolvedSnippet, SnippetSource};
+        use labby_codemode::snippet::tool_declarations::SnippetToolDeclarations;
+
+        let declared: SnippetToolDeclarations = vec![
+            "claude-macpoo::Bash".to_string(),
+            "claude-macpoo::Read".to_string(),
+        ]
+        .try_into()
+        .expect("valid exact tool declarations");
+        let snippet = ResolvedSnippet {
+            tools: Some(declared),
+            name: "scoped".to_string(),
+            description: None,
+            tags: Vec::new(),
+            inputs: BTreeMap::new(),
+            source: SnippetSource::User,
+            path: PathBuf::from("scoped.md"),
+            body: "async () => ({ ok: true })".to_string(),
+        };
+
+        let scope = snippet_execution_scope(&snippet);
+        assert!(scope.is_scoped());
+        assert!(scope.allows("claude-macpoo", "Bash"));
+        assert!(scope.allows("claude-macpoo", "Read"));
+        assert!(!scope.allows("github", "search_issues"));
+    }
+
     #[test]
     fn snippets_test_uses_raw_result_for_pass_fail_and_returns_shaped_display() {
         let pass = snippet_test_result(
diff --git a/docs/dev/CODE_MODE.md b/docs/dev/CODE_MODE.md
index 27f0d7573..5511a958d 100644
--- a/docs/dev/CODE_MODE.md
+++ b/docs/dev/CODE_MODE.md
@@ -276,9 +276,17 @@ async () => {
 
 `codemode.run()` lazily resolves snippet source through the host, then evaluates
 `return await (<snippet-code>)(input)` inside the same Javy/QuickJS runtime as the
-caller. A snippet can call `codemode.<upstream>.<tool>()`, `callTool()`,
-`writeArtifact()`, and other snippets, bounded by the same Code Mode timeout plus
-per-run snippet depth/count/byte budgets.
+caller. The saved source stays on the execution plane: model-facing discovery
+exposes only snippet metadata and the invocation helper, and execution responses
+do not echo the resolved source. An invoking model therefore pays context for the
+name, input schema/arguments, and returned result, not for the stored program on
+every run. Source enters model context only when a caller explicitly reads, edits,
+reviews, or authors it.
+
+A snippet can call `codemode.<upstream>.<tool>()`, `callTool()`, `writeArtifact()`,
+and other snippets, bounded by the same Code Mode timeout plus per-run snippet
+depth/count/byte budgets. Those byte limits are parser/sandbox/storage safety
+limits, not an assertion that saved source must fit in the invoking LLM context.
 
 `writeArtifact()` defaults `contentType` to `text/plain` when omitted or blank.
 When provided, it must be a simple ASCII `type/subtype` media type, up to 256
@@ -507,7 +515,7 @@ their JSON MCP representation.
 
 Defaults:
 
-- `max_source_bytes = 131072`
+- `max_source_bytes = 1048576`
 - `max_response_bytes = 24576`
 - `max_response_tokens = 6000`
 
diff --git a/docs/services/SNIPPETS.md b/docs/services/SNIPPETS.md
index a7c947e82..9c4877491 100644
--- a/docs/services/SNIPPETS.md
+++ b/docs/services/SNIPPETS.md
@@ -14,7 +14,7 @@ The generated [action catalog](../generated/action-catalog.md) is authoritative
 
 `snippets.list`, `help`, and `schema` are discovery operations. Built-in snippets are loaded from the checked-in snippet directory and user snippets are resolved from the Labby home.
 
-## Tool Declaration Metadata
+## Tool Declaration Scope
 
 Markdown frontmatter may include `tools` as a JSON string array or an indented
 list of exact `<upstream>::<tool>` identifiers. Storage and Code Mode discovery
@@ -22,11 +22,16 @@ preserve omission separately from an explicit empty array. Declarations are
 bounded to 128 unique identifiers of at most 1,024 bytes each; reserved local
 capabilities, malformed identifiers, and duplicate declaration keys are rejected.
 
-**This is descriptive metadata, not an execution restriction.** Omission records
-no declaration; `[]` expresses an intended deny-all declaration; a nonempty list
-records intended dependencies. Current execution still uses the existing caller
-policy regardless of this metadata. Do not rely on `tools` to limit a snippet's
-authority until host-side enforcement is implemented and qualified.
+For native saved-snippet execution (`snippets.exec` / `snippets.test`), Labby
+intersects a declaration with the caller's existing Code Mode policy before
+building the catalog. The declaration can narrow authority but never grant it:
+omission keeps the legacy caller scope, `[]` denies all upstream tools, and a
+nonempty list exposes only those exact dependencies. This also keeps one-shot
+snippet runs from cold-probing unrelated gateway upstreams.
+
+Nested `codemode.run()` inherits the already-established execution scope. Trusted
+local saved snippets may compose inside that declared scope; route-scoped callers
+still cannot use nested snippet resolution to widen their authority.
 
 ## Administrative Actions
 
diff --git a/docs/snippets/README.md b/docs/snippets/README.md
index 44adfb124..b8d83271d 100644
--- a/docs/snippets/README.md
+++ b/docs/snippets/README.md
@@ -245,7 +245,17 @@ async () => {
 
 `codemode.run()` resolves snippet source lazily through the live gateway and
 evaluates it inside the same Javy/QuickJS runtime as the caller. Snippet source
-is not injected into search/describe metadata.
+is not injected into search/describe metadata and is not echoed in the normal
+execution response. A saved snippet invocation should cost the model context for
+the snippet name, inputs, and compact result, not the stored JavaScript body.
+The source only needs to enter an LLM context when the user explicitly asks an
+agent to author, inspect, debug, or edit that source.
+
+When frontmatter declares exact `tools`, native saved-snippet execution uses that
+declaration to scope catalog construction and dispatch. This avoids waking or
+probing unrelated gateway upstreams for a workflow whose dependencies are
+already known. Snippets without declarations retain the legacy unscoped catalog
+behavior for compatibility.
 
 Successful admin/trusted-local Code Mode executions return an `execution_id`.
 Promote a prior execution through the live gateway snippets action, not a
diff --git a/docs/snippets/docker-host-inventory.md b/docs/snippets/docker-host-inventory.md
new file mode 100644
index 000000000..9824928c0
--- /dev/null
+++ b/docs/snippets/docker-host-inventory.md
@@ -0,0 +1,68 @@
+---
+name: docker-host-inventory
+title: "Docker Host Inventory"
+created: "2026-09-16"
+updated: "2026-09-16"
+description: Inventory one Docker host over key-only SSH with compact inspect data, recent logs, mounts, networks, ports, state, and image digest drift
+tags: [homelab, docker, ssh, inventory, readonly]
+tools:
+  - claude-macpoo::Bash
+inputs:
+  alias:
+    type: string
+    required: true
+  connect_timeout_seconds:
+    type: integer
+    default: 4
+    required: false
+  command_timeout_ms:
+    type: integer
+    default: 20000
+    required: false
+  log_lines:
+    type: integer
+    default: 20
+    required: false
+  containers_per_call:
+    type: integer
+    default: 4
+    required: false
+  check_updates:
+    type: boolean
+    default: true
+    required: false
+  update_timeout_seconds:
+    type: integer
+    default: 3
+    required: false
+  update_parallelism:
+    type: integer
+    default: 24
+    required: false
+---
+
+# Docker Host Inventory
+
+Reusable one-host primitive. Host identity is resolved before Docker enumeration. Container detail groups fan out concurrently. Image drift checks depend on the actual image references returned by the detail stage. Update checks never pull images.
+
+```js
+async (o = {}) => {
+  const i={alias:String(o.alias||"").trim(),connect_timeout_seconds:Math.max(1,Math.min(30,Number(o.connect_timeout_seconds??4))),command_timeout_ms:Math.max(5000,Math.min(60000,Number(o.command_timeout_ms??20000))),log_lines:Math.max(0,Math.min(200,Number(o.log_lines??20))),containers_per_call:Math.max(1,Math.min(20,Number(o.containers_per_call??4))),check_updates:o.check_updates!==false,update_timeout_seconds:Math.max(1,Math.min(15,Number(o.update_timeout_seconds??3))),update_parallelism:Math.max(1,Math.min(32,Number(o.update_parallelism??24)))};
+  if(!i.alias)throw new Error("docker-host-inventory requires alias");
+  const q=v=>"'"+String(v).split("'").join("'\"'\"'")+"'", txt=v=>typeof v==="string"?v:typeof v?.stdout==="string"?v.stdout:Array.isArray(v?.content)?v.content.map(x=>x?.text||"").join("\n"):"", clean=e=>{const s=String(e??""),m="Original tool error:",n=s.indexOf(m);return(n>=0?s.slice(n+m.length):s).trim().slice(0,1200)},chunk=(a,n)=>{const x=[];for(let p=0;p<a.length;p+=n)x.push(a.slice(p,p+n));return x};
+  const bash="claude-macpoo::Bash";
+  await callTool(bash,{command:"hostname; whoami; uname -s; pwd",timeout:i.command_timeout_ms});
+  const opts=["-o BatchMode=yes","-o NumberOfPasswordPrompts=0","-o PreferredAuthentications=publickey","-o PasswordAuthentication=no","-o KbdInteractiveAuthentication=no","-o ConnectionAttempts=1","-o ConnectTimeout="+i.connect_timeout_seconds].join(" "),ssh=r=>callTool(bash,{command:"ssh "+opts+" "+q(i.alias)+" "+q(r),timeout:i.command_timeout_ms});
+  const id=txt(await ssh("hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true")).split("\n").map(x=>x.trim()),host={alias:i.alias,hostname:id[0]||null,user:id[1]||null,platform:id[2]||null,docker_path:id[3]||null,docker_version:id[4]||null,timeout_path:id[5]||null};
+  if(!host.hostname)throw new Error("SSH probe returned no hostname for "+i.alias);
+  if(!host.docker_path)return{schema_version:"labby.docker.host_inventory.v1",ok:true,host,containers:[],errors:[],summary:{containers:0,container_states:{},image_update_states:{},updates_available:0,docker_available:false}};
+  const ids=txt(await ssh("docker ps -aq --no-trunc")).split("\n").map(x=>x.trim()).filter(x=>/^[0-9a-f]{12,64}$/i.test(x));
+  const fmt='{"id":{{json .Id}},"name":{{json .Name}},"image_ref":{{json .Config.Image}},"image_id":{{json .Image}},"created":{{json .Created}},"restart_count":{{json .RestartCount}},"state":{"status":{{json .State.Status}},"running":{{json .State.Running}},"paused":{{json .State.Paused}},"restarting":{{json .State.Restarting}},"oom_killed":{{json .State.OOMKilled}},"dead":{{json .State.Dead}},"pid":{{json .State.Pid}},"exit_code":{{json .State.ExitCode}},"error":{{json .State.Error}},"started_at":{{json .State.StartedAt}},"finished_at":{{json .State.FinishedAt}},"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}}},"ports":{{json .NetworkSettings.Ports}},"networks":{{json .NetworkSettings.Networks}},"mounts":{{json .Mounts}}}',sec="__LABBY_DOCKER_LOG_SECTION_9D81__",beg="__LABBY_DOCKER_LOG_BEGIN_9D81__:",end="__LABBY_DOCKER_LOG_END_9D81__:";
+  const detail=await codemode.batch(chunk(ids,i.containers_per_call).map(g=>async()=>{const list=g.join(" "),r=["docker inspect --format "+q(fmt)+" "+list,"printf "+q("\n"+sec+"\n"),"for id in "+list+"; do","printf "+q(beg+"%s\n")+" \"$id\"","docker logs --tail "+i.log_lines+" --timestamps \"$id\" 2>&1 || true","printf "+q(end+"%s\n")+" \"$id\"","done"].join("\n"),out=txt(await ssh(r)),at=out.indexOf("\n"+sec+"\n");if(at<0)throw new Error("inventory marker missing");const meta=out.slice(0,at).split("\n").map(x=>x.trim()).filter(Boolean).map(JSON.parse),logs={};let active=null;for(const line of out.slice(at+sec.length+2).split("\n")){if(line.startsWith(beg)){active=line.slice(beg.length);logs[active]=[];continue}if(line.startsWith(end)){active=null;continue}if(active)logs[active].push(line)}return meta.map(c=>({id:c.id,name:String(c.name||"").replace(/^\/+/,""),image_ref:c.image_ref||null,image_id:c.image_id||null,created:c.created||null,restart_count:c.restart_count??0,state:c.state||{},ports:Object.entries(c.ports||{}).map(([container_port,b])=>({container_port,bindings:(b||[]).map(x=>({host_ip:x.HostIp,host_port:x.HostPort}))})),networks:Object.entries(c.networks||{}).map(([name,x])=>({name,ip_address:x.IPAddress||"",global_ipv6_address:x.GlobalIPv6Address||"",gateway:x.Gateway||"",mac_address:x.MacAddress||"",aliases:x.Aliases||[]})),mounts:(c.mounts||[]).map(x=>({type:x.Type,name:x.Name||null,source:x.Source,destination:x.Destination,mode:x.Mode,rw:x.RW,propagation:x.Propagation})),logs:{requested_lines:i.log_lines,lines:logs[c.id]||[]}}))}));
+  const containers=[],errors=[];for(const x of detail.ok||[])containers.push(...x.value);for(const x of detail.failed||[])errors.push({stage:"inspect_logs",batch:x.i,error:clean(x.error)});
+  const updates={};if(i.check_updates&&containers.length){const images=Array.from(new Set(containers.map(c=>c.image_ref).filter(Boolean))),w=["img=\"$1\"","if printf '%s' \"$img\" | grep -Eq '^[0-9a-f]{12,64}$'; then printf '%s\tunknown\t\t\tlocal_image_id\n' \"$img\"; exit 0; fi","case \"$img\" in *@sha256:*) d=\"$(printf '%s' \"$img\" | cut -d@ -f2-)\"; printf '%s\tpinned\t%s\t%s\tpinned_digest\n' \"$img\" \"$d\" \"$d\"; exit 0 ;; esac","local_digests=\"$(docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' \"$img\" 2>/dev/null || true)\"","if [ -z \"$local_digests\" ]; then printf '%s\tunknown\t\t\tno_local_repo_digest\n' \"$img\"; exit 0; fi","remote_digest=\"$(timeout "+i.update_timeout_seconds+" docker buildx imagetools inspect \"$img\" 2>/dev/null | grep -m1 '^Digest:' | tr -s ' ' | cut -d' ' -f2 || true)\"","local_csv=\"$(printf '%s\n' \"$local_digests\" | tr '\n' ',' )\"","if [ -z \"$remote_digest\" ]; then printf '%s\tunknown\t%s\t\tregistry_digest_unavailable\n' \"$img\" \"$local_csv\"; exit 0; fi","if printf '%s\n' \"$local_digests\" | grep -Fq \"@$remote_digest\"; then status=current; else status=available; fi","printf '%s\t%s\t%s\t%s\tcompared_registry_digest\n' \"$img\" \"$status\" \"$local_csv\" \"$remote_digest\""].join("\n");try{const out=txt(await ssh("printf '%s\n' "+images.map(q).join(" ")+" | xargs -n1 -P"+i.update_parallelism+" sh -c "+q(w)+" sh"));for(const line of out.split("\n")){if(!line.trim())continue;const [image,status,localRaw,remote_digest,reason]=line.split("\t");updates[image]={status:status||"unknown",local_digests:String(localRaw||"").split(",").map(x=>x.trim()).filter(Boolean).map(x=>x.includes("@")?x.slice(x.lastIndexOf("@")+1):x),remote_digest:remote_digest||null,reason:reason||null}}}catch(e){errors.push({stage:"updates",error:clean(e)})}}
+  for(const c of containers)c.update=i.check_updates?(updates[c.image_ref]||{status:"unknown",local_digests:[],remote_digest:null,reason:"image_not_checked"}):{status:"not_checked",local_digests:[],remote_digest:null,reason:"disabled_by_input"};containers.sort((a,b)=>String(a.name).localeCompare(String(b.name)));
+  const states={},imageStates={};for(const c of containers){const s=c.state?.status||"unknown",u=c.update?.status||"unknown";states[s]=(states[s]||0)+1;imageStates[u]=(imageStates[u]||0)+1}
+  return{schema_version:"labby.docker.host_inventory.v1",ok:errors.length===0,host,containers,errors,summary:{containers:containers.length,container_states:states,image_update_states:imageStates,updates_available:containers.filter(c=>c.update?.status==="available").length,docker_available:true}};
+}
+```
diff --git a/docs/snippets/homelab-docker-inventory.md b/docs/snippets/homelab-docker-inventory.md
new file mode 100644
index 000000000..ee13690b6
--- /dev/null
+++ b/docs/snippets/homelab-docker-inventory.md
@@ -0,0 +1,73 @@
+---
+name: homelab-docker-inventory
+title: "Homelab Docker Inventory"
+created: "2026-09-15"
+updated: "2026-09-16"
+description: Discover key-auth homelab hosts, inventory Docker across reachable machines, and return a structured artifact and compact summary
+tags: [homelab, docker, ssh, inventory, ops, readonly]
+tools:
+  - claude-macpoo::Bash
+  - claude-macpoo::Read
+inputs:
+  ssh_config:
+    type: string
+    default: ""
+    required: false
+  exclude_hosts:
+    type: array
+    default: ["github.com", "orb"]
+    required: false
+  extra_hosts:
+    type: array
+    default: []
+    required: false
+  connect_timeout_seconds:
+    type: integer
+    default: 4
+    required: false
+  command_timeout_ms:
+    type: integer
+    default: 20000
+    required: false
+  log_lines:
+    type: integer
+    default: 20
+    required: false
+  containers_per_call:
+    type: integer
+    default: 4
+    required: false
+  check_updates:
+    type: boolean
+    default: true
+    required: false
+  update_timeout_seconds:
+    type: integer
+    default: 3
+    required: false
+  update_parallelism:
+    type: integer
+    default: 24
+    required: false
+---
+
+# Homelab Docker Inventory
+
+Thin orchestration snippet. SSH discovery is a required dependency, then independent Docker hosts fan out through the reusable one-host inventory snippet. The complete machine-readable report is written as an artifact while the direct result stays compact.
+
+```js
+async (o = {}) => {
+  const input={ssh_config:o.ssh_config??"",exclude_hosts:Array.isArray(o.exclude_hosts)?o.exclude_hosts:["github.com","orb"],extra_hosts:Array.isArray(o.extra_hosts)?o.extra_hosts:[],connect_timeout_seconds:Math.max(1,Math.min(30,Number(o.connect_timeout_seconds??4))),command_timeout_ms:Math.max(5000,Math.min(60000,Number(o.command_timeout_ms??20000))),log_lines:Math.max(0,Math.min(200,Number(o.log_lines??20))),containers_per_call:Math.max(1,Math.min(20,Number(o.containers_per_call??4))),check_updates:o.check_updates!==false,update_timeout_seconds:Math.max(1,Math.min(15,Number(o.update_timeout_seconds??3))),update_parallelism:Math.max(1,Math.min(32,Number(o.update_parallelism??24)))};
+  const discovery=await codemode.run("homelab-ssh-targets",{ssh_config:input.ssh_config,exclude_hosts:input.exclude_hosts,extra_hosts:input.extra_hosts,connect_timeout_seconds:input.connect_timeout_seconds,command_timeout_ms:input.command_timeout_ms});
+  if(!discovery?.ok)throw new Error("homelab SSH discovery failed");
+  const byDevice=new Map();
+  for(const t of discovery.targets||[]){if(!t?.ssh_reachable||!t.remote?.hostname||!t.remote?.docker_path)continue;const key=String(t.remote.hostname).toLowerCase()+"|"+String(t.remote.user||"").toLowerCase();if(!byDevice.has(key))byDevice.set(key,{key,hostname:t.remote.hostname,user:t.remote.user,platform:t.remote.platform,aliases:[],preferred_alias:t.alias,docker_version:t.remote.docker_version||null});byDevice.get(key).aliases.push(t.alias)}
+  const devices=Array.from(byDevice.values()), jobs=devices.map(d=>()=>codemode.run("docker-host-inventory",{alias:d.preferred_alias,connect_timeout_seconds:input.connect_timeout_seconds,command_timeout_ms:input.command_timeout_ms,log_lines:input.log_lines,containers_per_call:input.containers_per_call,check_updates:input.check_updates,update_timeout_seconds:input.update_timeout_seconds,update_parallelism:input.update_parallelism})),batch=await codemode.batch(jobs),inventories=new Array(devices.length),hostFailures=[];
+  for(const x of batch.ok||[])inventories[x.i]=x.value;for(const x of batch.failed||[])hostFailures.push({device:devices[x.i],error:String(x.error).slice(0,1200)});
+  const states={},updates={};let total=0,updatesAvailable=0,hostsWithErrors=hostFailures.length;
+  for(let n=0;n<devices.length;n++){const inv=inventories[n];if(!inv)continue;devices[n].inventory=inv;total+=inv.summary?.containers||0;updatesAvailable+=inv.summary?.updates_available||0;if((inv.errors||[]).length)hostsWithErrors++;for(const [k,v] of Object.entries(inv.summary?.container_states||{}))states[k]=(states[k]||0)+v;for(const [k,v] of Object.entries(inv.summary?.image_update_states||{}))updates[k]=(updates[k]||0)+v;}
+  const report={schema_version:"labby.homelab.docker_inventory.v1",generated_at:new Date().toISOString(),input,controller:discovery.controller,discovery:{...discovery.discovery,unique_reachable_devices:new Set((discovery.targets||[]).filter(t=>t?.ssh_reachable&&t.remote?.hostname).map(t=>String(t.remote.hostname).toLowerCase()+"|"+String(t.remote.user||"").toLowerCase())).size,docker_hosts:devices.length},ssh_targets:discovery.targets||[],devices,host_failures:hostFailures,summary:{containers:total,container_states:states,image_update_states:updates,updates_available:updatesAvailable,hosts_with_inventory_errors:hostsWithErrors}};
+  const artifact=await writeArtifact("homelab/docker-inventory.json",JSON.stringify(report,null,2),{contentType:"application/json"});
+  return{schema_version:report.schema_version,ok:hostsWithErrors===0,partial:(report.discovery.ssh_unreachable||0)>0||hostsWithErrors>0||(updates.unknown||0)>0,generated_at:report.generated_at,artifact,summary:report.summary,discovery:report.discovery,devices:devices.map(d=>({hostname:d.hostname,aliases:d.aliases,user:d.user,platform:d.platform,docker_version:d.docker_version,container_count:d.inventory?.summary?.containers||0,running_count:d.inventory?.summary?.container_states?.running||0,updates_available:d.inventory?.summary?.updates_available||0,inventory_errors:d.inventory?.errors||[]})),unreachable_targets:(discovery.targets||[]).filter(t=>!t.ssh_reachable).map(t=>({alias:t.alias,effective:t.effective,key_auth_configured:t.key_auth_configured,failure_kind:t.failure_kind,error:t.error}))};
+}
+```
diff --git a/docs/snippets/homelab-ssh-targets.md b/docs/snippets/homelab-ssh-targets.md
new file mode 100644
index 000000000..8233ae70d
--- /dev/null
+++ b/docs/snippets/homelab-ssh-targets.md
@@ -0,0 +1,101 @@
+---
+name: homelab-ssh-targets
+title: "Homelab SSH Targets"
+created: "2026-09-16"
+updated: "2026-09-16"
+description: Discover concrete SSH aliases, effective key-auth configuration, reachability, and remote host capabilities through the macpoo Claude MCP control plane
+tags: [homelab, ssh, discovery, readonly]
+tools:
+  - claude-macpoo::Bash
+  - claude-macpoo::Read
+inputs:
+  ssh_config:
+    type: string
+    default: ""
+    required: false
+  exclude_hosts:
+    type: array
+    default: ["github.com", "orb"]
+    required: false
+  extra_hosts:
+    type: array
+    default: []
+    required: false
+  connect_timeout_seconds:
+    type: integer
+    default: 4
+    required: false
+  command_timeout_ms:
+    type: integer
+    default: 20000
+    required: false
+---
+
+# Homelab SSH Targets
+
+Reusable read-only discovery primitive for homelab snippets. It uses the declared `claude-macpoo` control plane, parses concrete SSH aliases, expands non-glob includes, checks effective key-auth configuration with `ssh -G`, and probes reachable hosts using public-key-only authentication. Independent target checks fan out concurrently.
+
+`include_glob_skipped` warnings are explicit because wildcard Include expansion is intentionally left to a future filesystem-aware parser rather than guessed.
+
+```js
+async (o = {}) => {
+  const input = {
+    ssh_config: o.ssh_config ?? "",
+    exclude_hosts: Array.isArray(o.exclude_hosts) ? o.exclude_hosts : ["github.com", "orb"],
+    extra_hosts: Array.isArray(o.extra_hosts) ? o.extra_hosts : [],
+    connect_timeout_seconds: Math.max(1, Math.min(30, Number(o.connect_timeout_seconds ?? 4))),
+    command_timeout_ms: Math.max(5000, Math.min(60000, Number(o.command_timeout_ms ?? 20000)))
+  };
+  const quote = v => "'" + String(v).split("'").join("'\"'\"'") + "'";
+  const text = v => typeof v === "string" ? v : typeof v?.stdout === "string" ? v.stdout : typeof v?.file?.content === "string" ? v.file.content : Array.isArray(v?.content) ? v.content.map(x => x?.text || "").join("\n") : "";
+  const err = e => { const s = String(e ?? ""), m = "Original tool error:", i = s.indexOf(m); return (i >= 0 ? s.slice(i + m.length) : s).trim().slice(0, 1200); };
+  const kind = s => { s = String(s || "").toLowerCase(); if (s.includes("permission denied")) return "auth_failed"; if (s.includes("timed out") || s.includes("timeout")) return "timeout"; if (s.includes("refused")) return "connection_refused"; if (s.includes("no route") || s.includes("network is unreachable")) return "network_unreachable"; if (s.includes("resolve hostname") || s.includes("name or service not known")) return "dns_failed"; if (s.includes("host key verification failed")) return "host_key_failed"; return "other"; };
+  const fanout = async (items, fn) => { const r = await codemode.batch(items.map(x => () => fn(x))), out = new Array(items.length); for (const x of r.ok || []) out[x.i] = x.value; for (const x of r.failed || []) out[x.i] = { ok:false, error:err(x.error) }; return out; };
+
+  const bashTool = { id:"claude-macpoo::Bash", namespace:"claude-macpoo" };
+  const readTool = { id:"claude-macpoo::Read" };
+  const identity = text(await callTool(bashTool.id, { command:"hostname; whoami; uname -s; pwd; printenv HOME; command -v ssh || true", timeout:input.command_timeout_ms })).split("\n").map(x => x.trim());
+  const controller = { upstream:bashTool.namespace, bash_tool_id:bashTool.id, read_tool_id:readTool.id, hostname:identity[0] || null, user:identity[1] || null, platform:identity[2] || null, cwd:identity[3] || null, home:identity[4] || null, ssh_path:identity[5] || null };
+  if (!controller.home || !controller.ssh_path) throw new Error("Selected Claude MCP controller is missing HOME or ssh");
+
+  const root = input.ssh_config || controller.home + "/.ssh/config", queue = [root], seen = new Set(), aliases = new Map(), warnings = [];
+  const resolve = (p, from) => p.startsWith("~/") ? controller.home + p.slice(1) : p.startsWith("/") ? p : from.slice(0, Math.max(0, from.lastIndexOf("/")) + 1) + p;
+  while (queue.length && seen.size < 16) {
+    const path = queue.shift(); if (!path || seen.has(path)) continue; seen.add(path);
+    let body; try { body = text(await callTool(readTool.id, { file_path:path })); } catch (e) { warnings.push({type:"config_read_failed",path,error:err(e)}); continue; }
+    for (const raw of body.split("\n")) {
+      const line = raw.trim(); if (!line || line.startsWith("#")) continue;
+      const inc = line.match(/^Include\s+(.+)$/i);
+      if (inc) { for (const token of inc[1].trim().split(/\s+/)) { if (token.includes("*") || token.includes("?") || token.includes("[")) warnings.push({type:"include_glob_skipped",source:path,include:token}); else queue.push(resolve(token,path)); } continue; }
+      const host = line.match(/^Host\s+(.+)$/i); if (!host) continue;
+      for (const alias of host[1].trim().split(/\s+/)) if (alias && !alias.startsWith("!") && !alias.includes("*") && !alias.includes("?") && !alias.includes("[") && !input.exclude_hosts.includes(alias)) { if (!aliases.has(alias)) aliases.set(alias,{alias,sources:[]}); aliases.get(alias).sources.push(path); }
+    }
+  }
+  for (const raw of input.extra_hosts) { const alias = String(raw || "").trim(); if (alias && !input.exclude_hosts.includes(alias) && !aliases.has(alias)) aliases.set(alias,{alias,sources:["input.extra_hosts"]}); }
+
+  const configured = await fanout(Array.from(aliases.values()), async target => {
+    try {
+      const effective = {hostname:null,user:null,port:22,identity_files:[],identity_agent:null};
+      for (const line of text(await callTool(bashTool.id,{command:"ssh -G " + quote(target.alias),timeout:input.command_timeout_ms})).split("\n")) { const n=line.indexOf(" "); if (n<1) continue; const k=line.slice(0,n).toLowerCase(), v=line.slice(n+1).trim(); if(k==="hostname")effective.hostname=v; else if(k==="user")effective.user=v; else if(k==="port")effective.port=Number(v)||22; else if(k==="identityfile")effective.identity_files.push(v); else if(k==="identityagent")effective.identity_agent=v; }
+      return {...target,ok:true,effective,key_auth_configured:effective.identity_files.length>0 || Boolean(effective.identity_agent && effective.identity_agent!=="none")};
+    } catch(e) { return {...target,ok:false,key_auth_configured:false,error:err(e)}; }
+  });
+  const opts = ["-o BatchMode=yes","-o NumberOfPasswordPrompts=0","-o PreferredAuthentications=publickey","-o PasswordAuthentication=no","-o KbdInteractiveAuthentication=no","-o ConnectionAttempts=1","-o ConnectTimeout="+input.connect_timeout_seconds].join(" ");
+  const targets = await fanout(configured, async target => {
+    if (!target.ok) return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:"config_failed"};
+    try {
+      const probe = "hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true";
+      const lines = text(await callTool(bashTool.id,{command:"ssh "+opts+" "+quote(target.alias)+" "+quote(probe),timeout:Math.min(input.command_timeout_ms,12000)})).split("\n").map(x=>x.trim());
+      if (!lines[0]) return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:"empty_probe_response",error:"empty_probe_response"};
+      return {...target,ssh_reachable:true,key_auth_working:true,remote:{hostname:lines[0]||null,user:lines[1]||null,platform:lines[2]||null,docker_path:lines[3]||null,docker_version:lines[4]||null,timeout_path:lines[5]||null}};
+    } catch(e) { const message=err(e); return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:kind(message),error:message}; }
+  });
+  return {
+    schema_version:"labby.homelab.ssh_targets.v1",
+    ok:true,
+    controller:{...controller,ssh_config:root},
+    discovery:{parsed_config_files:Array.from(seen),warnings,configured_aliases:targets.length,key_auth_configured:targets.filter(x=>x.key_auth_configured).length,key_auth_working:targets.filter(x=>x.key_auth_working).length,ssh_unreachable:targets.filter(x=>!x.ssh_reachable).length},
+    targets
+  };
+}
+```
diff --git a/plugins/labby/skills/using-labby/references/code-mode.md b/plugins/labby/skills/using-labby/references/code-mode.md
index 99ad18210..89722eea4 100644
--- a/plugins/labby/skills/using-labby/references/code-mode.md
+++ b/plugins/labby/skills/using-labby/references/code-mode.md
@@ -302,7 +302,7 @@ enabled = true
 trace_params = true
 result_shape_policy = "off"
 timeout_ms = 30000
-max_source_bytes = 131072
+max_source_bytes = 1048576
 max_response_bytes = 24576
 max_response_tokens = 6000
 token_estimate_divisor = 4
diff --git a/plugins/labby/skills/using-labby/references/config-reference.md b/plugins/labby/skills/using-labby/references/config-reference.md
index cf16b1940..4f5f8cf3c 100644
--- a/plugins/labby/skills/using-labby/references/config-reference.md
+++ b/plugins/labby/skills/using-labby/references/config-reference.md
@@ -38,7 +38,7 @@ enabled = true
 trace_params = true
 result_shape_policy = "off"      # off | truncate
 timeout_ms = 30000
-max_source_bytes = 131072
+max_source_bytes = 1048576
 max_response_bytes = 24576
 max_response_tokens = 6000
 token_estimate_divisor = 4

From dcb4e9f745624e659ebe11871beb917e76ccb056 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:43:51 -0400
Subject: [PATCH 02/16] fix: restore complete crates/labby/src/config.rs

---
 crates/labby/src/config.rs | 2987 +++++++++++++++++++++++++++++++++++-
 1 file changed, 2986 insertions(+), 1 deletion(-)

diff --git a/crates/labby/src/config.rs b/crates/labby/src/config.rs
index 90aea6458..9592c3c73 100644
--- a/crates/labby/src/config.rs
+++ b/crates/labby/src/config.rs
@@ -2301,4 +2301,2989 @@ fn prune_config_backups(parent: &Path, target: &Path) -> Result<usize> {
         .map(|entry| {
             let entry = entry?;
             let path = entry.path();
-            let metadata = entry
\ No newline at end of file
+            let metadata = entry
+                .metadata()
+                .with_context(|| format!("inspect config backup {}", path.display()))?;
+            let modified = metadata
+                .modified()
+                .with_context(|| format!("inspect config backup {}", path.display()))?;
+            Ok(ConfigBackupCandidate {
+                path,
+                modified,
+                bytes: metadata.len(),
+            })
+        })
+        .collect::<Result<Vec<_>>>()?;
+    let removals = select_config_backups_to_prune(
+        backups,
+        std::time::SystemTime::now(),
+        ConfigBackupRetention {
+            max_count: CONFIG_BACKUP_RETENTION,
+            max_age: CONFIG_BACKUP_MAX_AGE,
+            max_bytes: CONFIG_BACKUP_MAX_BYTES,
+        },
+    );
+    for backup in &removals {
+        std::fs::remove_file(backup)
+            .with_context(|| format!("remove old config backup {}", backup.display()))?;
+    }
+    Ok(removals.len())
+}
+
+fn select_config_backups_to_prune(
+    mut backups: Vec<ConfigBackupCandidate>,
+    now: std::time::SystemTime,
+    retention: ConfigBackupRetention,
+) -> Vec<PathBuf> {
+    backups.sort_by(|left, right| {
+        left.modified
+            .cmp(&right.modified)
+            .then_with(|| left.path.cmp(&right.path))
+    });
+    let Some(newest) = backups.last().map(|candidate| candidate.path.clone()) else {
+        return Vec::new();
+    };
+    let mut retained_count = backups.len();
+    let mut retained_bytes = backups.iter().fold(0_u64, |total, candidate| {
+        total.saturating_add(candidate.bytes)
+    });
+    let mut removals = Vec::new();
+    for candidate in backups {
+        if candidate.path == newest {
+            continue;
+        }
+        let expired = now
+            .duration_since(candidate.modified)
+            .is_ok_and(|age| age > retention.max_age);
+        let over_count = retained_count > retention.max_count.max(1);
+        let over_bytes = retained_bytes > retention.max_bytes;
+        if expired || over_count || over_bytes {
+            retained_count = retained_count.saturating_sub(1);
+            retained_bytes = retained_bytes.saturating_sub(candidate.bytes);
+            removals.push(candidate.path);
+        }
+    }
+    removals
+}
+
+fn backup_config_file(path: &Path, raw: &str) -> Result<PathBuf> {
+    let nanos = std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .map_or(0, |duration| duration.as_nanos());
+    let pid = std::process::id();
+    for _ in 0..10 {
+        let counter = CONFIG_BACKUP_COUNTER.fetch_add(1, Ordering::Relaxed);
+        let backup = path.with_extension(format!("toml.bak.{nanos}.{pid}.{counter}"));
+        let mut options = OpenOptions::new();
+        options.write(true).create_new(true);
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::OpenOptionsExt;
+            options.mode(0o600);
+        }
+        match options.open(&backup) {
+            Ok(mut file) => {
+                if let Err(error) = secret_files::restrict_secret_file_permissions(&backup) {
+                    drop(file);
+                    drop(std::fs::remove_file(&backup));
+                    return Err(error).with_context(|| {
+                        format!("restrict backup {} before writing", backup.display())
+                    });
+                }
+                file.write_all(raw.as_bytes())
+                    .with_context(|| format!("write backup {}", backup.display()))?;
+                file.sync_all()
+                    .with_context(|| format!("sync backup {}", backup.display()))?;
+                return Ok(backup);
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
+            Err(e) => {
+                return Err(
+                    anyhow::Error::new(e).context(format!("create backup {}", backup.display()))
+                );
+            }
+        }
+    }
+    anyhow::bail!("failed to create unique backup for {}", path.display())
+}
+
+pub(crate) fn config_json_value_for_path(cfg: &LabConfig, path: &str) -> serde_json::Value {
+    match path {
+        "output.format" => serde_json::json!(cfg.output.format),
+        "mcp.transport" => serde_json::json!(cfg.mcp.transport),
+        "mcp.host" => serde_json::json!(cfg.mcp.host),
+        "mcp.port" => serde_json::json!(cfg.mcp.port),
+        "mcp.allowed_hosts" => serde_json::json!(cfg.mcp.allowed_hosts),
+        "log.filter" => serde_json::json!(cfg.log.filter),
+        "log.format" => serde_json::json!(cfg.log.format),
+        "local_logs.retention_days" => {
+            serde_json::json!(
+                cfg.local_logs
+                    .as_ref()
+                    .and_then(|value| value.retention_days)
+            )
+        }
+        "local_logs.max_bytes" => {
+            serde_json::json!(cfg.local_logs.as_ref().and_then(|value| value.max_bytes))
+        }
+        "local_logs.queue_capacity" => {
+            serde_json::json!(
+                cfg.local_logs
+                    .as_ref()
+                    .and_then(|value| value.queue_capacity)
+            )
+        }
+        "local_logs.subscriber_capacity" => {
+            serde_json::json!(
+                cfg.local_logs
+                    .as_ref()
+                    .and_then(|value| value.subscriber_capacity)
+            )
+        }
+        "api.cors_origins" => serde_json::json!(cfg.api.cors_origins),
+        "web.assets_dir" => {
+            serde_json::json!(
+                cfg.web
+                    .assets_dir
+                    .as_ref()
+                    .map(|path| path.display().to_string())
+            )
+        }
+        "workspace.root" => {
+            serde_json::json!(
+                cfg.workspace
+                    .root
+                    .as_ref()
+                    .map(|path| path.display().to_string())
+            )
+        }
+        "public_urls.app" => {
+            serde_json::json!(cfg.public_urls.as_ref().and_then(|value| value.app.clone()))
+        }
+        "public_urls.mcp_gateway" => serde_json::json!(
+            cfg.public_urls
+                .as_ref()
+                .and_then(|value| value.mcp_gateway.clone())
+        ),
+        "services.built_in_upstream_apis_enabled" => {
+            serde_json::json!(cfg.services.built_in_upstream_apis_enabled)
+        }
+        "services.tailscale.tailnet" => serde_json::json!(cfg.services.tailscale.tailnet),
+        "admin.enabled" => serde_json::json!(cfg.admin.enabled),
+        "code_mode.trace_params" => serde_json::json!(cfg.code_mode.trace_params),
+        "code_mode.timeout_ms" => serde_json::json!(cfg.code_mode.timeout_ms),
+        "code_mode.max_source_bytes" => serde_json::json!(cfg.code_mode.max_source_bytes),
+        "code_mode.max_response_bytes" => serde_json::json!(cfg.code_mode.max_response_bytes),
+        "code_mode.max_response_tokens" => serde_json::json!(cfg.code_mode.max_response_tokens),
+        "code_mode.token_estimate_divisor" => {
+            serde_json::json!(cfg.code_mode.token_estimate_divisor)
+        }
+        "code_mode.max_log_entries" => serde_json::json!(cfg.code_mode.max_log_entries),
+        "code_mode.max_log_bytes" => serde_json::json!(cfg.code_mode.max_log_bytes),
+        "gateway_import_mode" => serde_json::json!(cfg.gateway_import_mode),
+        "gateway.extra_stdio_commands" => serde_json::json!(cfg.gateway.extra_stdio_commands),
+        "upstream_request_timeout_ms" => serde_json::json!(cfg.upstream_request_timeout_ms),
+        "upstream_relay_timeout_ms" => serde_json::json!(cfg.upstream_relay_timeout_ms),
+        "web.disable_auth" => serde_json::json!(cfg.web.disable_auth),
+        "auth" => serde_json::to_value(&cfg.auth).unwrap_or(serde_json::Value::Null),
+        "code_mode.enabled" => serde_json::json!(cfg.code_mode.enabled),
+        "gateway.auto_reconnect" => serde_json::json!(cfg.gateway.auto_reconnect),
+        "gateway.disable_spawn_guard" => serde_json::json!(cfg.gateway.disable_spawn_guard),
+        "oauth.machines" => {
+            serde_json::to_value(&cfg.oauth.machines).unwrap_or(serde_json::Value::Null)
+        }
+        "upstream" => serde_json::to_value(&cfg.upstream).unwrap_or(serde_json::Value::Null),
+        "upstream_pending" => {
+            serde_json::to_value(&cfg.upstream_pending).unwrap_or(serde_json::Value::Null)
+        }
+        "upstream_import_tombstones" => {
+            serde_json::to_value(&cfg.upstream_import_tombstones).unwrap_or(serde_json::Value::Null)
+        }
+        "protected_mcp_routes" => {
+            serde_json::to_value(&cfg.protected_mcp_routes).unwrap_or(serde_json::Value::Null)
+        }
+        "virtual_servers" => {
+            serde_json::to_value(&cfg.virtual_servers).unwrap_or(serde_json::Value::Null)
+        }
+        "quarantined_virtual_servers" => serde_json::to_value(&cfg.quarantined_virtual_servers)
+            .unwrap_or(serde_json::Value::Null),
+        _ => serde_json::Value::Null,
+    }
+}
+
+/// Patch the non-secret built-in upstream API preference without rewriting
+/// unrelated TOML content.
+///
+/// This intentionally edits only `[services].built_in_upstream_apis_enabled`.
+/// It preserves comments, unknown keys, and plugin-owned sections that the
+/// full typed `LabConfig` serializer cannot round-trip.
+pub fn patch_built_in_upstream_apis_enabled(path: &Path, enabled: bool) -> Result<LabConfig> {
+    Ok(patch_config_scalars(
+        path,
+        &[ConfigScalarPatch::new(
+            "services.built_in_upstream_apis_enabled",
+            ConfigScalarValue::Bool(enabled),
+        )],
+    )?
+    .config)
+}
+
+#[allow(dead_code)]
+fn config_lock_path(path: &Path) -> PathBuf {
+    let mut lock = path.to_path_buf();
+    let file_name = path
+        .file_name()
+        .and_then(|name| name.to_str())
+        .unwrap_or("config.toml");
+    lock.set_file_name(format!("{file_name}.lock"));
+    lock
+}
+
+/// Names of the variables the process environment already carried when the
+/// first `load_dotenv` ran. dotenvy never overrides an existing variable, so
+/// these came from outside `.env` (a service manager, a container spec, the
+/// shell) and win over the file for the lifetime of the process.
+static PROCESS_ENV_KEYS_BEFORE_DOTENV: OnceLock<std::collections::BTreeSet<String>> =
+    OnceLock::new();
+
+/// Whether `key` was set in the process environment before `.env` was loaded,
+/// so an edit to `.env` cannot change its effective value. False until
+/// `load_dotenv` has run.
+#[must_use]
+pub fn env_key_set_outside_dotenv(key: &str) -> bool {
+    PROCESS_ENV_KEYS_BEFORE_DOTENV
+        .get()
+        .is_some_and(|keys| keys.contains(key))
+}
+
+/// Load `.env` files into the process environment.
+///
+/// Called after `load_toml()` and tracing init. Env vars loaded here
+/// override config.toml values at the point of use (each consumer checks
+/// env first, then falls back to config).
+pub fn load_dotenv() -> Result<()> {
+    // Names only, never values: the settings surface uses this to tell an
+    // externally managed variable from one `.env` supplied.
+    PROCESS_ENV_KEYS_BEFORE_DOTENV.get_or_init(|| {
+        std::env::vars_os()
+            .filter_map(|(key, _)| key.into_string().ok())
+            .collect()
+    });
+    // Candidates are ordered from authoritative installation state to the
+    // implicit development fallback. dotenvy preserves values loaded by an
+    // earlier candidate. An explicit LABBY_HOME excludes the CWD fallback.
+    for env_path in paths::dotenv_candidates()? {
+        if env_path.exists() {
+            dotenvy::from_path(&env_path)
+                .with_context(|| format!("failed to load {}", env_path.display()))?;
+        }
+    }
+
+    Ok(())
+}
+
+/// Load `.env` + `config.toml` in a single call (convenience for tests).
+#[allow(dead_code)]
+pub fn load() -> Result<LabConfig> {
+    let cfg = load_toml(&toml_candidates()?)?;
+    load_dotenv()?;
+    Ok(cfg)
+}
+
+/// Resolve the Code Mode `openapi` provider config from the parsed `[openapi]`
+/// TOML section plus `OPENAPI_<LABEL>_*` env vars.
+///
+/// Non-secret fields come from TOML; credentials (`OPENAPI_<LABEL>_TOKEN` /
+/// `OPENAPI_<LABEL>_API_KEY`) come from `env`. `base_url` is mandatory; reserved
+/// or duplicate labels, a missing/invalid base_url, an invalid spec_url, and an
+/// ambiguous spec source are all hard config errors that fail boot.
+///
+/// `env` is injected (rather than read from the process environment directly) so
+/// tests stay hermetic. In production callers pass a `std::env::var`-backed closure.
+#[cfg(feature = "gateway")]
+pub fn load_openapi_provider_config(
+    section: &OpenApiTomlSection,
+    env: &dyn Fn(&str) -> Option<String>,
+) -> std::result::Result<labby_openapi::OpenApiProviderConfig, ConfigError> {
+    use labby_openapi::{OpenApiCredential, OpenApiProviderConfig, OpenApiSpecConfig, SpecSource};
+
+    let mut specs = Vec::new();
+    let mut seen = std::collections::HashSet::new();
+    for raw in &section.specs {
+        let label = raw.label.trim().to_string();
+        // The wire dispatch key is `openapi::<label>.<operationId>`, split on the
+        // first `.` (operationIds may themselves contain `.`). A label containing
+        // `.`, `:`, or whitespace would misroute that split, so restrict labels to
+        // an unambiguous charset. Also keeps the `OPENAPI_<LABEL>_*` credential
+        // env-var lookup well-formed.
+        if label.is_empty()
+            || !label
+                .chars()
+                .all(|c| c.is_ascii_alphanumeric() || c == '_' || c == '-')
+        {
+            return Err(ConfigError::InvalidLabel { label });
+        }
+        if labby_openapi::RESERVED_NAMESPACES.contains(&label.as_str()) {
+            return Err(ConfigError::ReservedLabel { label });
+        }
+        if !seen.insert(label.clone()) {
+            return Err(ConfigError::DuplicateLabel { label });
+        }
+        let base_url: url::Url = raw
+            .base_url
+            .as_deref()
+            .map(str::trim)
+            .filter(|s| !s.is_empty())
+            .ok_or_else(|| ConfigError::MissingBaseUrl {
+                label: label.clone(),
+            })?
+            .parse()
+            .map_err(|_| ConfigError::InvalidBaseUrl {
+                label: label.clone(),
+            })?;
+
+        let upper = label.to_uppercase();
+        let credential = env(&format!("OPENAPI_{upper}_TOKEN"))
+            .filter(|t| !t.is_empty())
+            .map(OpenApiCredential::BearerToken)
+            .or_else(|| {
+                env(&format!("OPENAPI_{upper}_API_KEY"))
+                    .filter(|k| !k.is_empty())
+                    .map(|value| OpenApiCredential::ApiKey {
+                        header: raw
+                            .api_key_header
+                            .clone()
+                            .filter(|h| !h.trim().is_empty())
+                            .unwrap_or_else(|| "X-API-Key".into()),
+                        value,
+                    })
+            });
+
+        let spec_source = match (
+            raw.spec_url
+                .as_deref()
+                .map(str::trim)
+                .filter(|s| !s.is_empty()),
+            raw.spec_path
+                .as_deref()
+                .map(str::trim)
+                .filter(|s| !s.is_empty()),
+        ) {
+            (Some(u), None) => {
+                SpecSource::Url(u.parse().map_err(|_| ConfigError::InvalidSpecUrl {
+                    label: label.clone(),
+                })?)
+            }
+            (None, Some(p)) => SpecSource::Path(p.into()),
+            _ => {
+                return Err(ConfigError::SpecSourceAmbiguous {
+                    label: label.clone(),
+                });
+            }
+        };
+
+        specs.push(OpenApiSpecConfig {
+            label,
+            spec_source,
+            base_url,
+            allowed_operations: raw.allowed_operations.clone(),
+            credential,
+        });
+    }
+    Ok(OpenApiProviderConfig { specs })
+}
+
+/// A string value that redacts itself in `Debug` and `Display` output.
+///
+/// Use for secret env values (`API_KEY`, `TOKEN`, `PASSWORD`) so they
+/// never leak through `Debug`-printing config structs or tracing fields.
+#[allow(dead_code)]
+#[derive(Clone, Deserialize, PartialEq, Eq)]
+pub struct Secret(String);
+
+impl Secret {
+    #[must_use]
+    pub const fn new(value: String) -> Self {
+        Self(value)
+    }
+
+    #[must_use]
+    #[allow(dead_code)]
+    pub fn expose(&self) -> &str {
+        &self.0
+    }
+}
+
+impl std::fmt::Debug for Secret {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("[REDACTED]")
+    }
+}
+
+impl std::fmt::Display for Secret {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str("[REDACTED]")
+    }
+}
+
+impl Serialize for Secret {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
+        serializer.serialize_str("***REDACTED***")
+    }
+}
+
+/// Value from an instance env var — either plain text or a secret.
+///
+/// Always constructed programmatically via the private `scan_instances_from` helper; never
+/// deserialized from JSON. `Deserialize` is intentionally omitted — `Secret`
+/// serializes as `"***REDACTED***"` (a plain string), so an `#[serde(untagged)]`
+/// impl would silently pick `Plain` for every value, bypassing redaction.
+#[allow(dead_code)]
+#[derive(Debug, Clone, Serialize)]
+pub enum InstanceValue {
+    Plain(String),
+    Redacted(Secret),
+}
+
+impl InstanceValue {
+    #[must_use]
+    #[allow(dead_code)]
+    pub fn expose(&self) -> &str {
+        match self {
+            Self::Plain(s) => s,
+            Self::Redacted(s) => s.expose(),
+        }
+    }
+}
+
+/// Suffixes that carry secret values and must be wrapped in [`Secret`].
+#[allow(dead_code)]
+const SECRET_SUFFIXES: &[&str] = &["API_KEY", "TOKEN", "PASSWORD"];
+
+/// Parse multi-instance env vars for a given service prefix.
+///
+/// Returns a map from instance label (`"default"` or `"<label>"`) to the
+/// set of `(suffix, value)` pairs. Example: for prefix `UNRAID`, env vars
+/// `UNRAID_URL`, `UNRAID_API_KEY`, `UNRAID_NODE2_URL`, `UNRAID_NODE2_API_KEY`
+/// yield two entries keyed `"default"` and `"node2"`.
+///
+/// Suffixes are matched longest-first to avoid collisions when a label
+/// contains a shorter suffix as a substring.
+#[must_use]
+#[allow(dead_code)]
+pub fn scan_instances(prefix: &str) -> HashMap<String, HashMap<String, InstanceValue>> {
+    scan_instances_from(prefix, std::env::vars())
+}
+
+/// Inner implementation testable without mutating process env.
+fn scan_instances_from(
+    prefix: &str,
+    vars: impl Iterator<Item = (String, String)>,
+) -> HashMap<String, HashMap<String, InstanceValue>> {
+    let mut out: HashMap<String, HashMap<String, InstanceValue>> = HashMap::new();
+
+    let mut known_suffixes = ["URL", "API_KEY", "TOKEN", "USERNAME", "PASSWORD"];
+    known_suffixes.sort_by_key(|s| std::cmp::Reverse(s.len()));
+
+    let prefix_under = format!("{prefix}_");
+
+    for (key, value) in vars {
+        let Some(rest) = key.strip_prefix(&prefix_under) else {
+            continue;
+        };
+
+        for suffix in &known_suffixes {
+            let wrap = |v: String| {
+                if SECRET_SUFFIXES.contains(suffix) {
+                    InstanceValue::Redacted(Secret::new(v))
+                } else {
+                    InstanceValue::Plain(v)
+                }
+            };
+
+            if rest == *suffix {
+                out.entry("default".to_string())
+                    .or_default()
+                    .insert((*suffix).to_string(), wrap(value.clone()));
+                break;
+            }
+            if let Some(label) = rest.strip_suffix(&format!("_{suffix}"))
+                && !label.is_empty()
+            {
+                out.entry(label.to_ascii_lowercase())
+                    .or_default()
+                    .insert((*suffix).to_string(), wrap(value.clone()));
+                break;
+            }
+        }
+    }
+
+    out
+}
+
+#[cfg(test)]
+#[allow(clippy::panic)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn owned_section_typos_fail_while_foreign_top_level_extensions_survive() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(
+            &path,
+            "[mcp]\nporrt = 9876\n\n[external_extension]\nmode = \"custom\"\n",
+        )
+        .unwrap();
+
+        let error = load_toml(std::slice::from_ref(&path)).unwrap_err();
+        let detail = format!("{error:#}");
+        assert!(detail.contains("porrt"), "{detail}");
+
+        std::fs::write(&path, "[external_extension]\nmode = \"custom\"\n").unwrap();
+        assert!(load_toml(&[path]).is_ok());
+    }
+
+    #[test]
+    fn inherited_app_surface_sections_name_only_the_absent_tables() {
+        // An existing config.toml written before Code Mode and the Labby MCP
+        // Apps defaulted on inherits those defaults silently unless startup
+        // names them. Only genuinely absent sections are reported.
+        assert_eq!(
+            inherited_app_surface_sections(""),
+            vec!["code_mode", "mcp_apps"]
+        );
+        assert_eq!(
+            inherited_app_surface_sections("[mcp]\nport = 8765\n"),
+            vec!["code_mode", "mcp_apps"]
+        );
+        assert_eq!(
+            inherited_app_surface_sections("[code_mode]\nenabled = false\n"),
+            vec!["mcp_apps"]
+        );
+        assert_eq!(
+            inherited_app_surface_sections(
+                "[code_mode]\nenabled = true\n[mcp_apps]\nmanager = false\n"
+            ),
+            Vec::<&str>::new()
+        );
+        // Unparseable input is the loader's error to report, not this hint's.
+        assert_eq!(
+            inherited_app_surface_sections("mcp = \"bad"),
+            Vec::<&str>::new()
+        );
+    }
+
+    #[test]
+    fn top_level_scalar_typos_fail_but_named_extension_tables_survive() {
+        for typo in ["mcpp = 1\n", "config_verzion = 1\n"] {
+            let error = validate_top_level_extension_boundary(typo).unwrap_err();
+            assert!(error.to_string().contains("unknown top-level scalar"));
+        }
+        validate_top_level_extension_boundary("[vendor.example]\nenabled = true\n").unwrap();
+    }
+
+    #[test]
+    fn missing_config_version_migrates_to_current_and_future_versions_fail() {
+        let legacy: LabConfig = toml::from_str("[mcp]\nport = 9876\n").unwrap();
+        assert_eq!(legacy.config_version, CURRENT_CONFIG_VERSION);
+        legacy.validate().unwrap();
+
+        let future: LabConfig = toml::from_str("config_version = 999\n").unwrap();
+        let error = future.validate().unwrap_err();
+        assert!(error.to_string().contains("config_version 999"));
+    }
+
+    #[test]
+    fn patching_legacy_config_persists_the_migrated_format_version() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "[mcp]\nport = 8765\n").unwrap();
+
+        patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(9876),
+            )],
+        )
+        .unwrap();
+
+        let persisted = std::fs::read_to_string(path).unwrap();
+        assert!(persisted.contains("config_version = 1"), "{persisted}");
+    }
+
+    #[test]
+    fn config_mutations_retain_only_the_ten_newest_backups() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "config_version = 1\n[mcp]\nport = 8765\n").unwrap();
+        for port in 8800..8815 {
+            patch_config_scalars(
+                &path,
+                &[ConfigScalarPatch::new(
+                    "mcp.port",
+                    ConfigScalarValue::I64(port),
+                )],
+            )
+            .unwrap();
+        }
+
+        let backups = std::fs::read_dir(dir.path())
+            .unwrap()
+            .filter_map(Result::ok)
+            .filter(|entry| entry.file_name().to_string_lossy().contains(".toml.bak."))
+            .count();
+        assert_eq!(backups, 10);
+    }
+
+    #[test]
+    fn committed_config_reports_post_commit_maintenance_failure_as_warning() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "config_version = 1\n[mcp]\nport = 8765\n").unwrap();
+        std::fs::write(
+            dir.path().join(".labby-test-config-maintenance-failure"),
+            b"inject",
+        )
+        .unwrap();
+
+        let outcome = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(9876),
+            )],
+        )
+        .expect("durable commit must not be reported as failed");
+
+        assert_eq!(outcome.config.mcp.port, Some(9876));
+        assert!(
+            std::fs::read_to_string(&path)
+                .unwrap()
+                .contains("port = 9876")
+        );
+        assert!(
+            outcome
+                .maintenance_warning
+                .as_deref()
+                .is_some_and(|warning| warning.contains("configuration was committed"))
+        );
+        assert!(outcome.backup_path.is_some());
+    }
+
+    #[test]
+    fn backup_retention_enforces_age_and_bytes_without_pruning_newest() {
+        let now = std::time::UNIX_EPOCH + Duration::from_secs(10_000);
+        let candidates = vec![
+            ConfigBackupCandidate::fixture("old", 100, now - Duration::from_secs(5_000)),
+            ConfigBackupCandidate::fixture("large", 900, now - Duration::from_secs(20)),
+            ConfigBackupCandidate::fixture("newest", 900, now - Duration::from_secs(10)),
+        ];
+
+        let pruned = select_config_backups_to_prune(
+            candidates,
+            now,
+            ConfigBackupRetention {
+                max_count: 10,
+                max_age: Duration::from_secs(1_000),
+                max_bytes: 500,
+            },
+        );
+
+        assert_eq!(pruned, vec![PathBuf::from("old"), PathBuf::from("large")]);
+    }
+
+    #[test]
+    fn backup_retention_is_deterministic_for_equal_timestamps() {
+        let now = std::time::UNIX_EPOCH + Duration::from_secs(10_000);
+        let modified = now - Duration::from_secs(10);
+        let candidates = vec![
+            ConfigBackupCandidate::fixture("c", 1, modified),
+            ConfigBackupCandidate::fixture("a", 1, modified),
+            ConfigBackupCandidate::fixture("b", 1, modified),
+        ];
+
+        let pruned = select_config_backups_to_prune(
+            candidates,
+            now,
+            ConfigBackupRetention {
+                max_count: 2,
+                max_age: Duration::MAX,
+                max_bytes: u64::MAX,
+            },
+        );
+
+        assert_eq!(pruned, vec![PathBuf::from("a")]);
+    }
+
+    fn resolve_oauth_fixture(config: &AuthFileConfig) -> auth_config::AuthConfig {
+        resolve_auth_with_env(
+            Some(config),
+            [("LABBY_TOKEN_ENCRYPTION_KEY".to_string(), "11".repeat(32))],
+        )
+        .expect("OAuth fixture should resolve")
+    }
+
+    /// `install_resolved_preferences` must pick up config.toml values when no
+    /// overriding env var is set. This test does not touch process env, so
+    /// it's safe under both nextest's per-process isolation and cargo test's
+    /// threaded model, unlike a test that would need to mutate `std::env`.
+    #[test]
+    fn install_resolved_preferences_picks_up_config_toml_values() {
+        let mut config = LabConfig::default();
+        config.mcp.show_all = Some(true);
+        config.api.dev_mode = Some(true);
+        config.api.protected_mcp_connect_timeout_secs = Some(42);
+        config.mcp.catalog_notification_timeout_ms = Some(2_500);
+        config.code_mode.widget_callbacks = Some(true);
+        config.output.symbols = Some("ascii".to_string());
+
+        install_resolved_preferences(&config);
+
+        assert!(resolved_show_all(), "mcp.show_all should resolve true");
+        assert!(resolved_dev_mode(), "api.dev_mode should resolve true");
+        assert!(
+            resolved_widget_callbacks_enabled(),
+            "code_mode.widget_callbacks should resolve true"
+        );
+        assert_eq!(resolved_symbols().as_deref(), Some("ascii"));
+        assert_eq!(resolved_protected_mcp_connect_timeout_secs(), Some(42));
+        assert_eq!(
+            resolved_catalog_notification_timeout(),
+            Duration::from_millis(2_500)
+        );
+
+        // Restore defaults so this test doesn't leak state into whichever
+        // test the process/thread runs next (matches the existing
+        // process_code_mode_enabled restore-after-test convention below).
+        install_resolved_preferences(&LabConfig::default());
+        assert!(!resolved_show_all());
+        assert!(!resolved_dev_mode());
+        assert!(!resolved_widget_callbacks_enabled());
+        assert_eq!(resolved_symbols(), None);
+        assert_eq!(resolved_protected_mcp_connect_timeout_secs(), None);
+        assert_eq!(
+            resolved_catalog_notification_timeout(),
+            Duration::from_millis(DEFAULT_CATALOG_NOTIFICATION_TIMEOUT_MS)
+        );
+    }
+
+    fn parse_normalized_config(toml: &str) -> LabConfig {
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes().expect("normalize");
+        cfg
+    }
+
+    #[test]
+    fn artifact_authority_urls_have_separate_config_contracts() {
+        let cfg = parse_normalized_config(
+            r#"
+[[artifacts.sources]]
+id = "primary"
+kind = "depot"
+endpoint = "https://depot.example/api/artifacts/exact"
+control_plane_url = "https://depot.example"
+pinned_addresses = ["8.8.8.8"]
+bearer_token_env = "LABBY_DEPOT_TOKEN"
+"#,
+        );
+        let source = &cfg.artifacts.sources[0];
+        assert_eq!(source.endpoint, "https://depot.example/api/artifacts/exact");
+        assert_eq!(
+            source.control_plane_url.as_deref(),
+            Some("https://depot.example")
+        );
+        assert_eq!(
+            source.bearer_token_env.as_deref(),
+            Some("LABBY_DEPOT_TOKEN")
+        );
+    }
+
+    #[cfg(feature = "gateway")]
+    fn openapi_section(toml: &str) -> OpenApiTomlSection {
+        toml::from_str::<LabConfig>(toml).expect("parse").openapi
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_reserved_label_rejected() {
+        let toml = r#"[[openapi.specs]]
+label = "git"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+allowed_operations = ["getUser"]"#;
+        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
+        assert!(matches!(err, ConfigError::ReservedLabel { ref label } if label == "git"));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_dotted_label_rejected() {
+        // A label containing `.` would misroute the `openapi::<label>.<operationId>`
+        // dispatch split — reject it at config load.
+        let toml = r#"[[openapi.specs]]
+label = "ven.dor"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+allowed_operations = ["getUser"]"#;
+        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
+        assert!(matches!(err, ConfigError::InvalidLabel { ref label } if label == "ven.dor"));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_missing_base_url_rejected() {
+        let toml = r#"[[openapi.specs]]
+label = "vendor"
+spec_url = "https://api.example.com/openapi.json"
+allowed_operations = ["getUser"]"#;
+        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
+        assert!(matches!(err, ConfigError::MissingBaseUrl { .. }));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_duplicate_label_rejected() {
+        let toml = r#"[[openapi.specs]]
+label = "vendor"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+
+[[openapi.specs]]
+label = "vendor"
+base_url = "https://api2.example.com"
+spec_url = "https://api2.example.com/openapi.json""#;
+        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
+        assert!(matches!(err, ConfigError::DuplicateLabel { ref label } if label == "vendor"));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_ambiguous_spec_source_rejected() {
+        let toml = r#"[[openapi.specs]]
+label = "vendor"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+spec_path = "/tmp/openapi.json""#;
+        let err = load_openapi_provider_config(&openapi_section(toml), &|_| None).unwrap_err();
+        assert!(matches!(err, ConfigError::SpecSourceAmbiguous { .. }));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_credential_read_from_env_not_toml() {
+        let toml = r#"[[openapi.specs]]
+label = "vendor"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+allowed_operations = ["getUser"]"#;
+        let env = |k: &str| (k == "OPENAPI_VENDOR_TOKEN").then(|| "tok-123".to_string());
+        let cfg = load_openapi_provider_config(&openapi_section(toml), &env).unwrap();
+        assert!(cfg.specs[0].credential.is_some());
+        // Credential must NEVER round-trip through the TOML struct.
+        assert!(!format!("{:?}", cfg.specs[0]).contains("tok-123"));
+    }
+
+    #[cfg(feature = "gateway")]
+    #[test]
+    fn openapi_api_key_uses_configured_header() {
+        let toml = r#"[[openapi.specs]]
+label = "vendor"
+base_url = "https://api.example.com"
+spec_url = "https://api.example.com/openapi.json"
+api_key_header = "X-Custom-Key""#;
+        let env = |k: &str| (k == "OPENAPI_VENDOR_API_KEY").then(|| "sk-abc".to_string());
+        let cfg = load_openapi_provider_config(&openapi_section(toml), &env).unwrap();
+        match &cfg.specs[0].credential {
+            Some(labby_openapi::OpenApiCredential::ApiKey { header, .. }) => {
+                assert_eq!(header, "X-Custom-Key");
+            }
+            _ => panic!("expected ApiKey credential"),
+        }
+    }
+
+    fn vars<'a>(pairs: &'a [(&'a str, &'a str)]) -> impl Iterator<Item = (String, String)> + 'a {
+        pairs
+            .iter()
+            .map(|(k, v)| ((*k).to_string(), (*v).to_string()))
+    }
+
+    #[test]
+    fn service_preferences_default_enable_upstream_apis() {
+        let cfg = toml::from_str::<LabConfig>("").expect("empty config should parse");
+        assert!(cfg.services.built_in_upstream_apis_enabled);
+    }
+
+    #[test]
+    fn service_preferences_can_disable_upstream_apis() {
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+            [services]
+            built_in_upstream_apis_enabled = false
+            ",
+        )
+        .expect("services config should parse");
+
+        assert!(!cfg.services.built_in_upstream_apis_enabled);
+    }
+
+    #[test]
+    fn patch_built_in_upstream_apis_preserves_comments_and_unknown_sections() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(
+            &path,
+            r#"# operator note
+[services]
+# keep this comment
+built_in_upstream_apis_enabled = true
+
+[plugin_owned]
+future = "keep"
+"#,
+        )
+        .unwrap();
+
+        let cfg = patch_built_in_upstream_apis_enabled(&path, false).unwrap();
+        assert!(!cfg.services.built_in_upstream_apis_enabled);
+        let raw = std::fs::read_to_string(&path).unwrap();
+        assert!(raw.contains("# operator note"));
+        assert!(raw.contains("# keep this comment"));
+        assert!(raw.contains("[plugin_owned]"));
+        assert!(raw.contains("future = \"keep\""));
+        assert!(raw.contains("built_in_upstream_apis_enabled = false"));
+    }
+
+    #[test]
+    fn patch_config_scalars_rejects_non_table_parent_without_mutating() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "mcp = \"bad\"\n").unwrap();
+        let err = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(8765),
+            )],
+        )
+        .unwrap_err();
+        assert!(
+            format!("{err:#}").contains("not a table"),
+            "unexpected error: {err:#}"
+        );
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), "mcp = \"bad\"\n");
+    }
+
+    #[test]
+    fn patch_config_scalars_updates_inline_table_parent() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(
+            &path,
+            "services = { built_in_upstream_apis_enabled = true }\n",
+        )
+        .unwrap();
+        let outcome = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "services.built_in_upstream_apis_enabled",
+                ConfigScalarValue::Bool(false),
+            )],
+        )
+        .unwrap();
+        assert!(!outcome.config.services.built_in_upstream_apis_enabled);
+        let raw = std::fs::read_to_string(&path).unwrap();
+        assert!(raw.contains("built_in_upstream_apis_enabled = false"));
+    }
+
+    #[test]
+    fn patch_config_scalars_unsets_optional_instead_of_empty_string() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "[mcp]\nport = 8765\n").unwrap();
+        let outcome = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::UnsetOptional,
+            )],
+        )
+        .unwrap();
+        assert_eq!(outcome.config.mcp.port, None);
+        assert!(!std::fs::read_to_string(&path).unwrap().contains("port"));
+    }
+
+    #[test]
+    fn patch_config_scalars_creates_backup_and_preserves_comments() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        std::fs::write(&path, "# keep\n[mcp]\nhost = \"127.0.0.1\"\n").unwrap();
+        let outcome = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(8765),
+            )],
+        )
+        .unwrap();
+        let backup_path = outcome.backup_path.unwrap();
+        assert!(backup_path.is_file());
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            assert_eq!(
+                std::fs::metadata(&backup_path)
+                    .unwrap()
+                    .permissions()
+                    .mode()
+                    & 0o777,
+                0o600
+            );
+            assert_eq!(
+                std::fs::metadata(config_lock_path(&path))
+                    .unwrap()
+                    .permissions()
+                    .mode()
+                    & 0o777,
+                0o600,
+                "the persistent config lock must use the secret-file policy"
+            );
+        }
+        let raw = std::fs::read_to_string(&path).unwrap();
+        assert!(raw.contains("# keep"));
+        assert!(raw.contains("port = 8765"));
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::PermissionsExt;
+            assert_eq!(
+                std::fs::metadata(&path).unwrap().permissions().mode() & 0o777,
+                0o600,
+                "the replacement must not preserve a group/world-readable source mode"
+            );
+        }
+    }
+
+    #[test]
+    fn patch_config_scalars_skips_backup_and_write_for_noop() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        let raw = "[mcp]\nport = 8765\n";
+        std::fs::write(&path, raw).unwrap();
+        let outcome = patch_config_scalars(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(8765),
+            )],
+        )
+        .unwrap();
+        assert_eq!(outcome.backup_path, None);
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), raw);
+    }
+
+    #[test]
+    fn patch_config_scalars_checked_rejects_stale_expected_value() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("config.toml");
+        let raw = "[mcp]\nport = 8765\n";
+        std::fs::write(&path, raw).unwrap();
+        let err = patch_config_scalars_checked(
+            &path,
+            &[ConfigScalarPatch::new(
+                "mcp.port",
+                ConfigScalarValue::I64(8766),
+            )],
+            &[ExpectedConfigScalar::new(
+                "mcp.port",
+                serde_json::json!(9000),
+            )],
+        )
+        .unwrap_err();
+        assert!(
+            format!("{err:#}").contains("changed since it was loaded"),
+            "unexpected error: {err:#}"
+        );
+        assert_eq!(std::fs::read_to_string(&path).unwrap(), raw);
+    }
+
+    #[test]
+    fn resolve_auth_reads_ttls_from_config_toml_fields() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            sqlite_path: None,
+            key_path: None,
+            enable_dynamic_registration: None,
+            bootstrap_secret: Some("bootstrap".to_string()),
+            allowed_client_redirect_uris: Some(vec![
+                "https://callback.example.com/callback/*".to_string(),
+            ]),
+            allowed_email_domains: None,
+            viewer_email_domains: None,
+            viewer_project_id: None,
+            provider: None,
+            authelia_issuer_url: None,
+            authelia_client_id: None,
+            authelia_client_secret: None,
+            authelia_trusted_private_origin: None,
+            authelia_ca_certificate_path: None,
+            google_client_id: Some("client-id".to_string()),
+            google_client_secret: Some("client-secret".to_string()),
+            google_callback_path: Some("/auth/google/callback".to_string()),
+            google_scopes: Some(vec!["openid".to_string(), "email".to_string()]),
+            access_token_ttl_secs: Some(120),
+            refresh_token_ttl_secs: Some(3600),
+            auth_code_ttl_secs: Some(45),
+            admin_email: Some("admin@example.com".to_string()),
+            register_requests_per_minute: Some(5),
+            authorize_requests_per_minute: Some(15),
+            token_requests_per_minute: Some(25),
+            machine_clients: None,
+            enterprise_issuers: None,
+            max_pending_oauth_states: Some(256),
+            codex_issuer_compatibility: Some(true),
+        };
+
+        let resolved = resolve_oauth_fixture(&cfg);
+        assert_eq!(resolved.access_token_ttl.as_secs(), 120);
+        assert_eq!(resolved.refresh_token_ttl.as_secs(), 3600);
+        assert_eq!(resolved.auth_code_ttl.as_secs(), 45);
+        assert_eq!(
+            resolved.allowed_client_redirect_uris,
+            vec!["https://callback.example.com/callback/*".to_string()]
+        );
+        assert_eq!(resolved.register_requests_per_minute, 5);
+        assert_eq!(resolved.authorize_requests_per_minute, 15);
+        assert_eq!(resolved.token_requests_per_minute, 25);
+        assert_eq!(resolved.max_pending_oauth_states, 256);
+        assert!(resolved.codex_issuer_compatibility);
+    }
+
+    fn minimal_oauth_file_config() -> AuthFileConfig {
+        AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            bootstrap_secret: Some("bootstrap".to_string()),
+            google_client_id: Some("client-id".to_string()),
+            google_client_secret: Some("client-secret".to_string()),
+            admin_email: Some("admin@example.com".to_string()),
+            ..Default::default()
+        }
+    }
+
+    #[test]
+    fn oauth_product_enables_dynamic_registration_by_default() {
+        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
+        assert!(resolved.enable_dynamic_registration);
+    }
+
+    #[test]
+    fn oauth_product_allows_explicit_dynamic_registration_disable() {
+        let cfg = minimal_oauth_file_config();
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [
+                (
+                    "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
+                    "false".into(),
+                ),
+                (
+                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
+                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
+                ),
+            ],
+        )
+        .unwrap();
+        assert!(!resolved.enable_dynamic_registration);
+    }
+
+    #[test]
+    fn oauth_product_environment_overrides_file_registration_policy() {
+        let cfg = AuthFileConfig {
+            enable_dynamic_registration: Some(false),
+            ..minimal_oauth_file_config()
+        };
+        assert!(!resolve_oauth_fixture(&cfg).enable_dynamic_registration);
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [
+                (
+                    "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
+                    "true".into(),
+                ),
+                (
+                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
+                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
+                ),
+            ],
+        )
+        .unwrap();
+        assert!(resolved.enable_dynamic_registration);
+    }
+
+    #[test]
+    fn oauth_product_rejects_invalid_dynamic_registration_policy() {
+        let error = resolve_auth_with_env(
+            Some(&minimal_oauth_file_config()),
+            [(
+                "LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION".into(),
+                "maybe".into(),
+            )],
+        )
+        .unwrap_err();
+        assert!(
+            error
+                .to_string()
+                .contains("LABBY_AUTH_ENABLE_DYNAMIC_REGISTRATION")
+        );
+    }
+
+    #[test]
+    fn resolve_auth_accepts_authelia_only_file_configuration() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".into()),
+            public_url: Some("https://lab.example.com/base".into()),
+            provider: Some("authelia".into()),
+            authelia_issuer_url: Some("https://auth.example.com/application/o/labby".into()),
+            authelia_client_id: Some("labby".into()),
+            authelia_client_secret: Some("secret".into()),
+            authelia_ca_certificate_path: Some("/etc/labby/authelia-ca.pem".into()),
+            admin_email: Some("admin@example.com".into()),
+            ..Default::default()
+        };
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [(
+                "LABBY_TOKEN_ENCRYPTION_KEY".into(),
+                "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
+            )],
+        )
+        .unwrap();
+        assert_eq!(
+            resolved.inbound_provider,
+            Some(auth_config::InboundProviderKind::Authelia)
+        );
+        assert_eq!(
+            resolved.authelia.unwrap().ca_certificate_path,
+            Some(PathBuf::from("/etc/labby/authelia-ca.pem"))
+        );
+        assert!(resolved.google.client_id.is_empty());
+    }
+
+    #[test]
+    fn resolve_auth_authelia_environment_overrides_file_configuration() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".into()),
+            public_url: Some("https://lab.example.com".into()),
+            provider: Some("google".into()),
+            google_client_id: Some("legacy".into()),
+            google_client_secret: Some("legacy-secret".into()),
+            admin_email: Some("admin@example.com".into()),
+            ..Default::default()
+        };
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [
+                ("LABBY_AUTH_PROVIDER".into(), "authelia".into()),
+                (
+                    "LABBY_AUTHELIA_ISSUER_URL".into(),
+                    "https://auth.example.com/application/o/labby".into(),
+                ),
+                ("LABBY_AUTHELIA_CLIENT_ID".into(), "labby".into()),
+                (
+                    "LABBY_AUTHELIA_CLIENT_SECRET".into(),
+                    "authelia-secret".into(),
+                ),
+                (
+                    "LABBY_AUTHELIA_CA_CERT_PATH".into(),
+                    "/run/secrets/authelia-ca.pem".into(),
+                ),
+                (
+                    "LABBY_TOKEN_ENCRYPTION_KEY".into(),
+                    "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
+                ),
+            ],
+        )
+        .unwrap();
+        assert_eq!(
+            resolved.inbound_provider,
+            Some(auth_config::InboundProviderKind::Authelia)
+        );
+        let authelia = resolved.authelia.unwrap();
+        assert_eq!(authelia.client_id, "labby");
+        assert_eq!(
+            authelia.ca_certificate_path,
+            Some(PathBuf::from("/run/secrets/authelia-ca.pem"))
+        );
+    }
+
+    #[test]
+    fn doctor_projection_uses_resolved_file_only_authelia_provider() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".into()),
+            public_url: Some("https://lab.example.com".into()),
+            provider: Some("authelia".into()),
+            authelia_issuer_url: Some("https://auth.example.com/application/o/labby".into()),
+            authelia_client_id: Some("labby".into()),
+            authelia_client_secret: Some("secret".into()),
+            admin_email: Some("admin@example.com".into()),
+            ..Default::default()
+        };
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [(
+                "LABBY_TOKEN_ENCRYPTION_KEY".into(),
+                "000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f".into(),
+            )],
+        )
+        .unwrap();
+        let findings = crate::dispatch::doctor::run_auth_checks_with_config(Some(&resolved));
+        let provider = findings
+            .iter()
+            .find(|finding| finding.check == "auth:provider")
+            .unwrap();
+        assert!(matches!(
+            provider.severity,
+            crate::dispatch::doctor::Severity::Ok
+        ));
+        assert!(provider.message.contains("authelia"));
+        assert!(
+            !findings
+                .iter()
+                .any(|finding| finding.check.starts_with("auth:google-")
+                    && matches!(finding.severity, crate::dispatch::doctor::Severity::Fail))
+        );
+    }
+
+    #[test]
+    fn resolve_auth_reads_allowed_email_domains_from_config_toml() {
+        let mut cfg = minimal_oauth_file_config();
+        cfg.allowed_email_domains = Some(vec![
+            "Lime-Technology.com".to_string(),
+            "@example.org".to_string(),
+        ]);
+
+        let resolved = resolve_oauth_fixture(&cfg);
+
+        // Normalized to lowercase with any leading `@` stripped, so operators can
+        // write either `example.org` or `@example.org`.
+        assert_eq!(
+            resolved.allowed_email_domains,
+            vec!["lime-technology.com".to_string(), "example.org".to_string()]
+        );
+    }
+
+    #[test]
+    fn resolve_auth_defaults_allowed_email_domains_to_empty() {
+        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
+        assert!(resolved.allowed_email_domains.is_empty());
+    }
+
+    #[test]
+    fn viewer_domain_policy_requires_an_explicit_host_project() {
+        let mut cfg = minimal_oauth_file_config();
+        cfg.viewer_email_domains = Some(vec!["example.org".into()]);
+        let error = resolve_auth_with_env(
+            Some(&cfg),
+            [("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32))],
+        )
+        .unwrap_err();
+        assert!(error.to_string().contains("auth.viewer_project_id"));
+        cfg.viewer_project_id = Some(" bootstrap-default ".into());
+        let error = resolve_auth_with_env(
+            Some(&cfg),
+            [("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32))],
+        )
+        .unwrap_err();
+        assert!(error.to_string().contains("auth.viewer_project_id"));
+        cfg.viewer_project_id = Some("bootstrap-default".into());
+        let resolved = resolve_oauth_fixture(&cfg);
+        assert_eq!(resolved.viewer_email_domains, vec!["example.org"]);
+    }
+
+    #[test]
+    fn viewer_domains_env_overrides_file_but_cannot_supply_project() {
+        let mut cfg = minimal_oauth_file_config();
+        cfg.viewer_email_domains = Some(vec!["old.example".into()]);
+        cfg.viewer_project_id = Some("bootstrap-default".into());
+        let resolved = resolve_auth_with_env(
+            Some(&cfg),
+            [
+                (
+                    "LABBY_AUTH_VIEWER_EMAIL_DOMAINS".into(),
+                    "new.example".into(),
+                ),
+                ("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32)),
+            ],
+        )
+        .unwrap();
+        assert_eq!(resolved.viewer_email_domains, vec!["new.example"]);
+        cfg.viewer_project_id = None;
+        let error = resolve_auth_with_env(
+            Some(&cfg),
+            [
+                (
+                    "LABBY_AUTH_VIEWER_PROJECT_ID".into(),
+                    "bootstrap-default".into(),
+                ),
+                ("LABBY_TOKEN_ENCRYPTION_KEY".into(), "11".repeat(32)),
+            ],
+        )
+        .unwrap_err();
+        assert!(error.to_string().contains("auth.viewer_project_id"));
+    }
+
+    #[test]
+    fn viewer_policy_is_default_off() {
+        let resolved = resolve_oauth_fixture(&minimal_oauth_file_config());
+        assert!(resolved.viewer_email_domains.is_empty());
+    }
+
+    #[test]
+    fn resolve_auth_preserves_structured_machine_and_enterprise_configuration() {
+        let machine = auth_config::MachineClientConfig {
+            client_id: "ci-agent".to_string(),
+            client_secret: Some("secret".to_string()),
+            jwks: None,
+            scopes: vec!["lab".to_string()],
+            resources: vec!["https://lab.example.com/mcp".to_string()],
+        };
+        let issuer = auth_config::EnterpriseIssuerConfig {
+            issuer: "https://idp.example.com".to_string(),
+            jwks_uri: Some("https://idp.example.com/jwks".parse().unwrap()),
+            jwks: None,
+            allowed_client_ids: vec!["ci-agent".to_string()],
+        };
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            google_client_id: Some("google-client".to_string()),
+            google_client_secret: Some("google-secret".to_string()),
+            admin_email: Some("admin@example.com".to_string()),
+            machine_clients: Some(vec![machine.clone()]),
+            enterprise_issuers: Some(vec![issuer.clone()]),
+            ..AuthFileConfig::default()
+        };
+
+        let resolved = resolve_oauth_fixture(&cfg);
+        assert_eq!(resolved.machine_clients, vec![machine]);
+        assert_eq!(resolved.enterprise_issuers, vec![issuer]);
+    }
+
+    #[test]
+    fn resolve_auth_uses_curated_client_redirects_by_default() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            google_client_id: Some("client-id".to_string()),
+            google_client_secret: Some("client-secret".to_string()),
+            admin_email: Some("admin@example.com".to_string()),
+            ..AuthFileConfig::default()
+        };
+
+        let resolved = resolve_oauth_fixture(&cfg);
+
+        assert_eq!(
+            resolved.allowed_client_redirect_uris,
+            vec![
+                "https://chatgpt.com/aip/plugin-callback".to_string(),
+                "https://chat.openai.com/aip/plugin-callback".to_string(),
+                "https://chatgpt.com/connector/oauth/*".to_string(),
+                "https://chatgpt.com/connector_platform_oauth_redirect".to_string(),
+                "https://claude.ai/api/mcp/auth_callback".to_string(),
+                "https://claude.com/api/mcp/auth_callback".to_string(),
+            ]
+        );
+    }
+
+    #[test]
+    fn resolve_auth_explicit_empty_redirects_disable_product_defaults() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            google_client_id: Some("client-id".to_string()),
+            google_client_secret: Some("client-secret".to_string()),
+            admin_email: Some("admin@example.com".to_string()),
+            allowed_client_redirect_uris: Some(Vec::new()),
+            ..AuthFileConfig::default()
+        };
+
+        let resolved = resolve_oauth_fixture(&cfg);
+
+        assert_eq!(resolved.allowed_client_redirect_uris, Vec::<String>::new());
+    }
+
+    #[test]
+    fn resolve_auth_preserves_explicit_all_https_redirect_opt_in() {
+        let cfg = AuthFileConfig {
+            mode: Some("oauth".to_string()),
+            public_url: Some("https://lab.example.com".to_string()),
+            google_client_id: Some("client-id".to_string()),
+            google_client_secret: Some("client-secret".to_string()),
+            admin_email: Some("admin@example.com".to_string()),
+            allowed_client_redirect_uris: Some(vec!["https://*".to_string()]),
+            ..AuthFileConfig::default()
+        };
+
+        let resolved = resolve_oauth_fixture(&cfg);
+
+        assert_eq!(
+            resolved.allowed_client_redirect_uris,
+            vec!["https://*".to_string()]
+        );
+    }
+
+    #[test]
+    fn oauth_machine_config_deserializes() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[oauth.machines.node-a]
+target_url = "http://100.64.0.10:38935/callback/node-a"
+description = "Node A Claude callback target"
+default_port = 38935
+"#,
+        )
+        .expect("oauth machine config should parse");
+
+        assert_eq!(
+            cfg.oauth.machines["node-a"].target_url,
+            "http://100.64.0.10:38935/callback/node-a"
+        );
+        assert_eq!(
+            cfg.oauth.machines["node-a"].description.as_deref(),
+            Some("Node A Claude callback target")
+        );
+        assert_eq!(cfg.oauth.machines["node-a"].default_port, Some(38935));
+    }
+
+    #[test]
+    fn oauth_machine_defaults_keep_partial_configs_valid() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[web]
+assets_dir = "/tmp/labby"
+"#,
+        )
+        .expect("config without oauth section should still parse");
+
+        assert!(cfg.oauth.machines.is_empty());
+        assert_eq!(cfg.web.assets_dir, Some(PathBuf::from("/tmp/labby")));
+    }
+
+    #[test]
+    fn quarantined_virtual_servers_round_trip_through_toml() {
+        let raw = r#"
+[[quarantined_virtual_servers]]
+id = "missing-service"
+service = "missing-service"
+enabled = true
+
+[quarantined_virtual_servers.surfaces]
+mcp = true
+"#;
+        let cfg = toml::from_str::<LabConfig>(raw).expect("quarantine config should parse");
+        assert_eq!(cfg.quarantined_virtual_servers.len(), 1);
+        assert_eq!(cfg.quarantined_virtual_servers[0].id, "missing-service");
+        assert_eq!(
+            cfg.quarantined_virtual_servers[0].service,
+            "missing-service"
+        );
+        assert!(cfg.quarantined_virtual_servers[0].surfaces.mcp);
+
+        let serialized = toml::to_string(&cfg).expect("config should serialize");
+        let reparsed =
+            toml::from_str::<LabConfig>(&serialized).expect("serialized config should parse");
+        assert_eq!(reparsed.quarantined_virtual_servers.len(), 1);
+        assert_eq!(
+            reparsed.quarantined_virtual_servers[0].id,
+            "missing-service"
+        );
+    }
+
+    #[test]
+    fn workspace_root_defaults_under_labby_home() {
+        let cfg = toml::from_str::<LabConfig>("").expect("empty config should parse");
+        let home = Path::new("/tmp/lab-home");
+
+        assert_eq!(
+            workspace_root_for_home(&cfg, home),
+            home.join(".labby").join("workspace")
+        );
+    }
+
+    #[test]
+    fn file_stash_defaults_are_bounded_and_invalid_limits_fail_startup_validation() {
+        let mut config = LabConfig::default();
+        assert_eq!(config.file_stash.max_file_bytes, 104_857_600);
+        assert_eq!(config.file_stash.principal_quota_bytes, 1_073_741_824);
+        assert_eq!(config.file_stash.instance_quota_bytes, 10_737_418_240);
+        assert_eq!(config.file_stash.max_live_files_per_instance, 100_000);
+        assert_eq!(config.file_stash.queue_capacity, 64);
+        assert_eq!(config.file_stash.max_concurrent_uploads_per_principal, 2);
+        assert_eq!(config.file_stash.max_concurrent_uploads_per_instance, 8);
+        assert_eq!(config.file_stash.max_concurrent_downloads, 16);
+        assert_eq!(config.file_stash.download_idle_seconds, 30);
+        assert_eq!(config.file_stash.download_total_seconds, 600);
+        assert!(config.validate().is_ok());
+        config.file_stash.queue_capacity = 0;
+        assert!(config.validate().is_err());
+        let mut config = LabConfig::default();
+        config.file_stash.pending_ttl_seconds = config.file_stash.upload_total_seconds;
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn file_stash_rejects_every_resource_limit_outside_its_boundary() {
+        macro_rules! invalid {
+            ($field:ident, $value:expr) => {{
+                let mut config = LabConfig::default();
+                config.file_stash.$field = $value;
+                assert!(
+                    config.validate().is_err(),
+                    "{} accepted an invalid boundary value",
+                    stringify!($field)
+                );
+            }};
+        }
+        invalid!(max_file_bytes, 0);
+        invalid!(principal_quota_bytes, 0);
+        invalid!(instance_quota_bytes, 0);
+        invalid!(max_live_files_per_principal, 0);
+        invalid!(max_live_files_per_instance, 1);
+        invalid!(page_size, 0);
+        invalid!(max_query_bytes, 0);
+        invalid!(max_header_bytes, 0);
+        invalid!(grant_recipients_page_size, 0);
+        invalid!(max_mcp_read_bytes, 0);
+        invalid!(queue_capacity, 0);
+        invalid!(database_deadline_ms, 0);
+        invalid!(max_concurrent_uploads_per_principal, 0);
+        invalid!(max_concurrent_uploads_per_instance, 0);
+        invalid!(max_concurrent_downloads, 0);
+        invalid!(max_concurrent_mcp_reads, 0);
+        invalid!(upload_idle_seconds, 0);
+        invalid!(upload_total_seconds, 0);
+        invalid!(download_idle_seconds, 0);
+        invalid!(download_total_seconds, 0);
+        invalid!(pending_ttl_seconds, 0);
+        invalid!(janitor_batch_size, 0);
+        invalid!(janitor_backoff_max_seconds, 0);
+        invalid!(janitor_interval_seconds, 0);
+
+        invalid!(max_file_bytes, 1_073_741_825);
+        invalid!(principal_quota_bytes, 107_374_182_401);
+        invalid!(instance_quota_bytes, 1_099_511_627_777);
+        invalid!(max_live_files_per_principal, 100_001);
+        invalid!(max_live_files_per_instance, 1_000_001);
+        invalid!(page_size, 201);
+        invalid!(max_query_bytes, 1_025);
+        invalid!(max_header_bytes, 65_537);
+        invalid!(grant_recipients_page_size, 201);
+        invalid!(max_mcp_read_bytes, 26_214_401);
+        invalid!(queue_capacity, 1_025);
+        invalid!(database_deadline_ms, 30_001);
+        invalid!(max_concurrent_uploads_per_principal, 3);
+        invalid!(max_concurrent_uploads_per_instance, 9);
+        invalid!(max_concurrent_downloads, 257);
+        invalid!(max_concurrent_mcp_reads, 5);
+        invalid!(upload_idle_seconds, 31);
+        invalid!(upload_total_seconds, 601);
+        invalid!(download_idle_seconds, 31);
+        invalid!(download_total_seconds, 601);
+        invalid!(pending_ttl_seconds, 1_801);
+        invalid!(janitor_batch_size, 101);
+        invalid!(janitor_backoff_max_seconds, 301);
+        invalid!(janitor_interval_seconds, 3_601);
+
+        let mut config = LabConfig::default();
+        config.file_stash.janitor_backoff_max_seconds = 1;
+        assert!(config.validate().is_err());
+    }
+
+    #[test]
+    fn workspace_root_reads_config_toml_value() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[workspace]
+root = "/srv/labby-workspace"
+"#,
+        )
+        .expect("workspace config should parse");
+
+        assert_eq!(
+            workspace_root_for_home(&cfg, Path::new("/tmp/ignored")),
+            PathBuf::from("/srv/labby-workspace")
+        );
+    }
+
+    #[test]
+    fn web_ui_auth_disabled_env_prefers_canonical_alias() {
+        let setting = resolve_web_ui_auth_disabled_values(Some("true"), Some("false"))
+            .expect("env values should parse")
+            .expect("setting should resolve");
+
+        assert!(setting.disabled);
+        assert_eq!(setting.source, WEB_UI_AUTH_DISABLED_ENV);
+        assert!(!setting.legacy_alias);
+    }
+
+    #[test]
+    fn web_ui_auth_disabled_env_accepts_legacy_alias() {
+        let setting = resolve_web_ui_auth_disabled_values(None, Some("1"))
+            .expect("env values should parse")
+            .expect("setting should resolve");
+
+        assert!(setting.disabled);
+        assert_eq!(setting.source, WEB_UI_AUTH_DISABLED_LEGACY_ENV);
+        assert!(setting.legacy_alias);
+    }
+
+    #[test]
+    fn web_ui_auth_disabled_env_rejects_invalid_values() {
+        let error = resolve_web_ui_auth_disabled_values(Some("sometimes"), None)
+            .expect_err("invalid bool should fail");
+
+        assert!(
+            error
+                .to_string()
+                .contains("invalid LABBY_WEB_UI_AUTH_DISABLED value")
+        );
+    }
+
+    #[test]
+    fn secret_debug_redacts() {
+        let s = Secret::new("hunter2".into());
+        assert_eq!(format!("{s:?}"), "[REDACTED]");
+        assert_eq!(format!("{s}"), "[REDACTED]");
+        assert_eq!(s.expose(), "hunter2");
+    }
+
+    #[test]
+    fn secret_serialize_emits_placeholder_not_plaintext() {
+        let s = Secret::new("super-secret-api-key".into());
+        let json = serde_json::to_string(&s).expect("serialize must not fail");
+        assert_eq!(
+            json, "\"***REDACTED***\"",
+            "Secret must serialize to placeholder"
+        );
+        assert!(
+            !json.contains("super-secret-api-key"),
+            "Secret must never emit plaintext through serde"
+        );
+    }
+
+    #[test]
+    fn suffix_collision_longest_wins() {
+        let env = [("S_NODE_API_KEY_URL", "http://example.com")];
+        let result = scan_instances_from("S", vars(&env));
+        let inst = result
+            .get("node_api_key")
+            .expect("should find instance node_api_key");
+        assert_eq!(
+            inst.get("URL").expect("should have URL").expose(),
+            "http://example.com"
+        );
+    }
+
+    #[test]
+    fn default_instance_parsed() {
+        let env = [
+            ("SVC_URL", "http://localhost"),
+            ("SVC_API_KEY", "secret123"),
+        ];
+        let result = scan_instances_from("SVC", vars(&env));
+        let def = result.get("default").expect("should find default");
+        assert_eq!(def.get("URL").expect("URL").expose(), "http://localhost");
+        assert_eq!(def.get("API_KEY").expect("API_KEY").expose(), "secret123");
+        assert!(format!("{:?}", def.get("API_KEY").unwrap()).contains("[REDACTED]"));
+    }
+
+    #[test]
+    fn named_instance_parsed() {
+        let env = [
+            ("UNRAID_NODE2_URL", "http://node2"),
+            ("UNRAID_NODE2_TOKEN", "tok"),
+        ];
+        let result = scan_instances_from("UNRAID", vars(&env));
+        let inst = result.get("node2").expect("should find node2");
+        assert_eq!(inst.get("URL").expect("URL").expose(), "http://node2");
+        assert_eq!(inst.get("TOKEN").expect("TOKEN").expose(), "tok");
+        assert!(format!("{:?}", inst.get("TOKEN").unwrap()).contains("[REDACTED]"));
+    }
+
+    #[test]
+    fn unrelated_vars_ignored() {
+        let env = [
+            ("SVC_URL", "http://localhost"),
+            ("OTHER_URL", "http://other"),
+        ];
+        let result = scan_instances_from("SVC", vars(&env));
+        assert_eq!(result.len(), 1);
+        assert!(result.contains_key("default"));
+    }
+
+    #[test]
+    fn username_is_plain_not_secret() {
+        let env = [("SVC_USERNAME", "admin")];
+        let result = scan_instances_from("SVC", vars(&env));
+        let def = result.get("default").expect("should find default");
+        assert!(!format!("{:?}", def.get("USERNAME").unwrap()).contains("[REDACTED]"));
+    }
+
+    // ─── write_service_creds tests ──────────────────────────────────────────
+
+    fn example_cred() -> EnvCredential {
+        EnvCredential {
+            service: "example".to_owned(),
+            url: Some("http://localhost:7878".to_owned()),
+            secret: Some("abc123".to_owned()),
+            env_field: "EXAMPLE_API_KEY".to_owned(),
+        }
+    }
+
+    #[test]
+    fn write_service_creds_adds_new_keys() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
+        assert!(outcome.skipped.is_empty());
+        assert_eq!(outcome.written, 2);
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("EXAMPLE_URL=http://localhost:7878"));
+        assert!(content.contains("EXAMPLE_API_KEY=abc123"));
+    }
+
+    #[test]
+    fn write_service_creds_preserves_comments_and_blanks() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        std::fs::write(&path, "# my comment\nOTHER=val\n").unwrap();
+        write_service_creds(&path, &[example_cred()], false).unwrap();
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("# my comment"));
+        assert!(content.contains("OTHER=val"));
+    }
+
+    #[test]
+    fn write_service_creds_conflict_skip_without_force() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        std::fs::write(&path, "EXAMPLE_API_KEY=oldvalue\n").unwrap();
+        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
+        assert!(!outcome.skipped.is_empty());
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("oldvalue"));
+        assert!(!content.contains("abc123"));
+    }
+
+    #[test]
+    fn write_service_creds_conflict_overwrite_with_force() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        std::fs::write(&path, "EXAMPLE_API_KEY=oldvalue\n").unwrap();
+        let outcome = write_service_creds(&path, &[example_cred()], true).unwrap();
+        assert!(outcome.skipped.is_empty());
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("abc123"));
+        assert!(!content.contains("oldvalue"));
+    }
+
+    #[test]
+    fn write_service_creds_is_idempotent_when_matching() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        write_service_creds(&path, &[example_cred()], false).unwrap();
+        // Re-running with the exact same creds must be a written=0 no-op --
+        // this is the signal crate::dispatch::gateway::config_store relies on
+        // to skip a service-client refresh cycle.
+        let outcome = write_service_creds(&path, &[example_cred()], false).unwrap();
+        assert_eq!(outcome.written, 0);
+        assert!(outcome.backup_path.is_none());
+    }
+
+    #[test]
+    fn write_service_creds_quotes_value_with_special_chars() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join(".env");
+        let cred = EnvCredential {
+            service: "svc".to_owned(),
+            url: None,
+            secret: Some("has space".to_owned()),
+            env_field: "SVC_KEY".to_owned(),
+        };
+        write_service_creds(&path, &[cred], false).unwrap();
+        let content = std::fs::read_to_string(&path).unwrap();
+        assert!(content.contains("SVC_KEY=\"has space\""));
+    }
+
+    #[test]
+    fn upstream_oauth_pkce_parses() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+scopes = ["mcp"]
+
+[upstream.oauth.registration]
+strategy = "client_metadata_document"
+url = "https://acme.example.com/.well-known/oauth-client"
+"#,
+        )
+        .expect("pkce config should parse");
+
+        let upstream = &cfg.upstream[0];
+        let oauth = upstream.oauth.as_ref().expect("oauth present");
+        assert!(matches!(
+            oauth.mode,
+            UpstreamOauthMode::AuthorizationCodePkce
+        ));
+        assert_eq!(oauth.scopes.as_deref(), Some(&["mcp".to_string()][..]));
+        match &oauth.registration {
+            UpstreamOauthRegistration::ClientMetadataDocument { url } => {
+                assert_eq!(url, "https://acme.example.com/.well-known/oauth-client");
+            }
+            _ => panic!("expected client metadata document registration"),
+        }
+        upstream.validate().expect("validate ok");
+    }
+
+    #[test]
+    fn upstream_oauth_preregistered_parses() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+
+[upstream.oauth.registration]
+strategy = "preregistered"
+client_id = "my-client"
+"#,
+        )
+        .expect("preregistered config should parse");
+
+        let upstream = &cfg.upstream[0];
+        let oauth = upstream.oauth.as_ref().unwrap();
+        match &oauth.registration {
+            UpstreamOauthRegistration::Preregistered {
+                client_id,
+                client_secret_env,
+            } => {
+                assert_eq!(client_id, "my-client");
+                assert!(client_secret_env.is_none());
+            }
+            _ => panic!("expected preregistered OAuth client"),
+        }
+    }
+
+    #[test]
+    fn upstream_oauth_google_provider_credential_source_parses() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "google-calendar"
+url = "https://calendarmcp.googleapis.com/mcp/v1"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+scopes = ["https://www.googleapis.com/auth/calendar.events.readonly"]
+
+[upstream.oauth.credential]
+source = "google_provider"
+account = "admin@example.com"
+
+[upstream.oauth.registration]
+strategy = "preregistered"
+client_id = "google-client"
+client_secret_env = "LABBY_GOOGLE_CLIENT_SECRET"
+"#,
+        )
+        .expect("google provider credential config should parse");
+
+        let oauth = cfg.upstream[0].oauth.as_ref().unwrap();
+        assert_eq!(
+            oauth.credential,
+            UpstreamOauthCredentialSource::GoogleProvider {
+                account: Some("admin@example.com".to_string()),
+            }
+        );
+        cfg.upstream[0]
+            .validate()
+            .expect("shared Google configuration should validate");
+    }
+
+    #[test]
+    fn upstream_oauth_credential_source_defaults_to_dedicated() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+
+[upstream.oauth.registration]
+strategy = "preregistered"
+client_id = "my-client"
+"#,
+        )
+        .unwrap();
+        assert_eq!(
+            cfg.upstream[0].oauth.as_ref().unwrap().credential,
+            UpstreamOauthCredentialSource::Dedicated
+        );
+    }
+
+    #[test]
+    fn upstream_oauth_preregistered_with_secret_parses() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+
+[upstream.oauth.registration]
+strategy = "preregistered"
+client_id = "my-client"
+client_secret_env = "ACME_CLIENT_SECRET"
+"#,
+        )
+        .expect("preregistered+secret config should parse");
+
+        let upstream = &cfg.upstream[0];
+        let oauth = upstream.oauth.as_ref().unwrap();
+        match &oauth.registration {
+            UpstreamOauthRegistration::Preregistered {
+                client_id,
+                client_secret_env,
+            } => {
+                assert_eq!(client_id, "my-client");
+                assert_eq!(client_secret_env.as_deref(), Some("ACME_CLIENT_SECRET"));
+            }
+            _ => panic!("expected preregistered OAuth client with secret reference"),
+        }
+    }
+
+    #[test]
+    fn upstream_oauth_dynamic_parses() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+
+[upstream.oauth.registration]
+strategy = "dynamic"
+"#,
+        )
+        .expect("dynamic config should parse");
+
+        let upstream = &cfg.upstream[0];
+        let oauth = upstream.oauth.as_ref().unwrap();
+        assert!(matches!(
+            oauth.registration,
+            UpstreamOauthRegistration::Dynamic
+        ));
+    }
+
+    #[test]
+    fn upstream_oauth_conflicts_with_bearer_token_env() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+bearer_token_env = "ACME_TOKEN"
+
+[upstream.oauth]
+mode = "authorization_code_pkce"
+
+[upstream.oauth.registration]
+strategy = "dynamic"
+"#,
+        )
+        .expect("config parses; validation is a separate step");
+
+        let err = cfg.upstream[0].validate().unwrap_err();
+        match err {
+            ConfigError::ConflictingAuth { name } => assert_eq!(name, "acme"),
+            _ => panic!("expected ConflictingAuth"),
+        }
+    }
+
+    #[test]
+    fn code_mode_is_root_level_config() {
+        let cfg = toml::from_str::<LabConfig>(
+            r#"
+[code_mode]
+enabled = true
+timeout_ms = 2500
+
+[[upstream]]
+name = "acme"
+url = "https://acme.example.com/mcp"
+"#,
+        )
+        .expect("root code_mode parses");
+
+        assert!(cfg.code_mode.enabled);
+        assert_eq!(cfg.code_mode.timeout_ms, 2500);
+        cfg.validate().expect("root code_mode validates");
+    }
+
+    #[test]
+    fn code_mode_is_root_level_config_with_default_limits() {
+        let default_cfg = LabConfig::default();
+        assert_eq!(default_cfg.code_mode.timeout_ms, 30_000);
+        assert_eq!(default_cfg.code_mode.max_source_bytes, 1024 * 1024);
+        assert_eq!(default_cfg.code_mode.max_response_bytes, 24 * 1024);
+        assert_eq!(default_cfg.code_mode.max_response_tokens, 6000);
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+[code_mode]
+timeout_ms = 2500
+max_source_bytes = 65536
+max_response_bytes = 12000
+max_response_tokens = 3000
+",
+        )
+        .expect("root code_mode parses");
+
+        assert_eq!(cfg.code_mode.timeout_ms, 2500);
+        assert_eq!(cfg.code_mode.max_source_bytes, 65_536);
+        assert_eq!(cfg.code_mode.max_response_bytes, 12000);
+        assert_eq!(cfg.code_mode.max_response_tokens, 3000);
+    }
+
+    #[test]
+    fn upstream_request_timeout_is_root_level_config() {
+        let default_cfg = LabConfig::default();
+        assert_eq!(
+            default_cfg.upstream_request_timeout(),
+            Duration::from_secs(30)
+        );
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+upstream_request_timeout_ms = 60000
+",
+        )
+        .expect("root upstream request timeout parses");
+
+        assert_eq!(cfg.upstream_request_timeout_ms, Some(60_000));
+        assert_eq!(cfg.upstream_request_timeout(), Duration::from_mins(1));
+        cfg.validate().expect("timeout validates");
+    }
+
+    /// The HTTP transport backstop must never fire before the upstream deadline
+    /// it wraps. A fixed 30s cap in the router used to override both settings:
+    /// a 60s `upstream_request_timeout_ms` still returned a bare 504 at 30s,
+    /// discarding a tool call that went on to succeed.
+    #[test]
+    fn http_request_timeout_never_undercuts_configured_upstream_deadlines() {
+        for toml_src in [
+            "",
+            "upstream_request_timeout_ms = 60000",
+            // Both knobs at the top of their validated ranges.
+            "upstream_request_timeout_ms = 300000\nupstream_relay_timeout_ms = 1800000",
+            // Relay left at its 5 minute default while the pooled path is raised.
+            "upstream_request_timeout_ms = 120000",
+            // Relay raised while the pooled path stays at its default.
+            "upstream_relay_timeout_ms = 900000",
+        ] {
+            let cfg = toml::from_str::<LabConfig>(toml_src).expect("config parses");
+            cfg.validate().expect("config validates");
+
+            let http = cfg.http_request_timeout();
+            assert!(
+                http > cfg.upstream_request_timeout(),
+                "http timeout {http:?} must exceed the pooled upstream deadline {:?} for {toml_src:?}",
+                cfg.upstream_request_timeout(),
+            );
+            assert!(
+                http > cfg.upstream_relay_timeout(),
+                "http timeout {http:?} must exceed the relay deadline {:?} for {toml_src:?}",
+                cfg.upstream_relay_timeout(),
+            );
+        }
+    }
+
+    /// A Code Mode run is carried by the HTTP request that started it, so the
+    /// transport backstop must also cover `code_mode.timeout_ms`; otherwise a
+    /// long run outlives its own response.
+    #[test]
+    fn http_request_timeout_never_undercuts_code_mode_timeout() {
+        let cfg = toml::from_str::<LabConfig>(
+            "upstream_request_timeout_ms = 60000\nupstream_relay_timeout_ms = 60000\n[code_mode]\ntimeout_ms = 180000\n",
+        )
+        .expect("config parses");
+        cfg.validate().expect("config validates");
+        let http = cfg.http_request_timeout();
+        assert!(
+            http > Duration::from_millis(cfg.code_mode.timeout_ms),
+            "http timeout {http:?} must exceed the Code Mode deadline {} ms",
+            cfg.code_mode.timeout_ms
+        );
+    }
+
+    /// A synchronous `agents.run` holds its HTTP request for the whole Agent
+    /// runtime bound, which is fixed product policy rather than configuration.
+    #[test]
+    fn http_request_timeout_covers_the_agent_runtime_bound() {
+        let cfg = toml::from_str::<LabConfig>(
+            "upstream_request_timeout_ms = 60000\nupstream_relay_timeout_ms = 60000\n",
+        )
+        .expect("config parses");
+        cfg.validate().expect("config validates");
+        let bound = Duration::from_millis(labby_runtime::agent_runtime::AGENT_MAX_RUNTIME_MILLIS);
+        assert!(
+            cfg.http_request_timeout() > bound,
+            "http timeout {:?} must exceed the Agent runtime bound {bound:?}",
+            cfg.http_request_timeout()
+        );
+    }
+
+    /// The 5 minute relay default is the binding constraint out of the box, so
+    /// a default deployment must not cap HTTP requests at the 30s pooled value.
+    #[test]
+    fn http_request_timeout_default_accommodates_the_relay_path() {
+        let cfg = LabConfig::default();
+        assert_eq!(
+            cfg.http_request_timeout(),
+            cfg.upstream_relay_timeout() + HTTP_REQUEST_TIMEOUT_MARGIN,
+        );
+        assert!(cfg.http_request_timeout() > Duration::from_secs(30));
+    }
+
+    #[test]
+    fn upstream_relay_timeout_defaults_to_five_minutes_and_is_configurable() {
+        // Unset → 5 minute default (NOT the 30s request-timeout default), so a
+        // relayed elicitation is not aborted while a human is answering.
+        let default_cfg = LabConfig::default();
+        assert_eq!(default_cfg.upstream_relay_timeout_ms, None);
+        assert_eq!(default_cfg.upstream_relay_timeout(), Duration::from_mins(5));
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+upstream_relay_timeout_ms = 600000
+",
+        )
+        .expect("root upstream relay timeout parses");
+        assert_eq!(cfg.upstream_relay_timeout_ms, Some(600_000));
+        assert_eq!(cfg.upstream_relay_timeout(), Duration::from_mins(10));
+        cfg.validate().expect("relay timeout validates");
+    }
+
+    #[test]
+    fn upstream_relay_timeout_rejects_out_of_range() {
+        // Above the 30 min ceiling.
+        let too_big = LabConfig {
+            upstream_relay_timeout_ms: Some(1_800_001),
+            ..LabConfig::default()
+        };
+        assert!(matches!(
+            too_big.validate(),
+            Err(ConfigError::InvalidUpstreamRelayTimeout { value: 1_800_001 })
+        ));
+
+        // Zero is rejected just like the request timeout.
+        let zero = LabConfig {
+            upstream_relay_timeout_ms: Some(0),
+            ..LabConfig::default()
+        };
+        assert!(matches!(
+            zero.validate(),
+            Err(ConfigError::InvalidUpstreamRelayTimeout { value: 0 })
+        ));
+    }
+
+    #[test]
+    fn catalog_notification_timeout_defaults_to_five_seconds_and_is_configurable() {
+        let default_cfg = LabConfig::default();
+        assert_eq!(default_cfg.mcp.catalog_notification_timeout_ms, None);
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+[mcp]
+catalog_notification_timeout_ms = 2500
+",
+        )
+        .expect("mcp catalog notification timeout parses");
+
+        assert_eq!(cfg.mcp.catalog_notification_timeout_ms, Some(2_500));
+        cfg.validate()
+            .expect("catalog notification timeout validates");
+    }
+
+    #[test]
+    fn catalog_notification_timeout_rejects_out_of_range() {
+        let too_big = LabConfig {
+            mcp: McpPreferences {
+                catalog_notification_timeout_ms: Some(60_001),
+                ..McpPreferences::default()
+            },
+            ..LabConfig::default()
+        };
+        assert!(matches!(
+            too_big.validate(),
+            Err(ConfigError::InvalidCatalogNotificationTimeout { value: 60_001 })
+        ));
+
+        let zero = LabConfig {
+            mcp: McpPreferences {
+                catalog_notification_timeout_ms: Some(0),
+                ..McpPreferences::default()
+            },
+            ..LabConfig::default()
+        };
+        assert!(matches!(
+            zero.validate(),
+            Err(ConfigError::InvalidCatalogNotificationTimeout { value: 0 })
+        ));
+    }
+
+    #[test]
+    fn code_mode_validation_rejects_unbounded_execution_settings() {
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+[code_mode]
+timeout_ms = 0
+",
+        )
+        .expect("code_mode parses");
+        assert!(matches!(
+            cfg.validate(),
+            Err(ConfigError::InvalidCodeModeTimeout { value: 0 })
+        ));
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+[code_mode]
+timeout_ms = 5000
+max_response_bytes = 100
+",
+        )
+        .expect("code_mode parses");
+        assert!(matches!(
+            cfg.validate(),
+            Err(ConfigError::InvalidCodeModeMaxResponseBytes { value: 100 })
+        ));
+
+        let cfg = toml::from_str::<LabConfig>(
+            r"
+[code_mode]
+timeout_ms = 5000
+max_response_tokens = 100
+",
+        )
+        .expect("code_mode parses");
+        assert!(matches!(
+            cfg.validate(),
+            Err(ConfigError::InvalidCodeModeMaxResponseTokens { value: 100 })
+        ));
+    }
+
+    #[test]
+    fn protected_route_legacy_backend_path_folds_into_backend_url() {
+        let mut cfg = toml::from_str::<LabConfig>(
+            r#"
+[[protected_mcp_routes]]
+name = "tools"
+enabled = true
+public_host = "mcp.example.com"
+public_path = "/tools"
+backend_url = "http://10.0.0.12:3100"
+backend_mcp_path = "/mcp"
+"#,
+        )
+        .expect("protected route parses");
+
+        cfg.normalize_protected_mcp_routes()
+            .expect("protected route normalizes");
+
+        assert_eq!(
+            cfg.protected_mcp_routes[0].backend_url,
+            "http://10.0.0.12:3100/mcp"
+        );
+        assert_eq!(cfg.protected_mcp_routes[0].backend_mcp_path, "/mcp");
+    }
+
+    #[test]
+    fn protected_route_named_upstream_allows_empty_backend_url() {
+        let mut cfg = toml::from_str::<LabConfig>(
+            r#"
+[[protected_mcp_routes]]
+name = "telemetry"
+enabled = true
+public_host = "mcp.example.com"
+public_path = "/telemetry"
+upstream = " telemetry "
+"#,
+        )
+        .expect("protected route parses");
+
+        cfg.normalize_protected_mcp_routes()
+            .expect("upstream route normalizes");
+
+        assert_eq!(
+            cfg.protected_mcp_routes[0].upstream.as_deref(),
+            Some("telemetry")
+        );
+        assert_eq!(cfg.protected_mcp_routes[0].backend_url, "");
+        assert_eq!(cfg.protected_mcp_routes[0].backend_mcp_path, "/mcp");
+    }
+
+    #[test]
+    fn protected_route_gateway_subset_target_parses() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "ops"
+public_host = "mcp.example.com"
+public_path = "/ops"
+scopes = ["mcp:ops"]
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["gateway-alpha", "gateway-beta", " gateway-gamma "]
+services = ["gateway"]
+expose_code_mode = true
+"#;
+
+        let cfg = parse_normalized_config(toml);
+        let route = &cfg.protected_mcp_routes[0];
+
+        assert_eq!(route.name, "ops");
+        assert_eq!(route.backend_url, "");
+        assert_eq!(route.upstream, None);
+        assert!(route.is_gateway_subset());
+        let target = route.gateway_subset_target().expect("gateway subset");
+        assert_eq!(
+            target.upstreams,
+            vec!["gateway-alpha", "gateway-beta", "gateway-gamma"]
+        );
+        assert_eq!(target.services, vec!["gateway"]);
+        assert!(target.expose_code_mode);
+    }
+
+    #[test]
+    fn protected_route_legacy_backend_url_maps_to_proxy_target() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "telemetry"
+public_host = "mcp.example.com"
+public_path = "/telemetry"
+backend_url = "http://10.0.0.2:3100/mcp"
+"#;
+
+        let cfg = parse_normalized_config(toml);
+        let route = &cfg.protected_mcp_routes[0];
+
+        assert!(matches!(
+            route.effective_target(),
+            ProtectedMcpRouteEffectiveTarget::BackendUrl { .. }
+        ));
+    }
+
+    #[test]
+    fn protected_route_rejects_target_with_legacy_backend() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "bad"
+public_host = "mcp.example.com"
+public_path = "/bad"
+backend_url = "http://10.0.0.2:3100/mcp"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["gateway-beta"]
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        let err = cfg
+            .normalize_protected_mcp_routes()
+            .expect_err("target and backend_url must conflict");
+        assert!(err.to_string().contains(
+            "protected MCP route target cannot be combined with upstream or backend_url"
+        ));
+    }
+
+    #[test]
+    fn protected_route_rejects_empty_gateway_subset_entries() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "bad"
+public_host = "mcp.example.com"
+public_path = "/bad"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["gateway-alpha", " "]
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        let err = cfg
+            .normalize_protected_mcp_routes()
+            .expect_err("empty upstream entry must fail");
+        assert!(err.to_string().contains("target.upstreams"));
+        assert!(
+            err.to_string()
+                .contains("gateway_subset target entries must not be empty")
+        );
+    }
+
+    #[test]
+    fn protected_route_allows_same_gateway_subset_path_on_different_hosts() {
+        let toml = r#"
+[[upstream]]
+name = "gateway-alpha"
+enabled = false
+url = "https://gateway-alpha.example.com/mcp"
+
+[[protected_mcp_routes]]
+name = "media-a"
+public_host = "mcp-a.example.com"
+public_path = "/ops"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["gateway-alpha"]
+
+[[protected_mcp_routes]]
+name = "media-b"
+public_host = "mcp-b.example.com"
+public_path = "/ops"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["gateway-alpha"]
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("host and path together identify a protected route");
+        cfg.validate()
+            .expect("same subset path on distinct hosts is valid");
+    }
+
+    #[test]
+    fn config_validation_rejects_reserved_protected_route_path() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "bad"
+public_host = "mcp.example.com"
+public_path = "/v1"
+backend_url = "http://10.0.0.2:3100/mcp"
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("normalization should not hide validation failure");
+        let err = cfg
+            .validate()
+            .expect_err("reserved protected route path must fail validation");
+
+        assert!(err.to_string().contains("public_path"));
+        assert!(err.to_string().contains("reserved"));
+    }
+
+    #[test]
+    fn config_validation_rejects_public_callback_relay_protected_route_path() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "bad"
+public_host = "mcp.example.com"
+public_path = "/callback/devhost"
+backend_url = "http://10.0.0.2:3100/mcp"
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("normalization should not hide validation failure");
+        let err = cfg
+            .validate()
+            .expect_err("callback relay protected route path must fail validation");
+
+        assert!(err.to_string().contains("public_path"));
+        assert!(err.to_string().contains("reserved"));
+    }
+
+    #[test]
+    fn config_validation_rejects_empty_gateway_subset_target() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "empty"
+public_host = "mcp.example.com"
+public_path = "/empty"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("normalization should not hide validation failure");
+        let err = cfg
+            .validate()
+            .expect_err("empty gateway_subset target must fail validation");
+
+        assert!(err.to_string().contains("gateway_subset target"));
+    }
+
+    #[test]
+    fn config_validation_accepts_gateway_subset_loadout_target() {
+        let toml = r#"
+[[upstream]]
+name = "gateway-alpha"
+enabled = false
+url = "https://gateway-alpha.example.com/mcp"
+
+[[loadouts]]
+name = "sd"
+upstreams = ["gateway-alpha"]
+
+[[protected_mcp_routes]]
+name = "sd"
+public_host = "sd.example.com"
+public_path = "/mcp"
+scopes = ["mcp:read"]
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+loadout = " sd "
+"#;
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+
+        cfg.normalize_protected_mcp_routes()
+            .expect("loadout route normalization succeeds");
+        cfg.validate().expect("known loadout route is valid");
+        let ProtectedMcpRouteTarget::GatewaySubset(target) = cfg.protected_mcp_routes[0]
+            .target
+            .as_ref()
+            .expect("gateway subset target");
+        assert_eq!(target.loadout.as_deref(), Some("sd"));
+    }
+
+    #[test]
+    fn config_validation_rejects_unknown_gateway_subset_targets() {
+        let toml = r#"
+[[upstream]]
+name = "gateway-alpha"
+url = "https://gateway_alpha.example.com/mcp"
+
+[[protected_mcp_routes]]
+name = "ops"
+public_host = "mcp.example.com"
+public_path = "/ops"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["sonnar"]
+services = ["gateway", "nope"]
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("normalization should not hide validation failure");
+        let err = cfg
+            .validate()
+            .expect_err("unknown gateway_subset targets must fail validation");
+
+        assert!(
+            err.to_string().contains("sonnar") || err.to_string().contains("nope"),
+            "unexpected error: {err}"
+        );
+    }
+
+    #[test]
+    fn config_validation_allows_stale_targets_on_disabled_gateway_subset_routes() {
+        let toml = r#"
+[[protected_mcp_routes]]
+name = "retired-ops"
+enabled = false
+public_host = "mcp.example.com"
+public_path = "/ops"
+
+[protected_mcp_routes.target]
+kind = "gateway_subset"
+upstreams = ["removed-upstream"]
+services = ["removed-service"]
+"#;
+
+        let mut cfg: LabConfig = toml::from_str(toml).expect("parse");
+        cfg.normalize_protected_mcp_routes()
+            .expect("disabled route remains structurally valid");
+        cfg.validate()
+            .expect("disabled routes must not block gateway startup");
+    }
+
+    // ── Code Mode: CodeModeConfig defaults ───────────────────────────────────
+
+    #[test]
+    fn code_mode_config_token_estimate_divisor_defaults_to_4() {
+        let config = CodeModeConfig::default();
+        // PRESENCE: default divisor is exactly 4
+        assert_eq!(
+            config.token_estimate_divisor, 4,
+            "token_estimate_divisor default must be 4"
+        );
+        // ABSENCE: it is not 0 or 1 (which would drastically change truncation)
+        assert_ne!(config.token_estimate_divisor, 0);
+        assert_ne!(config.token_estimate_divisor, 1);
+    }
+
+    #[test]
+    fn code_mode_config_defaults_are_sane() {
+        let config = CodeModeConfig::default();
+        // PRESENCE: timeout and output limits are positive
+        assert!(config.timeout_ms > 0);
+        assert!(config.max_response_bytes > 0);
+        assert!(config.max_response_tokens > 0);
+        // ABSENCE: not wildly large (sanity bounds)
+        assert!(config.timeout_ms <= 60_000);
+    }
+
+    // ── Process-wide atomic flags ─────────────────────────────────────────────
+
+    #[test]
+    fn process_code_mode_flag_round_trips() {
+        let _guard = process_code_mode_test_guard();
+
+        set_process_code_mode_enabled_for_test(true);
+        assert!(
+            process_code_mode_enabled(),
+            "code_mode must be true after set_process_code_mode_enabled(true)"
+        );
+
+        set_process_code_mode_enabled_for_test(false);
+        assert!(
+            !process_code_mode_enabled(),
+            "code_mode must be false after set_process_code_mode_enabled(false)"
+        );
+    }
+
+    // ── T3: secret file permission tests (S2) ────────────────────────────────
+
+    #[cfg(unix)]
+    fn file_mode(path: &Path) -> u32 {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::metadata(path)
+            .unwrap_or_else(|e| panic!("metadata {}: {e}", path.display()))
+            .permissions()
+            .mode()
+            & 0o777
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn write_service_creds_creates_file_with_mode_0o600() {
+        let dir = tempfile::tempdir().expect("tempdir");
+        let env_path = dir.path().join(".env");
+
+        let creds = [EnvCredential {
+            service: "myservice".to_string(),
+            url: None,
+            secret: Some("supersecret".to_string()),
+            env_field: "MYSERVICE_TOKEN".to_string(),
+        }];
+
+        write_service_creds(&env_path, &creds, false).expect("write_service_creds");
+
+        assert_eq!(
+            file_mode(&env_path),
+            0o600,
+            ".env must be 0o600 after write_service_creds"
+        );
+    }
+
+    // Backup-file 0o600 perms and retention pruning are covered directly by
+    // env_merge's own unix_perms_set_to_0600 / backup_pruning_keeps_last_ten
+    // tests -- write_service_creds delegates entirely to env_merge::merge for
+    // that behavior and adds no file-handling logic of its own.
+
+    #[test]
+    #[cfg(unix)]
+    fn heal_env_file_permissions_tightens_loose_env() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = tempfile::tempdir().expect("tempdir");
+        let env_path = dir.path().join(".env");
+        std::fs::write(&env_path, "TOKEN=secret\n").expect("write");
+        std::fs::set_permissions(&env_path, std::fs::Permissions::from_mode(0o644))
+            .expect("chmod 644");
+
+        heal_env_file_permissions(&env_path);
+
+        assert_eq!(
+            file_mode(&env_path),
+            0o600,
+            "heal must tighten .env to 0o600"
+        );
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn heal_env_file_permissions_tightens_backup_files() {
+        use std::os::unix::fs::PermissionsExt;
+
+        let dir = tempfile::tempdir().expect("tempdir");
+        let env_path = dir.path().join(".env");
+        let bak_path = dir.path().join(".env.bak.1234567890");
+
+        std::fs::write(&env_path, "TOKEN=secret\n").expect("write env");
+        std::fs::write(&bak_path, "TOKEN=oldsecret\n").expect("write bak");
+
+        for p in [&env_path, &bak_path] {
+            std::fs::set_permissions(p, std::fs::Permissions::from_mode(0o644)).expect("chmod 644");
+        }
+
+        heal_env_file_permissions(&env_path);
+
+        assert_eq!(file_mode(&env_path), 0o600, ".env must be healed");
+        assert_eq!(file_mode(&bak_path), 0o600, ".env.bak.* must be healed");
+    }
+
+    // usage_telemetry_enabled() delegates to the pure resolve_usage_telemetry_enabled()
+    // so these tests never need to mutate process env (this crate forbids
+    // `unsafe`, and `std::env::set_var`/`remove_var` are `unsafe fn` as of
+    // Rust 2024) — same shape as the resolve_web_ui_auth_disabled_values
+    // tests above.
+    #[test]
+    fn usage_telemetry_enabled_defaults_true_when_unset() {
+        assert!(
+            resolve_usage_telemetry_enabled(None),
+            "usage telemetry must default to enabled when the env var is unset"
+        );
+    }
+
+    #[test]
+    fn usage_telemetry_enabled_false_when_set_to_1() {
+        assert!(
+            !resolve_usage_telemetry_enabled(Some("1")),
+            "usage telemetry must be disabled when the env var is \"1\""
+        );
+    }
+
+    #[test]
+    fn usage_telemetry_enabled_true_for_other_values() {
+        assert!(
+            resolve_usage_telemetry_enabled(Some("true")),
+            "only the exact value \"1\" should disable usage telemetry"
+        );
+        assert!(
+            resolve_usage_telemetry_enabled(Some("0")),
+            "\"0\" is not the disable sentinel; telemetry stays enabled"
+        );
+    }
+
+    #[test]
+    fn usage_db_path_is_under_dot_labby_home_dir() {
+        let path = usage_db_path().unwrap();
+        assert_eq!(path.file_name().and_then(|n| n.to_str()), Some("usage.db"));
+        assert_eq!(
+            path.parent()
+                .and_then(|p| p.file_name())
+                .and_then(|n| n.to_str()),
+            Some(".labby")
+        );
+    }
+
+    /// Review finding on lab-eyeuv: the reserved-prefix guard was added to
+    /// `labby_runtime`'s copy of `normalize_protected_mcp_routes`, but
+    /// `load_toml` runs THIS copy — and the route scopes mounted by
+    /// `cli/serve.rs` are built from this config. The guard has to live on
+    /// both, and this test pins the serve-path copy specifically.
+    #[test]
+    fn serve_path_normalization_rejects_reserved_in_process_upstreams() {
+        let mut route: ProtectedMcpRouteConfig = toml::from_str(
+            "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
+        )
+        .unwrap();
+        route.backend_url = String::new();
+        route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
+            ProtectedGatewaySubsetTarget {
+                project_id: None,
+                upstreams: vec![format!("{IN_PROCESS_UPSTREAM_PREFIX}setup")],
+                services: Vec::new(),
+                expose_code_mode: false,
+                loadout: None,
+            },
+        ));
+        let mut cfg = LabConfig {
+            protected_mcp_routes: vec![route],
+            ..LabConfig::default()
+        };
+
+        let error = cfg
+            .normalize_protected_mcp_routes()
+            .expect_err("the serve-path copy must reject the reserved prefix");
+        let rendered = error.to_string();
+        assert!(rendered.contains("__in_process__setup"), "{rendered}");
+    }
+
+    #[test]
+    fn serve_path_project_id_normalization_is_bounded_and_compatible() {
+        fn config(project_id: Option<String>) -> LabConfig {
+            let mut route: ProtectedMcpRouteConfig = toml::from_str(
+                "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
+            )
+            .unwrap();
+            route.backend_url = String::new();
+            route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
+                ProtectedGatewaySubsetTarget {
+                    project_id,
+                    ..Default::default()
+                },
+            ));
+            LabConfig {
+                protected_mcp_routes: vec![route],
+                ..Default::default()
+            }
+        }
+
+        let mut omitted = config(None);
+        omitted
+            .normalize_protected_mcp_routes()
+            .expect("legacy None");
+        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
+            omitted.protected_mcp_routes[0].target.as_ref()
+        else {
+            unreachable!()
+        };
+        assert_eq!(target.project_id, None);
+
+        let max = labby_runtime::gateway_config::MAX_PROJECT_ID_LEN;
+        let expected = "x".repeat(max);
+        let mut trimmed = config(Some(format!("  {expected}  ")));
+        trimmed.normalize_protected_mcp_routes().expect("128 bytes");
+        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
+            trimmed.protected_mcp_routes[0].target.as_ref()
+        else {
+            unreachable!()
+        };
+        assert_eq!(target.project_id.as_deref(), Some(expected.as_str()));
+
+        for invalid in ["   ".to_string(), "x".repeat(max + 1)] {
+            assert!(
+                config(Some(invalid))
+                    .normalize_protected_mcp_routes()
+                    .is_err()
+            );
+        }
+    }
+}

From 25e631d43372ce3bad826ab3954203660b846e29 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:43:53 -0400
Subject: [PATCH 03/16] fix: restore complete
 crates/labby-gateway/src/gateway/manager/tests/code_mode.rs

---
 .../src/gateway/manager/tests/code_mode.rs    | 707 +++++++++++++++++-
 1 file changed, 706 insertions(+), 1 deletion(-)

diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index c896c56ce..f9431d859 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -2297,4 +2297,709 @@ impl wiremock::Respond for OneShotHttpResponder {
                 self.list_tools_requests.fetch_add(1, Ordering::SeqCst);
                 wiremock::ResponseTemplate::new(200)
                     .set_delay(self.list_tools_delay)
-                    .set_body_json(json!({
\ No newline at end of file
+                    .set_body_json(json!({
+                        "jsonrpc": "2.0",
+                        "id": id,
+                        "result": {"tools": [{
+                            "name": self.tool,
+                            "description": "one-shot catalog fixture",
+                            "inputSchema": {"type": "object"}
+                        }]}
+                    }))
+            }
+            "prompts/list" => wiremock::ResponseTemplate::new(200)
+                .set_delay(self.list_prompts_delay)
+                .set_body_json(json!({
+                    "jsonrpc": "2.0",
+                    "id": id,
+                    "result": {"prompts": []}
+                })),
+            other => wiremock::ResponseTemplate::new(500)
+                .set_body_string(format!("unexpected MCP method: {other}")),
+        }
+    }
+}
+
+async fn cold_http_upstream(
+    name: &str,
+    responder: OneShotHttpResponder,
+) -> (wiremock::MockServer, UpstreamConfig) {
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::method("POST"))
+        .and(wiremock::matchers::path("/mcp"))
+        .respond_with(responder)
+        .mount(&server)
+        .await;
+    let mut upstream = fixture_http_upstream(name);
+    upstream.url = Some(format!("{}/mcp", server.uri()));
+    (server, upstream)
+}
+
+/// An upstream that accepts the connection and then refuses the MCP handshake.
+///
+/// Deliberately not `fixture_http_upstream`'s closed port: a connect to a
+/// closed port is refused instantly on Unix but sits in SYN retransmit on
+/// Windows, so that upstream can end a run either as a genuine failure or as
+/// still in flight. Tests that assert the *failure* arm specifically — as the
+/// negative cache must, since only a real failure may be suppressed — need a
+/// fixture that fails the same way on every platform. Accepting the connection
+/// and answering 500 does that.
+async fn refusing_http_upstream(name: &str) -> (wiremock::MockServer, UpstreamConfig) {
+    let server = wiremock::MockServer::start().await;
+    wiremock::Mock::given(wiremock::matchers::method("POST"))
+        .and(wiremock::matchers::path("/mcp"))
+        .respond_with(wiremock::ResponseTemplate::new(500))
+        .mount(&server)
+        .await;
+    let mut upstream = fixture_http_upstream(name);
+    upstream.url = Some(format!("{}/mcp", server.uri()));
+    (server, upstream)
+}
+
+/// A socket that accepts and never answers, so a connect stalls until its
+/// discovery timeout (far beyond any budget used here).
+async fn stalled_http_upstream(name: &str) -> UpstreamConfig {
+    let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
+        .await
+        .expect("bind stalled upstream fixture");
+    let addr = listener.local_addr().expect("listener addr");
+    tokio::spawn(async move {
+        while let Ok((socket, _)) = listener.accept().await {
+            tokio::spawn(async move {
+                let _socket = socket;
+                tokio::time::sleep(Duration::from_mins(2)).await;
+            });
+        }
+    });
+    let mut upstream = fixture_http_upstream(name);
+    upstream.url = Some(format!("http://{addr}/mcp"));
+    upstream
+}
+
+/// A manager with a fresh (cold) pool, the given Code Mode timeout, the
+/// one-shot catalog cache redirected to `cache_path`, and the discovery
+/// concurrency pinned to the product default of 3 so the tests do not depend
+/// on whatever the machine's process default happens to be. (An ambient
+/// `LABBY_UPSTREAM_DISCOVERY_CONCURRENCY` still overrides the config value.)
+async fn one_shot_manager_at(
+    upstreams: Vec<UpstreamConfig>,
+    timeout_ms: u64,
+    cache_path: PathBuf,
+) -> (GatewayManager, Arc<UpstreamPool>) {
+    one_shot_manager_with_concurrency(upstreams, timeout_ms, cache_path, 3).await
+}
+
+async fn one_shot_manager_with_concurrency(
+    upstreams: Vec<UpstreamConfig>,
+    timeout_ms: u64,
+    cache_path: PathBuf,
+    concurrency: usize,
+) -> (GatewayManager, Arc<UpstreamPool>) {
+    let (mut manager, pool) = code_mode_manager_with_upstreams(upstreams.clone()).await;
+    manager
+        .seed_config_unchecked_for_tests(GatewayConfig {
+            code_mode: CodeModeConfig {
+                enabled: true,
+                timeout_ms,
+                ..CodeModeConfig::default()
+            },
+            gateway: labby_runtime::gateway_config::GatewayPreferences {
+                upstream_discovery_concurrency: Some(concurrency),
+                ..labby_runtime::gateway_config::GatewayPreferences::default()
+            },
+            upstream: upstreams,
+            ..GatewayConfig::default()
+        })
+        .await;
+    manager.set_code_mode_catalog_cache_path_for_tests(cache_path);
+    (manager, pool)
+}
+
+async fn received_request_count(server: &wiremock::MockServer) -> usize {
+    server
+        .received_requests()
+        .await
+        .map_or(0, |requests| requests.len())
+}
+
+fn tool_ids(tools: &[UpstreamTool]) -> Vec<String> {
+    tools
+        .iter()
+        .map(|tool| format!("{}::{}", tool.upstream_name, tool.tool.name))
+        .collect()
+}
+
+/// Outer liveness guard for a budget-bounded one-shot catalog call.
+///
+/// These tests prove that the cold-connect budget, not a per-upstream
+/// discovery timeout, is what bounds the wait. The guard therefore has to stay
+/// below that discovery timeout — 30s for the stalled HTTP fixtures, since
+/// `UpstreamPool::new` uses the 30s `DEFAULT_REQUEST_TIMEOUT` — so a budget
+/// that stopped working still fails the test rather than merely running long.
+///
+/// Within that ceiling it should be as generous as possible: the calls being
+/// guarded finish in a few hundred milliseconds, and the guard is not the
+/// assertion. The returned catalog and the emitted warning carry the meaning.
+/// Earlier values as low as 5s left only a scheduling hiccup of headroom on a
+/// loaded machine, which is a flake waiting to happen and already bit the
+/// sibling Windows shard once. Note that the margin is not what makes these
+/// guards reliable: what did is [`with_captured_logs`] building the guarded
+/// future after it holds `TRACING_TEST_LOCK`, so queueing for that lock is no
+/// longer charged here. This value is headroom on top of that fix, not a
+/// substitute for it.
+const BUDGET_GUARD: Duration = Duration::from_secs(20);
+
+/// Run a future while capturing tracing output, returning its result and the
+/// captured JSON log lines.
+///
+/// Takes a closure rather than a future on purpose. `TRACING_TEST_LOCK` is
+/// process-wide and is held for the whole captured await, so under `cargo test`
+/// — one process for the entire crate — callers queue behind each other for as
+/// long as the current holder's call takes. `tokio::time::timeout` computes its
+/// deadline eagerly at construction, so building it at the call site would
+/// start the clock before this lock is acquired and charge that queue time to
+/// the caller's guard, failing it with `Elapsed` without the guarded call ever
+/// having been slow. Constructing the future here, after the lock is held,
+/// keeps a guard a measure of the call rather than of lock contention.
+#[allow(clippy::await_holding_lock)] // TRACING_TEST_LOCK must span the captured await
+async fn with_captured_logs<T, F>(build_future: impl FnOnce() -> F) -> (T, String)
+where
+    F: Future<Output = T>,
+{
+    let _tracing_lock = crate::test_support::TRACING_TEST_LOCK
+        .lock()
+        .unwrap_or_else(|error| error.into_inner());
+    let buffer = crate::test_support::SharedBuf::default();
+    let subscriber = tracing_subscriber::registry().with(
+        tracing_subscriber::fmt::layer()
+            .json()
+            .with_writer(buffer.clone())
+            .with_ansi(false)
+            .without_time(),
+    );
+    let tracing_guard = tracing::subscriber::set_default(subscriber);
+    let output = build_future().await;
+    drop(tracing_guard);
+    (output, crate::test_support::captured_logs(&buffer))
+}
+
+/// The budget warning line, if any, from captured logs.
+fn budget_warning(logs: &str) -> Option<&str> {
+    logs.lines()
+        .find(|line| line.contains("cold-connect budget exhausted"))
+}
+
+/// One-shot CLI catalog: dead and stalled upstreams ahead of a genuinely cold
+/// healthy one must not starve it. Uncached upstreams are probed concurrently
+/// under a budget derived from the Code Mode timeout (half of 6s here), the
+/// stalled straggler is named and omitted for this run, and the upstream that
+/// completed is persisted so the next run does not pay for it again. Serial
+/// probing would first wait out the stalled upstream's 30s discovery timeout,
+/// which the 15s guard rejects.
+///
+/// How the refused upstream is classified is deliberately not asserted: a
+/// connect to a closed port is refused immediately on Unix but can stay
+/// pending on Windows, so it may end the run either as a failure or as still
+/// in flight. Only that it never lands in the catalog or the cache matters
+/// here; the failure-reporting path is pinned by
+/// `one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast`.
+#[tokio::test]
+async fn one_shot_cli_catalog_bounds_cold_connects_and_persists_completed_upstreams() {
+    let stalled = stalled_http_upstream("alpha").await;
+    // `fixture_http_upstream` points at 127.0.0.1:9, which nothing listens on.
+    let dead = fixture_http_upstream("beta");
+    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    let (manager, _pool) = one_shot_manager_at(
+        vec![stalled.clone(), dead.clone(), healthy.clone()],
+        6_000,
+        cache_path.clone(),
+    )
+    .await;
+
+    let (tools, logs) = with_captured_logs(|| {
+        tokio::time::timeout(
+            BUDGET_GUARD,
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
+    })
+    .await;
+    let tools = tools
+        .expect("one-shot catalog must not wait out a stalled upstream's discovery timeout")
+        .expect("stalled and dead upstreams are omitted from the proxy, not an error");
+
+    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
+    assert_eq!(responder.list_tools_requests(), 1);
+    let warning = budget_warning(&logs).expect("the budget cutoff must be logged");
+    assert!(
+        warning.contains("in_flight_upstreams") && warning.contains("alpha"),
+        "the stalled upstream must be named as in flight: {warning}"
+    );
+    assert!(
+        !warning.contains("omega"),
+        "a completed upstream is not unfinished: {warning}"
+    );
+
+    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
+    assert_eq!(
+        cache
+            .fresh_tools("omega", &catalog_cache::fingerprint(&healthy))
+            .map(|tools| tools.len()),
+        Some(1),
+        "an upstream that completed must be persisted even though another stalled"
+    );
+    for (name, config) in [("alpha", &stalled), ("beta", &dead)] {
+        assert!(
+            cache
+                .fresh_tools(name, &catalog_cache::fingerprint(config))
+                .is_none(),
+            "{name} did not connect and must not be cached, so the next run retries it"
+        );
+    }
+}
+
+/// A scoped saved snippet must not wake unrelated upstreams on the one-shot
+/// cached catalog path. The live catalog already honors `allowed_upstreams`;
+/// this pins the CLI/snippet cache path to the same contract.
+#[tokio::test]
+async fn one_shot_cli_cached_catalog_honors_allowed_upstreams() {
+    let alpha_responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let omega_responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let (_alpha_server, alpha) = cold_http_upstream("alpha", alpha_responder.clone()).await;
+    let (_omega_server, omega) = cold_http_upstream("omega", omega_responder.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let (manager, _pool) = one_shot_manager_at(
+        vec![alpha, omega],
+        4_000,
+        cache_dir.path().join("codemode-catalog.json"),
+    )
+    .await;
+    let allowed = std::collections::BTreeSet::from(["omega".to_string()]);
+
+    let tools = manager
+        .code_mode_catalog_tools_cached_allowed(None, None, Some(&allowed))
+        .await
+        .expect("scoped cached catalog");
+
+    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
+    assert_eq!(omega_responder.list_tools_requests(), 1);
+    assert_eq!(
+        alpha_responder.list_tools_requests(),
+        0,
+        "unrelated upstream must not be cold-probed for a scoped saved snippet"
+    );
+}
+
+/// Partial means partial, not empty: when the budget ends before any upstream
+/// connected and nothing was served from cache, the one-shot catalog is an
+/// error naming what was still connecting, never a silently empty proxy.
+#[tokio::test]
+async fn one_shot_cli_catalog_errors_when_nothing_connects_within_the_budget() {
+    let stalled = stalled_http_upstream("alpha").await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let (manager, _pool) = one_shot_manager_at(
+        vec![stalled],
+        400,
+        cache_dir.path().join("codemode-catalog.json"),
+    )
+    .await;
+
+    let error = tokio::time::timeout(
+        BUDGET_GUARD,
+        manager.code_mode_catalog_tools_cached(None, None),
+    )
+    .await
+    .expect("the budget must bound the wait")
+    .expect_err("an empty catalog at the deadline is an error");
+    match error {
+        ToolError::Sdk { sdk_kind, message } => {
+            assert_eq!(sdk_kind, "upstream_connect_error");
+            assert!(
+                message.contains("still connecting") && message.contains("alpha"),
+                "the error must name the stalled upstream: {message}"
+            );
+        }
+        other => panic!("expected upstream_connect_error, got {other:?}"),
+    }
+}
+
+/// The same rule holds without a deadline: if every uncached upstream fails
+/// fast and nothing was cached, the run errors and names each failure, rather
+/// than handing the sandbox an empty proxy with exit code 0.
+#[tokio::test]
+async fn one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast() {
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let (manager, _pool) = one_shot_manager_at(
+        vec![
+            fixture_http_upstream("beta"),
+            fixture_http_upstream("gamma"),
+        ],
+        10_000,
+        cache_dir.path().join("codemode-catalog.json"),
+    )
+    .await;
+
+    let error = tokio::time::timeout(
+        BUDGET_GUARD,
+        manager.code_mode_catalog_tools_cached(None, None),
+    )
+    .await
+    .expect("connection refused fails fast")
+    .expect_err("all-failed with an empty cache is an error");
+    match error {
+        ToolError::Sdk { sdk_kind, message } => {
+            assert_eq!(sdk_kind, "upstream_connect_error");
+            assert!(
+                message.contains("beta") && message.contains("gamma"),
+                "the error must name every failed upstream: {message}"
+            );
+        }
+        other => panic!("expected upstream_connect_error, got {other:?}"),
+    }
+}
+
+/// Concurrent probes settle out of order, yet the catalog must follow the
+/// configured upstream order; and a fresh process (new manager and pool, same
+/// cache file) must serve a fresh cache entry without connecting again.
+#[tokio::test]
+async fn one_shot_cli_catalog_keeps_config_order_and_serves_repeat_runs_from_cache() {
+    let slow = OneShotHttpResponder::new("slow_tool", Duration::from_millis(300));
+    let fast = OneShotHttpResponder::new("fast_tool", Duration::ZERO);
+    let (_slow_server, zeta) = cold_http_upstream("zeta", slow.clone()).await;
+    let (_fast_server, alpha) = cold_http_upstream("alpha", fast.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    let upstreams = vec![zeta, alpha];
+
+    let (first_manager, _pool) =
+        one_shot_manager_at(upstreams.clone(), 10_000, cache_path.clone()).await;
+    let first = first_manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect("both cold upstreams connect");
+    assert_eq!(
+        tool_ids(&first),
+        vec!["zeta::slow_tool", "alpha::fast_tool"]
+    );
+    assert_eq!(slow.list_tools_requests(), 1);
+    assert_eq!(fast.list_tools_requests(), 1);
+
+    let slow_requests = received_request_count(&_slow_server).await;
+    let fast_requests = received_request_count(&_fast_server).await;
+
+    let (second_manager, _pool) = one_shot_manager_at(upstreams, 10_000, cache_path).await;
+    let second = second_manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect("fresh cache entries need no connects");
+    assert_eq!(tool_ids(&second), tool_ids(&first));
+    assert_eq!(
+        slow.list_tools_requests(),
+        1,
+        "a fresh cache entry must short-circuit without a connect"
+    );
+    assert_eq!(fast.list_tools_requests(), 1);
+    assert_eq!(
+        (
+            received_request_count(&_slow_server).await,
+            received_request_count(&_fast_server).await
+        ),
+        (slow_requests, fast_requests),
+        "a cache hit must send no request at all, not even discovery"
+    );
+}
+
+/// A cached upstream keeps the run partial rather than failed when a
+/// straggler misses the budget: the cached tools are served without a
+/// connect and the straggler is named.
+#[tokio::test]
+async fn one_shot_cli_catalog_serves_cached_upstreams_when_a_straggler_misses_the_budget() {
+    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    let (warm_manager, _pool) =
+        one_shot_manager_at(vec![healthy.clone()], 10_000, cache_path.clone()).await;
+    warm_manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect("warm the cache");
+    assert_eq!(responder.list_tools_requests(), 1);
+
+    let stalled = stalled_http_upstream("alpha").await;
+    let (manager, _pool) = one_shot_manager_at(vec![stalled, healthy], 400, cache_path).await;
+    let (tools, logs) = with_captured_logs(|| {
+        tokio::time::timeout(
+            BUDGET_GUARD,
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
+    })
+    .await;
+    let tools = tools
+        .expect("the budget must bound the wait")
+        .expect("a cached upstream keeps the catalog partial, not failed");
+
+    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
+    assert_eq!(
+        responder.list_tools_requests(),
+        1,
+        "the cached upstream must be served without a connect"
+    );
+    let warning = budget_warning(&logs).expect("the budget cutoff must be logged");
+    assert!(
+        warning.contains("alpha"),
+        "straggler must be named: {warning}"
+    );
+}
+
+/// An upstream whose tools landed before the budget ended is connected even if
+/// the connect's trailing prompt-cache refresh is what the deadline cut off:
+/// its tools are served and cached, and nothing is reported as unfinished.
+#[tokio::test]
+async fn one_shot_cli_catalog_keeps_an_upstream_whose_tools_landed_before_the_cutoff() {
+    let responder = OneShotHttpResponder::new("ping", Duration::ZERO)
+        .with_prompts_delay(Duration::from_mins(2));
+    let (_server, mut healthy) = cold_http_upstream("omega", responder).await;
+    healthy.proxy_prompts = true;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    let (manager, _pool) =
+        one_shot_manager_at(vec![healthy.clone()], 4_000, cache_path.clone()).await;
+
+    let (tools, logs) = with_captured_logs(|| {
+        tokio::time::timeout(
+            BUDGET_GUARD,
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
+    })
+    .await;
+    let tools = tools
+        .expect("the budget must bound the wait")
+        .expect("tools that landed before the cutoff are served");
+
+    assert_eq!(tool_ids(&tools), vec!["omega::ping"]);
+    assert!(
+        budget_warning(&logs).is_none(),
+        "a harvested upstream is not unfinished: {logs}"
+    );
+    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
+    assert_eq!(
+        cache
+            .fresh_tools("omega", &catalog_cache::fingerprint(&healthy))
+            .map(|tools| tools.len()),
+        Some(1)
+    );
+}
+
+/// OAuth upstreams stay subject-scoped on the one-shot path: with a subject
+/// their tools are served from the subject cache, without one they are
+/// skipped, and they are never written to the on-disk catalog cache.
+#[tokio::test]
+async fn one_shot_cli_catalog_keeps_oauth_upstreams_subject_scoped_and_uncached() {
+    let upstream = fixture_oauth_upstream("private", "http://unused.invalid/mcp");
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    let (manager, pool) =
+        one_shot_manager_at(vec![upstream.clone()], 10_000, cache_path.clone()).await;
+    pool.install_test_subject_tools_for_upstream(
+        &upstream,
+        "alice",
+        vec![rmcp::model::Tool::new(
+            "private_ping".to_string(),
+            "private ping".to_string(),
+            Arc::new(serde_json::Map::new()),
+        )],
+    )
+    .await;
+
+    let with_subject = manager
+        .code_mode_catalog_tools_cached(None, Some("alice"))
+        .await
+        .expect("subject-scoped tools are served");
+    assert_eq!(tool_ids(&with_subject), vec!["private::private_ping"]);
+
+    let without_subject = manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect("OAuth upstreams are skipped without a subject");
+    assert!(without_subject.is_empty());
+
+    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
+    assert!(
+        cache
+            .fresh_tools("private", &catalog_cache::fingerprint(&upstream))
+            .is_none(),
+        "subject-scoped catalogs must never reach the shared cache"
+    );
+}
+
+/// Probes that never got a discovery slot are reported as not attempted, not
+/// as still connecting: with one slot and a stalled upstream ahead of a
+/// healthy one, the healthy one is never contacted and the error says so.
+#[tokio::test]
+async fn one_shot_cli_catalog_names_unattempted_upstreams_when_stalled_probes_fill_the_slots() {
+    let stalled = stalled_http_upstream("alpha").await;
+    let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let (manager, _pool) = one_shot_manager_with_concurrency(
+        vec![stalled, healthy],
+        1_000,
+        cache_dir.path().join("codemode-catalog.json"),
+        1,
+    )
+    .await;
+
+    let error = tokio::time::timeout(
+        BUDGET_GUARD,
+        manager.code_mode_catalog_tools_cached(None, None),
+    )
+    .await
+    .expect("the budget must bound the wait")
+    .expect_err("nothing connected, so the catalog is an error");
+    assert_eq!(responder.list_tools_requests(), 0, "omega never got a slot");
+    match error {
+        ToolError::Sdk { sdk_kind, message } => {
+            assert_eq!(sdk_kind, "upstream_connect_error");
+            assert!(
+                message.contains("still connecting") && message.contains("alpha"),
+                "alpha was in flight: {message}"
+            );
+            assert!(
+                message.contains("not attempted") && message.contains("omega"),
+                "omega was never attempted: {message}"
+            );
+        }
+        other => panic!("expected upstream_connect_error, got {other:?}"),
+    }
+    let second = tokio::time::timeout(
+        BUDGET_GUARD,
+        manager.code_mode_catalog_tools_cached(None, None),
+    )
+    .await
+    .expect("second bounded run completes")
+    .expect("omega gets the next admission turn");
+    assert_eq!(tool_ids(&second), vec!["omega::ping"]);
+    assert_eq!(responder.list_tools_requests(), 1);
+}
+
+/// A fresh cache entry with zero tools (a resource- or prompt-only upstream)
+/// still counts as served from cache: a straggler missing the budget leaves
+/// the run partial with an empty tool list, not failed.
+#[tokio::test]
+async fn one_shot_cli_catalog_treats_a_cached_zero_tool_upstream_as_served() {
+    let quiet = fixture_http_upstream("omega");
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+    catalog_cache::merge_and_store(
+        cache_path.clone(),
+        vec![catalog_cache::CatalogCacheUpdate {
+            upstream_name: "omega".to_string(),
+            fingerprint: catalog_cache::fingerprint(&quiet),
+            tools: Vec::new(),
+        }],
+        Vec::new(),
+    )
+    .await;
+
+    let stalled = stalled_http_upstream("alpha").await;
+    let (manager, _pool) = one_shot_manager_at(vec![stalled, quiet], 400, cache_path).await;
+    let (tools, logs) = with_captured_logs(|| {
+        tokio::time::timeout(
+            BUDGET_GUARD,
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
+    })
+    .await;
+    let tools = tools
+        .expect("the budget must bound the wait")
+        .expect("a cached zero-tool upstream keeps the run partial, not failed");
+    assert!(tools.is_empty());
+    let warning = budget_warning(&logs).expect("the straggler must be logged");
+    assert!(
+        warning.contains("alpha"),
+        "straggler must be named: {warning}"
+    );
+}
+
+/// A genuinely failing upstream must not cost a connect on every invocation.
+///
+/// `fixture_http_upstream` points at the discard port, so the probe fails fast
+/// rather than stalling — this is the failure path, distinct from the
+/// budget-exhaustion paths, and the only one the negative cache may suppress.
+#[tokio::test]
+async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+
+    let (dead_server, dead) = refusing_http_upstream("dead").await;
+    let (server, healthy) =
+        cold_http_upstream("healthy", OneShotHttpResponder::new("ping", Duration::ZERO)).await;
+    let (manager, _pool) =
+        one_shot_manager_at(vec![dead.clone(), healthy], 4_000, cache_path.clone()).await;
+
+    let first = manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect("first run should serve the healthy upstream");
+    assert_eq!(
+        first
+            .iter()
+            .map(|tool| tool.tool.name.as_ref())
+            .collect::<Vec<_>>(),
+        vec!["ping"]
+    );
+
+    // The failure is now on disk, and the healthy upstream is cached, so the
+    // second run must reach neither the network nor the dead upstream.
+    let cache = catalog_cache::CatalogCache::load_from(&cache_path);
+    assert!(
+        cache.probe_suppressed("dead", &catalog_cache::fingerprint(&dead)),
+        "a failed probe must leave a negative entry"
+    );
+
+    let (second, logs) =
+        with_captured_logs(|| manager.code_mode_catalog_tools_cached(None, None)).await;
+    let second = second.expect("second run should still serve the cached healthy upstream");
+    assert_eq!(
+        second
+            .iter()
+            .map(|tool| tool.tool.name.as_ref())
+            .collect::<Vec<_>>(),
+        vec!["ping"]
+    );
+    assert!(
+        logs.contains("suppressed"),
+        "a suppressed upstream must be reported, not silently dropped: {logs}"
+    );
+    drop(server);
+    drop(dead_server);
+}
+
+/// Suppression must never be the reason a catalog comes back empty.
+#[tokio::test]
+async fn an_entirely_suppressed_fleet_is_an_error_not_an_empty_catalog() {
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let cache_path = cache_dir.path().join("codemode-catalog.json");
+
+    let (dead_server, dead) = refusing_http_upstream("dead").await;
+    let (manager, _pool) = one_shot_manager_at(vec![dead], 4_000, cache_path.clone()).await;
+
+    manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect_err("a fleet with nothing reachable is already an error");
+
+    let error = manager
+        .code_mode_catalog_tools_cached(None, None)
+        .await
+        .expect_err("suppression must not turn that into a silent empty catalog");
+    let message = format!("{error}");
+    assert!(
+        message.contains("suppressed") && message.contains("dead"),
+        "the error must name the suppressed upstream: {message}"
+    );
+    drop(dead_server);
+}

From 26cd8e16ba81ed06c71a251f7f798b3b45ed16b3 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:43:55 -0400
Subject: [PATCH 04/16] fix: restore complete
 crates/labby-runtime/src/gateway_config.rs

---
 crates/labby-runtime/src/gateway_config.rs | 609 ++++++++++++++++++++-
 1 file changed, 608 insertions(+), 1 deletion(-)

diff --git a/crates/labby-runtime/src/gateway_config.rs b/crates/labby-runtime/src/gateway_config.rs
index c0cf39841..85800105d 100644
--- a/crates/labby-runtime/src/gateway_config.rs
+++ b/crates/labby-runtime/src/gateway_config.rs
@@ -2151,4 +2151,611 @@ expose_code_mode = true
         }
 
         let unlabelled: UpstreamConfig =
-            toml::from_str("name=\"asana\"\nurl=\"https://x/mcp\"\n").unwrap();
\ No newline at end of file
+            toml::from_str("name=\"asana\"\nurl=\"https://x/mcp\"\n").unwrap();
+        assert!(
+            !toml::to_string(&unlabelled)
+                .unwrap()
+                .contains("display_name"),
+            "configs without a label keep serializing byte-identically"
+        );
+    }
+
+    #[test]
+    fn the_first_party_origin_label_is_reserved_from_upstreams() {
+        let cfg: UpstreamConfig =
+            toml::from_str("name=\"labby\"\nurl=\"https://x/mcp\"\nproxy_skills=true\n").unwrap();
+        let error = cfg
+            .validate()
+            .expect_err("an upstream must not claim Labby's own skill namespace");
+        assert!(format!("{error}").contains("reserved"));
+
+        // ...but only when it actually proxies skills; the name is otherwise
+        // unremarkable and must not break an existing deployment.
+        let without: UpstreamConfig =
+            toml::from_str("name=\"labby\"\nurl=\"https://x/mcp\"\n").unwrap();
+        without.validate().expect("no skills, no reservation");
+    }
+
+    #[test]
+    fn omitted_transport_preserves_legacy_inference() {
+        let http: UpstreamConfig =
+            toml::from_str("name=\"http\"\nurl=\"https://example.com/mcp\"\n").unwrap();
+        assert_eq!(http.effective_transport(), Some(UpstreamTransport::Http));
+
+        let websocket: UpstreamConfig =
+            toml::from_str("name=\"ws\"\nurl=\"wss://example.com/mcp\"\n").unwrap();
+        assert_eq!(
+            websocket.effective_transport(),
+            Some(UpstreamTransport::Websocket)
+        );
+
+        let stdio: UpstreamConfig = toml::from_str("name=\"stdio\"\ncommand=\"server\"\n").unwrap();
+        assert_eq!(stdio.effective_transport(), Some(UpstreamTransport::Stdio));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn filesystem_unix_socket_transport_parses_and_validates() {
+        let cfg: UpstreamConfig = toml::from_str(
+            "name=\"local\"\ntransport=\"unix_socket\"\nsocket_path=\"/tmp/local-mcp.sock\"\nurl=\"http://local.internal/mcp\"\n",
+        )
+        .unwrap();
+
+        assert_eq!(
+            cfg.effective_transport(),
+            Some(UpstreamTransport::UnixSocket)
+        );
+        assert_eq!(cfg.socket_path.as_deref(), Some("/tmp/local-mcp.sock"));
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn socket_path_without_unix_transport_is_rejected() {
+        let cfg: UpstreamConfig = toml::from_str(
+            "name=\"bad\"\nsocket_path=\"/tmp/local-mcp.sock\"\nurl=\"http://local.internal/mcp\"\n",
+        )
+        .unwrap();
+
+        let error = cfg.validate().unwrap_err();
+        assert!(matches!(error, ConfigError::InvalidTransport { .. }));
+        assert!(error.to_string().contains("socket_path requires transport"));
+    }
+
+    #[cfg(unix)]
+    #[test]
+    fn unix_socket_requires_url_and_valid_path() {
+        let missing_url: UpstreamConfig = toml::from_str(
+            "name=\"bad\"\ntransport=\"unix_socket\"\nsocket_path=\"/tmp/local-mcp.sock\"\n",
+        )
+        .unwrap();
+        assert!(missing_url.validate().is_err());
+
+        let empty_abstract_socket: UpstreamConfig = toml::from_str(
+            "name=\"bad\"\ntransport=\"unix_socket\"\nsocket_path=\"@\"\nurl=\"http://local.internal/mcp\"\n",
+        )
+        .unwrap();
+        assert!(empty_abstract_socket.validate().is_err());
+
+        #[cfg(target_os = "linux")]
+        {
+            let abstract_socket: UpstreamConfig = toml::from_str(
+                "name=\"local\"\ntransport=\"unix_socket\"\nsocket_path=\"@local-mcp\"\nurl=\"http://local.internal/mcp\"\n",
+            )
+            .unwrap();
+            assert!(abstract_socket.validate().is_ok());
+        }
+    }
+
+    #[test]
+    fn custom_headers_validate_before_pool_publication() {
+        let valid: UpstreamConfig = toml::from_str(
+            "name=\"local\"\nurl=\"http://local.internal/mcp\"\n[headers]\nx-labby-test=\"present\"\n",
+        )
+        .unwrap();
+        assert!(valid.validate().is_ok());
+
+        for invalid_toml in [
+            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\nauthorization=\"Bearer secret\"\n",
+            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\n\"bad header\"=\"value\"\n",
+            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\n[headers]\nx-test=\"bad\\nvalue\"\n",
+        ] {
+            let cfg: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
+            assert!(cfg.validate().is_err());
+        }
+    }
+
+    #[test]
+    fn inferred_transports_enforce_their_field_contracts() {
+        for invalid_toml in [
+            "name=\"bad\"\ncommand=\"server\"\n[headers]\nx-test=\"value\"\n",
+            "name=\"bad\"\nurl=\"ws://local.internal/mcp\"\n[headers]\nx-test=\"value\"\n",
+            "name=\"bad\"\nurl=\"http://local.internal/mcp\"\ncommand=\"server\"\n",
+            "name=\"bad\"\n",
+        ] {
+            let cfg: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
+            assert!(
+                cfg.validate().is_err(),
+                "config should fail: {invalid_toml}"
+            );
+        }
+    }
+
+    #[test]
+    fn stdio_preserves_named_bearer_environment_injection() {
+        let cfg: UpstreamConfig = toml::from_str(
+            "name=\"stdio\"\ncommand=\"server\"\nbearer_token_env=\"SERVER_TOKEN\"\n",
+        )
+        .unwrap();
+
+        assert_eq!(cfg.effective_transport(), Some(UpstreamTransport::Stdio));
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn explicit_transport_rejects_conflicting_fields() {
+        let cfg: UpstreamConfig = toml::from_str(
+            "name=\"bad\"\ntransport=\"stdio\"\ncommand=\"server\"\nurl=\"http://local.internal/mcp\"\n",
+        )
+        .unwrap();
+        assert!(cfg.validate().is_err());
+    }
+
+    #[test]
+    fn google_provider_oauth_requires_https_preregistered_secret_and_scopes() {
+        let valid: UpstreamConfig = toml::from_str(
+            r#"
+name = "google-calendar"
+url = "https://calendarmcp.googleapis.com/mcp/v1"
+[oauth]
+mode = "authorization_code_pkce"
+scopes = ["https://www.googleapis.com/auth/calendar.events.readonly"]
+[oauth.credential]
+source = "google_provider"
+account = "admin@example.com"
+[oauth.registration]
+strategy = "preregistered"
+client_id = "google-client"
+client_secret_env = "LABBY_GOOGLE_CLIENT_SECRET"
+"#,
+        )
+        .unwrap();
+        assert!(valid.validate().is_ok());
+
+        for invalid_toml in [
+            r#"
+name = "google-calendar"
+url = "http://calendarmcp.googleapis.com/mcp/v1"
+[oauth]
+mode = "authorization_code_pkce"
+scopes = ["calendar"]
+[oauth.credential]
+source = "google_provider"
+[oauth.registration]
+strategy = "preregistered"
+client_id = "google-client"
+client_secret_env = "SECRET"
+"#,
+            r#"
+name = "google-calendar"
+url = "https://calendarmcp.googleapis.com/mcp/v1"
+[oauth]
+mode = "authorization_code_pkce"
+scopes = ["calendar"]
+[oauth.credential]
+source = "google_provider"
+[oauth.registration]
+strategy = "dynamic"
+"#,
+            r#"
+name = "google-calendar"
+url = "https://calendarmcp.googleapis.com/mcp/v1"
+[oauth]
+mode = "authorization_code_pkce"
+scopes = ["calendar"]
+[oauth.credential]
+source = "google_provider"
+[oauth.registration]
+strategy = "preregistered"
+client_id = "google-client"
+"#,
+            r#"
+name = "google-calendar"
+url = "https://calendarmcp.googleapis.com/mcp/v1"
+[oauth]
+mode = "authorization_code_pkce"
+[oauth.credential]
+source = "google_provider"
+[oauth.registration]
+strategy = "preregistered"
+client_id = "google-client"
+client_secret_env = "SECRET"
+"#,
+        ] {
+            let config: UpstreamConfig = toml::from_str(invalid_toml).unwrap();
+            assert!(matches!(
+                config.validate(),
+                Err(ConfigError::InvalidOauth { .. })
+            ));
+        }
+    }
+
+    #[test]
+    fn google_provider_credential_debug_redacts_account_selector() {
+        let source = UpstreamOauthCredentialSource::GoogleProvider {
+            account: Some("admin@example.com".to_string()),
+        };
+        let debug = format!("{source:?}");
+        assert!(!debug.contains("admin@example.com"));
+        assert!(debug.contains("<redacted>"));
+    }
+
+    #[test]
+    fn code_mode_config_defaults_roundtrip() {
+        let cfg: CodeModeConfig = toml::from_str("").unwrap();
+        let expected = CodeModeConfig::default();
+        assert_eq!(cfg, expected);
+        assert!(cfg.enabled);
+        assert!(cfg.trusted_read_only_tools.is_empty());
+        assert!(cfg.mcp_ui_enabled);
+        assert!(cfg.trace_params);
+        assert_eq!(cfg.timeout_ms, 30_000);
+        assert_eq!(cfg.token_estimate_divisor, 4);
+    }
+
+    #[test]
+    fn code_mode_timeout_range_boundaries() {
+        for (timeout_ms, accepted) in [
+            (0, false),
+            (1, true),
+            (MAX_CODE_MODE_TIMEOUT_MS, true),
+            (MAX_CODE_MODE_TIMEOUT_MS + 1, false),
+        ] {
+            let cfg = CodeModeConfig {
+                timeout_ms,
+                ..CodeModeConfig::default()
+            };
+            let result = cfg.validate();
+            assert_eq!(
+                result.is_ok(),
+                accepted,
+                "timeout_ms={timeout_ms}: {result:?}"
+            );
+            if !accepted {
+                assert!(matches!(
+                    result,
+                    Err(ConfigError::InvalidCodeModeTimeout { value }) if value == timeout_ms
+                ));
+            }
+        }
+    }
+
+    #[test]
+    fn a_legacy_trusted_read_only_tools_list_still_parses_but_is_never_echoed_back() {
+        // The field is retired: it exists only so an existing config file keeps
+        // parsing. It must not round-trip, or an operator reading the config back
+        // would see a populated list that looks like a live security control.
+        let cfg: CodeModeConfig =
+            toml::from_str("trusted_read_only_tools = [\"dookie::read_file\"]\n").unwrap();
+        assert_eq!(cfg.trusted_read_only_tools, vec!["dookie::read_file"]);
+
+        let round_tripped = serde_json::to_value(&cfg).unwrap();
+        assert!(
+            round_tripped.get("trusted_read_only_tools").is_none(),
+            "the retired field must never be serialized back to any surface"
+        );
+    }
+
+    #[test]
+    fn code_mode_mcp_ui_can_be_enabled_in_toml() {
+        let cfg: CodeModeConfig = toml::from_str(
+            "mcp_ui_enabled = true
+",
+        )
+        .unwrap();
+        assert!(cfg.mcp_ui_enabled);
+        assert!(cfg.enabled);
+    }
+
+    #[test]
+    fn mcp_apps_config_defaults_all_managed_apps_enabled() {
+        let cfg: McpAppsConfig = toml::from_str("").unwrap();
+        assert_eq!(cfg, McpAppsConfig::default());
+        assert!(cfg.manager);
+        assert!(cfg.add_server);
+        assert!(cfg.server_logs);
+        assert!(cfg.gateway_status);
+        assert!(cfg.settings);
+    }
+
+    #[test]
+    fn documented_labby_app_defaults_match_code() {
+        // GATEWAY.md is the operator-facing statement of the Labby-owned app
+        // surface defaults. Code Mode and every managed MCP App now default
+        // on, so the doc must not still promise an off-by-default posture.
+        let doc = include_str!("../../../docs/services/GATEWAY.md");
+        assert!(CodeModeConfig::default().enabled);
+        assert!(CodeModeConfig::default().mcp_ui_enabled);
+        assert_eq!(
+            McpAppsConfig::default(),
+            McpAppsConfig {
+                manager: true,
+                add_server: true,
+                server_logs: true,
+                gateway_status: true,
+                settings: true,
+            }
+        );
+        assert!(
+            !doc.contains("defaults to `false` and must be explicitly enabled"),
+            "docs/services/GATEWAY.md still documents the retired off-by-default app posture"
+        );
+        assert!(
+            doc.contains("defaults to `true`") || doc.contains("enabled by default"),
+            "docs/services/GATEWAY.md must state that Labby-owned app surfaces default on"
+        );
+    }
+
+    #[test]
+    fn mcp_apps_config_supports_independent_visibility_switches() {
+        let cfg: McpAppsConfig = toml::from_str(
+            "manager = true\nadd_server = false\nserver_logs = true\ngateway_status = false\nsettings = false\n",
+        )
+        .unwrap();
+        assert!(cfg.manager);
+        assert!(!cfg.add_server);
+        assert!(cfg.server_logs);
+        assert!(!cfg.gateway_status);
+        assert!(!cfg.settings);
+    }
+
+    #[test]
+    fn semantic_search_defaults_to_unconfigured() {
+        let cfg = CodeModeConfig::default();
+        assert!(cfg.semantic_search.tei_url.is_none());
+        assert!(!cfg.semantic_search.is_configured());
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn semantic_search_with_valid_http_url_is_configured_and_valid() {
+        let mut cfg = CodeModeConfig::default();
+        cfg.semantic_search.tei_url = Some("http://localhost:52000".to_string());
+        assert!(cfg.semantic_search.is_configured());
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn semantic_search_with_https_url_is_valid() {
+        let mut cfg = CodeModeConfig::default();
+        cfg.semantic_search.tei_url = Some("https://tei.internal.example:8443".to_string());
+        assert!(cfg.validate().is_ok());
+    }
+
+    #[test]
+    fn semantic_search_with_non_http_scheme_fails_validation() {
+        let mut cfg = CodeModeConfig::default();
+        cfg.semantic_search.tei_url = Some("ftp://example.com".to_string());
+        let err = cfg.validate().unwrap_err();
+        assert!(matches!(
+            err,
+            ConfigError::InvalidSemanticSearchTeiUrl { .. }
+        ));
+    }
+
+    #[test]
+    fn semantic_search_with_malformed_url_fails_validation() {
+        let mut cfg = CodeModeConfig::default();
+        cfg.semantic_search.tei_url = Some("not a url at all".to_string());
+        let err = cfg.validate().unwrap_err();
+        assert!(matches!(
+            err,
+            ConfigError::InvalidSemanticSearchTeiUrl { .. }
+        ));
+    }
+
+    #[test]
+    fn semantic_search_blend_weight_out_of_range_fails_validation() {
+        let mut cfg = CodeModeConfig::default();
+        cfg.semantic_search.blend_weight = 1.5;
+        let err = cfg.validate().unwrap_err();
+        assert!(matches!(
+            err,
+            ConfigError::InvalidSemanticSearchBlendWeight { .. }
+        ));
+    }
+
+    #[test]
+    fn semantic_search_toml_round_trips_with_defaults_when_omitted() {
+        // An existing config.toml with a `[code_mode]` section but no
+        // `semantic_search` subsection must still deserialize (backward
+        // compatibility with every config.toml written before this feature).
+        let toml_str = "enabled = true\ntimeout_ms = 30000\n";
+        let cfg: CodeModeConfig = toml::from_str(toml_str).unwrap();
+        assert!(cfg.semantic_search.tei_url.is_none());
+        assert!(!cfg.semantic_search.is_configured());
+    }
+
+    #[test]
+    fn protected_route_backend_mcp_path_defaults_to_mcp() {
+        let route: ProtectedMcpRouteConfig = toml::from_str(
+            "name=\"r\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\nbackend_url=\"http://10.0.0.1:3100/mcp\"\n",
+        )
+        .unwrap();
+        assert_eq!(route.backend_mcp_path, "/mcp");
+        assert!(route.enabled);
+        assert_eq!(route.scopes, vec!["mcp:read", "mcp:write"]);
+    }
+
+    /// Bead lab-eyeuv: `__in_process__*` is the namespace of the synthetic
+    /// builtin-service peers (issue #210 FU-1). A configured upstream using
+    /// that prefix would shadow a builtin's catalog entry and capture its
+    /// Code Mode tool calls, so it is rejected at load rather than merely
+    /// discouraged by comment.
+    #[test]
+    fn upstream_name_rejects_the_reserved_in_process_prefix() {
+        let cfg: UpstreamConfig =
+            toml::from_str("name=\"__in_process__gateway\"\nurl=\"https://example.com/mcp\"\n")
+                .unwrap();
+
+        let error = cfg
+            .validate()
+            .expect_err("reserved prefix must be rejected");
+        let rendered = error.to_string();
+        assert!(rendered.contains("__in_process__"), "{rendered}");
+
+        // Ordinary names that merely contain the token are fine — only the
+        // prefix is reserved.
+        let ok: UpstreamConfig =
+            toml::from_str("name=\"my__in_process__thing\"\nurl=\"https://example.com/mcp\"\n")
+                .unwrap();
+        assert!(ok.validate().is_ok());
+    }
+
+    /// A protected route must not be able to opt itself into builtin tools by
+    /// naming a synthetic peer in its upstream allowlist — the `fail closed`
+    /// property FU-1 documents is now enforced, not assumed.
+    #[test]
+    fn protected_route_rejects_reserved_in_process_upstreams() {
+        let mut route: ProtectedMcpRouteConfig = toml::from_str(
+            "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
+        )
+        .unwrap();
+        route.backend_url = String::new();
+        route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
+            ProtectedGatewaySubsetTarget {
+                project_id: None,
+                loadout: None,
+                upstreams: vec![format!("{IN_PROCESS_UPSTREAM_PREFIX}setup")],
+                services: Vec::new(),
+                expose_code_mode: false,
+            },
+        ));
+        let mut cfg = GatewayConfig {
+            protected_mcp_routes: vec![route],
+            ..GatewayConfig::default()
+        };
+
+        let error = cfg
+            .normalize_protected_mcp_routes()
+            .expect_err("a protected route must not name an in-process peer");
+        let rendered = error.to_string();
+        assert!(rendered.contains("__in_process__setup"), "{rendered}");
+        assert!(rendered.contains("target.services"), "{rendered}");
+    }
+
+    /// The reserved prefix and the name builder in `labby-gateway` must stay
+    /// in lockstep; the builder formats with this constant.
+    #[test]
+    fn in_process_prefix_constant_is_stable() {
+        assert_eq!(IN_PROCESS_UPSTREAM_PREFIX, "__in_process__");
+    }
+    /// `gateway.loadout.*` responses must always carry `upstreams` and
+    /// `services` as arrays. Omitting an empty selection made every JSON
+    /// consumer that treats them as required arrays fail on a Loadout that
+    /// picked only upstreams or only services.
+    #[test]
+    fn loadout_json_always_carries_both_selection_arrays() {
+        let upstreams_only = GatewayLoadoutConfig {
+            name: "sd".to_string(),
+            upstreams: vec!["chrome-devtools".to_string()],
+            ..GatewayLoadoutConfig::default()
+        };
+        let services_only = GatewayLoadoutConfig {
+            name: "ops".to_string(),
+            services: vec!["gateway".to_string()],
+            ..GatewayLoadoutConfig::default()
+        };
+
+        for loadout in [&upstreams_only, &services_only] {
+            let value = serde_json::to_value(loadout).expect("loadout serializes to JSON");
+            let object = value.as_object().expect("loadout serializes as an object");
+            assert!(
+                object
+                    .get("upstreams")
+                    .is_some_and(serde_json::Value::is_array),
+                "upstreams must always be an array: {value}"
+            );
+            assert!(
+                object
+                    .get("services")
+                    .is_some_and(serde_json::Value::is_array),
+                "services must always be an array: {value}"
+            );
+        }
+
+        assert_eq!(
+            serde_json::to_value(&services_only)
+                .expect("loadout serializes to JSON")
+                .get("upstreams"),
+            Some(&serde_json::json!([])),
+            "a services-only Loadout still reports an empty upstream selection"
+        );
+    }
+
+    /// Always-serialized selections must survive a TOML round trip, including
+    /// the explicit empty arrays now written into `config.toml`.
+    #[test]
+    fn loadout_toml_round_trips_empty_selection_arrays() {
+        let services_only = GatewayLoadoutConfig {
+            name: "ops".to_string(),
+            services: vec!["gateway".to_string()],
+            ..GatewayLoadoutConfig::default()
+        };
+
+        let rendered = toml::to_string(&services_only).expect("loadout serializes to TOML");
+        assert!(rendered.contains("upstreams = []"), "{rendered}");
+
+        let parsed: GatewayLoadoutConfig =
+            toml::from_str(&rendered).expect("loadout parses back from TOML");
+        assert_eq!(parsed, services_only);
+    }
+    #[test]
+    fn protected_route_project_id_normalization_is_bounded_and_compatible() {
+        fn config(project_id: Option<String>) -> GatewayConfig {
+            let mut route: ProtectedMcpRouteConfig = toml::from_str(
+                "name=\"scoped\"\npublic_host=\"mcp.example.com\"\npublic_path=\"/svc\"\n",
+            )
+            .unwrap();
+            route.backend_url = String::new();
+            route.target = Some(ProtectedMcpRouteTarget::GatewaySubset(
+                ProtectedGatewaySubsetTarget {
+                    project_id,
+                    ..Default::default()
+                },
+            ));
+            GatewayConfig {
+                protected_mcp_routes: vec![route],
+                ..Default::default()
+            }
+        }
+
+        let mut omitted = config(None);
+        omitted
+            .normalize_protected_mcp_routes()
+            .expect("legacy None");
+        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
+            omitted.protected_mcp_routes[0].target.as_ref()
+        else {
+            unreachable!()
+        };
+        assert_eq!(target.project_id, None);
+
+        let expected = "x".repeat(MAX_PROJECT_ID_LEN);
+        let mut trimmed = config(Some(format!("  {expected}  ")));
+        trimmed.normalize_protected_mcp_routes().expect("128 bytes");
+        let Some(ProtectedMcpRouteTarget::GatewaySubset(target)) =
+            trimmed.protected_mcp_routes[0].target.as_ref()
+        else {
+            unreachable!()
+        };
+        assert_eq!(target.project_id.as_deref(), Some(expected.as_str()));
+
+        for invalid in ["   ".to_string(), "x".repeat(MAX_PROJECT_ID_LEN + 1)] {
+            assert!(
+                config(Some(invalid))
+                    .normalize_protected_mcp_routes()
+                    .is_err()
+            );
+        }
+    }
+}

From 74edfc5fd61206d3b990cf7fc3965480d006b26f Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:43:58 -0400
Subject: [PATCH 05/16] fix: restore complete
 crates/labby/src/dispatch/setup/settings.rs


From 6e257cf4d7f8d73b0cbed255749b68a43f6f5a26 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:48:06 -0400
Subject: [PATCH 06/16] fix(codemode): bound saved snippet file reads

---
 crates/labby-codemode/src/snippet/store.rs | 32 ++++++++++++++++++++--
 1 file changed, 30 insertions(+), 2 deletions(-)

diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index 9c37d3ff6..d464175b2 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -1,4 +1,5 @@
 use std::fs;
+use std::io::Read;
 use std::path::{Path, PathBuf};
 
 use std::collections::BTreeMap;
@@ -397,7 +398,7 @@ fn collect_snippets(
             continue;
         }
         names.insert(stem.to_string());
-        let body = match fs::read_to_string(&path) {
+        let body = match read_snippet_body(&path) {
             Ok(body) => body,
             Err(_) => continue,
         };
@@ -436,12 +437,27 @@ fn has_snippet_extension(path: &Path) -> bool {
         .is_some_and(|ext| SNIPPET_EXTENSIONS.contains(&ext))
 }
 
+fn read_snippet_body(path: &Path) -> Result<String, ToolError> {
+    let file = fs::File::open(path).map_err(|e| io_error("open snippet", path, e))?;
+    let mut body = String::new();
+    file.take((MAX_SNIPPET_FILE_BYTES + 1) as u64)
+        .read_to_string(&mut body)
+        .map_err(|e| io_error("read snippet", path, e))?;
+    if body.len() > MAX_SNIPPET_FILE_BYTES {
+        return Err(ToolError::InvalidParam {
+            message: format!("snippet file exceeds {MAX_SNIPPET_FILE_BYTES} bytes"),
+            param: "body".to_string(),
+        });
+    }
+    Ok(body)
+}
+
 fn read_resolved(
     name: &str,
     source: SnippetSource,
     path: PathBuf,
 ) -> Result<ResolvedSnippet, ToolError> {
-    let body = fs::read_to_string(&path).map_err(|e| io_error("read snippet", &path, e))?;
+    let body = read_snippet_body(&path)?;
     validate_snippet_body(name, &body)?;
     let (description, tags, inputs, tools) =
         snippet_metadata_fields(frontmatter(&body)?.filter(|m| m.name == name));
@@ -1293,6 +1309,18 @@ mod tests {
         assert!(format!("{error}").contains("snippet file exceeds"));
     }
 
+    #[test]
+    fn read_resolved_bounds_file_bytes_before_full_read() {
+        let dir = tempfile::tempdir().expect("temp snippets");
+        let path = dir.path().join("demo.js");
+        fs::write(&path, vec![b'x'; MAX_SNIPPET_FILE_BYTES + 4096])
+            .expect("write oversized fixture");
+
+        let error = read_resolved("demo", SnippetSource::User, path)
+            .expect_err("oversized on-disk snippet must fail before a full read");
+        assert!(format!("{error}").contains("snippet file exceeds"));
+    }
+
     #[test]
     fn merge_snippet_input_rejects_unknown_declared_inputs() {
         let body = "---\nname: demo\ndescription: Demo snippet\ninputs:\n  host:\n    type: string\n    default: node-a\n---\n\n```js\nasync (input) => input\n```\n";

From 1ce0f6cb6422d463fad7756136586055a6a89152 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:50:23 -0400
Subject: [PATCH 07/16] fix(codemode): validate bounded snippet bytes

---
 crates/labby-codemode/src/snippet/store.rs | 22 ++++++++++++++++++----
 1 file changed, 18 insertions(+), 4 deletions(-)

diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index d464175b2..d8e853842 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -439,17 +439,20 @@ fn has_snippet_extension(path: &Path) -> bool {
 
 fn read_snippet_body(path: &Path) -> Result<String, ToolError> {
     let file = fs::File::open(path).map_err(|e| io_error("open snippet", path, e))?;
-    let mut body = String::new();
+    let mut bytes = Vec::new();
     file.take((MAX_SNIPPET_FILE_BYTES + 1) as u64)
-        .read_to_string(&mut body)
+        .read_to_end(&mut bytes)
         .map_err(|e| io_error("read snippet", path, e))?;
-    if body.len() > MAX_SNIPPET_FILE_BYTES {
+    if bytes.len() > MAX_SNIPPET_FILE_BYTES {
         return Err(ToolError::InvalidParam {
             message: format!("snippet file exceeds {MAX_SNIPPET_FILE_BYTES} bytes"),
             param: "body".to_string(),
         });
     }
-    Ok(body)
+    String::from_utf8(bytes).map_err(|_| ToolError::InvalidParam {
+        message: "snippet file must contain valid UTF-8".to_string(),
+        param: "body".to_string(),
+    })
 }
 
 fn read_resolved(
@@ -1321,6 +1324,17 @@ mod tests {
         assert!(format!("{error}").contains("snippet file exceeds"));
     }
 
+    #[test]
+    fn read_resolved_rejects_non_utf8_snippet_files() {
+        let dir = tempfile::tempdir().expect("temp snippets");
+        let path = dir.path().join("demo.js");
+        fs::write(&path, [0xff, 0xfe, 0xfd]).expect("write non-UTF8 fixture");
+
+        let error = read_resolved("demo", SnippetSource::User, path)
+            .expect_err("saved snippets are UTF-8 text");
+        assert!(format!("{error}").contains("valid UTF-8"));
+    }
+
     #[test]
     fn merge_snippet_input_rejects_unknown_declared_inputs() {
         let body = "---\nname: demo\ndescription: Demo snippet\ninputs:\n  host:\n    type: string\n    default: node-a\n---\n\n```js\nasync (input) => input\n```\n";

From 0b3ec732ca115e63763edfc8e3adb5eb56e8a0dc Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:53:11 -0400
Subject: [PATCH 08/16] fix(codemode): close snippet review gaps

---
 .../src/gateway/manager/code_mode_runtime.rs  |  3 +++
 .../src/gateway/manager/tests/code_mode.rs    | 26 +++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
index ba8a605d6..bc3540192 100644
--- a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
+++ b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
@@ -471,6 +471,9 @@ impl GatewayManager {
         if !cfg.code_mode.enabled {
             return Ok(Vec::new());
         }
+        if allowed_upstreams.is_some_and(BTreeSet::is_empty) {
+            return Ok(Vec::new());
+        }
 
         let cache_path = self.code_mode_catalog_cache_path();
         let cache = catalog_cache::CatalogCache::load_from(&cache_path);
diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index f9431d859..1c79ccd0c 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -2592,6 +2592,32 @@ async fn one_shot_cli_cached_catalog_honors_allowed_upstreams() {
     );
 }
 
+#[tokio::test]
+async fn one_shot_cli_cached_catalog_accepts_explicit_deny_all_scope() {
+    let alpha_responder = OneShotHttpResponder::new("ping", Duration::ZERO);
+    let (_alpha_server, alpha) = cold_http_upstream("alpha", alpha_responder.clone()).await;
+    let cache_dir = tempfile::tempdir().expect("tempdir");
+    let (manager, _pool) = one_shot_manager_at(
+        vec![alpha],
+        4_000,
+        cache_dir.path().join("codemode-catalog.json"),
+    )
+    .await;
+    let allowed = std::collections::BTreeSet::new();
+
+    let tools = manager
+        .code_mode_catalog_tools_cached_allowed(None, None, Some(&allowed))
+        .await
+        .expect("deny-all scope needs no upstream catalog");
+
+    assert!(tools.is_empty());
+    assert_eq!(
+        alpha_responder.list_tools_requests(),
+        0,
+        "deny-all scope must not probe any upstream"
+    );
+}
+
 /// Partial means partial, not empty: when the budget ends before any upstream
 /// connected and nothing was served from cache, the one-shot catalog is an
 /// error naming what was still connecting, never a silently empty proxy.

From e31967bd04dd0016c75ecce2af542d701923280c Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:58:50 -0400
Subject: [PATCH 09/16] refactor(snippets): keep saved workflows readable

---
 crates/labby-codemode/src/snippet/store.rs |  15 +-
 docs/snippets/docker-host-inventory.md     | 295 +++++++++++++++++--
 docs/snippets/homelab-docker-inventory.md  | 178 +++++++++++-
 docs/snippets/homelab-ssh-targets.md       | 317 +++++++++++++++++----
 4 files changed, 717 insertions(+), 88 deletions(-)

diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index d8e853842..4608fe640 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -234,10 +234,16 @@ pub fn code_for_snippet(snippet: &ResolvedSnippet) -> Result<String, ToolError>
     } else {
         snippet.body.trim().to_string()
     };
+    let code = normalize_snippet_code(&code).to_string();
     validate_snippet_code(&code)?;
     Ok(code)
 }
 
+fn normalize_snippet_code(code: &str) -> &str {
+    let code = code.trim();
+    code.strip_suffix(';').map_or(code, str::trim_end)
+}
+
 /// Validate and atomically create or replace a user Markdown snippet.
 pub fn create_user_snippet(
     lab_home: &Path,
@@ -545,7 +551,7 @@ pub fn validate_snippet_body(name: &str, body: &str) -> Result<(), ToolError> {
 
 /// Validate executable snippet JavaScript against the Code Mode source-size contract.
 pub fn validate_snippet_code(code: &str) -> Result<(), ToolError> {
-    let code = code.trim();
+    let code = normalize_snippet_code(code);
     if code.is_empty() {
         return Err(ToolError::InvalidParam {
             message: "snippet code is empty".to_string(),
@@ -1042,6 +1048,13 @@ mod tests {
         assert!(validate_snippet_body("demo", valid_body()).is_ok());
     }
 
+    #[test]
+    fn validate_snippet_code_accepts_formatter_trailing_semicolon() {
+        let code = "async () => ({ ok: true });";
+        assert!(validate_snippet_code(code).is_ok());
+        assert_eq!(normalize_snippet_code(code), "async () => ({ ok: true })");
+    }
+
     #[test]
     fn validate_snippet_body_rejects_malformed_javascript_before_execution() {
         let body = "---\nname: demo\ndescription: Broken snippet\ntags: []\n---\n\n```js\nasync () => { const broken = ; return broken; }\n```\n";
diff --git a/docs/snippets/docker-host-inventory.md b/docs/snippets/docker-host-inventory.md
index 9824928c0..7292242e1 100644
--- a/docs/snippets/docker-host-inventory.md
+++ b/docs/snippets/docker-host-inventory.md
@@ -47,22 +47,281 @@ Reusable one-host primitive. Host identity is resolved before Docker enumeration
 
 ```js
 async (o = {}) => {
-  const i={alias:String(o.alias||"").trim(),connect_timeout_seconds:Math.max(1,Math.min(30,Number(o.connect_timeout_seconds??4))),command_timeout_ms:Math.max(5000,Math.min(60000,Number(o.command_timeout_ms??20000))),log_lines:Math.max(0,Math.min(200,Number(o.log_lines??20))),containers_per_call:Math.max(1,Math.min(20,Number(o.containers_per_call??4))),check_updates:o.check_updates!==false,update_timeout_seconds:Math.max(1,Math.min(15,Number(o.update_timeout_seconds??3))),update_parallelism:Math.max(1,Math.min(32,Number(o.update_parallelism??24)))};
-  if(!i.alias)throw new Error("docker-host-inventory requires alias");
-  const q=v=>"'"+String(v).split("'").join("'\"'\"'")+"'", txt=v=>typeof v==="string"?v:typeof v?.stdout==="string"?v.stdout:Array.isArray(v?.content)?v.content.map(x=>x?.text||"").join("\n"):"", clean=e=>{const s=String(e??""),m="Original tool error:",n=s.indexOf(m);return(n>=0?s.slice(n+m.length):s).trim().slice(0,1200)},chunk=(a,n)=>{const x=[];for(let p=0;p<a.length;p+=n)x.push(a.slice(p,p+n));return x};
-  const bash="claude-macpoo::Bash";
-  await callTool(bash,{command:"hostname; whoami; uname -s; pwd",timeout:i.command_timeout_ms});
-  const opts=["-o BatchMode=yes","-o NumberOfPasswordPrompts=0","-o PreferredAuthentications=publickey","-o PasswordAuthentication=no","-o KbdInteractiveAuthentication=no","-o ConnectionAttempts=1","-o ConnectTimeout="+i.connect_timeout_seconds].join(" "),ssh=r=>callTool(bash,{command:"ssh "+opts+" "+q(i.alias)+" "+q(r),timeout:i.command_timeout_ms});
-  const id=txt(await ssh("hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true")).split("\n").map(x=>x.trim()),host={alias:i.alias,hostname:id[0]||null,user:id[1]||null,platform:id[2]||null,docker_path:id[3]||null,docker_version:id[4]||null,timeout_path:id[5]||null};
-  if(!host.hostname)throw new Error("SSH probe returned no hostname for "+i.alias);
-  if(!host.docker_path)return{schema_version:"labby.docker.host_inventory.v1",ok:true,host,containers:[],errors:[],summary:{containers:0,container_states:{},image_update_states:{},updates_available:0,docker_available:false}};
-  const ids=txt(await ssh("docker ps -aq --no-trunc")).split("\n").map(x=>x.trim()).filter(x=>/^[0-9a-f]{12,64}$/i.test(x));
-  const fmt='{"id":{{json .Id}},"name":{{json .Name}},"image_ref":{{json .Config.Image}},"image_id":{{json .Image}},"created":{{json .Created}},"restart_count":{{json .RestartCount}},"state":{"status":{{json .State.Status}},"running":{{json .State.Running}},"paused":{{json .State.Paused}},"restarting":{{json .State.Restarting}},"oom_killed":{{json .State.OOMKilled}},"dead":{{json .State.Dead}},"pid":{{json .State.Pid}},"exit_code":{{json .State.ExitCode}},"error":{{json .State.Error}},"started_at":{{json .State.StartedAt}},"finished_at":{{json .State.FinishedAt}},"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}}},"ports":{{json .NetworkSettings.Ports}},"networks":{{json .NetworkSettings.Networks}},"mounts":{{json .Mounts}}}',sec="__LABBY_DOCKER_LOG_SECTION_9D81__",beg="__LABBY_DOCKER_LOG_BEGIN_9D81__:",end="__LABBY_DOCKER_LOG_END_9D81__:";
-  const detail=await codemode.batch(chunk(ids,i.containers_per_call).map(g=>async()=>{const list=g.join(" "),r=["docker inspect --format "+q(fmt)+" "+list,"printf "+q("\n"+sec+"\n"),"for id in "+list+"; do","printf "+q(beg+"%s\n")+" \"$id\"","docker logs --tail "+i.log_lines+" --timestamps \"$id\" 2>&1 || true","printf "+q(end+"%s\n")+" \"$id\"","done"].join("\n"),out=txt(await ssh(r)),at=out.indexOf("\n"+sec+"\n");if(at<0)throw new Error("inventory marker missing");const meta=out.slice(0,at).split("\n").map(x=>x.trim()).filter(Boolean).map(JSON.parse),logs={};let active=null;for(const line of out.slice(at+sec.length+2).split("\n")){if(line.startsWith(beg)){active=line.slice(beg.length);logs[active]=[];continue}if(line.startsWith(end)){active=null;continue}if(active)logs[active].push(line)}return meta.map(c=>({id:c.id,name:String(c.name||"").replace(/^\/+/,""),image_ref:c.image_ref||null,image_id:c.image_id||null,created:c.created||null,restart_count:c.restart_count??0,state:c.state||{},ports:Object.entries(c.ports||{}).map(([container_port,b])=>({container_port,bindings:(b||[]).map(x=>({host_ip:x.HostIp,host_port:x.HostPort}))})),networks:Object.entries(c.networks||{}).map(([name,x])=>({name,ip_address:x.IPAddress||"",global_ipv6_address:x.GlobalIPv6Address||"",gateway:x.Gateway||"",mac_address:x.MacAddress||"",aliases:x.Aliases||[]})),mounts:(c.mounts||[]).map(x=>({type:x.Type,name:x.Name||null,source:x.Source,destination:x.Destination,mode:x.Mode,rw:x.RW,propagation:x.Propagation})),logs:{requested_lines:i.log_lines,lines:logs[c.id]||[]}}))}));
-  const containers=[],errors=[];for(const x of detail.ok||[])containers.push(...x.value);for(const x of detail.failed||[])errors.push({stage:"inspect_logs",batch:x.i,error:clean(x.error)});
-  const updates={};if(i.check_updates&&containers.length){const images=Array.from(new Set(containers.map(c=>c.image_ref).filter(Boolean))),w=["img=\"$1\"","if printf '%s' \"$img\" | grep -Eq '^[0-9a-f]{12,64}$'; then printf '%s\tunknown\t\t\tlocal_image_id\n' \"$img\"; exit 0; fi","case \"$img\" in *@sha256:*) d=\"$(printf '%s' \"$img\" | cut -d@ -f2-)\"; printf '%s\tpinned\t%s\t%s\tpinned_digest\n' \"$img\" \"$d\" \"$d\"; exit 0 ;; esac","local_digests=\"$(docker image inspect --format '{{range .RepoDigests}}{{println .}}{{end}}' \"$img\" 2>/dev/null || true)\"","if [ -z \"$local_digests\" ]; then printf '%s\tunknown\t\t\tno_local_repo_digest\n' \"$img\"; exit 0; fi","remote_digest=\"$(timeout "+i.update_timeout_seconds+" docker buildx imagetools inspect \"$img\" 2>/dev/null | grep -m1 '^Digest:' | tr -s ' ' | cut -d' ' -f2 || true)\"","local_csv=\"$(printf '%s\n' \"$local_digests\" | tr '\n' ',' )\"","if [ -z \"$remote_digest\" ]; then printf '%s\tunknown\t%s\t\tregistry_digest_unavailable\n' \"$img\" \"$local_csv\"; exit 0; fi","if printf '%s\n' \"$local_digests\" | grep -Fq \"@$remote_digest\"; then status=current; else status=available; fi","printf '%s\t%s\t%s\t%s\tcompared_registry_digest\n' \"$img\" \"$status\" \"$local_csv\" \"$remote_digest\""].join("\n");try{const out=txt(await ssh("printf '%s\n' "+images.map(q).join(" ")+" | xargs -n1 -P"+i.update_parallelism+" sh -c "+q(w)+" sh"));for(const line of out.split("\n")){if(!line.trim())continue;const [image,status,localRaw,remote_digest,reason]=line.split("\t");updates[image]={status:status||"unknown",local_digests:String(localRaw||"").split(",").map(x=>x.trim()).filter(Boolean).map(x=>x.includes("@")?x.slice(x.lastIndexOf("@")+1):x),remote_digest:remote_digest||null,reason:reason||null}}}catch(e){errors.push({stage:"updates",error:clean(e)})}}
-  for(const c of containers)c.update=i.check_updates?(updates[c.image_ref]||{status:"unknown",local_digests:[],remote_digest:null,reason:"image_not_checked"}):{status:"not_checked",local_digests:[],remote_digest:null,reason:"disabled_by_input"};containers.sort((a,b)=>String(a.name).localeCompare(String(b.name)));
-  const states={},imageStates={};for(const c of containers){const s=c.state?.status||"unknown",u=c.update?.status||"unknown";states[s]=(states[s]||0)+1;imageStates[u]=(imageStates[u]||0)+1}
-  return{schema_version:"labby.docker.host_inventory.v1",ok:errors.length===0,host,containers,errors,summary:{containers:containers.length,container_states:states,image_update_states:imageStates,updates_available:containers.filter(c=>c.update?.status==="available").length,docker_available:true}};
-}
+	const i = {
+		alias: String(o.alias || "").trim(),
+		connect_timeout_seconds: Math.max(
+			1,
+			Math.min(30, Number(o.connect_timeout_seconds ?? 4)),
+		),
+		command_timeout_ms: Math.max(
+			5000,
+			Math.min(60000, Number(o.command_timeout_ms ?? 20000)),
+		),
+		log_lines: Math.max(0, Math.min(200, Number(o.log_lines ?? 20))),
+		containers_per_call: Math.max(
+			1,
+			Math.min(20, Number(o.containers_per_call ?? 4)),
+		),
+		check_updates: o.check_updates !== false,
+		update_timeout_seconds: Math.max(
+			1,
+			Math.min(15, Number(o.update_timeout_seconds ?? 3)),
+		),
+		update_parallelism: Math.max(
+			1,
+			Math.min(32, Number(o.update_parallelism ?? 24)),
+		),
+	};
+	if (!i.alias) throw new Error("docker-host-inventory requires alias");
+	const q = (v) => "'" + String(v).split("'").join("'\"'\"'") + "'",
+		txt = (v) =>
+			typeof v === "string"
+				? v
+				: typeof v?.stdout === "string"
+					? v.stdout
+					: Array.isArray(v?.content)
+						? v.content.map((x) => x?.text || "").join("\n")
+						: "",
+		clean = (e) => {
+			const s = String(e ?? ""),
+				m = "Original tool error:",
+				n = s.indexOf(m);
+			return (n >= 0 ? s.slice(n + m.length) : s).trim().slice(0, 1200);
+		},
+		chunk = (a, n) => {
+			const x = [];
+			for (let p = 0; p < a.length; p += n) x.push(a.slice(p, p + n));
+			return x;
+		};
+	const bash = "claude-macpoo::Bash";
+	await callTool(bash, {
+		command: "hostname; whoami; uname -s; pwd",
+		timeout: i.command_timeout_ms,
+	});
+	const opts = [
+			"-o BatchMode=yes",
+			"-o NumberOfPasswordPrompts=0",
+			"-o PreferredAuthentications=publickey",
+			"-o PasswordAuthentication=no",
+			"-o KbdInteractiveAuthentication=no",
+			"-o ConnectionAttempts=1",
+			"-o ConnectTimeout=" + i.connect_timeout_seconds,
+		].join(" "),
+		ssh = (r) =>
+			callTool(bash, {
+				command: "ssh " + opts + " " + q(i.alias) + " " + q(r),
+				timeout: i.command_timeout_ms,
+			});
+	const id = txt(
+			await ssh(
+				"hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true",
+			),
+		)
+			.split("\n")
+			.map((x) => x.trim()),
+		host = {
+			alias: i.alias,
+			hostname: id[0] || null,
+			user: id[1] || null,
+			platform: id[2] || null,
+			docker_path: id[3] || null,
+			docker_version: id[4] || null,
+			timeout_path: id[5] || null,
+		};
+	if (!host.hostname)
+		throw new Error("SSH probe returned no hostname for " + i.alias);
+	if (!host.docker_path)
+		return {
+			schema_version: "labby.docker.host_inventory.v1",
+			ok: true,
+			host,
+			containers: [],
+			errors: [],
+			summary: {
+				containers: 0,
+				container_states: {},
+				image_update_states: {},
+				updates_available: 0,
+				docker_available: false,
+			},
+		};
+	const ids = txt(await ssh("docker ps -aq --no-trunc"))
+		.split("\n")
+		.map((x) => x.trim())
+		.filter((x) => /^[0-9a-f]{12,64}$/i.test(x));
+	const fmt =
+			'{"id":{{json .Id}},"name":{{json .Name}},"image_ref":{{json .Config.Image}},"image_id":{{json .Image}},"created":{{json .Created}},"restart_count":{{json .RestartCount}},"state":{"status":{{json .State.Status}},"running":{{json .State.Running}},"paused":{{json .State.Paused}},"restarting":{{json .State.Restarting}},"oom_killed":{{json .State.OOMKilled}},"dead":{{json .State.Dead}},"pid":{{json .State.Pid}},"exit_code":{{json .State.ExitCode}},"error":{{json .State.Error}},"started_at":{{json .State.StartedAt}},"finished_at":{{json .State.FinishedAt}},"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}}},"ports":{{json .NetworkSettings.Ports}},"networks":{{json .NetworkSettings.Networks}},"mounts":{{json .Mounts}}}',
+		sec = "__LABBY_DOCKER_LOG_SECTION_9D81__",
+		beg = "__LABBY_DOCKER_LOG_BEGIN_9D81__:",
+		end = "__LABBY_DOCKER_LOG_END_9D81__:";
+	const detail = await codemode.batch(
+		chunk(ids, i.containers_per_call).map((g) => async () => {
+			const list = g.join(" "),
+				r = [
+					"docker inspect --format " + q(fmt) + " " + list,
+					"printf " + q("\n" + sec + "\n"),
+					"for id in " + list + "; do",
+					"printf " + q(beg + "%s\n") + ' "$id"',
+					"docker logs --tail " +
+						i.log_lines +
+						' --timestamps "$id" 2>&1 || true',
+					"printf " + q(end + "%s\n") + ' "$id"',
+					"done",
+				].join("\n"),
+				out = txt(await ssh(r)),
+				at = out.indexOf("\n" + sec + "\n");
+			if (at < 0) throw new Error("inventory marker missing");
+			const meta = out
+					.slice(0, at)
+					.split("\n")
+					.map((x) => x.trim())
+					.filter(Boolean)
+					.map(JSON.parse),
+				logs = {};
+			let active = null;
+			for (const line of out.slice(at + sec.length + 2).split("\n")) {
+				if (line.startsWith(beg)) {
+					active = line.slice(beg.length);
+					logs[active] = [];
+					continue;
+				}
+				if (line.startsWith(end)) {
+					active = null;
+					continue;
+				}
+				if (active) logs[active].push(line);
+			}
+			return meta.map((c) => ({
+				id: c.id,
+				name: String(c.name || "").replace(/^\/+/, ""),
+				image_ref: c.image_ref || null,
+				image_id: c.image_id || null,
+				created: c.created || null,
+				restart_count: c.restart_count ?? 0,
+				state: c.state || {},
+				ports: Object.entries(c.ports || {}).map(([container_port, b]) => ({
+					container_port,
+					bindings: (b || []).map((x) => ({
+						host_ip: x.HostIp,
+						host_port: x.HostPort,
+					})),
+				})),
+				networks: Object.entries(c.networks || {}).map(([name, x]) => ({
+					name,
+					ip_address: x.IPAddress || "",
+					global_ipv6_address: x.GlobalIPv6Address || "",
+					gateway: x.Gateway || "",
+					mac_address: x.MacAddress || "",
+					aliases: x.Aliases || [],
+				})),
+				mounts: (c.mounts || []).map((x) => ({
+					type: x.Type,
+					name: x.Name || null,
+					source: x.Source,
+					destination: x.Destination,
+					mode: x.Mode,
+					rw: x.RW,
+					propagation: x.Propagation,
+				})),
+				logs: { requested_lines: i.log_lines, lines: logs[c.id] || [] },
+			}));
+		}),
+	);
+	const containers = [],
+		errors = [];
+	for (const x of detail.ok || []) containers.push(...x.value);
+	for (const x of detail.failed || [])
+		errors.push({ stage: "inspect_logs", batch: x.i, error: clean(x.error) });
+	const updates = {};
+	if (i.check_updates && containers.length) {
+		const images = Array.from(
+				new Set(containers.map((c) => c.image_ref).filter(Boolean)),
+			),
+			w = [
+				'img="$1"',
+				"if printf '%s' \"$img\" | grep -Eq '^[0-9a-f]{12,64}$'; then printf '%s\tunknown\t\t\tlocal_image_id\n' \"$img\"; exit 0; fi",
+				'case "$img" in *@sha256:*) d="$(printf \'%s\' "$img" | cut -d@ -f2-)"; printf \'%s\tpinned\t%s\t%s\tpinned_digest\n\' "$img" "$d" "$d"; exit 0 ;; esac',
+				'local_digests="$(docker image inspect --format \'{{range .RepoDigests}}{{println .}}{{end}}\' "$img" 2>/dev/null || true)"',
+				'if [ -z "$local_digests" ]; then printf \'%s\tunknown\t\t\tno_local_repo_digest\n\' "$img"; exit 0; fi',
+				'remote_digest="$(timeout ' +
+					i.update_timeout_seconds +
+					" docker buildx imagetools inspect \"$img\" 2>/dev/null | grep -m1 '^Digest:' | tr -s ' ' | cut -d' ' -f2 || true)\"",
+				"local_csv=\"$(printf '%s\n' \"$local_digests\" | tr '\n' ',' )\"",
+				'if [ -z "$remote_digest" ]; then printf \'%s\tunknown\t%s\t\tregistry_digest_unavailable\n\' "$img" "$local_csv"; exit 0; fi',
+				'if printf \'%s\n\' "$local_digests" | grep -Fq "@$remote_digest"; then status=current; else status=available; fi',
+				'printf \'%s\t%s\t%s\t%s\tcompared_registry_digest\n\' "$img" "$status" "$local_csv" "$remote_digest"',
+			].join("\n");
+		try {
+			const out = txt(
+				await ssh(
+					"printf '%s\n' " +
+						images.map(q).join(" ") +
+						" | xargs -n1 -P" +
+						i.update_parallelism +
+						" sh -c " +
+						q(w) +
+						" sh",
+				),
+			);
+			for (const line of out.split("\n")) {
+				if (!line.trim()) continue;
+				const [image, status, localRaw, remote_digest, reason] =
+					line.split("\t");
+				updates[image] = {
+					status: status || "unknown",
+					local_digests: String(localRaw || "")
+						.split(",")
+						.map((x) => x.trim())
+						.filter(Boolean)
+						.map((x) =>
+							x.includes("@") ? x.slice(x.lastIndexOf("@") + 1) : x,
+						),
+					remote_digest: remote_digest || null,
+					reason: reason || null,
+				};
+			}
+		} catch (e) {
+			errors.push({ stage: "updates", error: clean(e) });
+		}
+	}
+	for (const c of containers)
+		c.update = i.check_updates
+			? updates[c.image_ref] || {
+					status: "unknown",
+					local_digests: [],
+					remote_digest: null,
+					reason: "image_not_checked",
+				}
+			: {
+					status: "not_checked",
+					local_digests: [],
+					remote_digest: null,
+					reason: "disabled_by_input",
+				};
+	containers.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+	const states = {},
+		imageStates = {};
+	for (const c of containers) {
+		const s = c.state?.status || "unknown",
+			u = c.update?.status || "unknown";
+		states[s] = (states[s] || 0) + 1;
+		imageStates[u] = (imageStates[u] || 0) + 1;
+	}
+	return {
+		schema_version: "labby.docker.host_inventory.v1",
+		ok: errors.length === 0,
+		host,
+		containers,
+		errors,
+		summary: {
+			containers: containers.length,
+			container_states: states,
+			image_update_states: imageStates,
+			updates_available: containers.filter(
+				(c) => c.update?.status === "available",
+			).length,
+			docker_available: true,
+		},
+	};
+};
 ```
diff --git a/docs/snippets/homelab-docker-inventory.md b/docs/snippets/homelab-docker-inventory.md
index ee13690b6..1ddbfe95d 100644
--- a/docs/snippets/homelab-docker-inventory.md
+++ b/docs/snippets/homelab-docker-inventory.md
@@ -57,17 +57,169 @@ Thin orchestration snippet. SSH discovery is a required dependency, then indepen
 
 ```js
 async (o = {}) => {
-  const input={ssh_config:o.ssh_config??"",exclude_hosts:Array.isArray(o.exclude_hosts)?o.exclude_hosts:["github.com","orb"],extra_hosts:Array.isArray(o.extra_hosts)?o.extra_hosts:[],connect_timeout_seconds:Math.max(1,Math.min(30,Number(o.connect_timeout_seconds??4))),command_timeout_ms:Math.max(5000,Math.min(60000,Number(o.command_timeout_ms??20000))),log_lines:Math.max(0,Math.min(200,Number(o.log_lines??20))),containers_per_call:Math.max(1,Math.min(20,Number(o.containers_per_call??4))),check_updates:o.check_updates!==false,update_timeout_seconds:Math.max(1,Math.min(15,Number(o.update_timeout_seconds??3))),update_parallelism:Math.max(1,Math.min(32,Number(o.update_parallelism??24)))};
-  const discovery=await codemode.run("homelab-ssh-targets",{ssh_config:input.ssh_config,exclude_hosts:input.exclude_hosts,extra_hosts:input.extra_hosts,connect_timeout_seconds:input.connect_timeout_seconds,command_timeout_ms:input.command_timeout_ms});
-  if(!discovery?.ok)throw new Error("homelab SSH discovery failed");
-  const byDevice=new Map();
-  for(const t of discovery.targets||[]){if(!t?.ssh_reachable||!t.remote?.hostname||!t.remote?.docker_path)continue;const key=String(t.remote.hostname).toLowerCase()+"|"+String(t.remote.user||"").toLowerCase();if(!byDevice.has(key))byDevice.set(key,{key,hostname:t.remote.hostname,user:t.remote.user,platform:t.remote.platform,aliases:[],preferred_alias:t.alias,docker_version:t.remote.docker_version||null});byDevice.get(key).aliases.push(t.alias)}
-  const devices=Array.from(byDevice.values()), jobs=devices.map(d=>()=>codemode.run("docker-host-inventory",{alias:d.preferred_alias,connect_timeout_seconds:input.connect_timeout_seconds,command_timeout_ms:input.command_timeout_ms,log_lines:input.log_lines,containers_per_call:input.containers_per_call,check_updates:input.check_updates,update_timeout_seconds:input.update_timeout_seconds,update_parallelism:input.update_parallelism})),batch=await codemode.batch(jobs),inventories=new Array(devices.length),hostFailures=[];
-  for(const x of batch.ok||[])inventories[x.i]=x.value;for(const x of batch.failed||[])hostFailures.push({device:devices[x.i],error:String(x.error).slice(0,1200)});
-  const states={},updates={};let total=0,updatesAvailable=0,hostsWithErrors=hostFailures.length;
-  for(let n=0;n<devices.length;n++){const inv=inventories[n];if(!inv)continue;devices[n].inventory=inv;total+=inv.summary?.containers||0;updatesAvailable+=inv.summary?.updates_available||0;if((inv.errors||[]).length)hostsWithErrors++;for(const [k,v] of Object.entries(inv.summary?.container_states||{}))states[k]=(states[k]||0)+v;for(const [k,v] of Object.entries(inv.summary?.image_update_states||{}))updates[k]=(updates[k]||0)+v;}
-  const report={schema_version:"labby.homelab.docker_inventory.v1",generated_at:new Date().toISOString(),input,controller:discovery.controller,discovery:{...discovery.discovery,unique_reachable_devices:new Set((discovery.targets||[]).filter(t=>t?.ssh_reachable&&t.remote?.hostname).map(t=>String(t.remote.hostname).toLowerCase()+"|"+String(t.remote.user||"").toLowerCase())).size,docker_hosts:devices.length},ssh_targets:discovery.targets||[],devices,host_failures:hostFailures,summary:{containers:total,container_states:states,image_update_states:updates,updates_available:updatesAvailable,hosts_with_inventory_errors:hostsWithErrors}};
-  const artifact=await writeArtifact("homelab/docker-inventory.json",JSON.stringify(report,null,2),{contentType:"application/json"});
-  return{schema_version:report.schema_version,ok:hostsWithErrors===0,partial:(report.discovery.ssh_unreachable||0)>0||hostsWithErrors>0||(updates.unknown||0)>0,generated_at:report.generated_at,artifact,summary:report.summary,discovery:report.discovery,devices:devices.map(d=>({hostname:d.hostname,aliases:d.aliases,user:d.user,platform:d.platform,docker_version:d.docker_version,container_count:d.inventory?.summary?.containers||0,running_count:d.inventory?.summary?.container_states?.running||0,updates_available:d.inventory?.summary?.updates_available||0,inventory_errors:d.inventory?.errors||[]})),unreachable_targets:(discovery.targets||[]).filter(t=>!t.ssh_reachable).map(t=>({alias:t.alias,effective:t.effective,key_auth_configured:t.key_auth_configured,failure_kind:t.failure_kind,error:t.error}))};
-}
+	const input = {
+		ssh_config: o.ssh_config ?? "",
+		exclude_hosts: Array.isArray(o.exclude_hosts)
+			? o.exclude_hosts
+			: ["github.com", "orb"],
+		extra_hosts: Array.isArray(o.extra_hosts) ? o.extra_hosts : [],
+		connect_timeout_seconds: Math.max(
+			1,
+			Math.min(30, Number(o.connect_timeout_seconds ?? 4)),
+		),
+		command_timeout_ms: Math.max(
+			5000,
+			Math.min(60000, Number(o.command_timeout_ms ?? 20000)),
+		),
+		log_lines: Math.max(0, Math.min(200, Number(o.log_lines ?? 20))),
+		containers_per_call: Math.max(
+			1,
+			Math.min(20, Number(o.containers_per_call ?? 4)),
+		),
+		check_updates: o.check_updates !== false,
+		update_timeout_seconds: Math.max(
+			1,
+			Math.min(15, Number(o.update_timeout_seconds ?? 3)),
+		),
+		update_parallelism: Math.max(
+			1,
+			Math.min(32, Number(o.update_parallelism ?? 24)),
+		),
+	};
+	const discovery = await codemode.run("homelab-ssh-targets", {
+		ssh_config: input.ssh_config,
+		exclude_hosts: input.exclude_hosts,
+		extra_hosts: input.extra_hosts,
+		connect_timeout_seconds: input.connect_timeout_seconds,
+		command_timeout_ms: input.command_timeout_ms,
+	});
+	if (!discovery?.ok) throw new Error("homelab SSH discovery failed");
+	const byDevice = new Map();
+	for (const t of discovery.targets || []) {
+		if (!t?.ssh_reachable || !t.remote?.hostname || !t.remote?.docker_path)
+			continue;
+		const key =
+			String(t.remote.hostname).toLowerCase() +
+			"|" +
+			String(t.remote.user || "").toLowerCase();
+		if (!byDevice.has(key))
+			byDevice.set(key, {
+				key,
+				hostname: t.remote.hostname,
+				user: t.remote.user,
+				platform: t.remote.platform,
+				aliases: [],
+				preferred_alias: t.alias,
+				docker_version: t.remote.docker_version || null,
+			});
+		byDevice.get(key).aliases.push(t.alias);
+	}
+	const devices = Array.from(byDevice.values()),
+		jobs = devices.map(
+			(d) => () =>
+				codemode.run("docker-host-inventory", {
+					alias: d.preferred_alias,
+					connect_timeout_seconds: input.connect_timeout_seconds,
+					command_timeout_ms: input.command_timeout_ms,
+					log_lines: input.log_lines,
+					containers_per_call: input.containers_per_call,
+					check_updates: input.check_updates,
+					update_timeout_seconds: input.update_timeout_seconds,
+					update_parallelism: input.update_parallelism,
+				}),
+		),
+		batch = await codemode.batch(jobs),
+		inventories = new Array(devices.length),
+		hostFailures = [];
+	for (const x of batch.ok || []) inventories[x.i] = x.value;
+	for (const x of batch.failed || [])
+		hostFailures.push({
+			device: devices[x.i],
+			error: String(x.error).slice(0, 1200),
+		});
+	const states = {},
+		updates = {};
+	let total = 0,
+		updatesAvailable = 0,
+		hostsWithErrors = hostFailures.length;
+	for (let n = 0; n < devices.length; n++) {
+		const inv = inventories[n];
+		if (!inv) continue;
+		devices[n].inventory = inv;
+		total += inv.summary?.containers || 0;
+		updatesAvailable += inv.summary?.updates_available || 0;
+		if ((inv.errors || []).length) hostsWithErrors++;
+		for (const [k, v] of Object.entries(inv.summary?.container_states || {}))
+			states[k] = (states[k] || 0) + v;
+		for (const [k, v] of Object.entries(inv.summary?.image_update_states || {}))
+			updates[k] = (updates[k] || 0) + v;
+	}
+	const report = {
+		schema_version: "labby.homelab.docker_inventory.v1",
+		generated_at: new Date().toISOString(),
+		input,
+		controller: discovery.controller,
+		discovery: {
+			...discovery.discovery,
+			unique_reachable_devices: new Set(
+				(discovery.targets || [])
+					.filter((t) => t?.ssh_reachable && t.remote?.hostname)
+					.map(
+						(t) =>
+							String(t.remote.hostname).toLowerCase() +
+							"|" +
+							String(t.remote.user || "").toLowerCase(),
+					),
+			).size,
+			docker_hosts: devices.length,
+		},
+		ssh_targets: discovery.targets || [],
+		devices,
+		host_failures: hostFailures,
+		summary: {
+			containers: total,
+			container_states: states,
+			image_update_states: updates,
+			updates_available: updatesAvailable,
+			hosts_with_inventory_errors: hostsWithErrors,
+		},
+	};
+	const artifact = await writeArtifact(
+		"homelab/docker-inventory.json",
+		JSON.stringify(report, null, 2),
+		{ contentType: "application/json" },
+	);
+	return {
+		schema_version: report.schema_version,
+		ok: hostsWithErrors === 0,
+		partial:
+			(report.discovery.ssh_unreachable || 0) > 0 ||
+			hostsWithErrors > 0 ||
+			(updates.unknown || 0) > 0,
+		generated_at: report.generated_at,
+		artifact,
+		summary: report.summary,
+		discovery: report.discovery,
+		devices: devices.map((d) => ({
+			hostname: d.hostname,
+			aliases: d.aliases,
+			user: d.user,
+			platform: d.platform,
+			docker_version: d.docker_version,
+			container_count: d.inventory?.summary?.containers || 0,
+			running_count: d.inventory?.summary?.container_states?.running || 0,
+			updates_available: d.inventory?.summary?.updates_available || 0,
+			inventory_errors: d.inventory?.errors || [],
+		})),
+		unreachable_targets: (discovery.targets || [])
+			.filter((t) => !t.ssh_reachable)
+			.map((t) => ({
+				alias: t.alias,
+				effective: t.effective,
+				key_auth_configured: t.key_auth_configured,
+				failure_kind: t.failure_kind,
+				error: t.error,
+			})),
+	};
+};
 ```
diff --git a/docs/snippets/homelab-ssh-targets.md b/docs/snippets/homelab-ssh-targets.md
index 8233ae70d..7c599a85f 100644
--- a/docs/snippets/homelab-ssh-targets.md
+++ b/docs/snippets/homelab-ssh-targets.md
@@ -39,63 +39,268 @@ Reusable read-only discovery primitive for homelab snippets. It uses the declare
 
 ```js
 async (o = {}) => {
-  const input = {
-    ssh_config: o.ssh_config ?? "",
-    exclude_hosts: Array.isArray(o.exclude_hosts) ? o.exclude_hosts : ["github.com", "orb"],
-    extra_hosts: Array.isArray(o.extra_hosts) ? o.extra_hosts : [],
-    connect_timeout_seconds: Math.max(1, Math.min(30, Number(o.connect_timeout_seconds ?? 4))),
-    command_timeout_ms: Math.max(5000, Math.min(60000, Number(o.command_timeout_ms ?? 20000)))
-  };
-  const quote = v => "'" + String(v).split("'").join("'\"'\"'") + "'";
-  const text = v => typeof v === "string" ? v : typeof v?.stdout === "string" ? v.stdout : typeof v?.file?.content === "string" ? v.file.content : Array.isArray(v?.content) ? v.content.map(x => x?.text || "").join("\n") : "";
-  const err = e => { const s = String(e ?? ""), m = "Original tool error:", i = s.indexOf(m); return (i >= 0 ? s.slice(i + m.length) : s).trim().slice(0, 1200); };
-  const kind = s => { s = String(s || "").toLowerCase(); if (s.includes("permission denied")) return "auth_failed"; if (s.includes("timed out") || s.includes("timeout")) return "timeout"; if (s.includes("refused")) return "connection_refused"; if (s.includes("no route") || s.includes("network is unreachable")) return "network_unreachable"; if (s.includes("resolve hostname") || s.includes("name or service not known")) return "dns_failed"; if (s.includes("host key verification failed")) return "host_key_failed"; return "other"; };
-  const fanout = async (items, fn) => { const r = await codemode.batch(items.map(x => () => fn(x))), out = new Array(items.length); for (const x of r.ok || []) out[x.i] = x.value; for (const x of r.failed || []) out[x.i] = { ok:false, error:err(x.error) }; return out; };
+	const input = {
+		ssh_config: o.ssh_config ?? "",
+		exclude_hosts: Array.isArray(o.exclude_hosts)
+			? o.exclude_hosts
+			: ["github.com", "orb"],
+		extra_hosts: Array.isArray(o.extra_hosts) ? o.extra_hosts : [],
+		connect_timeout_seconds: Math.max(
+			1,
+			Math.min(30, Number(o.connect_timeout_seconds ?? 4)),
+		),
+		command_timeout_ms: Math.max(
+			5000,
+			Math.min(60000, Number(o.command_timeout_ms ?? 20000)),
+		),
+	};
+	const quote = (v) => "'" + String(v).split("'").join("'\"'\"'") + "'";
+	const text = (v) =>
+		typeof v === "string"
+			? v
+			: typeof v?.stdout === "string"
+				? v.stdout
+				: typeof v?.file?.content === "string"
+					? v.file.content
+					: Array.isArray(v?.content)
+						? v.content.map((x) => x?.text || "").join("\n")
+						: "";
+	const err = (e) => {
+		const s = String(e ?? ""),
+			m = "Original tool error:",
+			i = s.indexOf(m);
+		return (i >= 0 ? s.slice(i + m.length) : s).trim().slice(0, 1200);
+	};
+	const kind = (s) => {
+		s = String(s || "").toLowerCase();
+		if (s.includes("permission denied")) return "auth_failed";
+		if (s.includes("timed out") || s.includes("timeout")) return "timeout";
+		if (s.includes("refused")) return "connection_refused";
+		if (s.includes("no route") || s.includes("network is unreachable"))
+			return "network_unreachable";
+		if (
+			s.includes("resolve hostname") ||
+			s.includes("name or service not known")
+		)
+			return "dns_failed";
+		if (s.includes("host key verification failed")) return "host_key_failed";
+		return "other";
+	};
+	const fanout = async (items, fn) => {
+		const r = await codemode.batch(items.map((x) => () => fn(x))),
+			out = new Array(items.length);
+		for (const x of r.ok || []) out[x.i] = x.value;
+		for (const x of r.failed || [])
+			out[x.i] = { ok: false, error: err(x.error) };
+		return out;
+	};
 
-  const bashTool = { id:"claude-macpoo::Bash", namespace:"claude-macpoo" };
-  const readTool = { id:"claude-macpoo::Read" };
-  const identity = text(await callTool(bashTool.id, { command:"hostname; whoami; uname -s; pwd; printenv HOME; command -v ssh || true", timeout:input.command_timeout_ms })).split("\n").map(x => x.trim());
-  const controller = { upstream:bashTool.namespace, bash_tool_id:bashTool.id, read_tool_id:readTool.id, hostname:identity[0] || null, user:identity[1] || null, platform:identity[2] || null, cwd:identity[3] || null, home:identity[4] || null, ssh_path:identity[5] || null };
-  if (!controller.home || !controller.ssh_path) throw new Error("Selected Claude MCP controller is missing HOME or ssh");
+	const bashTool = { id: "claude-macpoo::Bash", namespace: "claude-macpoo" };
+	const readTool = { id: "claude-macpoo::Read" };
+	const identity = text(
+		await callTool(bashTool.id, {
+			command:
+				"hostname; whoami; uname -s; pwd; printenv HOME; command -v ssh || true",
+			timeout: input.command_timeout_ms,
+		}),
+	)
+		.split("\n")
+		.map((x) => x.trim());
+	const controller = {
+		upstream: bashTool.namespace,
+		bash_tool_id: bashTool.id,
+		read_tool_id: readTool.id,
+		hostname: identity[0] || null,
+		user: identity[1] || null,
+		platform: identity[2] || null,
+		cwd: identity[3] || null,
+		home: identity[4] || null,
+		ssh_path: identity[5] || null,
+	};
+	if (!controller.home || !controller.ssh_path)
+		throw new Error("Selected Claude MCP controller is missing HOME or ssh");
 
-  const root = input.ssh_config || controller.home + "/.ssh/config", queue = [root], seen = new Set(), aliases = new Map(), warnings = [];
-  const resolve = (p, from) => p.startsWith("~/") ? controller.home + p.slice(1) : p.startsWith("/") ? p : from.slice(0, Math.max(0, from.lastIndexOf("/")) + 1) + p;
-  while (queue.length && seen.size < 16) {
-    const path = queue.shift(); if (!path || seen.has(path)) continue; seen.add(path);
-    let body; try { body = text(await callTool(readTool.id, { file_path:path })); } catch (e) { warnings.push({type:"config_read_failed",path,error:err(e)}); continue; }
-    for (const raw of body.split("\n")) {
-      const line = raw.trim(); if (!line || line.startsWith("#")) continue;
-      const inc = line.match(/^Include\s+(.+)$/i);
-      if (inc) { for (const token of inc[1].trim().split(/\s+/)) { if (token.includes("*") || token.includes("?") || token.includes("[")) warnings.push({type:"include_glob_skipped",source:path,include:token}); else queue.push(resolve(token,path)); } continue; }
-      const host = line.match(/^Host\s+(.+)$/i); if (!host) continue;
-      for (const alias of host[1].trim().split(/\s+/)) if (alias && !alias.startsWith("!") && !alias.includes("*") && !alias.includes("?") && !alias.includes("[") && !input.exclude_hosts.includes(alias)) { if (!aliases.has(alias)) aliases.set(alias,{alias,sources:[]}); aliases.get(alias).sources.push(path); }
-    }
-  }
-  for (const raw of input.extra_hosts) { const alias = String(raw || "").trim(); if (alias && !input.exclude_hosts.includes(alias) && !aliases.has(alias)) aliases.set(alias,{alias,sources:["input.extra_hosts"]}); }
+	const root = input.ssh_config || controller.home + "/.ssh/config",
+		queue = [root],
+		seen = new Set(),
+		aliases = new Map(),
+		warnings = [];
+	const resolve = (p, from) =>
+		p.startsWith("~/")
+			? controller.home + p.slice(1)
+			: p.startsWith("/")
+				? p
+				: from.slice(0, Math.max(0, from.lastIndexOf("/")) + 1) + p;
+	while (queue.length && seen.size < 16) {
+		const path = queue.shift();
+		if (!path || seen.has(path)) continue;
+		seen.add(path);
+		let body;
+		try {
+			body = text(await callTool(readTool.id, { file_path: path }));
+		} catch (e) {
+			warnings.push({ type: "config_read_failed", path, error: err(e) });
+			continue;
+		}
+		for (const raw of body.split("\n")) {
+			const line = raw.trim();
+			if (!line || line.startsWith("#")) continue;
+			const inc = line.match(/^Include\s+(.+)$/i);
+			if (inc) {
+				for (const token of inc[1].trim().split(/\s+/)) {
+					if (token.includes("*") || token.includes("?") || token.includes("["))
+						warnings.push({
+							type: "include_glob_skipped",
+							source: path,
+							include: token,
+						});
+					else queue.push(resolve(token, path));
+				}
+				continue;
+			}
+			const host = line.match(/^Host\s+(.+)$/i);
+			if (!host) continue;
+			for (const alias of host[1].trim().split(/\s+/))
+				if (
+					alias &&
+					!alias.startsWith("!") &&
+					!alias.includes("*") &&
+					!alias.includes("?") &&
+					!alias.includes("[") &&
+					!input.exclude_hosts.includes(alias)
+				) {
+					if (!aliases.has(alias)) aliases.set(alias, { alias, sources: [] });
+					aliases.get(alias).sources.push(path);
+				}
+		}
+	}
+	for (const raw of input.extra_hosts) {
+		const alias = String(raw || "").trim();
+		if (alias && !input.exclude_hosts.includes(alias) && !aliases.has(alias))
+			aliases.set(alias, { alias, sources: ["input.extra_hosts"] });
+	}
 
-  const configured = await fanout(Array.from(aliases.values()), async target => {
-    try {
-      const effective = {hostname:null,user:null,port:22,identity_files:[],identity_agent:null};
-      for (const line of text(await callTool(bashTool.id,{command:"ssh -G " + quote(target.alias),timeout:input.command_timeout_ms})).split("\n")) { const n=line.indexOf(" "); if (n<1) continue; const k=line.slice(0,n).toLowerCase(), v=line.slice(n+1).trim(); if(k==="hostname")effective.hostname=v; else if(k==="user")effective.user=v; else if(k==="port")effective.port=Number(v)||22; else if(k==="identityfile")effective.identity_files.push(v); else if(k==="identityagent")effective.identity_agent=v; }
-      return {...target,ok:true,effective,key_auth_configured:effective.identity_files.length>0 || Boolean(effective.identity_agent && effective.identity_agent!=="none")};
-    } catch(e) { return {...target,ok:false,key_auth_configured:false,error:err(e)}; }
-  });
-  const opts = ["-o BatchMode=yes","-o NumberOfPasswordPrompts=0","-o PreferredAuthentications=publickey","-o PasswordAuthentication=no","-o KbdInteractiveAuthentication=no","-o ConnectionAttempts=1","-o ConnectTimeout="+input.connect_timeout_seconds].join(" ");
-  const targets = await fanout(configured, async target => {
-    if (!target.ok) return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:"config_failed"};
-    try {
-      const probe = "hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true";
-      const lines = text(await callTool(bashTool.id,{command:"ssh "+opts+" "+quote(target.alias)+" "+quote(probe),timeout:Math.min(input.command_timeout_ms,12000)})).split("\n").map(x=>x.trim());
-      if (!lines[0]) return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:"empty_probe_response",error:"empty_probe_response"};
-      return {...target,ssh_reachable:true,key_auth_working:true,remote:{hostname:lines[0]||null,user:lines[1]||null,platform:lines[2]||null,docker_path:lines[3]||null,docker_version:lines[4]||null,timeout_path:lines[5]||null}};
-    } catch(e) { const message=err(e); return {...target,ssh_reachable:false,key_auth_working:false,failure_kind:kind(message),error:message}; }
-  });
-  return {
-    schema_version:"labby.homelab.ssh_targets.v1",
-    ok:true,
-    controller:{...controller,ssh_config:root},
-    discovery:{parsed_config_files:Array.from(seen),warnings,configured_aliases:targets.length,key_auth_configured:targets.filter(x=>x.key_auth_configured).length,key_auth_working:targets.filter(x=>x.key_auth_working).length,ssh_unreachable:targets.filter(x=>!x.ssh_reachable).length},
-    targets
-  };
-}
+	const configured = await fanout(
+		Array.from(aliases.values()),
+		async (target) => {
+			try {
+				const effective = {
+					hostname: null,
+					user: null,
+					port: 22,
+					identity_files: [],
+					identity_agent: null,
+				};
+				for (const line of text(
+					await callTool(bashTool.id, {
+						command: "ssh -G " + quote(target.alias),
+						timeout: input.command_timeout_ms,
+					}),
+				).split("\n")) {
+					const n = line.indexOf(" ");
+					if (n < 1) continue;
+					const k = line.slice(0, n).toLowerCase(),
+						v = line.slice(n + 1).trim();
+					if (k === "hostname") effective.hostname = v;
+					else if (k === "user") effective.user = v;
+					else if (k === "port") effective.port = Number(v) || 22;
+					else if (k === "identityfile") effective.identity_files.push(v);
+					else if (k === "identityagent") effective.identity_agent = v;
+				}
+				return {
+					...target,
+					ok: true,
+					effective,
+					key_auth_configured:
+						effective.identity_files.length > 0 ||
+						Boolean(
+							effective.identity_agent && effective.identity_agent !== "none",
+						),
+				};
+			} catch (e) {
+				return {
+					...target,
+					ok: false,
+					key_auth_configured: false,
+					error: err(e),
+				};
+			}
+		},
+	);
+	const opts = [
+		"-o BatchMode=yes",
+		"-o NumberOfPasswordPrompts=0",
+		"-o PreferredAuthentications=publickey",
+		"-o PasswordAuthentication=no",
+		"-o KbdInteractiveAuthentication=no",
+		"-o ConnectionAttempts=1",
+		"-o ConnectTimeout=" + input.connect_timeout_seconds,
+	].join(" ");
+	const targets = await fanout(configured, async (target) => {
+		if (!target.ok)
+			return {
+				...target,
+				ssh_reachable: false,
+				key_auth_working: false,
+				failure_kind: "config_failed",
+			};
+		try {
+			const probe =
+				"hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true";
+			const lines = text(
+				await callTool(bashTool.id, {
+					command:
+						"ssh " + opts + " " + quote(target.alias) + " " + quote(probe),
+					timeout: Math.min(input.command_timeout_ms, 12000),
+				}),
+			)
+				.split("\n")
+				.map((x) => x.trim());
+			if (!lines[0])
+				return {
+					...target,
+					ssh_reachable: false,
+					key_auth_working: false,
+					failure_kind: "empty_probe_response",
+					error: "empty_probe_response",
+				};
+			return {
+				...target,
+				ssh_reachable: true,
+				key_auth_working: true,
+				remote: {
+					hostname: lines[0] || null,
+					user: lines[1] || null,
+					platform: lines[2] || null,
+					docker_path: lines[3] || null,
+					docker_version: lines[4] || null,
+					timeout_path: lines[5] || null,
+				},
+			};
+		} catch (e) {
+			const message = err(e);
+			return {
+				...target,
+				ssh_reachable: false,
+				key_auth_working: false,
+				failure_kind: kind(message),
+				error: message,
+			};
+		}
+	});
+	return {
+		schema_version: "labby.homelab.ssh_targets.v1",
+		ok: true,
+		controller: { ...controller, ssh_config: root },
+		discovery: {
+			parsed_config_files: Array.from(seen),
+			warnings,
+			configured_aliases: targets.length,
+			key_auth_configured: targets.filter((x) => x.key_auth_configured).length,
+			key_auth_working: targets.filter((x) => x.key_auth_working).length,
+			ssh_unreachable: targets.filter((x) => !x.ssh_reachable).length,
+		},
+		targets,
+	};
+};
 ```

From dd6135df2568efd2b8f118088ead44609ee4b4b3 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:07:37 -0400
Subject: [PATCH 10/16] fix(snippets): harden log framing

---
 crates/labby-codemode/src/snippet/store.rs | 25 ++++++++++++++++++++++
 docs/snippets/docker-host-inventory.md     |  9 ++++----
 docs/snippets/homelab-docker-inventory.md  |  2 +-
 docs/snippets/homelab-ssh-targets.md       |  2 +-
 4 files changed, 32 insertions(+), 6 deletions(-)

diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index 4608fe640..c8a250887 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -1171,6 +1171,31 @@ mod tests {
         );
     }
 
+    #[test]
+    fn docker_host_inventory_uses_per_run_log_markers() {
+        let lab_home = tempfile::tempdir().expect("temp lab home");
+        let snippet = resolve_snippet(
+            lab_home.path(),
+            &builtin_snippet_dir(),
+            "docker-host-inventory",
+        )
+        .expect("resolve docker host inventory");
+        let code = code_for_snippet(&snippet).expect("valid docker inventory source");
+
+        assert!(
+            code.contains("Math.random()"),
+            "log framing must carry a per-run nonce"
+        );
+        assert!(
+            code.contains("__LABBY_DOCKER_LOG_SECTION_${markerNonce}__"),
+            "section marker must incorporate the per-run nonce"
+        );
+        assert!(
+            !code.contains("__LABBY_DOCKER_LOG_SECTION_9D81__"),
+            "static framing lets container output spoof parser boundaries"
+        );
+    }
+
     #[test]
     fn repo_status_gh_pulse_builtin_is_discoverable_and_executable() {
         let lab_home = tempfile::tempdir().expect("temp lab home");
diff --git a/docs/snippets/docker-host-inventory.md b/docs/snippets/docker-host-inventory.md
index 7292242e1..c47f9ff4b 100644
--- a/docs/snippets/docker-host-inventory.md
+++ b/docs/snippets/docker-host-inventory.md
@@ -151,9 +151,10 @@ async (o = {}) => {
 		.filter((x) => /^[0-9a-f]{12,64}$/i.test(x));
 	const fmt =
 			'{"id":{{json .Id}},"name":{{json .Name}},"image_ref":{{json .Config.Image}},"image_id":{{json .Image}},"created":{{json .Created}},"restart_count":{{json .RestartCount}},"state":{"status":{{json .State.Status}},"running":{{json .State.Running}},"paused":{{json .State.Paused}},"restarting":{{json .State.Restarting}},"oom_killed":{{json .State.OOMKilled}},"dead":{{json .State.Dead}},"pid":{{json .State.Pid}},"exit_code":{{json .State.ExitCode}},"error":{{json .State.Error}},"started_at":{{json .State.StartedAt}},"finished_at":{{json .State.FinishedAt}},"health":{{with index .State "Health"}}{{json .Status}}{{else}}null{{end}}},"ports":{{json .NetworkSettings.Ports}},"networks":{{json .NetworkSettings.Networks}},"mounts":{{json .Mounts}}}',
-		sec = "__LABBY_DOCKER_LOG_SECTION_9D81__",
-		beg = "__LABBY_DOCKER_LOG_BEGIN_9D81__:",
-		end = "__LABBY_DOCKER_LOG_END_9D81__:";
+		markerNonce = `${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`,
+		sec = `__LABBY_DOCKER_LOG_SECTION_${markerNonce}__`,
+		beg = `__LABBY_DOCKER_LOG_BEGIN_${markerNonce}__:`,
+		end = `__LABBY_DOCKER_LOG_END_${markerNonce}__:`;
 	const detail = await codemode.batch(
 		chunk(ids, i.containers_per_call).map((g) => async () => {
 			const list = g.join(" "),
@@ -323,5 +324,5 @@ async (o = {}) => {
 			docker_available: true,
 		},
 	};
-};
+}
 ```
diff --git a/docs/snippets/homelab-docker-inventory.md b/docs/snippets/homelab-docker-inventory.md
index 1ddbfe95d..3038957a1 100644
--- a/docs/snippets/homelab-docker-inventory.md
+++ b/docs/snippets/homelab-docker-inventory.md
@@ -221,5 +221,5 @@ async (o = {}) => {
 				error: t.error,
 			})),
 	};
-};
+}
 ```
diff --git a/docs/snippets/homelab-ssh-targets.md b/docs/snippets/homelab-ssh-targets.md
index 7c599a85f..e7f76087e 100644
--- a/docs/snippets/homelab-ssh-targets.md
+++ b/docs/snippets/homelab-ssh-targets.md
@@ -302,5 +302,5 @@ async (o = {}) => {
 		},
 		targets,
 	};
-};
+}
 ```

From 51061cfa854d7624f481e41a9babd121e06276fe Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:16:09 -0400
Subject: [PATCH 11/16] fix(codemode): preserve trace params when result must
 shrink

---
 crates/labby-codemode/src/truncate.rs | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/crates/labby-codemode/src/truncate.rs b/crates/labby-codemode/src/truncate.rs
index cd351bc8b..85755ddab 100644
--- a/crates/labby-codemode/src/truncate.rs
+++ b/crates/labby-codemode/src/truncate.rs
@@ -39,16 +39,17 @@ pub(crate) fn truncate_execution_response(
     // This keeps a useful compact result from being replaced by a truncation
     // marker merely because tracing was enabled.
     if response.calls.iter().any(|call| call.params.is_some()) {
-        for call in &mut response.calls {
+        let mut without_params = response.clone();
+        for call in &mut without_params.calls {
             call.params = None;
         }
         if response_within_budget(
-            &response,
+            &without_params,
             max_response_bytes,
             max_response_tokens,
             token_estimate_divisor,
         ) {
-            return response;
+            return without_params;
         }
     }
 

From d8855d7cd7b97a191c0921d54b1706422d4cd8e1 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 11:58:31 -0400
Subject: [PATCH 12/16] fix(codemode): close saved snippet review findings

---
 crates/labby-codemode/src/execute.rs          | 40 +++++++++++-
 crates/labby-codemode/src/runner.rs           | 17 ++++-
 crates/labby-codemode/src/runner_drive.rs     |  8 ++-
 .../src/runner_drive/artifacts.rs             |  2 +-
 crates/labby-codemode/src/snippet/store.rs    | 64 +++++++++++++-----
 .../src/gateway/code_mode/search.rs           | 34 ++++++++--
 .../src/gateway/manager/code_mode_runtime.rs  | 11 ++++
 .../src/gateway/manager/tests/code_mode.rs    | 28 ++++----
 crates/labby-gateway/src/upstream/pool.rs     | 12 ++++
 .../src/upstream/pool/prompts_list.rs         | 13 ++--
 .../src/upstream/pool/resources_list.rs       | 16 ++---
 .../src/upstream/pool/stdio_transport.rs      | 36 ++++++++--
 docs/snippets/docker-host-inventory.md        | 43 +++++++-----
 docs/snippets/homelab-docker-inventory.md     | 65 +++++++++++++++++--
 docs/snippets/homelab-ssh-targets.md          | 51 ++++++++++-----
 15 files changed, 339 insertions(+), 101 deletions(-)

diff --git a/crates/labby-codemode/src/execute.rs b/crates/labby-codemode/src/execute.rs
index 123c15017..0065eba61 100644
--- a/crates/labby-codemode/src/execute.rs
+++ b/crates/labby-codemode/src/execute.rs
@@ -12,6 +12,7 @@ use crate::host::{CodeModeHost, ExecCtx, ToolCallOutcome, ToolsRender};
 use labby_runtime::{CodeModeConfig, CodeModeResultShapePolicy};
 
 use super::CodeModeBroker;
+use super::config::MAX_SOURCE_BYTES;
 use super::normalize_user_code;
 use super::shape::shape_final_result;
 use super::truncate::{response_within_budget, truncate_execution_response};
@@ -101,11 +102,20 @@ impl<H: CodeModeHost> CodeModeBroker<'_, H> {
             }
             .into());
         }
+        let max_source_bytes = config.max_source_bytes.min(MAX_SOURCE_BYTES);
+        if code.len() > max_source_bytes {
+            return Err(ToolError::InvalidParam {
+                message: format!("code exceeds max length {max_source_bytes} bytes"),
+                param: "code".to_string(),
+            }
+            .into());
+        }
         let started = std::time::Instant::now();
         let mut response = self
             .execute_sandboxed(
                 code,
                 execution_timeout(config.timeout_ms),
+                max_source_bytes,
                 caller,
                 surface,
                 config.max_log_entries,
@@ -258,6 +268,7 @@ impl<H: CodeModeHost> CodeModeBroker<'_, H> {
         &self,
         code: &str,
         timeout: Duration,
+        snippet_max_bytes: usize,
         caller: CodeModeCaller,
         surface: CodeModeSurface,
         max_log_entries: usize,
@@ -325,6 +336,7 @@ impl<H: CodeModeHost> CodeModeBroker<'_, H> {
             max_log_bytes,
             trace_params,
             scope,
+            snippet_max_bytes,
             execution_id,
         )
         .await
@@ -858,6 +870,31 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn broker_enforces_configured_source_limit_before_runner_start() {
+        let host = NoopHost::default();
+        let broker = CodeModeBroker::new(Some(&host));
+        let config = CodeModeConfig {
+            max_source_bytes: 1024,
+            ..CodeModeConfig::default()
+        };
+        let code = format!("async () => \"{}\"", "x".repeat(2048));
+
+        let error = broker
+            .execute_with_raw_response(
+                &code,
+                CodeModeCaller::TrustedLocal,
+                CodeModeSurface::Cli,
+                config,
+                ToolScope::default(),
+                None,
+            )
+            .await
+            .expect_err("configured lower source limit must reject before runner start");
+
+        assert!(format!("{error}").contains("code exceeds max length 1024 bytes"));
+    }
+
     #[test]
     fn execution_timeout_reserves_response_delivery_margin() {
         assert_eq!(execution_timeout(30_000), Duration::from_millis(29_500));
@@ -1360,8 +1397,7 @@ mod tests {
                 CodeModeCaller::TrustedLocal,
                 CodeModeSurface::Cli,
                 &ToolScope::default(),
-                ExecCtx::none(),
-            )
+                ExecCtx::none(),            )
             .await
             .expect("a host list_tools failure must fail open, not propagate as an error");
         assert_eq!(result, json!({ "dts": null }));
diff --git a/crates/labby-codemode/src/runner.rs b/crates/labby-codemode/src/runner.rs
index b8776f1cb..496121e2b 100644
--- a/crates/labby-codemode/src/runner.rs
+++ b/crates/labby-codemode/src/runner.rs
@@ -8,6 +8,7 @@ use serde_json::Value;
 
 use crate::CodeModeCallError;
 
+use super::config::MAX_SNIPPET_RESOLVED_BYTES_PER_RUN;
 use super::protocol::CODE_MODE_STACK_SIZE_LIMIT;
 use super::protocol::{
     CodeModeRunnerInput, CodeModeRunnerOutput, CodeModeRunnerResult, CodeModeRunnerState,
@@ -444,7 +445,7 @@ globalThis.__labSnippetResolveCount = 0;
 globalThis.__labSnippetResolvedBytes = 0;
 globalThis.__labSnippetMaxDepth = 8;
 globalThis.__labSnippetMaxResolves = 32;
-globalThis.__labSnippetMaxBytes = 262144;
+globalThis.__labSnippetMaxBytes = {snippet_max_bytes};
 {codec}
 globalThis.callTool = (id, params = {{}}) => {{
   if (typeof id !== "string" || id.trim() === "") {{
@@ -599,9 +600,23 @@ globalThis.__labMainPromise = (async () => {{
         codec = CODE_MODE_VALUE_CODEC_JS,
         invoker = invoker,
         proxy = proxy,
+        snippet_max_bytes = MAX_SNIPPET_RESOLVED_BYTES_PER_RUN,
     )
 }
 
+#[cfg(test)]
+mod wrapper_tests {
+    use super::*;
+
+    #[test]
+    fn generated_wrapper_uses_the_shared_composed_snippet_budget() {
+        let wrapped = wrap_code_mode("async () => ({ ok: true })", "");
+        assert!(wrapped.contains(&format!(
+            "globalThis.__labSnippetMaxBytes = {MAX_SNIPPET_RESOLVED_BYTES_PER_RUN};"
+        )));
+    }
+}
+
 enum JavyMainPromiseState {
     Pending,
     /// The async function returned. `result` is the JSON-serialized return value,
diff --git a/crates/labby-codemode/src/runner_drive.rs b/crates/labby-codemode/src/runner_drive.rs
index 42169ed88..e9050be79 100644
--- a/crates/labby-codemode/src/runner_drive.rs
+++ b/crates/labby-codemode/src/runner_drive.rs
@@ -191,6 +191,8 @@ pub(crate) struct RunnerConfig {
     pub max_log_bytes: usize,
     pub trace_params: bool,
     pub capability_filter: ToolScope,
+    /// Effective total byte budget for source resolved through `codemode.run`.
+    pub snippet_max_bytes: usize,
     /// Durable-run execution id, minted by the caller (binary/gateway). `None`
     /// on the write-free/standalone path; flows into every [`ExecCtx`] so the
     /// host's `record_step` can key its per-execution journal buffer.
@@ -283,6 +285,7 @@ impl<H: CodeModeHost> CodeModeBroker<'_, H> {
         max_log_bytes: usize,
         trace_params: bool,
         capability_filter: ToolScope,
+        snippet_max_bytes: usize,
         execution_id: Option<Arc<str>>,
     ) -> Result<CodeModeExecutionResponse, CodeModeExecutionError> {
         // Read the openapi registry/client from the host at the config-build site
@@ -318,6 +321,7 @@ impl<H: CodeModeHost> CodeModeBroker<'_, H> {
             max_log_bytes,
             trace_params,
             capability_filter,
+            snippet_max_bytes: snippet_max_bytes.min(MAX_SNIPPET_RESOLVED_BYTES_PER_RUN),
             execution_id,
             openapi_registry,
             openapi_http_client,
@@ -1393,8 +1397,7 @@ async fn handle_completed_tool_call(
                         error_kind: None,
                         ui,
                     },
-                ));
-            }
+                ));            }
             write_runner_input_by_deadline(
                 stdin,
                 &CodeModeRunnerInput::ToolResult {
@@ -1468,6 +1471,7 @@ mod tests {
             max_log_bytes: 4096,
             trace_params: false,
             capability_filter: ToolScope::default(),
+            snippet_max_bytes: MAX_SNIPPET_RESOLVED_BYTES_PER_RUN,
             execution_id: None,
             openapi_registry: labby_openapi::OpenApiRegistry::default(),
             openapi_http_client: labby_openapi::http::build_dispatch_client()
diff --git a/crates/labby-codemode/src/runner_drive/artifacts.rs b/crates/labby-codemode/src/runner_drive/artifacts.rs
index e41e28bec..f3715953e 100644
--- a/crates/labby-codemode/src/runner_drive/artifacts.rs
+++ b/crates/labby-codemode/src/runner_drive/artifacts.rs
@@ -148,7 +148,7 @@ async fn resolve_snippet_for_runner<H: CodeModeHost>(
     let resolved = host.resolve_snippet(name, input).await?;
     let (name, code, input) = (resolved.name, resolved.code, resolved.input);
     state.snippet_resolved_bytes = state.snippet_resolved_bytes.saturating_add(code.len());
-    if state.snippet_resolved_bytes > MAX_SNIPPET_RESOLVED_BYTES_PER_RUN {
+    if state.snippet_resolved_bytes > cfg.snippet_max_bytes {
         return Err(ToolError::Sdk {
             sdk_kind: "snippet_budget_exceeded".to_string(),
             message: "resolved snippet code budget exceeded".to_string(),
diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index c8a250887..3c3fb16d3 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -344,13 +344,15 @@ pub fn resolve_snippet(
     if let Some(path) = find_snippet_file(builtin_dir, name) {
         return read_resolved(name, SnippetSource::Builtin, path);
     }
+    tracing::debug!(
+        snippet = %name,
+        user_dir = %user_dir.display(),
+        builtin_dir = %builtin_dir.display(),
+        "saved snippet was not found in configured authorities"
+    );
     Err(ToolError::Sdk {
         sdk_kind: "not_found".to_string(),
-        message: format!(
-            "snippet `{name}` not found; searched user snippets at `{}` and built-ins at `{}`",
-            user_dir.display(),
-            builtin_dir.display()
-        ),
+        message: format!("snippet `{name}` not found"),
     })
 }
 
@@ -1076,21 +1078,15 @@ mod tests {
     }
 
     #[test]
-    fn resolve_snippet_not_found_reports_searched_authorities() {
+    fn resolve_snippet_not_found_does_not_expose_filesystem_authorities() {
         let lab_home = tempfile::tempdir().expect("lab home");
         let builtin = tempfile::tempdir().expect("builtin snippets");
         let error = resolve_snippet(lab_home.path(), builtin.path(), "missing")
             .expect_err("missing snippet must fail");
         let message = format!("{error}");
         assert!(message.contains("missing"));
-        assert!(
-            message.contains(&user_snippet_dir(lab_home.path()).display().to_string()),
-            "error must identify the user snippet authority: {message}"
-        );
-        assert!(
-            message.contains(&builtin.path().display().to_string()),
-            "error must identify the builtin snippet authority: {message}"
-        );
+        assert!(!message.contains(&user_snippet_dir(lab_home.path()).display().to_string()));
+        assert!(!message.contains(&builtin.path().display().to_string()));
     }
 
     #[test]
@@ -1196,6 +1192,43 @@ mod tests {
         );
     }
 
+    #[test]
+    fn homelab_inventory_snippets_pin_ssh_safety_and_artifact_redaction() {
+        let lab_home = tempfile::tempdir().expect("temp lab home");
+        let builtin = builtin_snippet_dir();
+        let ssh = code_for_snippet(
+            &resolve_snippet(lab_home.path(), &builtin, "homelab-ssh-targets")
+                .expect("resolve ssh targets"),
+        )
+        .expect("valid ssh targets source");
+        let docker = code_for_snippet(
+            &resolve_snippet(lab_home.path(), &builtin, "docker-host-inventory")
+                .expect("resolve docker host inventory"),
+        )
+        .expect("valid docker host source");
+        let aggregate = code_for_snippet(
+            &resolve_snippet(lab_home.path(), &builtin, "homelab-docker-inventory")
+                .expect("resolve aggregate inventory"),
+        )
+        .expect("valid aggregate source");
+
+        for code in [&ssh, &docker] {
+            assert!(code.contains("-o ForwardAgent=no"));
+            assert!(code.contains("-o ClearAllForwardings=yes"));
+            assert!(code.contains("ssh ") && code.contains(" -- "));
+            assert!(code.contains("docker_path=%s"));
+            assert!(code.contains("timeout_path=%s"));
+        }
+        assert!(ssh.contains("ssh -G -- "));
+        assert!(ssh.contains("config_file_limit_reached"));
+        assert!(ssh.contains("config_truncated"));
+        assert!(aggregate.contains("delete artifactInput.ssh_config"));
+        assert!(aggregate.contains("parsed_config_file_count"));
+        assert!(aggregate.contains("identity_files_configured"));
+        assert!(aggregate.contains("artifactTargets"));
+        assert!(aggregate.contains("ssh_config_supplied"));
+    }
+
     #[test]
     fn repo_status_gh_pulse_builtin_is_discoverable_and_executable() {
         let lab_home = tempfile::tempdir().expect("temp lab home");
@@ -1364,8 +1397,7 @@ mod tests {
 
     #[test]
     fn read_resolved_rejects_non_utf8_snippet_files() {
-        let dir = tempfile::tempdir().expect("temp snippets");
-        let path = dir.path().join("demo.js");
+        let dir = tempfile::tempdir().expect("temp snippets");        let path = dir.path().join("demo.js");
         fs::write(&path, [0xff, 0xfe, 0xfd]).expect("write non-UTF8 fixture");
 
         let error = read_resolved("demo", SnippetSource::User, path)
diff --git a/crates/labby-gateway/src/gateway/code_mode/search.rs b/crates/labby-gateway/src/gateway/code_mode/search.rs
index 60031c2a0..37ea0fb81 100644
--- a/crates/labby-gateway/src/gateway/code_mode/search.rs
+++ b/crates/labby-gateway/src/gateway/code_mode/search.rs
@@ -152,12 +152,13 @@ pub(crate) async fn build_tools_render(
 }
 
 fn filter_tools_for_access(tools: Vec<UpstreamTool>, scope: &ToolScope) -> Vec<UpstreamTool> {
-    if !scope.is_read_only() {
-        return tools;
-    }
     tools
         .into_iter()
-        .filter(super::code_mode_host::tool_is_explicitly_read_only)
+        .filter(|tool| {
+            scope.allows(tool.upstream_name.as_ref(), tool.tool.name.as_ref())
+                && (!scope.is_read_only()
+                    || super::code_mode_host::tool_is_explicitly_read_only(tool))
+        })
         .collect()
 }
 
@@ -767,6 +768,31 @@ mod tests {
         );
     }
 
+    #[test]
+    fn exact_tool_scope_filters_model_facing_catalog_within_allowed_upstream() {
+        let named = Arc::<str>::from("fixture");
+        let make = |name: &str| UpstreamTool {
+            tool: rmcp::model::Tool::new(
+                name.to_string(),
+                "fixture",
+                Arc::new(serde_json::Map::new()),
+            ),
+            input_schema: None,
+            output_schema: None,
+            upstream_name: Arc::clone(&named),
+            destructive: false,
+        };
+        let scope = ToolScope::scoped_namespaces(
+            vec!["fixture".to_string()],
+            vec!["fixture::query".to_string()],
+        );
+
+        let filtered = filter_tools_for_access(vec![make("query"), make("mutate")], &scope);
+
+        assert_eq!(filtered.len(), 1);
+        assert_eq!(filtered[0].tool.name.as_ref(), "query");
+    }
+
     #[test]
     fn read_only_catalog_filter_is_fail_closed() {
         let named = Arc::<str>::from("fixture");
diff --git a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
index bc3540192..59d16aa25 100644
--- a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
+++ b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
@@ -599,6 +599,7 @@ impl GatewayManager {
         let mut updates = Vec::new();
         let mut connected = 0usize;
         let mut failures = Vec::new();
+        let mut failed_upstream_names = Vec::new();
         let mut failed_probes = Vec::new();
         let budget_exhausted = loop {
             match tokio::time::timeout_at(deadline, probes.next()).await {
@@ -625,6 +626,7 @@ impl GatewayManager {
                         "upstream connect failed; omitting from codemode proxy and \
                          suppressing retries briefly"
                     );
+                    failed_upstream_names.push(upstream.name.clone());
                     failures.push(format!("{}: {error}", upstream.name));
                     // Only this arm is a real failure. The budget-exhausted
                     // paths below are not, and must not be suppressed.
@@ -725,6 +727,15 @@ impl GatewayManager {
                 ),
             });
         }
+        if !failed_upstream_names.is_empty() {
+            tracing::warn!(
+                surface = "dispatch",
+                service = "gateway",
+                action = "code_mode.catalog_cache",
+                failed_upstreams = ?failed_upstream_names,
+                "one-shot Code Mode catalog is partial because upstream probes failed"
+            );
+        }
         if !suppressed.is_empty() {
             warn_suppressed(&suppressed);
         }
diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index 1c79ccd0c..ad27b7804 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -1397,8 +1397,7 @@ async fn palette_search_reports_truncation_when_global_inspection_budget_is_exha
                         tool: rmcp::model::Tool::new(
                             name,
                             "ordinary fixture",
-                            Arc::new(serde_json::Map::new()),
-                        ),
+                            Arc::new(serde_json::Map::new()),                        ),
                         input_schema: None,
                         output_schema: None,
                         upstream_name: Arc::clone(&upstream_name),
@@ -2503,7 +2502,7 @@ fn budget_warning(logs: &str) -> Option<&str> {
 /// in flight. Only that it never lands in the catalog or the cache matters
 /// here; the failure-reporting path is pinned by
 /// `one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast`.
-#[tokio::test]
+#[tokio::test(flavor = "current_thread")]
 async fn one_shot_cli_catalog_bounds_cold_connects_and_persists_completed_upstreams() {
     let stalled = stalled_http_upstream("alpha").await;
     // `fixture_http_upstream` points at 127.0.0.1:9, which nothing listens on.
@@ -2740,7 +2739,7 @@ async fn one_shot_cli_catalog_keeps_config_order_and_serves_repeat_runs_from_cac
 /// A cached upstream keeps the run partial rather than failed when a
 /// straggler misses the budget: the cached tools are served without a
 /// connect and the straggler is named.
-#[tokio::test]
+#[tokio::test(flavor = "current_thread")]
 async fn one_shot_cli_catalog_serves_cached_upstreams_when_a_straggler_misses_the_budget() {
     let responder = OneShotHttpResponder::new("ping", Duration::ZERO);
     let (_server, healthy) = cold_http_upstream("omega", responder.clone()).await;
@@ -2783,7 +2782,7 @@ async fn one_shot_cli_catalog_serves_cached_upstreams_when_a_straggler_misses_th
 /// An upstream whose tools landed before the budget ended is connected even if
 /// the connect's trailing prompt-cache refresh is what the deadline cut off:
 /// its tools are served and cached, and nothing is reported as unfinished.
-#[tokio::test]
+#[tokio::test(flavor = "current_thread")]
 async fn one_shot_cli_catalog_keeps_an_upstream_whose_tools_landed_before_the_cutoff() {
     let responder = OneShotHttpResponder::new("ping", Duration::ZERO)
         .with_prompts_delay(Duration::from_mins(2));
@@ -2797,8 +2796,7 @@ async fn one_shot_cli_catalog_keeps_an_upstream_whose_tools_landed_before_the_cu
     let (tools, logs) = with_captured_logs(|| {
         tokio::time::timeout(
             BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),
-        )
+            manager.code_mode_catalog_tools_cached(None, None),        )
     })
     .await;
     let tools = tools
@@ -2914,7 +2912,7 @@ async fn one_shot_cli_catalog_names_unattempted_upstreams_when_stalled_probes_fi
 /// A fresh cache entry with zero tools (a resource- or prompt-only upstream)
 /// still counts as served from cache: a straggler missing the budget leaves
 /// the run partial with an empty tool list, not failed.
-#[tokio::test]
+#[tokio::test(flavor = "current_thread")]
 async fn one_shot_cli_catalog_treats_a_cached_zero_tool_upstream_as_served() {
     let quiet = fixture_http_upstream("omega");
     let cache_dir = tempfile::tempdir().expect("tempdir");
@@ -2955,7 +2953,7 @@ async fn one_shot_cli_catalog_treats_a_cached_zero_tool_upstream_as_served() {
 /// `fixture_http_upstream` points at the discard port, so the probe fails fast
 /// rather than stalling — this is the failure path, distinct from the
 /// budget-exhaustion paths, and the only one the negative cache may suppress.
-#[tokio::test]
+#[tokio::test(flavor = "current_thread")]
 async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
     let cache_dir = tempfile::tempdir().expect("tempdir");
     let cache_path = cache_dir.path().join("codemode-catalog.json");
@@ -2966,10 +2964,9 @@ async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
     let (manager, _pool) =
         one_shot_manager_at(vec![dead.clone(), healthy], 4_000, cache_path.clone()).await;
 
-    let first = manager
-        .code_mode_catalog_tools_cached(None, None)
-        .await
-        .expect("first run should serve the healthy upstream");
+    let (first, first_logs) =
+        with_captured_logs(|| manager.code_mode_catalog_tools_cached(None, None)).await;
+    let first = first.expect("first run should serve the healthy upstream");
     assert_eq!(
         first
             .iter()
@@ -2977,6 +2974,11 @@ async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
             .collect::<Vec<_>>(),
         vec!["ping"]
     );
+    assert!(
+        first_logs.contains("catalog is partial because upstream probes failed")
+            && first_logs.contains("dead"),
+        "partial one-shot catalog must emit one actionable failed-upstream warning: {first_logs}"
+    );
 
     // The failure is now on disk, and the healthy upstream is cached, so the
     // second run must reach neither the network nor the dead upstream.
diff --git a/crates/labby-gateway/src/upstream/pool.rs b/crates/labby-gateway/src/upstream/pool.rs
index 729594c6e..84f6659d6 100644
--- a/crates/labby-gateway/src/upstream/pool.rs
+++ b/crates/labby-gateway/src/upstream/pool.rs
@@ -10,6 +10,8 @@ use std::sync::{
 };
 
 use dashmap::DashMap;
+#[cfg(test)]
+use std::sync::atomic::AtomicUsize;
 use std::time::{Duration, Instant};
 
 use arc_swap::ArcSwap;
@@ -419,6 +421,12 @@ pub struct UpstreamPool {
     /// Shared per-upstream SEP-2243 recovery metrics. Gateway-managed pools
     /// inherit one process-lifetime store across pool replacement.
     header_recovery_metrics_store: HeaderRecoveryMetricsStore,
+    /// Test-local serialization counters live on the pool so parallel catalog
+    /// tests cannot contaminate each other's measurement oracles.
+    #[cfg(test)]
+    pub(super) merged_prompt_measurements: Arc<AtomicUsize>,
+    #[cfg(test)]
+    pub(super) merged_resource_measurements: Arc<AtomicUsize>,
 }
 
 /// Type-erased-over-lifecycle running client service.
@@ -635,6 +643,10 @@ impl UpstreamPool {
             shared_http_client,
             usage_store: None,
             header_recovery_metrics_store: HeaderRecoveryMetricsStore::default(),
+            #[cfg(test)]
+            merged_prompt_measurements: Arc::new(AtomicUsize::new(0)),
+            #[cfg(test)]
+            merged_resource_measurements: Arc::new(AtomicUsize::new(0)),
         }
     }
 
diff --git a/crates/labby-gateway/src/upstream/pool/prompts_list.rs b/crates/labby-gateway/src/upstream/pool/prompts_list.rs
index 97d912c2f..7d5c3d05c 100644
--- a/crates/labby-gateway/src/upstream/pool/prompts_list.rs
+++ b/crates/labby-gateway/src/upstream/pool/prompts_list.rs
@@ -21,12 +21,6 @@ use super::helpers::merge_upstream_prompts;
 use super::logging::is_capability_unsupported;
 use super::tools::MAX_UPSTREAM_PROMPTS;
 
-/// Number of prompt serializations performed while bounding the merged
-/// envelope; tests assert each prompt is measured once.
-#[cfg(test)]
-pub(super) static MERGED_PROMPT_MEASUREMENTS: std::sync::atomic::AtomicUsize =
-    std::sync::atomic::AtomicUsize::new(0);
-
 /// One regular non-OAuth upstream Prompt with exact pre-namespace provenance.
 /// This is observational listing metadata, not prompt execution authority.
 #[derive(Clone, Debug, PartialEq)]
@@ -224,7 +218,8 @@ impl UpstreamPool {
             super::helpers::max_response_bytes(),
             |prompt| {
                 #[cfg(test)]
-                MERGED_PROMPT_MEASUREMENTS.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+                self.merged_prompt_measurements
+                    .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
                 serde_json::to_vec(prompt).map_or(usize::MAX, |body| body.len() + 1)
             },
         );
@@ -519,12 +514,12 @@ mod tests {
         for index in 1..5 {
             attach_prompt_server(&pool, &format!("many-{index}"), ManyPromptsServer).await;
         }
-        MERGED_PROMPT_MEASUREMENTS.store(0, Ordering::SeqCst);
+        pool.merged_prompt_measurements.store(0, Ordering::SeqCst);
 
         let prompts = pool.list_upstream_prompts(&[]).await;
 
         assert_eq!(prompts.len(), 3000.min(MAX_UPSTREAM_PROMPTS));
-        let measurements = MERGED_PROMPT_MEASUREMENTS.load(Ordering::SeqCst);
+        let measurements = pool.merged_prompt_measurements.load(Ordering::SeqCst);
         assert!(
             measurements <= 3000,
             "each prompt must be measured once while bounding the merged envelope; measured {measurements} times"
diff --git a/crates/labby-gateway/src/upstream/pool/resources_list.rs b/crates/labby-gateway/src/upstream/pool/resources_list.rs
index 4502177d8..70498d986 100644
--- a/crates/labby-gateway/src/upstream/pool/resources_list.rs
+++ b/crates/labby-gateway/src/upstream/pool/resources_list.rs
@@ -46,12 +46,6 @@ use super::tools::MAX_UPSTREAM_RESOURCES;
 /// stalls every queued OAuth writer behind one slow upstream.
 const CATALOG_LISTING_TIMEOUT: Duration = Duration::from_secs(10);
 
-/// Number of resource serializations performed while bounding the merged
-/// envelope; tests assert each resource is measured once.
-#[cfg(test)]
-pub(super) static MERGED_RESOURCE_MEASUREMENTS: std::sync::atomic::AtomicUsize =
-    std::sync::atomic::AtomicUsize::new(0);
-
 /// One regular upstream Resource with its exact pre-rewrite provenance.
 ///
 /// This is observational listing metadata, not read authority or a grant.
@@ -515,7 +509,8 @@ impl UpstreamPool {
         let mut bytes = 2usize;
         resources.retain(|item| {
             #[cfg(test)]
-            MERGED_RESOURCE_MEASUREMENTS.fetch_add(1, std::sync::atomic::Ordering::SeqCst);
+            self.merged_resource_measurements
+                .fetch_add(1, std::sync::atomic::Ordering::SeqCst);
             bytes = bytes.saturating_add(
                 serde_json::to_vec(&item.resource).map_or(usize::MAX, |body| body.len() + 1),
             );
@@ -1057,12 +1052,12 @@ mod tests {
             .expect("connection identity");
             pool.resource_upstreams.write().await.push(name);
         }
-        MERGED_RESOURCE_MEASUREMENTS.store(0, Ordering::SeqCst);
+        pool.merged_resource_measurements.store(0, Ordering::SeqCst);
 
         let resources = pool.list_upstream_resources_allowed(None).await;
 
         assert_eq!(resources.len(), 3000.min(MAX_UPSTREAM_RESOURCES));
-        let measurements = MERGED_RESOURCE_MEASUREMENTS.load(Ordering::SeqCst);
+        let measurements = pool.merged_resource_measurements.load(Ordering::SeqCst);
         assert!(
             measurements <= 3000,
             "each resource must be measured once while bounding the merged envelope; measured {measurements} times"
@@ -1402,8 +1397,7 @@ mod tests {
         let before = pool.catalog.read().await["alpha"].clone();
 
         let stale_rows = vec![Resource::new("file:///stale", "stale")];
-        assert!(
-            pool.apply_observed_resource_list_success(&stale, &stale_rows)
+        assert!(            pool.apply_observed_resource_list_success(&stale, &stale_rows)
                 .await
                 .is_none()
         );
diff --git a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
index e38bbb724..24ca2ada1 100644
--- a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
+++ b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
@@ -232,6 +232,15 @@ fn exit_signal(_status: Option<&ExitStatus>) -> Option<i32> {
     None
 }
 
+const fn termination_is_clean(
+    expected: bool,
+    success: bool,
+    killed_after_timeout: bool,
+    invalidated_count: usize,
+) -> bool {
+    expected && invalidated_count == 0 && (success || killed_after_timeout)
+}
+
 async fn log_termination(
     upstream: String,
     generation: u64,
@@ -249,7 +258,12 @@ async fn log_termination(
     let success = status.is_some_and(ExitStatus::success);
     let invalidated_count = invalidated_requests.len();
 
-    if invalidated_count == 0 {
+    if termination_is_clean(
+        expected,
+        success,
+        exit.killed_after_timeout,
+        invalidated_count,
+    ) {
         tracing::info!(
             surface = "dispatch",
             service = "upstream.pool",
@@ -266,7 +280,7 @@ async fn log_termination(
             invalidated_count,
             stderr_tail = %stderr_tail,
             success,
-            "stdio upstream child terminated without affected requests"
+            "stdio upstream child terminated cleanly"
         );
     } else {
         tracing::warn!(
@@ -285,7 +299,8 @@ async fn log_termination(
             invalidated_count,
             invalidated_requests = ?invalidated_requests,
             stderr_tail = %stderr_tail,
-            "stdio upstream child terminated with affected requests"
+            success,
+            "stdio upstream child terminated unexpectedly or with affected requests"
         );
     }
 }
@@ -413,8 +428,11 @@ impl Drop for DiagnosticChildTransport {
                 upstream,
                 generation,
                 pid,
+                // Dropping the transport is owner-initiated teardown. A child that
+                // exits on its own is observed by `receive*` as `transport_eof`
+                // before Drop and remains unexpected.
                 "transport_drop",
-                false,
+                true,
                 diagnostics,
                 invalidated,
                 exit,
@@ -470,6 +488,16 @@ mod tests {
     use super::*;
     use tokio::io::{AsyncReadExt, AsyncWriteExt};
 
+    #[test]
+    fn termination_severity_distinguishes_expected_teardown_from_unexpected_exit() {
+        assert!(termination_is_clean(true, true, false, 0));
+        assert!(termination_is_clean(true, false, true, 0));
+        assert!(!termination_is_clean(false, true, false, 0));
+        assert!(!termination_is_clean(false, false, false, 0));
+        assert!(!termination_is_clean(true, false, false, 0));
+        assert!(!termination_is_clean(true, true, false, 1));
+    }
+
     #[test]
     fn inflight_registry_is_scoped_to_connection_generation() {
         let upstream = format!(
diff --git a/docs/snippets/docker-host-inventory.md b/docs/snippets/docker-host-inventory.md
index c47f9ff4b..bebf9ffff 100644
--- a/docs/snippets/docker-host-inventory.md
+++ b/docs/snippets/docker-host-inventory.md
@@ -104,30 +104,39 @@ async (o = {}) => {
 			"-o PreferredAuthentications=publickey",
 			"-o PasswordAuthentication=no",
 			"-o KbdInteractiveAuthentication=no",
+			"-o ForwardAgent=no",
+			"-o ClearAllForwardings=yes",
 			"-o ConnectionAttempts=1",
 			"-o ConnectTimeout=" + i.connect_timeout_seconds,
 		].join(" "),
 		ssh = (r) =>
 			callTool(bash, {
-				command: "ssh " + opts + " " + q(i.alias) + " " + q(r),
+				command: "ssh " + opts + " -- " + q(i.alias) + " " + q(r),
 				timeout: i.command_timeout_ms,
 			});
-	const id = txt(
-			await ssh(
-				"hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true",
-			),
-		)
-			.split("\n")
-			.map((x) => x.trim()),
-		host = {
-			alias: i.alias,
-			hostname: id[0] || null,
-			user: id[1] || null,
-			platform: id[2] || null,
-			docker_path: id[3] || null,
-			docker_version: id[4] || null,
-			timeout_path: id[5] || null,
-		};
+	const hostProbe = [
+		'printf "hostname=%s\n" "$(hostname)"',
+		'printf "user=%s\n" "$(whoami)"',
+		'printf "platform=%s\n" "$(uname -s)"',
+		'printf "docker_path=%s\n" "$(command -v docker 2>/dev/null || true)"',
+		'printf "docker_version=%s\n" "$(docker version --format \'{{.Server.Version}}\' 2>/dev/null || true)"',
+		'printf "timeout_path=%s\n" "$(command -v timeout 2>/dev/null || true)"',
+	].join("; ");
+	const fields = {};
+	for (const line of txt(await ssh(hostProbe)).split("\n")) {
+		const n = line.indexOf("=");
+		if (n < 1) continue;
+		fields[line.slice(0, n)] = line.slice(n + 1).trim();
+	}
+	const host = {
+		alias: i.alias,
+		hostname: fields.hostname || null,
+		user: fields.user || null,
+		platform: fields.platform || null,
+		docker_path: fields.docker_path || null,
+		docker_version: fields.docker_version || null,
+		timeout_path: fields.timeout_path || null,
+	};
 	if (!host.hostname)
 		throw new Error("SSH probe returned no hostname for " + i.alias);
 	if (!host.docker_path)
diff --git a/docs/snippets/homelab-docker-inventory.md b/docs/snippets/homelab-docker-inventory.md
index 3038957a1..b915b82da 100644
--- a/docs/snippets/homelab-docker-inventory.md
+++ b/docs/snippets/homelab-docker-inventory.md
@@ -154,13 +154,65 @@ async (o = {}) => {
 		for (const [k, v] of Object.entries(inv.summary?.image_update_states || {}))
 			updates[k] = (updates[k] || 0) + v;
 	}
+	const artifactInput = { ...input };
+	delete artifactInput.ssh_config;
+	artifactInput.ssh_config_supplied = Boolean(input.ssh_config);
+	const sourceController = discovery.controller || {};
+	const artifactController = {
+		upstream: sourceController.upstream || null,
+		hostname: sourceController.hostname || null,
+		user: sourceController.user || null,
+		platform: sourceController.platform || null,
+		ssh_path: sourceController.ssh_path || null,
+		ssh_config_supplied: Boolean(sourceController.ssh_config),
+	};
+	const sanitizeEffective = (effective) =>
+		effective
+			? {
+				hostname: effective.hostname || null,
+				user: effective.user || null,
+				port: effective.port || 22,
+				identity_files_configured: (effective.identity_files || []).length,
+				identity_agent_configured: Boolean(
+					effective.identity_agent && effective.identity_agent !== "none",
+				),
+			}
+			: null;
+	const redactLocal = (value) => {
+		let text = String(value || "");
+		for (const local of [input.ssh_config, sourceController.home, sourceController.cwd])
+			if (local) text = text.split(String(local)).join("<redacted-local-path>");
+		return text;
+	};
+	const sanitizeTarget = (target) => ({
+		alias: target.alias,
+		source_count: (target.sources || []).length,
+		effective: sanitizeEffective(target.effective),
+		key_auth_configured: target.key_auth_configured,
+		key_auth_working: target.key_auth_working,
+		ssh_reachable: target.ssh_reachable,
+		failure_kind: target.failure_kind || null,
+		error: target.error ? redactLocal(target.error) : null,
+		remote: target.remote || null,
+	});
+	const artifactDiscovery = { ...(discovery.discovery || {}) };
+	artifactDiscovery.parsed_config_file_count = (
+		artifactDiscovery.parsed_config_files || []
+	).length;
+	delete artifactDiscovery.parsed_config_files;
+	artifactDiscovery.warnings = (artifactDiscovery.warnings || []).map((warning) => ({
+		type: warning.type,
+		limit: warning.limit,
+		remaining: warning.remaining,
+	}));
+	const artifactTargets = (discovery.targets || []).map(sanitizeTarget);
 	const report = {
 		schema_version: "labby.homelab.docker_inventory.v1",
 		generated_at: new Date().toISOString(),
-		input,
-		controller: discovery.controller,
+		input: artifactInput,
+		controller: artifactController,
 		discovery: {
-			...discovery.discovery,
+			...artifactDiscovery,
 			unique_reachable_devices: new Set(
 				(discovery.targets || [])
 					.filter((t) => t?.ssh_reachable && t.remote?.hostname)
@@ -173,7 +225,7 @@ async (o = {}) => {
 			).size,
 			docker_hosts: devices.length,
 		},
-		ssh_targets: discovery.targets || [],
+		ssh_targets: artifactTargets,
 		devices,
 		host_failures: hostFailures,
 		summary: {
@@ -193,6 +245,7 @@ async (o = {}) => {
 		schema_version: report.schema_version,
 		ok: hostsWithErrors === 0,
 		partial:
+			discovery.partial === true ||
 			(report.discovery.ssh_unreachable || 0) > 0 ||
 			hostsWithErrors > 0 ||
 			(updates.unknown || 0) > 0,
@@ -215,10 +268,10 @@ async (o = {}) => {
 			.filter((t) => !t.ssh_reachable)
 			.map((t) => ({
 				alias: t.alias,
-				effective: t.effective,
+				effective: sanitizeEffective(t.effective),
 				key_auth_configured: t.key_auth_configured,
 				failure_kind: t.failure_kind,
-				error: t.error,
+				error: t.error ? redactLocal(t.error) : null,
 			})),
 	};
 }
diff --git a/docs/snippets/homelab-ssh-targets.md b/docs/snippets/homelab-ssh-targets.md
index e7f76087e..87e221d56 100644
--- a/docs/snippets/homelab-ssh-targets.md
+++ b/docs/snippets/homelab-ssh-targets.md
@@ -174,6 +174,14 @@ async (o = {}) => {
 				}
 		}
 	}
+	const config_truncated = queue.length > 0;
+	if (config_truncated) {
+		warnings.push({
+			type: "config_file_limit_reached",
+			limit: 16,
+			remaining: queue.length,
+		});
+	}
 	for (const raw of input.extra_hosts) {
 		const alias = String(raw || "").trim();
 		if (alias && !input.exclude_hosts.includes(alias) && !aliases.has(alias))
@@ -193,7 +201,7 @@ async (o = {}) => {
 				};
 				for (const line of text(
 					await callTool(bashTool.id, {
-						command: "ssh -G " + quote(target.alias),
+						command: "ssh -G -- " + quote(target.alias),
 						timeout: input.command_timeout_ms,
 					}),
 				).split("\n")) {
@@ -233,6 +241,8 @@ async (o = {}) => {
 		"-o PreferredAuthentications=publickey",
 		"-o PasswordAuthentication=no",
 		"-o KbdInteractiveAuthentication=no",
+		"-o ForwardAgent=no",
+		"-o ClearAllForwardings=yes",
 		"-o ConnectionAttempts=1",
 		"-o ConnectTimeout=" + input.connect_timeout_seconds,
 	].join(" ");
@@ -245,18 +255,27 @@ async (o = {}) => {
 				failure_kind: "config_failed",
 			};
 		try {
-			const probe =
-				"hostname; whoami; uname -s; command -v docker || true; docker version --format '{{.Server.Version}}' 2>/dev/null || true; command -v timeout || true";
-			const lines = text(
+			const probe = [
+				'printf "hostname=%s\n" "$(hostname)"',
+				'printf "user=%s\n" "$(whoami)"',
+				'printf "platform=%s\n" "$(uname -s)"',
+				'printf "docker_path=%s\n" "$(command -v docker 2>/dev/null || true)"',
+				'printf "docker_version=%s\n" "$(docker version --format \'{{.Server.Version}}\' 2>/dev/null || true)"',
+				'printf "timeout_path=%s\n" "$(command -v timeout 2>/dev/null || true)"',
+			].join("; ");
+			const fields = {};
+			for (const line of text(
 				await callTool(bashTool.id, {
 					command:
-						"ssh " + opts + " " + quote(target.alias) + " " + quote(probe),
+						"ssh " + opts + " -- " + quote(target.alias) + " " + quote(probe),
 					timeout: Math.min(input.command_timeout_ms, 12000),
 				}),
-			)
-				.split("\n")
-				.map((x) => x.trim());
-			if (!lines[0])
+			).split("\n")) {
+				const n = line.indexOf("=");
+				if (n < 1) continue;
+				fields[line.slice(0, n)] = line.slice(n + 1).trim();
+			}
+			if (!fields.hostname)
 				return {
 					...target,
 					ssh_reachable: false,
@@ -269,12 +288,12 @@ async (o = {}) => {
 				ssh_reachable: true,
 				key_auth_working: true,
 				remote: {
-					hostname: lines[0] || null,
-					user: lines[1] || null,
-					platform: lines[2] || null,
-					docker_path: lines[3] || null,
-					docker_version: lines[4] || null,
-					timeout_path: lines[5] || null,
+					hostname: fields.hostname || null,
+					user: fields.user || null,
+					platform: fields.platform || null,
+					docker_path: fields.docker_path || null,
+					docker_version: fields.docker_version || null,
+					timeout_path: fields.timeout_path || null,
 				},
 			};
 		} catch (e) {
@@ -291,10 +310,12 @@ async (o = {}) => {
 	return {
 		schema_version: "labby.homelab.ssh_targets.v1",
 		ok: true,
+		partial: warnings.length > 0,
 		controller: { ...controller, ssh_config: root },
 		discovery: {
 			parsed_config_files: Array.from(seen),
 			warnings,
+			config_truncated,
 			configured_aliases: targets.length,
 			key_auth_configured: targets.filter((x) => x.key_auth_configured).length,
 			key_auth_working: targets.filter((x) => x.key_auth_working).length,

From 535babb2a52cba84180a0c9bfbdbab1c86b97038 Mon Sep 17 00:00:00 2001
From: jmagar <38927646+jmagar@users.noreply.github.com>
Date: Wed, 16 Sep 2026 11:59:59 -0400
Subject: [PATCH 13/16] fix: preserve full file boundaries in review update

---
 crates/labby-codemode/src/execute.rs                        | 3 ++-
 crates/labby-codemode/src/runner_drive.rs                   | 3 ++-
 crates/labby-codemode/src/snippet/store.rs                  | 3 ++-
 crates/labby-gateway/src/gateway/manager/tests/code_mode.rs | 6 ++++--
 crates/labby-gateway/src/upstream/pool/resources_list.rs    | 3 ++-
 5 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/crates/labby-codemode/src/execute.rs b/crates/labby-codemode/src/execute.rs
index 0065eba61..d94144eb0 100644
--- a/crates/labby-codemode/src/execute.rs
+++ b/crates/labby-codemode/src/execute.rs
@@ -1397,7 +1397,8 @@ mod tests {
                 CodeModeCaller::TrustedLocal,
                 CodeModeSurface::Cli,
                 &ToolScope::default(),
-                ExecCtx::none(),            )
+                ExecCtx::none(),
+            )
             .await
             .expect("a host list_tools failure must fail open, not propagate as an error");
         assert_eq!(result, json!({ "dts": null }));
diff --git a/crates/labby-codemode/src/runner_drive.rs b/crates/labby-codemode/src/runner_drive.rs
index e9050be79..9102e3c90 100644
--- a/crates/labby-codemode/src/runner_drive.rs
+++ b/crates/labby-codemode/src/runner_drive.rs
@@ -1397,7 +1397,8 @@ async fn handle_completed_tool_call(
                         error_kind: None,
                         ui,
                     },
-                ));            }
+                ));
+            }
             write_runner_input_by_deadline(
                 stdin,
                 &CodeModeRunnerInput::ToolResult {
diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index 3c3fb16d3..e68ec6dd4 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -1397,7 +1397,8 @@ mod tests {
 
     #[test]
     fn read_resolved_rejects_non_utf8_snippet_files() {
-        let dir = tempfile::tempdir().expect("temp snippets");        let path = dir.path().join("demo.js");
+        let dir = tempfile::tempdir().expect("temp snippets");
+        let path = dir.path().join("demo.js");
         fs::write(&path, [0xff, 0xfe, 0xfd]).expect("write non-UTF8 fixture");
 
         let error = read_resolved("demo", SnippetSource::User, path)
diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index ad27b7804..0406f48a5 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -1397,7 +1397,8 @@ async fn palette_search_reports_truncation_when_global_inspection_budget_is_exha
                         tool: rmcp::model::Tool::new(
                             name,
                             "ordinary fixture",
-                            Arc::new(serde_json::Map::new()),                        ),
+                            Arc::new(serde_json::Map::new()),
+                        ),
                         input_schema: None,
                         output_schema: None,
                         upstream_name: Arc::clone(&upstream_name),
@@ -2796,7 +2797,8 @@ async fn one_shot_cli_catalog_keeps_an_upstream_whose_tools_landed_before_the_cu
     let (tools, logs) = with_captured_logs(|| {
         tokio::time::timeout(
             BUDGET_GUARD,
-            manager.code_mode_catalog_tools_cached(None, None),        )
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
     })
     .await;
     let tools = tools
diff --git a/crates/labby-gateway/src/upstream/pool/resources_list.rs b/crates/labby-gateway/src/upstream/pool/resources_list.rs
index 70498d986..16f7a4c7d 100644
--- a/crates/labby-gateway/src/upstream/pool/resources_list.rs
+++ b/crates/labby-gateway/src/upstream/pool/resources_list.rs
@@ -1397,7 +1397,8 @@ mod tests {
         let before = pool.catalog.read().await["alpha"].clone();
 
         let stale_rows = vec![Resource::new("file:///stale", "stale")];
-        assert!(            pool.apply_observed_resource_list_success(&stale, &stale_rows)
+        assert!(
+            pool.apply_observed_resource_list_success(&stale, &stale_rows)
                 .await
                 .is_none()
         );

From 82dbaf0c9bb97aa9798d46fc3e30c70526f02176 Mon Sep 17 00:00:00 2001
From: Jake Magar <jmagar@users.noreply.github.com>
Date: Thu, 17 Sep 2026 09:54:06 -0400
Subject: [PATCH 14/16] fix(codemode): close saved snippet hardening review

---
 crates/labby-codemode/src/execute.rs          |  53 +++++
 crates/labby-codemode/src/runner.rs           |  26 +--
 crates/labby-codemode/src/snippet/store.rs    |  53 ++++-
 .../src/gateway/manager/code_mode_runtime.rs  |  18 ++
 .../src/gateway/manager/tests/code_mode.rs    |  31 ++-
 .../labby-gateway/src/security/spawn_guard.rs |  67 ++++--
 .../src/upstream/pool/stdio_transport.rs      |  32 +--
 crates/labby/src/api/services/snippets.rs     |  21 +-
 crates/labby/src/cli/gateway/code.rs          |   3 -
 .../labby/src/dispatch/snippets/dispatch.rs   | 205 ++++++++++++++----
 crates/labby/src/mcp/call_tool.rs             |   7 +-
 crates/labby/src/mcp/call_tool_codemode.rs    |   2 +-
 crates/labby/src/mcp/services/snippets.rs     | 130 +++++++++--
 docs/snippets/docker-host-inventory.md        |   8 +-
 docs/snippets/homelab-docker-inventory.md     |   3 +-
 docs/snippets/homelab-ssh-targets.md          |  18 +-
 16 files changed, 543 insertions(+), 134 deletions(-)

diff --git a/crates/labby-codemode/src/execute.rs b/crates/labby-codemode/src/execute.rs
index d94144eb0..057f2d1ac 100644
--- a/crates/labby-codemode/src/execute.rs
+++ b/crates/labby-codemode/src/execute.rs
@@ -1167,6 +1167,59 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn raw_tool_call_boundary_rejects_undeclared_and_out_of_route_tools() {
+        let host = FixtureHost::new(vec![
+            ToolDescriptor::tool("alpha", "tool1", "allowed", None, None),
+            ToolDescriptor::tool("alpha", "other_tool", "undeclared sibling", None, None),
+            ToolDescriptor::tool("beta", "tool2", "out of route", None, None),
+        ]);
+        let broker = CodeModeBroker::new(Some(&host));
+        let scope = ToolScope::scoped_namespaces(
+            vec!["alpha".to_string()],
+            vec!["alpha::tool1".to_string()],
+        );
+
+        for id in ["alpha::other_tool", "beta::tool2"] {
+            let error = broker
+                .call_tool_id(
+                    id,
+                    json!({}),
+                    CodeModeCaller::TrustedLocal,
+                    CodeModeSurface::Cli,
+                    &scope,
+                    ExecCtx::none(),
+                )
+                .await
+                .expect_err("raw callTool target outside the effective snippet scope must fail");
+            assert_eq!(error.kind(), "unknown_tool");
+            assert!(
+                error
+                    .to_string()
+                    .contains("outside this Code Mode execution capability set"),
+                "scope rejection must happen before host dispatch: {error:?}"
+            );
+        }
+
+        let allowed = broker
+            .call_tool_id(
+                "alpha::tool1",
+                json!({}),
+                CodeModeCaller::TrustedLocal,
+                CodeModeSurface::Cli,
+                &scope,
+                ExecCtx::none(),
+            )
+            .await
+            .expect_err("fixture host intentionally rejects real dispatch after scope admission");
+        assert!(
+            allowed
+                .to_string()
+                .contains("FixtureHost does not dispatch real tool calls"),
+            "the declared in-route tool must pass the scope boundary and reach the host"
+        );
+    }
+
     #[tokio::test]
     async fn dispatch_internal_call_resource_discovery_round_trips_uri() {
         let host = FixtureHost::new(Vec::new());
diff --git a/crates/labby-codemode/src/runner.rs b/crates/labby-codemode/src/runner.rs
index 496121e2b..6912884f8 100644
--- a/crates/labby-codemode/src/runner.rs
+++ b/crates/labby-codemode/src/runner.rs
@@ -604,19 +604,6 @@ globalThis.__labMainPromise = (async () => {{
     )
 }
 
-#[cfg(test)]
-mod wrapper_tests {
-    use super::*;
-
-    #[test]
-    fn generated_wrapper_uses_the_shared_composed_snippet_budget() {
-        let wrapped = wrap_code_mode("async () => ({ ok: true })", "");
-        assert!(wrapped.contains(&format!(
-            "globalThis.__labSnippetMaxBytes = {MAX_SNIPPET_RESOLVED_BYTES_PER_RUN};"
-        )));
-    }
-}
-
 enum JavyMainPromiseState {
     Pending,
     /// The async function returned. `result` is the JSON-serialized return value,
@@ -971,3 +958,16 @@ fn runner_read_input() -> Result<CodeModeRunnerInput, RunnerReadError> {
         serde_json::from_str(&line).map_err(|err| RunnerReadError::Other(err.to_string()))
     })
 }
+
+#[cfg(test)]
+mod wrapper_tests {
+    use super::*;
+
+    #[test]
+    fn generated_wrapper_uses_the_shared_composed_snippet_budget() {
+        let wrapped = wrap_code_mode("async () => ({ ok: true })", "");
+        assert!(wrapped.contains(&format!(
+            "globalThis.__labSnippetMaxBytes = {MAX_SNIPPET_RESOLVED_BYTES_PER_RUN};"
+        )));
+    }
+}
diff --git a/crates/labby-codemode/src/snippet/store.rs b/crates/labby-codemode/src/snippet/store.rs
index e68ec6dd4..2c8b6bd3f 100644
--- a/crates/labby-codemode/src/snippet/store.rs
+++ b/crates/labby-codemode/src/snippet/store.rs
@@ -469,7 +469,12 @@ fn read_resolved(
     path: PathBuf,
 ) -> Result<ResolvedSnippet, ToolError> {
     let body = read_snippet_body(&path)?;
-    validate_snippet_body(name, &body)?;
+    // Resolution is a host-side lookup, not a second execution validator. Keep
+    // the file/frontmatter/size contract here, then let code_for_snippet() do
+    // the single authoritative Javy parse immediately before execution (or an
+    // explicit existing-snippet validation). This avoids compiling the same
+    // saved program twice per invocation.
+    validate_snippet_body_structure(name, &body)?;
     let (description, tags, inputs, tools) =
         snippet_metadata_fields(frontmatter(&body)?.filter(|m| m.name == name));
     Ok(ResolvedSnippet {
@@ -518,8 +523,7 @@ fn snippet_metadata_fields(
         .unwrap_or_default()
 }
 
-/// Validate snippet source size, syntax envelope, and frontmatter/name consistency.
-pub fn validate_snippet_body(name: &str, body: &str) -> Result<(), ToolError> {
+fn validate_snippet_body_structure(name: &str, body: &str) -> Result<(), ToolError> {
     if body.len() > MAX_SNIPPET_FILE_BYTES {
         return Err(ToolError::InvalidParam {
             message: format!("snippet file exceeds {MAX_SNIPPET_FILE_BYTES} bytes"),
@@ -548,6 +552,17 @@ pub fn validate_snippet_body(name: &str, body: &str) -> Result<(), ToolError> {
             param: "body".to_string(),
         });
     }
+    Ok(())
+}
+
+/// Validate snippet source size, syntax, and frontmatter/name consistency.
+pub fn validate_snippet_body(name: &str, body: &str) -> Result<(), ToolError> {
+    validate_snippet_body_structure(name, body)?;
+    let code = if has_frontmatter(body) || body.contains("```") {
+        extract_javascript_block(body)?
+    } else {
+        body.trim().to_string()
+    };
     validate_snippet_code(&code)
 }
 
@@ -581,7 +596,9 @@ pub fn validate_snippet_code(code: &str) -> Result<(), ToolError> {
         sdk_kind: "internal_error".to_string(),
         message: format!("unable to initialize JavaScript validator: {error}"),
     })?;
-    let source = format!("export default ({code});");
+    // Keep generated delimiters on their own lines. A valid snippet may end
+    // in a // comment, which must not consume the validator's closing `);`.
+    let source = format!("export default (\n{code}\n);");
     runtime
         .compile_to_bytecode("snippet-validation.js", &source)
         .map_err(|error| {
@@ -1057,6 +1074,15 @@ mod tests {
         assert_eq!(normalize_snippet_code(code), "async () => ({ ok: true })");
     }
 
+    #[test]
+    fn validate_snippet_code_accepts_trailing_line_comment() {
+        let code = "async () => ({ ok: true }) // formatter note";
+        assert!(
+            validate_snippet_code(code).is_ok(),
+            "the validator's generated closing delimiter must not be swallowed by a trailing // comment"
+        );
+    }
+
     #[test]
     fn validate_snippet_body_rejects_malformed_javascript_before_execution() {
         let body = "---\nname: demo\ndescription: Broken snippet\ntags: []\n---\n\n```js\nasync () => { const broken = ; return broken; }\n```\n";
@@ -1219,14 +1245,29 @@ mod tests {
             assert!(code.contains("docker_path=%s"));
             assert!(code.contains("timeout_path=%s"));
         }
-        assert!(ssh.contains("ssh -G -- "));
+        assert!(
+            ssh.contains("-F "),
+            "custom SSH config must reach ssh -G and live probes"
+        );
+        assert!(ssh.contains(r#"const slash = from.lastIndexOf("/")"#));
+        assert!(ssh.contains(r#"slash >= 0 ? from.slice(0, slash + 1) : """#));
+        assert!(
+            !ssh.contains(r#"Math.max(0, from.lastIndexOf("/"))"#),
+            "bare config filenames must not prefix relative Includes with the first filename character"
+        );
         assert!(ssh.contains("config_file_limit_reached"));
         assert!(ssh.contains("config_truncated"));
+        assert!(docker.contains("ssh_config"));
+        assert!(
+            docker.contains("-F "),
+            "one-host inventory must reuse a supplied custom SSH config"
+        );
+        assert!(aggregate.contains("ssh_config: input.ssh_config"));
         assert!(aggregate.contains("delete artifactInput.ssh_config"));
         assert!(aggregate.contains("parsed_config_file_count"));
         assert!(aggregate.contains("identity_files_configured"));
         assert!(aggregate.contains("artifactTargets"));
-        assert!(aggregate.contains("ssh_config_supplied"));
+        assert!(aggregate.contains("ssh_config_supplied: Boolean(input.ssh_config)"));
     }
 
     #[test]
diff --git a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
index 59d16aa25..8f3998122 100644
--- a/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
+++ b/crates/labby-gateway/src/gateway/manager/code_mode_runtime.rs
@@ -513,6 +513,13 @@ impl GatewayManager {
         if pending.is_empty() {
             if !suppressed.is_empty() {
                 if cache_hits == 0 {
+                    tracing::warn!(
+                        surface = "dispatch",
+                        service = "gateway",
+                        action = "code_mode.catalog_cache",
+                        suppressed_upstreams = ?suppressed,
+                        "one-shot Code Mode catalog has no usable upstreams"
+                    );
                     return Err(ToolError::Sdk {
                         sdk_kind: "upstream_connect_error".to_string(),
                         message: format!(
@@ -719,6 +726,17 @@ impl GatewayManager {
                     not_attempted.join(", ")
                 ));
             }
+            tracing::warn!(
+                surface = "dispatch",
+                service = "gateway",
+                action = "code_mode.catalog_cache",
+                failed_upstreams = ?failed_upstream_names,
+                suppressed_upstreams = ?suppressed,
+                in_flight_upstreams = ?in_flight,
+                not_attempted_upstreams = ?not_attempted,
+                budget_ms = budget.as_millis(),
+                "one-shot Code Mode catalog has no usable upstreams"
+            );
             return Err(ToolError::Sdk {
                 sdk_kind: "upstream_connect_error".to_string(),
                 message: format!(
diff --git a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
index 0406f48a5..5a70246b6 100644
--- a/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
+++ b/crates/labby-gateway/src/gateway/manager/tests/code_mode.rs
@@ -2667,13 +2667,16 @@ async fn one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast() {
     )
     .await;
 
-    let error = tokio::time::timeout(
-        BUDGET_GUARD,
-        manager.code_mode_catalog_tools_cached(None, None),
-    )
-    .await
-    .expect("connection refused fails fast")
-    .expect_err("all-failed with an empty cache is an error");
+    let (error, logs) = with_captured_logs(|| {
+        tokio::time::timeout(
+            BUDGET_GUARD,
+            manager.code_mode_catalog_tools_cached(None, None),
+        )
+    })
+    .await;
+    let error = error
+        .expect("connection refused fails fast")
+        .expect_err("all-failed with an empty cache is an error");
     match error {
         ToolError::Sdk { sdk_kind, message } => {
             assert_eq!(sdk_kind, "upstream_connect_error");
@@ -2684,6 +2687,13 @@ async fn one_shot_cli_catalog_errors_when_every_uncached_upstream_fails_fast() {
         }
         other => panic!("expected upstream_connect_error, got {other:?}"),
     }
+    assert_eq!(
+        logs.matches("one-shot Code Mode catalog has no usable upstreams")
+            .count(),
+        1,
+        "an all-failed cold catalog must emit one aggregate actionable WARN: {logs}"
+    );
+    assert!(logs.contains("beta") && logs.contains("gamma"));
 }
 
 /// Concurrent probes settle out of order, yet the catalog must follow the
@@ -2981,6 +2991,13 @@ async fn a_failed_probe_is_suppressed_on_the_next_one_shot_run() {
             && first_logs.contains("dead"),
         "partial one-shot catalog must emit one actionable failed-upstream warning: {first_logs}"
     );
+    assert_eq!(
+        first_logs
+            .matches("one-shot Code Mode catalog is partial because upstream probes failed")
+            .count(),
+        1,
+        "one failed probe plus one healthy upstream must produce exactly one aggregate warning: {first_logs}"
+    );
 
     // The failure is now on disk, and the healthy upstream is cached, so the
     // second run must reach neither the network nor the dead upstream.
diff --git a/crates/labby-gateway/src/security/spawn_guard.rs b/crates/labby-gateway/src/security/spawn_guard.rs
index 64e92ed91..2fc52cb72 100644
--- a/crates/labby-gateway/src/security/spawn_guard.rs
+++ b/crates/labby-gateway/src/security/spawn_guard.rs
@@ -12,7 +12,7 @@
 //! - [`DANGEROUS_DOCKER_FLAGS`] / [`DANGEROUS_NODE_FLAGS`] / [`DANGEROUS_BUN_FLAGS`] — argv flags that
 //!   are rejected for the corresponding runtime families.
 
-use std::collections::BTreeSet;
+use std::collections::{BTreeSet, VecDeque};
 use std::sync::{Mutex, OnceLock};
 
 use labby_runtime::error::ToolError;
@@ -82,7 +82,7 @@ pub const DANGEROUS_PYTHON_FLAGS: &[&str] = &["-c", "--command", "-"];
 /// Deno subcommands/flags that eval inline code or grant blanket permissions.
 pub const DANGEROUS_DENO_FLAGS: &[&str] = &["eval", "--allow-all", "-A"];
 
-/// Validate that a stdio `command` string is in the runtime-hint allowlist.
+/// Configuration rationale for spawn-guard bypass warning deduplication.
 ///
 /// This is the primary S1/S6 guard: only known safe runtimes may be persisted
 /// as the `command` of a stdio upstream. Callers that receive a raw command
@@ -99,30 +99,55 @@ pub const DANGEROUS_DENO_FLAGS: &[&str] = &["eval", "--allow-all", "-A"];
 /// skip the command allowlist **entirely**. This is a coarse, global escape
 /// hatch — with it set, `bash`, `/bin/sh -c`, and arbitrary binaries like
 /// `/tmp/evil` all become spawnable. Prefer `extra_stdio_commands` and leave
-/// the guard on. When the bypass is active, the first validation of each
-/// distinct command emits a `WARN`; repeats are suppressed so one unsafe
-/// setting cannot flood every CLI response while the weakened posture remains
-/// visible.
-///
-/// Returns `invalid_param` if the command is not in either allowlist.
+/// the guard on. When the bypass is active, the first validation of a recently
+/// unseen command emits a `WARN`; repeats are suppressed while retained in a
+/// fixed-size history, so arbitrary command strings cannot grow process memory
+/// without bound. Evicted old commands may warn again.
+const SPAWN_GUARD_WARNING_DEDUPE_CAPACITY: usize = 32;
+
+#[derive(Default)]
+struct SpawnGuardWarningDedupe {
+    seen: BTreeSet<String>,
+    order: VecDeque<String>,
+}
+
+impl SpawnGuardWarningDedupe {
+    fn should_warn(&mut self, command: &str) -> bool {
+        if self.seen.contains(command) {
+            return false;
+        }
+        if self.order.len() == SPAWN_GUARD_WARNING_DEDUPE_CAPACITY
+            && let Some(evicted) = self.order.pop_front()
+        {
+            self.seen.remove(&evicted);
+        }
+        let command = command.to_string();
+        self.seen.insert(command.clone());
+        self.order.push_back(command);
+        true
+    }
+}
+
 fn warn_spawn_guard_bypass(command: &str) {
-    static WARNED_COMMANDS: OnceLock<Mutex<BTreeSet<String>>> = OnceLock::new();
-    let warned = WARNED_COMMANDS.get_or_init(|| Mutex::new(BTreeSet::new()));
-    let first_for_command = warned
+    static WARNED_COMMANDS: OnceLock<Mutex<SpawnGuardWarningDedupe>> = OnceLock::new();
+    let warned = WARNED_COMMANDS.get_or_init(|| Mutex::new(SpawnGuardWarningDedupe::default()));
+    let first_for_recent_command = warned
         .lock()
         .unwrap_or_else(|poisoned| poisoned.into_inner())
-        .insert(command.to_string());
-    if first_for_command {
+        .should_warn(command);
+    if first_for_recent_command {
         tracing::warn!(
             service = "upstream.pool",
             command = %command,
             "SECURITY: spawn-guard bypass active — command allowlist NOT enforced \
              (disable_spawn_guard = true); prefer scoping with [gateway] extra_stdio_commands; \
-             repeated warnings for this command are suppressed"
+             repeated warnings for this recently seen command are suppressed with bounded history"
         );
     }
 }
 
+/// Validate that a stdio `command` string is in the runtime-hint allowlist.
+/// Returns `invalid_param` if the command is not in either allowlist.
 pub fn validate_stdio_command(
     command: &str,
     extra: &[String],
@@ -516,6 +541,20 @@ mod tests {
         );
     }
 
+    #[test]
+    fn spawn_guard_warning_dedupe_stays_bounded_under_unique_commands() {
+        let mut dedupe = SpawnGuardWarningDedupe::default();
+        for index in 0..(SPAWN_GUARD_WARNING_DEDUPE_CAPACITY * 4) {
+            assert!(dedupe.should_warn(&format!("/tmp/unique-{index}")));
+            assert!(dedupe.order.len() <= SPAWN_GUARD_WARNING_DEDUPE_CAPACITY);
+        }
+        assert_eq!(dedupe.order.len(), SPAWN_GUARD_WARNING_DEDUPE_CAPACITY);
+        assert!(
+            dedupe.should_warn("/tmp/unique-0"),
+            "an evicted old command may warn again, keeping memory bounded instead of remembering arbitrary input forever"
+        );
+    }
+
     #[test]
     fn command_no_bypass_emits_no_warn() {
         use tracing_subscriber::layer::SubscriberExt;
diff --git a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
index 24ca2ada1..3d01ee2f5 100644
--- a/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
+++ b/crates/labby-gateway/src/upstream/pool/stdio_transport.rs
@@ -234,11 +234,14 @@ fn exit_signal(_status: Option<&ExitStatus>) -> Option<i32> {
 
 const fn termination_is_clean(
     expected: bool,
-    success: bool,
-    killed_after_timeout: bool,
+    wait_error_present: bool,
     invalidated_count: usize,
 ) -> bool {
-    expected && invalidated_count == 0 && (success || killed_after_timeout)
+    // Owner-initiated shutdown is expected even when the child reports a
+    // signal/non-zero status: process wrappers may terminate the child while
+    // dropping its transport. What remains actionable is a teardown/reap
+    // failure or a request that was still in flight.
+    expected && !wait_error_present && invalidated_count == 0
 }
 
 async fn log_termination(
@@ -258,12 +261,7 @@ async fn log_termination(
     let success = status.is_some_and(ExitStatus::success);
     let invalidated_count = invalidated_requests.len();
 
-    if termination_is_clean(
-        expected,
-        success,
-        exit.killed_after_timeout,
-        invalidated_count,
-    ) {
+    if termination_is_clean(expected, exit.wait_error.is_some(), invalidated_count) {
         tracing::info!(
             surface = "dispatch",
             service = "upstream.pool",
@@ -490,12 +488,16 @@ mod tests {
 
     #[test]
     fn termination_severity_distinguishes_expected_teardown_from_unexpected_exit() {
-        assert!(termination_is_clean(true, true, false, 0));
-        assert!(termination_is_clean(true, false, true, 0));
-        assert!(!termination_is_clean(false, true, false, 0));
-        assert!(!termination_is_clean(false, false, false, 0));
-        assert!(!termination_is_clean(true, false, false, 0));
-        assert!(!termination_is_clean(true, true, false, 1));
+        assert!(
+            termination_is_clean(true, false, 0),
+            "owner-initiated teardown with no stranded requests is expected even when the child is terminated by the transport owner"
+        );
+        assert!(
+            !termination_is_clean(true, true, 0),
+            "a teardown/reap error remains actionable even during expected shutdown"
+        );
+        assert!(!termination_is_clean(false, false, 0));
+        assert!(!termination_is_clean(true, false, 1));
     }
 
     #[test]
diff --git a/crates/labby/src/api/services/snippets.rs b/crates/labby/src/api/services/snippets.rs
index 041f14a1d..084a979df 100644
--- a/crates/labby/src/api/services/snippets.rs
+++ b/crates/labby/src/api/services/snippets.rs
@@ -77,7 +77,19 @@ async fn handle(
     let request_id = headers.get("x-request-id").and_then(|v| v.to_str().ok());
     require_snippets_admin(&req.action, request_id, auth.as_ref())?;
     let manager = state.gateway_manager.clone();
-    let promotion_context = crate::dispatch::snippets::dispatch::SnippetPromotionContext {
+    let execution_caller = auth.as_ref().map_or(
+        crate::dispatch::gateway::code_mode::CodeModeCaller::TrustedLocal,
+        |value| crate::dispatch::gateway::code_mode::CodeModeCaller::Scoped {
+            capabilities: labby_codemode::CodeModeCallerCapabilities {
+                can_read: true,
+                can_execute: true,
+                can_use_snippets: true,
+                is_admin: true,
+            },
+            sub: Some(value.0.sub.clone()),
+        },
+    );
+    let dispatch_context = crate::dispatch::snippets::dispatch::SnippetDispatchContext {
         actor_key: auth
             .as_ref()
             .and_then(|value| value.0.actor_key.as_deref())
@@ -86,6 +98,9 @@ async fn handle(
         route_scope: "root".to_string(),
         capability_filter_fingerprint: crate::dispatch::gateway::code_mode::ToolScope::default()
             .fingerprint(),
+        execution_scope: crate::dispatch::gateway::code_mode::ToolScope::default(),
+        execution_caller,
+        execution_surface: crate::dispatch::gateway::code_mode::CodeModeSurface::Api,
     };
 
     handle_action_with_meta(
@@ -106,13 +121,11 @@ async fn handle(
                 let manager = manager
                     .as_ref()
                     .ok_or_else(|| ToolError::internal_message("gateway manager not wired"))?;
-                let promotion_context =
-                    (action == "snippets.promote").then(|| promotion_context.clone());
                 return crate::dispatch::snippets::dispatch::dispatch_with_manager_and_context(
                     manager,
                     &action,
                     params,
-                    promotion_context,
+                    Some(dispatch_context.clone()),
                 )
                 .await;
             }
diff --git a/crates/labby/src/cli/gateway/code.rs b/crates/labby/src/cli/gateway/code.rs
index bec5819b2..d3ff5b1f7 100644
--- a/crates/labby/src/cli/gateway/code.rs
+++ b/crates/labby/src/cli/gateway/code.rs
@@ -177,9 +177,6 @@ mod tests {
     #[test]
     fn cli_source_read_uses_shared_hard_ceiling() {
         let max_source_bytes = labby_codemode::MAX_SOURCE_BYTES;
-        let above_default =
-            "a".repeat(crate::config::CodeModeConfig::default().max_source_bytes + 1);
-        assert!(read_code_mode_source(Some(above_default), None, max_source_bytes as u64).is_ok());
         let at_limit = "a".repeat(max_source_bytes);
         assert!(read_code_mode_source(Some(at_limit), None, max_source_bytes as u64).is_ok());
 
diff --git a/crates/labby/src/dispatch/snippets/dispatch.rs b/crates/labby/src/dispatch/snippets/dispatch.rs
index 73db21767..8c3047fbb 100644
--- a/crates/labby/src/dispatch/snippets/dispatch.rs
+++ b/crates/labby/src/dispatch/snippets/dispatch.rs
@@ -6,7 +6,7 @@ use crate::dispatch::gateway::code_mode::{
     CodeModeBroker, CodeModeCaller, CodeModeSourceLookup, CodeModeSurface, ToolScope,
 };
 use crate::dispatch::helpers::{action_schema, help_payload, lab_home, require_str, to_json};
-use labby_codemode::CodeModeExecutionResponse;
+use labby_codemode::{CodeModeExecutionResponse, MAX_SOURCE_BYTES};
 
 use super::catalog::ACTIONS;
 use super::store::{
@@ -51,11 +51,19 @@ struct PromoteParams {
 }
 
 #[derive(Debug, Clone)]
-pub struct SnippetPromotionContext {
+pub struct SnippetDispatchContext {
     pub actor_key: Option<String>,
     pub is_admin: bool,
     pub route_scope: String,
     pub capability_filter_fingerprint: String,
+    /// Caller/route authority inherited by saved snippet execution. A snippet's
+    /// own declaration may only narrow this scope, never widen it.
+    pub execution_scope: ToolScope,
+    /// Preserve the initiating surface's identity/capabilities all the way into
+    /// Code Mode. Treating remote snippet calls as trusted-local would erase
+    /// runtime ownership and OAuth-subject semantics.
+    pub execution_caller: CodeModeCaller,
+    pub execution_surface: CodeModeSurface,
 }
 
 struct SnippetExecutionOutcome {
@@ -63,7 +71,7 @@ struct SnippetExecutionOutcome {
     display_response: CodeModeExecutionResponse,
 }
 
-impl SnippetPromotionContext {
+impl SnippetDispatchContext {
     #[must_use]
     pub fn trusted_local() -> Self {
         Self {
@@ -71,6 +79,9 @@ impl SnippetPromotionContext {
             is_admin: true,
             route_scope: "root".to_string(),
             capability_filter_fingerprint: ToolScope::default().fingerprint(),
+            execution_scope: ToolScope::default(),
+            execution_caller: CodeModeCaller::TrustedLocal,
+            execution_surface: CodeModeSurface::Cli,
         }
     }
 }
@@ -84,17 +95,29 @@ pub async fn dispatch_with_manager_and_context(
     manager: &crate::dispatch::gateway::manager::GatewayManager,
     action: &str,
     params: Value,
-    promotion_context: Option<SnippetPromotionContext>,
+    dispatch_context: Option<SnippetDispatchContext>,
 ) -> Result<Value, ToolError> {
-    dispatch_inner(Some(manager), action, params, promotion_context).await
+    dispatch_inner(Some(manager), action, params, dispatch_context).await
 }
 
 async fn dispatch_inner(
     manager: Option<&crate::dispatch::gateway::manager::GatewayManager>,
     action: &str,
     params: Value,
-    promotion_context: Option<SnippetPromotionContext>,
+    dispatch_context: Option<SnippetDispatchContext>,
 ) -> Result<Value, ToolError> {
+    let execution_scope = dispatch_context
+        .as_ref()
+        .map(|context| context.execution_scope.clone())
+        .unwrap_or_default();
+    let execution_caller = dispatch_context
+        .as_ref()
+        .map(|context| context.execution_caller.clone())
+        .unwrap_or(CodeModeCaller::TrustedLocal);
+    let execution_surface = dispatch_context
+        .as_ref()
+        .map(|context| context.execution_surface)
+        .unwrap_or(CodeModeSurface::Cli);
     match action {
         "help" => Ok(help_payload("snippets", ACTIONS)),
         "schema" => {
@@ -121,7 +144,7 @@ async fn dispatch_inner(
         }
         "snippets.promote" => {
             let params: PromoteParams = parse_params(params)?;
-            promote_snippet(manager, params, promotion_context).await
+            promote_snippet(manager, params, dispatch_context).await
         }
         "snippets.validate" => {
             let params: ValidateParams = parse_params(params)?;
@@ -140,13 +163,27 @@ async fn dispatch_inner(
             let Some(name) = params.name else {
                 return Err(missing_param("missing required parameter `name`", "name"));
             };
-            let outcome = execute_snippet_outcome(manager, &name, params.params).await?;
+            let outcome = execute_snippet_outcome(
+                manager,
+                &name,
+                params.params,
+                &execution_scope,
+                &execution_caller,
+                execution_surface,
+            )
+            .await?;
             to_json(outcome.display_response)
         }
         "snippets.test" => {
             let params: ExecParams = parse_params(params)?;
             if params.all {
-                return test_all_snippets(manager).await;
+                return test_all_snippets(
+                    manager,
+                    &execution_scope,
+                    &execution_caller,
+                    execution_surface,
+                )
+                .await;
             }
             let Some(name) = params.name else {
                 return Err(missing_param(
@@ -154,7 +191,15 @@ async fn dispatch_inner(
                     "name",
                 ));
             };
-            let outcome = execute_snippet_outcome(manager, &name, params.params).await?;
+            let outcome = execute_snippet_outcome(
+                manager,
+                &name,
+                params.params,
+                &execution_scope,
+                &execution_caller,
+                execution_surface,
+            )
+            .await?;
             snippet_test_result(name, outcome)
         }
         unknown => Err(ToolError::UnknownAction {
@@ -168,14 +213,14 @@ async fn dispatch_inner(
 async fn promote_snippet(
     manager: Option<&crate::dispatch::gateway::manager::GatewayManager>,
     params: PromoteParams,
-    promotion_context: Option<SnippetPromotionContext>,
+    dispatch_context: Option<SnippetDispatchContext>,
 ) -> Result<Value, ToolError> {
     validate_snippet_name(&params.name)?;
     let manager = manager.ok_or_else(|| ToolError::Sdk {
         sdk_kind: "gateway_unavailable".to_string(),
         message: "snippets.promote requires the live gateway manager source store".to_string(),
     })?;
-    let context = promotion_context.unwrap_or_else(SnippetPromotionContext::trusted_local);
+    let context = dispatch_context.unwrap_or_else(SnippetDispatchContext::trusted_local);
     let source = manager
         .resolve_code_mode_source(
             &params.execution_id,
@@ -244,12 +289,22 @@ fn validate_snippet(name: Option<&str>, body: Option<&str>) -> Result<Value, Too
 
 async fn test_all_snippets(
     manager: Option<&crate::dispatch::gateway::manager::GatewayManager>,
+    caller_scope: &ToolScope,
+    caller: &CodeModeCaller,
+    surface: CodeModeSurface,
 ) -> Result<Value, ToolError> {
     let snippets = list_snippets(&lab_home(), &builtin_snippet_dir())?;
     let mut results = Vec::with_capacity(snippets.len());
     for snippet in snippets {
-        match execute_snippet_outcome(manager, &snippet.name, Value::Object(Default::default()))
-            .await
+        match execute_snippet_outcome(
+            manager,
+            &snippet.name,
+            Value::Object(Default::default()),
+            caller_scope,
+            caller,
+            surface,
+        )
+        .await
         {
             Ok(outcome) => {
                 let passed = snippet_response_passed(&outcome.raw_response);
@@ -298,18 +353,24 @@ fn snippet_test_result(name: String, outcome: SnippetExecutionOutcome) -> Result
     }))
 }
 
-fn snippet_execution_scope(snippet: &super::store::ResolvedSnippet) -> ToolScope {
+fn snippet_execution_scope(
+    snippet: &super::store::ResolvedSnippet,
+    caller_scope: &ToolScope,
+) -> ToolScope {
     snippet
         .tools
         .as_ref()
-        .map(|declared| declared.intersect(&ToolScope::default()))
-        .unwrap_or_default()
+        .map(|declared| declared.intersect(caller_scope))
+        .unwrap_or_else(|| caller_scope.clone())
 }
 
 async fn execute_snippet_outcome(
     manager: Option<&crate::dispatch::gateway::manager::GatewayManager>,
     name: &str,
     input: Value,
+    caller_scope: &ToolScope,
+    caller: &CodeModeCaller,
+    surface: CodeModeSurface,
 ) -> Result<SnippetExecutionOutcome, ToolError> {
     let owned_manager;
     let manager = if let Some(manager) = manager {
@@ -323,18 +384,18 @@ async fn execute_snippet_outcome(
     let snippet = resolve_snippet(&lab_home(), &builtin_snippet_dir(), name)?;
     let code = code_for_snippet(&snippet)?;
     let input = merge_snippet_input(&snippet, input)?;
-    let code = wrap_snippet_with_input(&code, &input)?;
+    let max_source_bytes = config.max_source_bytes.min(MAX_SOURCE_BYTES);
+    let code = wrap_snippet_with_input_bounded(&code, &input, max_source_bytes)?;
     // Saved snippet source stays entirely on the execution plane. When the
     // snippet declares exact upstream dependencies, use that declaration to
-    // scope catalog construction and dispatch instead of cold-probing every
-    // configured upstream. Snippets without declarations retain legacy
-    // unscoped behavior for compatibility.
-    let scope = snippet_execution_scope(&snippet);
+    // narrow the caller/route authority instead of cold-probing every configured
+    // upstream. Snippets without declarations inherit the caller scope exactly.
+    let scope = snippet_execution_scope(&snippet, caller_scope);
     let outcome = broker
         .execute_with_raw_response(
             &code,
-            CodeModeCaller::TrustedLocal,
-            CodeModeSurface::Cli,
+            caller.clone(),
+            surface,
             config,
             scope,
             // Snippet execution is a local trusted-CLI path with no durable-run
@@ -356,14 +417,28 @@ async fn execute_snippet_outcome(
     })
 }
 
-fn wrap_snippet_with_input(code: &str, input: &Value) -> Result<String, ToolError> {
+fn wrap_snippet_with_input_bounded(
+    code: &str,
+    input: &Value,
+    max_source_bytes: usize,
+) -> Result<String, ToolError> {
     let input = serde_json::to_string(input).map_err(|e| ToolError::InvalidParam {
         message: format!("snippet params must be JSON-serializable: {e}"),
         param: "params".to_string(),
     })?;
-    Ok(format!(
+    let wrapped = format!(
         "async () => {{\n  const __labSnippetInput = {input};\n  return await ({code})(__labSnippetInput);\n}}"
-    ))
+    );
+    if wrapped.len() > max_source_bytes {
+        return Err(ToolError::InvalidParam {
+            message: format!(
+                "saved snippet invocation exceeds Code Mode source limit {max_source_bytes} bytes after serializing params ({} bytes)",
+                wrapped.len()
+            ),
+            param: "params".to_string(),
+        });
+    }
+    Ok(wrapped)
 }
 
 fn parse_params<T: serde::de::DeserializeOwned>(params: Value) -> Result<T, ToolError> {
@@ -419,22 +494,22 @@ mod tests {
         }
     }
 
-    #[test]
-    fn saved_snippet_tool_declarations_scope_execution_catalog() {
+    fn resolved_snippet_with_tools(
+        tools: Option<Vec<&str>>,
+    ) -> crate::dispatch::snippets::store::ResolvedSnippet {
         use std::collections::BTreeMap;
         use std::path::PathBuf;
 
         use crate::dispatch::snippets::store::{ResolvedSnippet, SnippetSource};
         use labby_codemode::snippet::tool_declarations::SnippetToolDeclarations;
 
-        let declared: SnippetToolDeclarations = vec![
-            "claude-macpoo::Bash".to_string(),
-            "claude-macpoo::Read".to_string(),
-        ]
-        .try_into()
-        .expect("valid exact tool declarations");
-        let snippet = ResolvedSnippet {
-            tools: Some(declared),
+        ResolvedSnippet {
+            tools: tools.map(|tools| {
+                SnippetToolDeclarations::try_from(
+                    tools.into_iter().map(ToOwned::to_owned).collect::<Vec<_>>(),
+                )
+                .expect("valid exact tool declarations")
+            }),
             name: "scoped".to_string(),
             description: None,
             tags: Vec::new(),
@@ -442,15 +517,67 @@ mod tests {
             source: SnippetSource::User,
             path: PathBuf::from("scoped.md"),
             body: "async () => ({ ok: true })".to_string(),
-        };
+        }
+    }
+
+    #[test]
+    fn saved_snippet_tool_declarations_narrow_but_never_widen_route_authority() {
+        let snippet = resolved_snippet_with_tools(Some(vec!["alpha::tool1", "beta::tool2"]));
+        let caller_scope = ToolScope::scoped_namespaces(vec!["alpha".to_string()], Vec::new());
+
+        let scope = snippet_execution_scope(&snippet, &caller_scope);
+
+        assert!(scope.is_scoped());
+        assert!(scope.allows("alpha", "tool1"));
+        assert!(
+            !scope.allows("alpha", "other_tool"),
+            "an exact snippet declaration must deny undeclared siblings on an allowed upstream"
+        );
+        assert!(
+            !scope.allows("beta", "tool2"),
+            "a snippet declaration must never restore an upstream removed by the route"
+        );
+    }
+
+    #[test]
+    fn saved_snippet_without_declarations_inherits_route_scope_exactly() {
+        let snippet = resolved_snippet_with_tools(None);
+        let caller_scope = ToolScope::scoped_namespaces(vec!["alpha".to_string()], Vec::new());
+
+        let scope = snippet_execution_scope(&snippet, &caller_scope);
+
+        assert_eq!(scope, caller_scope);
+        assert!(scope.allows("alpha", "other_tool"));
+        assert!(!scope.allows("beta", "tool2"));
+    }
+
+    #[test]
+    fn trusted_local_saved_snippet_retains_declared_exact_tool_scope() {
+        let snippet =
+            resolved_snippet_with_tools(Some(vec!["claude-macpoo::Bash", "claude-macpoo::Read"]));
+
+        let scope = snippet_execution_scope(&snippet, &ToolScope::default());
 
-        let scope = snippet_execution_scope(&snippet);
         assert!(scope.is_scoped());
         assert!(scope.allows("claude-macpoo", "Bash"));
         assert!(scope.allows("claude-macpoo", "Read"));
         assert!(!scope.allows("github", "search_issues"));
     }
 
+    #[test]
+    fn saved_snippet_invocation_checks_final_wrapped_source_size() {
+        let code = "async () => ({ ok: true })";
+        let input = json!({ "payload": "x".repeat(256) });
+
+        let error = wrap_snippet_with_input_bounded(code, &input, 128)
+            .expect_err("serialized params must count toward the runtime source limit");
+
+        assert_eq!(error.kind(), "invalid_param");
+        let message = format!("{error}");
+        assert!(message.contains("saved snippet invocation"));
+        assert!(message.contains("128"));
+    }
+
     #[test]
     fn snippets_test_uses_raw_result_for_pass_fail_and_returns_shaped_display() {
         let pass = snippet_test_result(
diff --git a/crates/labby/src/mcp/call_tool.rs b/crates/labby/src/mcp/call_tool.rs
index a7d703fa8..e28b79943 100644
--- a/crates/labby/src/mcp/call_tool.rs
+++ b/crates/labby/src/mcp/call_tool.rs
@@ -1774,11 +1774,14 @@ impl LabMcpServer {
                 unreachable!("Depot publishing is gateway-only")
             } else if cfg!(feature = "gateway")
                 && service == "snippets"
-                && action == "snippets.promote"
+                && matches!(
+                    action.as_str(),
+                    "snippets.exec" | "snippets.test" | "snippets.promote"
+                )
             {
                 #[cfg(feature = "gateway")]
                 return self
-                    .call_snippets_promote_impl(
+                    .call_snippets_contextual_impl(
                         &action, params, &args, start, &subject, actor_key, &context,
                     )
                     .await
diff --git a/crates/labby/src/mcp/call_tool_codemode.rs b/crates/labby/src/mcp/call_tool_codemode.rs
index 1bb499489..1fe44791c 100644
--- a/crates/labby/src/mcp/call_tool_codemode.rs
+++ b/crates/labby/src/mcp/call_tool_codemode.rs
@@ -960,7 +960,7 @@ impl LabMcpServer {
     }
 }
 
-fn code_mode_capabilities_for_scopes(scopes: &[String]) -> CodeModeCallerCapabilities {
+pub(crate) fn code_mode_capabilities_for_scopes(scopes: &[String]) -> CodeModeCallerCapabilities {
     let is_admin = scopes.iter().any(|scope| scope == "lab:admin");
     CodeModeCallerCapabilities {
         can_read: scopes
diff --git a/crates/labby/src/mcp/services/snippets.rs b/crates/labby/src/mcp/services/snippets.rs
index a756f052d..6617838e5 100644
--- a/crates/labby/src/mcp/services/snippets.rs
+++ b/crates/labby/src/mcp/services/snippets.rs
@@ -1,9 +1,8 @@
 //! MCP adapter for snippets-specific request context.
 //!
-//! Normal snippets operations dispatch through `crate::dispatch::snippets`.
-//! Promotion is the MCP-specific exception because it must resolve the live
-//! gateway manager source store against the caller actor, admin state, route
-//! scope, and route-scoped capability filter.
+//! Saved snippet execution and promotion must preserve the MCP route authority.
+//! This adapter threads the live gateway manager plus the route-derived Code Mode
+//! capability scope into dispatch so snippets can only narrow caller authority.
 
 use std::time::Instant;
 
@@ -21,8 +20,44 @@ use crate::mcp::result_format::{
 };
 use crate::mcp::server::LabMcpServer;
 
+fn execution_scope_for_route(
+    route_scope: &crate::mcp::route_scope::McpRouteScope,
+) -> crate::dispatch::gateway::code_mode::ToolScope {
+    route_scope
+        .allowed_upstreams()
+        .map(|allowed| {
+            crate::dispatch::gateway::code_mode::ToolScope::scoped_namespaces(
+                allowed.iter().cloned().collect(),
+                Vec::new(),
+            )
+        })
+        .unwrap_or_default()
+}
+
+fn execution_caller_for_mcp(
+    scopes: Option<&[String]>,
+    sub: Option<String>,
+    host_provider: Option<(&str, &str)>,
+) -> crate::dispatch::gateway::code_mode::CodeModeCaller {
+    let Some(scopes) = scopes else {
+        return crate::dispatch::gateway::code_mode::CodeModeCaller::TrustedLocal;
+    };
+    let capabilities = super::super::call_tool_codemode::code_mode_capabilities_for_scopes(scopes);
+    match host_provider {
+        Some((provider_token, provider_request_id)) => {
+            crate::dispatch::gateway::code_mode::CodeModeCaller::ScopedHostProvider {
+                capabilities,
+                sub,
+                provider_token: provider_token.to_string(),
+                provider_request_id: provider_request_id.to_string(),
+            }
+        }
+        None => crate::dispatch::gateway::code_mode::CodeModeCaller::Scoped { capabilities, sub },
+    }
+}
+
 impl LabMcpServer {
-    pub(crate) async fn call_snippets_promote_impl(
+    pub(crate) async fn call_snippets_contextual_impl(
         &self,
         action: &str,
         params: Value,
@@ -44,31 +79,34 @@ impl LabMcpServer {
         };
 
         let auth = auth_context_from_extensions(&context.extensions);
-        let capability_filter_fingerprint = self
-            .route_scope
-            .allowed_upstreams()
-            .map(|allowed| {
-                crate::dispatch::gateway::code_mode::ToolScope::scoped_namespaces(
-                    allowed.iter().cloned().collect(),
-                    Vec::new(),
-                )
-                .fingerprint()
-            })
-            .unwrap_or_else(|| {
-                crate::dispatch::gateway::code_mode::ToolScope::default().fingerprint()
-            });
-        let promotion_context = crate::dispatch::snippets::dispatch::SnippetPromotionContext {
+        let execution_scope = execution_scope_for_route(&self.route_scope);
+        let capability_filter_fingerprint = execution_scope.fingerprint();
+        let sub = self
+            .route_oauth_subject(
+                self.request_subject(context)
+                    .map(std::borrow::Cow::Borrowed),
+            )
+            .map(std::borrow::Cow::into_owned);
+        let host_provider = self
+            .request_host_provider_token(context)
+            .zip(self.request_host_provider_request_id(context));
+        let execution_caller =
+            execution_caller_for_mcp(auth.map(|auth| auth.scopes.as_slice()), sub, host_provider);
+        let dispatch_context = crate::dispatch::snippets::dispatch::SnippetDispatchContext {
             actor_key: actor_key.map(ToOwned::to_owned),
             is_admin: auth.is_none_or(|auth| auth.scopes.iter().any(|scope| scope == "lab:admin")),
             route_scope: self.route_scope.label(),
             capability_filter_fingerprint,
+            execution_scope,
+            execution_caller,
+            execution_surface: crate::dispatch::gateway::code_mode::CodeModeSurface::Mcp,
         };
 
         let result = crate::dispatch::snippets::dispatch::dispatch_with_manager_and_context(
             manager,
             action,
             params,
-            Some(promotion_context),
+            Some(dispatch_context),
         )
         .await
         .map_err(|te| anyhow::Error::from(DispatchError::from(te)));
@@ -88,3 +126,55 @@ impl LabMcpServer {
         Ok(result)
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::mcp::route_scope::McpRouteScope;
+
+    #[test]
+    fn protected_route_becomes_a_namespace_scoped_snippet_authority() {
+        let route = McpRouteScope::protected_subset("team-route", ["alpha"], ["snippets"], true);
+
+        let scope = execution_scope_for_route(&route);
+
+        assert!(scope.is_scoped());
+        assert!(scope.allows("alpha", "tool1"));
+        assert!(!scope.allows("beta", "tool2"));
+    }
+
+    #[test]
+    fn root_route_keeps_trusted_local_snippet_authority_unscoped() {
+        let scope = execution_scope_for_route(&McpRouteScope::Root);
+
+        assert!(!scope.is_scoped());
+        assert!(scope.allows("alpha", "tool1"));
+        assert!(scope.allows("beta", "tool2"));
+    }
+
+    #[test]
+    fn authenticated_mcp_snippet_caller_preserves_identity_instead_of_becoming_trusted_local() {
+        let scopes = vec!["lab:admin".to_string()];
+        let caller = execution_caller_for_mcp(Some(&scopes), Some("alice".to_string()), None);
+
+        assert!(!matches!(
+            caller,
+            crate::dispatch::gateway::code_mode::CodeModeCaller::TrustedLocal
+        ));
+        assert_eq!(caller.subject(), Some("alice"));
+        assert!(caller.is_admin());
+    }
+
+    #[test]
+    fn authenticated_mcp_snippet_caller_preserves_host_provider_context() {
+        let scopes = vec!["lab:admin".to_string()];
+        let caller = execution_caller_for_mcp(
+            Some(&scopes),
+            Some("alice".to_string()),
+            Some(("provider-secret", "request-7")),
+        );
+
+        assert_eq!(caller.subject(), Some("alice"));
+        assert_eq!(caller.host_provider_token(), Some("provider-secret"));
+    }
+}
diff --git a/docs/snippets/docker-host-inventory.md b/docs/snippets/docker-host-inventory.md
index bebf9ffff..bcb384297 100644
--- a/docs/snippets/docker-host-inventory.md
+++ b/docs/snippets/docker-host-inventory.md
@@ -11,6 +11,10 @@ inputs:
   alias:
     type: string
     required: true
+  ssh_config:
+    type: string
+    default: ""
+    required: false
   connect_timeout_seconds:
     type: integer
     default: 4
@@ -49,6 +53,7 @@ Reusable one-host primitive. Host identity is resolved before Docker enumeration
 async (o = {}) => {
 	const i = {
 		alias: String(o.alias || "").trim(),
+		ssh_config: o.ssh_config ?? "",
 		connect_timeout_seconds: Math.max(
 			1,
 			Math.min(30, Number(o.connect_timeout_seconds ?? 4)),
@@ -109,9 +114,10 @@ async (o = {}) => {
 			"-o ConnectionAttempts=1",
 			"-o ConnectTimeout=" + i.connect_timeout_seconds,
 		].join(" "),
+		configOpt = i.ssh_config ? "-F " + q(i.ssh_config) + " " : "",
 		ssh = (r) =>
 			callTool(bash, {
-				command: "ssh " + opts + " -- " + q(i.alias) + " " + q(r),
+				command: "ssh " + configOpt + opts + " -- " + q(i.alias) + " " + q(r),
 				timeout: i.command_timeout_ms,
 			});
 	const hostProbe = [
diff --git a/docs/snippets/homelab-docker-inventory.md b/docs/snippets/homelab-docker-inventory.md
index b915b82da..520abbba2 100644
--- a/docs/snippets/homelab-docker-inventory.md
+++ b/docs/snippets/homelab-docker-inventory.md
@@ -119,6 +119,7 @@ async (o = {}) => {
 			(d) => () =>
 				codemode.run("docker-host-inventory", {
 					alias: d.preferred_alias,
+					ssh_config: input.ssh_config,
 					connect_timeout_seconds: input.connect_timeout_seconds,
 					command_timeout_ms: input.command_timeout_ms,
 					log_lines: input.log_lines,
@@ -164,7 +165,7 @@ async (o = {}) => {
 		user: sourceController.user || null,
 		platform: sourceController.platform || null,
 		ssh_path: sourceController.ssh_path || null,
-		ssh_config_supplied: Boolean(sourceController.ssh_config),
+		ssh_config_supplied: Boolean(input.ssh_config),
 	};
 	const sanitizeEffective = (effective) =>
 		effective
diff --git a/docs/snippets/homelab-ssh-targets.md b/docs/snippets/homelab-ssh-targets.md
index 87e221d56..409603d5e 100644
--- a/docs/snippets/homelab-ssh-targets.md
+++ b/docs/snippets/homelab-ssh-targets.md
@@ -121,16 +121,18 @@ async (o = {}) => {
 		throw new Error("Selected Claude MCP controller is missing HOME or ssh");
 
 	const root = input.ssh_config || controller.home + "/.ssh/config",
+		configOpt = input.ssh_config ? "-F " + quote(root) + " " : "",
 		queue = [root],
 		seen = new Set(),
 		aliases = new Map(),
 		warnings = [];
-	const resolve = (p, from) =>
-		p.startsWith("~/")
-			? controller.home + p.slice(1)
-			: p.startsWith("/")
-				? p
-				: from.slice(0, Math.max(0, from.lastIndexOf("/")) + 1) + p;
+	const resolve = (p, from) => {
+		if (p.startsWith("~/")) return controller.home + p.slice(1);
+		if (p.startsWith("/")) return p;
+		const slash = from.lastIndexOf("/");
+		const dir = slash >= 0 ? from.slice(0, slash + 1) : "";
+		return dir + p;
+	};
 	while (queue.length && seen.size < 16) {
 		const path = queue.shift();
 		if (!path || seen.has(path)) continue;
@@ -201,7 +203,7 @@ async (o = {}) => {
 				};
 				for (const line of text(
 					await callTool(bashTool.id, {
-						command: "ssh -G -- " + quote(target.alias),
+						command: "ssh " + configOpt + "-G -- " + quote(target.alias),
 						timeout: input.command_timeout_ms,
 					}),
 				).split("\n")) {
@@ -267,7 +269,7 @@ async (o = {}) => {
 			for (const line of text(
 				await callTool(bashTool.id, {
 					command:
-						"ssh " + opts + " -- " + quote(target.alias) + " " + quote(probe),
+						"ssh " + configOpt + opts + " -- " + quote(target.alias) + " " + quote(probe),
 					timeout: Math.min(input.command_timeout_ms, 12000),
 				}),
 			).split("\n")) {

From 79078d8f1f92051f393b359c8d8f4c5b948c5d16 Mon Sep 17 00:00:00 2001
From: Jake Magar <jmagar@users.noreply.github.com>
Date: Thu, 17 Sep 2026 12:02:36 -0400
Subject: [PATCH 15/16] fix(codemode): close final hardening review gaps

---
 crates/labby-codemode/src/truncate.rs         | 76 +++++++++++++++++--
 .../src/gateway/enrichment/provider.rs        | 19 +++--
 .../labby/src/dispatch/snippets/dispatch.rs   |  4 +-
 3 files changed, 81 insertions(+), 18 deletions(-)

diff --git a/crates/labby-codemode/src/truncate.rs b/crates/labby-codemode/src/truncate.rs
index 85755ddab..23a80e1f5 100644
--- a/crates/labby-codemode/src/truncate.rs
+++ b/crates/labby-codemode/src/truncate.rs
@@ -39,17 +39,16 @@ pub(crate) fn truncate_execution_response(
     // This keeps a useful compact result from being replaced by a truncation
     // marker merely because tracing was enabled.
     if response.calls.iter().any(|call| call.params.is_some()) {
-        let mut without_params = response.clone();
-        for call in &mut without_params.calls {
+        for call in &mut response.calls {
             call.params = None;
         }
         if response_within_budget(
-            &without_params,
+            &response,
             max_response_bytes,
             max_response_tokens,
             token_estimate_divisor,
         ) {
-            return without_params;
+            return response;
         }
     }
 
@@ -377,8 +376,9 @@ mod tests {
 
     /// FR-5 (issue #210, lab-41e7m.2): the DEFAULT truncation path replaces an
     /// over-budget result with an OBJECT marker — `truncated: true`,
-    /// `next_action`, a bounded `preview` — while `calls[]` metadata survives
-    /// verbatim. Structure must never collapse to a bare string here; the
+    /// `next_action`, a bounded `preview` — while required `calls[]` metadata
+    /// survives after optional trace params are shed. Structure must never
+    /// collapse to a bare string here; the
     /// string-marker path is `shape.rs`, which only runs under a non-`Off`
     /// result-shape policy.
     #[test]
@@ -429,9 +429,13 @@ mod tests {
             marker["preview"].as_str().is_some_and(|s| s.len() <= 1024),
             "preview is bounded"
         );
+        let mut expected_calls = calls;
+        for call in &mut expected_calls {
+            call.params = None;
+        }
         assert_eq!(
-            truncated.calls, calls,
-            "structured calls[] metadata must survive result truncation"
+            truncated.calls, expected_calls,
+            "required calls[] metadata must survive after optional trace params are dropped"
         );
         assert!(
             truncated.result_shaping.is_none(),
@@ -478,6 +482,62 @@ mod tests {
         assert!(response_within_budget(&truncated, 24 * 1024, 6_000, 4));
     }
 
+    #[test]
+    fn high_fanout_trace_params_stay_dropped_when_result_also_needs_truncation() {
+        let calls = (0..24)
+            .map(|i| CodeModeExecutedCall {
+                id: format!("ssh::{i}"),
+                ok: true,
+                elapsed_ms: 25,
+                start_ms: Some(i * 3),
+                params: Some(json!({
+                    "command": format!("ssh host-{i} {}", "x".repeat(2048)),
+                    "timeout": 20_000
+                })),
+                error_kind: None,
+                ui: None,
+            })
+            .collect::<Vec<_>>();
+        let mut response =
+            response_with_logs(json!({"rows": vec!["r".repeat(96); 180]}), Vec::new());
+        response.calls = calls;
+        let max_bytes = 12 * 1024;
+        let max_tokens = 100_000;
+        let divisor = 4;
+        assert!(
+            !response_within_budget(&response, max_bytes, max_tokens, divisor),
+            "oracle must begin over budget"
+        );
+        let mut without_params = response.clone();
+        for call in &mut without_params.calls {
+            call.params = None;
+        }
+        assert!(
+            !response_within_budget(&without_params, max_bytes, max_tokens, divisor),
+            "the result must still need truncation after optional trace params are removed"
+        );
+
+        let truncated = truncate_execution_response(response, max_bytes, max_tokens, divisor);
+
+        assert_eq!(truncated.calls.len(), 24, "call records must survive");
+        assert!(
+            truncated.calls.iter().all(|call| call.params.is_none()),
+            "optional trace params must remain dropped while later pressure valves run"
+        );
+        assert_eq!(
+            truncated
+                .result
+                .as_ref()
+                .and_then(Value::as_object)
+                .and_then(|marker| marker.get("truncated")),
+            Some(&json!(true)),
+            "the independently oversized result should still become a truncation marker"
+        );
+        assert!(response_within_budget(
+            &truncated, max_bytes, max_tokens, divisor
+        ));
+    }
+
     #[test]
     fn large_log_set_cut_matches_probe_serialized_contract() {
         // Varied line lengths plus JSON-escaped and multibyte characters so the
diff --git a/crates/labby-gateway/src/gateway/enrichment/provider.rs b/crates/labby-gateway/src/gateway/enrichment/provider.rs
index 0fa8754d6..2c4739300 100644
--- a/crates/labby-gateway/src/gateway/enrichment/provider.rs
+++ b/crates/labby-gateway/src/gateway/enrichment/provider.rs
@@ -613,6 +613,12 @@ mod tests {
 
     use super::*;
 
+    // These tests assert provider process behavior, not scheduler latency. A loaded
+    // workspace shard can delay a newly spawned shell beyond one second, so keep
+    // classification tests comfortably above that noise floor. Timeout behavior
+    // itself is covered separately with an intentionally tiny deadline.
+    const PROCESS_TEST_TIMEOUT_MS: u64 = 5_000;
+
     fn sample_input() -> UpstreamEnrichmentInput {
         UpstreamEnrichmentInput {
             name: "github".to_string(),
@@ -680,7 +686,7 @@ printf '{"proposals":[{"upstream":"github","hint":"capabilities: repository issu
         let proposals = run_provider_preview(
             GatewayEnrichmentProvider::Codex,
             &[sample_input()],
-            &runner(script, 1_000, 1_024),
+            &runner(script, PROCESS_TEST_TIMEOUT_MS, 1_024),
         )
         .await
         .expect("provider succeeds with isolated environment");
@@ -704,7 +710,7 @@ head -c 256 /dev/zero | tr '\0' x
             run_provider_preview(
                 GatewayEnrichmentProvider::Codex,
                 &[sample_input()],
-                &runner(script, 1_000, 64),
+                &runner(script, PROCESS_TEST_TIMEOUT_MS, 64),
             )
             .await,
         );
@@ -724,10 +730,7 @@ head -c 256 /dev/zero | tr '\0' x >&2
             run_provider_preview(
                 GatewayEnrichmentProvider::Codex,
                 &[sample_input()],
-                // Process startup approached the one-second deadline under a loaded full-suite
-                // run. Keep the content cap exact while giving this process-bound assertion a
-                // deadline that measures output classification rather than scheduler latency.
-                &runner(script, 5_000, 64),
+                &runner(script, PROCESS_TEST_TIMEOUT_MS, 64),
             )
             .await,
         );
@@ -748,7 +751,7 @@ exit 9
             run_provider_preview(
                 GatewayEnrichmentProvider::Codex,
                 &[sample_input()],
-                &runner(script, 1_000, 1_024),
+                &runner(script, PROCESS_TEST_TIMEOUT_MS, 1_024),
             )
             .await,
         );
@@ -769,7 +772,7 @@ exit 9
             run_provider_preview(
                 GatewayEnrichmentProvider::Codex,
                 &[sample_input()],
-                &runner(script, 1_000, 1_024),
+                &runner(script, PROCESS_TEST_TIMEOUT_MS, 1_024),
             )
             .await,
         );
diff --git a/crates/labby/src/dispatch/snippets/dispatch.rs b/crates/labby/src/dispatch/snippets/dispatch.rs
index 8c3047fbb..64b0d344a 100644
--- a/crates/labby/src/dispatch/snippets/dispatch.rs
+++ b/crates/labby/src/dispatch/snippets/dispatch.rs
@@ -398,8 +398,8 @@ async fn execute_snippet_outcome(
             surface,
             config,
             scope,
-            // Snippet execution is a local trusted-CLI path with no durable-run
-            // execution id; `None` keeps `record_step` write-free here.
+            // Saved-snippet dispatch does not mint a durable execution id on
+            // this path; `None` keeps `record_step` write-free here.
             None,
         )
         .await

From ae323ae798c7e15f15cc5f191bfa2cb5ad252ad1 Mon Sep 17 00:00:00 2001
From: Jacob Magar <jmagar@gmail.com>
Date: Sat, 19 Sep 2026 00:51:43 -0400
Subject: [PATCH 16/16] fix(codemode): update catalog descriptor tests

---
 crates/labby-codemode/src/execute.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/crates/labby-codemode/src/execute.rs b/crates/labby-codemode/src/execute.rs
index e50487d1b..5df34b329 100644
--- a/crates/labby-codemode/src/execute.rs
+++ b/crates/labby-codemode/src/execute.rs
@@ -1190,9 +1190,9 @@ mod tests {
     #[tokio::test]
     async fn raw_tool_call_boundary_rejects_undeclared_and_out_of_route_tools() {
         let host = FixtureHost::new(vec![
-            ToolDescriptor::tool("alpha", "tool1", "allowed", None, None),
-            ToolDescriptor::tool("alpha", "other_tool", "undeclared sibling", None, None),
-            ToolDescriptor::tool("beta", "tool2", "out of route", None, None),
+            CatalogDescriptor::tool("alpha", "tool1", "allowed", None, None),
+            CatalogDescriptor::tool("alpha", "other_tool", "undeclared sibling", None, None),
+            CatalogDescriptor::tool("beta", "tool2", "out of route", None, None),
         ]);
         let broker = CodeModeBroker::new(Some(&host));
         let scope = ToolScope::scoped_namespaces(