Phase 3d: add actionable configuration parse errors

This change reports malformed JSON separately from typed policy errors and makes configuration failures actionable without leaking secrets or allowing untrusted text to corrupt diagnostics.

Details:
- include complete JSON paths and source locations for one-shot and state-aware failures
- preserve state-aware output ownership while rejecting trailing data and malformed experimental blocks
- escape control characters, redact secret-bearing values, and avoid retaining a full untyped request tree
- document the diagnostic contract and add focused parser coverage

Tests:
- cargo fmt --all -- --check
- cargo check -p wxc_common -p wxc --all-targets
- cargo clippy -p wxc_common -p wxc --all-targets -- -D warnings
- cargo test -p wxc_common -p wxc
- node scripts/versioning/check-schema-codegen.js
- node scripts/versioning/check-sdk-types-codegen.js
- node scripts/versioning/check-schema-versions.js

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Generated-with: gpt-5.6-sol
Copilot-Session: f66f1e4b-72f7-4508-abb2-3bb3d4c808b9

Author: Gudge

.github/copilot-instructions.md

@@ -118,7 +118,7 @@ The Rust workspace (`src/`) implements multiple sandboxing backends behind the `
 
 ### Config flow
 
-1. User provides JSON config (file or base64) → `config_parser.rs` deserializes into the typed wire model (`wxc_common::wire`) → validates and maps to `ExecutionRequest` (the internal execution model in `models.rs`)
+1. User provides JSON config (file or base64) → `config_deserialize.rs` performs path-aware typed deserialization into the wire model (`wxc_common::wire`) → `config_parser.rs` validates and maps it to `ExecutionRequest` (the internal execution model in `models.rs`)
 2. `ExecutionRequest` includes the containment backend selection, process config, filesystem/network policies, and optional experimental features
 3. The appropriate `ScriptRunner` implementation executes the process and returns `ScriptResponse`
 
@@ -210,7 +210,7 @@ The workspace is organized into six top-level directories under `src/`:
 
 ### Config parser pattern
 
-The parser deserializes JSON directly into the typed wire model (`wxc_common::wire`), the single source of truth for the config shape (it also generates the JSON schema). `config_parser.rs` then maps the wire types to the validated domain structs in `models.rs`. The stable surface uses `deny_unknown_fields` (closed); the `experimental` block is permissive.
+The parser deserializes JSON directly into the typed wire model (`wxc_common::wire`), the single source of truth for the config shape (it also generates the JSON schema). All typed config deserialization goes through `config_deserialize.rs`, which distinguishes syntax errors from typed policy errors and adds the complete JSON path plus source line/column when available; state-aware backend errors are prefixed with their full `experimental.<backend>.<phase>` location. `config_parser.rs` then maps the wire types to the validated domain structs in `models.rs`. The stable surface uses `deny_unknown_fields` (closed); the `experimental` block is permissive.
 
 ### TypeScript conventions
 

docs/state-aware-lifecycle/mxc-state-aware-sandbox-api.md

@@ -675,6 +675,15 @@ state-aware mode so `stdout` remains parseable without sentinels. (One-shot disp
 keeps its existing `stdout` logger behaviour — the stricter routing applies to
 state-aware only.)
 
+Configuration parse-phase failures follow the same state-aware contract: the typed
+`{error}` envelope is the only primary output, while the human-readable actionable
+parse diagnostic is written only to configured auxiliary sinks (`--log-file` and the
+Windows diagnostic console). It is not duplicated to the logger's primary
+console/buffer output, so a parse failure does not add stderr noise even with
+`--debug`. Dispatch-time failures, including typed per-backend configuration
+errors, use the same auxiliary-only diagnostic routing before the executor emits
+their typed `{error}` envelope.
+
 For exec specifically, MXC diagnostic output mixes with the script's own stderr when
 `--debug` is passed. This is a small amount of pre- and post-dispatch noise; consumers
 wanting clean separation should use `--log-file <path>` instead, which routes diagnostic
@@ -982,26 +991,30 @@ implements one trait, the other, or both, depending on its declared participatio
 
 ### 9.1 Wire envelope (Rust mirror)
 
-MXC's parser at `src/core/wxc_common/src/config_parser.rs` deserializes the
-wire-format JSON directly into the typed wire model in
-`src/core/wxc_common/src/wire.rs` (`wire::MxcConfig`), then maps it into the
-typed domain models (`convert_wire_config` → `ExecutionRequest`, with `From`
-impls beside the domain types for the trivial enum/struct conversions) before
-dispatch. The state-aware path reuses this same wire model.
+`src/core/wxc_common/src/config_deserialize.rs` performs path-aware JSON
+deserialization into the typed wire model in
+`src/core/wxc_common/src/wire.rs` (`wire::MxcConfig`).
+`src/core/wxc_common/src/config_parser.rs` discriminates request shape,
+validates the wire model, and maps it into the typed domain models
+(`convert_wire_config` → `ExecutionRequest`, with `From` impls beside the
+domain types for trivial enum/struct conversions). The state-aware path reuses
+this wire model while retaining its per-backend `experimental` subtree for
+dispatch-time typing.
 
 ```rust
 // In config_parser.rs — discrimination is by presence of the `phase` key in
-// the decoded JSON; both shapes deserialize into the one wire::MxcConfig type,
-// which declares `phase` / `sandboxId` and the per-backend `experimental` block.
-let value: serde_json::Value = serde_json::from_str(&json_str)?;
-if value.get("phase").is_some() {
-    // state-aware: peel off the raw `experimental` block (typed per-backend at
-    // dispatch), deserialize the rest into wire::MxcConfig, then map.
-    convert_wire_state_aware(value, logger, allow_missing_command)
+// the source JSON without building a full untyped request tree.
+let discriminator: RequestDiscriminator<'_> =
+    config_deserialize::from_str(&json_str)?;
+if discriminator.phase.is_some() {
+    convert_wire_state_aware(
+        &json_str,
+        discriminator.experimental,
+        logger,
+        allow_missing_command,
+    )
 } else {
-    // one-shot: deserialize wire::MxcConfig from the source text (preserving
-    // serde line/column diagnostics) and map.
-    let cfg: wire::MxcConfig = serde_json::from_str(&json_str)?;
+    let cfg: wire::MxcConfig = config_deserialize::from_str(&json_str)?;
     convert_wire_config(cfg, logger, true, allow_missing_command)
 }
 ```

docs/versioning.md

@@ -438,6 +438,16 @@ HRESULT EnumerateSandboxSpecVersionInfo(
 
 Negotiation failures are **typed and actionable** — never a silent fallback:
 
+- **JSON and policy-shape failures** distinguish malformed JSON syntax from
+  valid JSON that does not match the typed wire contract. Typed failures name
+  the full policy path (for example, `network.proxy.localhost`), retain Serde's
+  expected type/value information, and include source line/column when parsing
+  directly from request text. State-aware per-backend configuration errors are
+  prefixed with their full `experimental.<backend>.<phase>` location. Diagnostic
+  text escapes control characters, and errors at secret-bearing paths redact the
+  submitted value. After the root JSON value, only whitespace is accepted;
+  trailing JSON values or other trailing content are rejected as malformed
+  syntax.
 - **Schema-range failures** (Stage 1) carry a clear "older than supported" /
   "newer than supported" message telling the caller whether to update the config
   or upgrade `wxc-exec`.

src/Cargo.lock

@@ -94,6 +94,7 @@ windows = { version = "0.62", features = [
 windows-core = "0.62"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
+serde_path_to_error = "0.1"
 thiserror = "2"
 anyhow = "1"
 base64 = "0.22"

src/Cargo.toml

@@ -226,14 +226,16 @@ fn apply_command_override(
     }
 }
 
-/// Drives the state-aware dispatch flow. On envelope success, writes the
-/// JSON to stdout and exits 0. On exec success, exits with the script's
-/// exit code (output already streamed). On failure, writes a JSON error
-/// envelope to stdout and exits 1. Diagnostic logger output goes to stderr
-/// regardless of mode (per design §7.3 stream protocol — stdout reserved
-/// for the response envelope).
+fn log_state_aware_dispatch_error(logger: &mut Logger, error: &MxcError) {
+    logger.log_diagnostic_line(&error.to_string());
+}
+
+/// Runs state-aware dispatch while reserving stdout for envelopes or script output.
 fn run_state_aware_main(parsed: ParsedStateAwareRequest, dry_run: bool, logger: &mut Logger) -> ! {
     let outcome = mxc_engine::run_state_aware(parsed, dry_run);
+    if let Err(error) = &outcome {
+        log_state_aware_dispatch_error(logger, error);
+    }
     // Diagnostic buffer flushes to stderr regardless of success/failure so it
     // never interleaves with the stdout envelope.
     let buffered = logger.get_buffer().to_string();
@@ -1145,6 +1147,31 @@ mod tests {
         Logger::new(Mode::Buffer)
     }
 
+    #[test]
+    fn state_aware_dispatch_errors_use_only_auxiliary_diagnostic_sinks() {
+        let directory = tempfile::tempdir().unwrap();
+        let log_path = directory.path().join("mxc.log");
+        let mut logger = test_logger();
+        logger.enable_file_sink(&log_path).unwrap();
+        let error = MxcError::malformed_request(
+            "Invalid configuration at `experimental.wslc.start.portMappings[0].windowsPort`",
+        );
+
+        log_state_aware_dispatch_error(&mut logger, &error);
+
+        assert!(
+            logger.get_buffer().is_empty(),
+            "the JSON envelope must retain primary output ownership"
+        );
+        drop(logger);
+        let log = std::fs::read_to_string(log_path).unwrap();
+        assert_eq!(
+            log.matches("experimental.wslc.start.portMappings[0].windowsPort")
+                .count(),
+            1
+        );
+    }
+
     #[test]
     fn cli_parses_flags_after_config_path_without_command_override() {
         let cli = parse_cli(&["wxc-exec", "policy.json", "--experimental", "--debug"]);

src/core/wxc/src/main.rs

@@ -12,7 +12,8 @@ schema-gen = ["dep:schemars"]
 
 [dependencies]
 serde = { workspace = true }
-serde_json = { workspace = true }
+serde_json = { workspace = true, features = ["raw_value"] }
+serde_path_to_error = { workspace = true }
 thiserror = { workspace = true }
 base64 = { workspace = true }
 url = { workspace = true }