[ProcessContainer] Add caller-controlled PTY support

[Branden Bonaby (bbonaby)]

📖 Description

• Adds caller-controlled PTY execution for Windows ProcessContainer through spawnWithPty.
• Preserves normal ProcessContainer tier selection, including BaseContainer/PSEC when it can enforce the request.
• Keeps DACL guard lifetime, policy validation, timeout, and process-tree cleanup intact.
• Supports terminal input, merged output, resize, wait, timeout, and process-tree termination.
• Drains unclaimed ConPTY output before teardown so ClosePseudoConsole cannot block on a full pipe.

Limitations

• PTY output is a single merged terminal stream rather than separate stdout and stderr.
• BaseContainer/PSEC currently creates the child successfully but does not attach its input or output to ConPTY on the tested Windows host. The public SDK integration test therefore times out with an empty terminal transcript; this remains under investigation.

Architecture

flowchart LR
    Caller[SDK caller<br/>Rust / Node / .NET] --> Engine[mxc_engine<br/>ProcessContainer dispatch]
    Engine --> Select[Normal ProcessContainer tier selection]
    Select --> Base[BaseContainer / PSEC]
    Select --> App[AppContainer tier]
    Base --> ConPTY[ConPTY]
    App --> ConPTY[ConPTY]
    ConPTY --> Pty[MxcPty<br/>input / merged output / resize / wait]
    Pty --> Caller

Loading

🔗 References

• [SDK] Add caller-controlled PTY process APIs  #1377

🔍 Validation

• cargo fmt --all -- --check — passed.
• cargo test -p process_container_common host_process_uses_pseudo_console_transport -- --nocapture — passed.
• cargo test -p process_container_common fallback_detector::tests — passed (26 tests).
• cargo test -p process_container_common dispatcher::tests — passed (28 tests).
• cargo test -p mxc-sdk --test streaming_processcontainer processcontainer_pty_supports_io_resize_and_wait -- --ignored --nocapture — currently fails on BaseContainer: TimedOut with an empty terminal transcript.
• cargo clippy -p process_container_common -p mxc-sdk --all-targets -- -D warnings — passed.
• npm run build && npm test from sdk/node — passed (406 tests; 20 skipped).
• dotnet run --project Microsoft.Mxc.Sdk.Tests/Microsoft.Mxc.Sdk.Tests.csproj --no-build --no-restore -- -class Microsoft.Mxc.Sdk.Tests.MxcPtyProcessTests from sdk/dotnet — passed (9 tests).
• cargo test -p process_container_common — 323 passed; the unrelated host-loopback proxy test timed out with WinSock error 10060 on this host.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (see docs/pull-requests.md)

📋 Issue Type

• Bug fix
• Feature
• Task

---

GitHub Actions runs the PR validation build automatically. The ADO pipeline
(MXC-PR-Build) is the Azure version of the PR pipeline, kept in parity with the GitHub
Actions build; it runs on merge to main, and Microsoft reviewers with write access can trigger it
on a PR with /azp run. See docs/pull-requests.md.

If the dependency-feed-check check fails on a new dependency, the crate must be added to
the feed before the PR can pass. See docs/pull-requests.md
for the steps.

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

The base branch was changed.

[Copilot]

Copilot review overview

🟡 Changes recommended

A stale validator makes ProcessContainer PTY spawning unreachable, and timeout enforcement is incomplete for Rust SDK PTY waits.

Review effort: Balanced
Findings: 4

Open (4)

• Enforce scriptTimeout during AppContainer PTY polling · New
• Enforce scriptTimeout during PTY try_wait polling · New
• Remove ProcessContainer PTY rejection guard · New
• Validate handles before constructing BorrowedHandle · New

What changed in this PR

Adds caller-controlled ConPTY execution to Windows ProcessContainer while retaining backend fallback and policy enforcement.

Changes:

• Adds PTY creation, I/O, resize, wait, and teardown support.
• Integrates PTYs into AppContainer, BaseContainer/PSEC, and DACL wrappers.
• Updates SDK documentation to list ProcessContainer support.

File	Description
src/​core/​wxc_common/​src/​process_util.rs	Adds Windows handle conversions.
src/​core/​mxc-sdk/​src/​lib.rs	Documents ProcessContainer PTY support.
src/​core/​mxc_engine/​src/​dispatch.rs	Routes ProcessContainer PTY requests.
src/​backends/​process_container/​common/​src/​secenv.rs	Adds the PSEC pseudo-console attribute.
src/​backends/​process_container/​common/​src/​pseudo_console.rs	Implements ConPTY ownership and I/O.
src/​backends/​process_container/​common/​src/​lib.rs	Registers the PTY module.
src/​backends/​process_container/​common/​src/​dispatcher.rs	Forwards PTY operations through DACL guards.
src/​backends/​process_container/​common/​src/​base_container_runner.rs	Integrates PTYs with BaseContainer.
src/​backends/​process_container/​common/​src/​appcontainer_runner.rs	Integrates PTYs with AppContainer.
src/​backends/​process_container/​common/​examples/​lm_capture.rs	Updates startup-info construction.
sdk/​node/​README.md	Documents Node.js support.
sdk/​dotnet/​README.md	Documents .NET support.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Copilot review overview

🟡 Changes recommended

Existing ProcessContainer validation still rejects every PTY request before either new launch path runs.

Review effort: Balanced
Findings: 4 · 1 · 1

Open (6)

• Validate handles before constructing BorrowedHandle
• Remove ProcessContainer PTY rejection guard
• Enforce scriptTimeout during PTY try_wait polling
• Enforce scriptTimeout during AppContainer PTY polling
• Add Windows ProcessContainer PTY integration coverage · New
• Update Rust SDK README to document Windows ProcessContainer support · New

[Copilot]

Copilot review overview

🟡 Changes recommended

Both ProcessContainer tiers can misclassify a process that exited near its deadline as timed out.

Review effort: Balanced
Findings: 1 · 3 · 1

Open (5)

• Remove ProcessContainer PTY rejection guard
• Avoid timing out exited AppContainer processes · New
• Avoid timing out successfully exited processes · New
• Add Windows ProcessContainer PTY integration coverage
• Update Rust SDK README to document Windows ProcessContainer support

Resolved since last review (3)

• Validate handles before constructing BorrowedHandle
• Enforce scriptTimeout during PTY try_wait polling
• Enforce scriptTimeout during AppContainer PTY polling

[Copilot]

Copilot review overview

🟡 Changes recommended

Inheritable ConPTY pipe handles can leak and block teardown, while blocking and polling waits currently apply inconsistent timeout deadlines.

Review effort: Balanced
Findings: 1 · 1

Open (2)

• Use non-inheritable ConPTY pipes to prevent EOF hangs · New
• Apply the same deadline to both process wait APIs · New

Resolved since last review (5)

• Remove ProcessContainer PTY rejection guard
• Avoid timing out successfully exited processes
• Avoid timing out exited AppContainer processes
• Add Windows ProcessContainer PTY integration coverage
• Update Rust SDK README to document Windows ProcessContainer support

Previously missed (1)

In code that hasn't changed since last review

Rename fallible handle conversion to try_into_std_owned_handle

src/​core/​wxc_common/​src/​process_util.rs:331

This public fallible conversion is named like an infallible Into operation, unlike the adjacent OwnedHandle::try_into_std_owned_handle API. Rename it to try_into_std_owned_handle and update its ProcessContainer call sites so callers can recognize that it may fail.

[Copilot]

Copilot review overview

🔵 Needs a closer look

Low-level ConPTY lifecycle and teardown behavior still requires the noted real ProcessContainer workload validation.

Review effort: Balanced
Findings: 1

Open (1)

• Apply the same deadline to both process wait APIs

Resolved since last review (1)

• Use non-inheritable ConPTY pipes to prevent EOF hangs

[Copilot]

Copilot review overview

🟡 Changes recommended

Integration coverage does not currently verify timeout termination or merged stderr behavior.

Review effort: Balanced
Findings: 2

Open (2)

• Add PTY integration coverage for timeout and process-tree termination · New
• Integration test does not verify merged stderr output · New

Resolved since last review (1)

• Apply the same deadline to both process wait APIs

[Copilot]

Copilot review overview

🟡 Changes recommended

Normal tier selection can choose the acknowledged nonfunctional BaseContainer PTY path, causing empty-output timeouts.

Review effort: Balanced
Findings: 1 · 2

Open (3)

• PTY tier selection can choose BaseContainer without I/O attachment · New
• Integration test does not verify merged stderr output
• Add PTY integration coverage for timeout and process-tree termination

Previously missed (1)

In code that hasn't changed since last review

Correct startup comment about PTY standard handle flags

src/​backends/​process_container/​common/​src/​appcontainer_runner.rs:1084

This launch description contradicts the startup info above: PTY mode sets STARTF_USESTDHANDLES at line 1007, with null standard handles, while only bInheritHandles is false. Correct the comment so future changes do not remove a flag this implementation intentionally relies on.

[Branden Bonaby (bbonaby)]

Moving this one to draft. Looks like the CreateProcessSecurityEnvironment API flow doesn't currently support creating in PTYs yet.