From 29d7aecf860a26ed0dfeb38b5a47e9b29b1acb7a Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 11 Nov 2026 06:27:39 +0000
Subject: [PATCH 1/2] Initial plan


From 602ef6662b17976724bcb0bf826a7e41e7bd52dd Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Wed, 11 Nov 2026 06:31:11 +0000
Subject: [PATCH 2/2] docs: clarify IsolationSession companion-profile cleanup
 limits

Co-authored-by: shanselman <2892+shanselman@users.noreply.github.com>
---
 .../backends/isolation-session/oneshot.md     |  4 +++
 .../isolation-session/state-aware-rust.md     | 30 +++++++++++++++++++
 .../state-aware-typescript.md                 |  5 ++++
 3 files changed, 39 insertions(+)

diff --git a/docs/development/architecture/backends/isolation-session/oneshot.md b/docs/development/architecture/backends/isolation-session/oneshot.md
index 15591508a8..847e6bc7da 100644
--- a/docs/development/architecture/backends/isolation-session/oneshot.md
+++ b/docs/development/architecture/backends/isolation-session/oneshot.md
@@ -61,6 +61,10 @@ Windows agent user account (an opaque, OS-assigned name), launches a per-session
 host process, and exposes the running script as an `IsoSessionProcess` handle
 from which the runner reads pipe handles for I/O.
 
+Create-and-run cleanup uses the same stop and remove-user APIs and has the same
+[companion-profile cleanup limitations](state-aware-rust.md#cleanup-contract-and-profile-limitations)
+as container lifecycle operations.
+
 ## Architecture
 
 This backend follows the existing single-binary, multiple-backend pattern.
diff --git a/docs/development/architecture/backends/isolation-session/state-aware-rust.md b/docs/development/architecture/backends/isolation-session/state-aware-rust.md
index ba83ff89aa..a0e5ef54ef 100644
--- a/docs/development/architecture/backends/isolation-session/state-aware-rust.md
+++ b/docs/development/architecture/backends/isolation-session/state-aware-rust.md
@@ -397,6 +397,36 @@ remove `phase` and `sandboxId` from the JSON payload and pass them as
 | stop | OS-side dependent | Stopping an already-stopped session surfaces an HRESULT from `StopSessionAsync`; mapped to `backend_error`. The agent user remains — only the running session is gone. |
 | deprovision | becomes `stale_id` | After a successful deprovision, the agent user is gone. A second deprovision on the same `sandboxId` fails the OS-side agent-user lookup (`HRESULT_FROM_WIN32(ERROR_NOT_FOUND)`), which the runner maps to `MxcError::StaleId`. |
 
+## Cleanup contract and profile limitations
+
+The supported caller sequence is to finish and dispose live SDK process handles,
+then stop the container and deprovision it, including on workload failure.
+Node's `runInContainer` disposes its process handle in `finally`; callers using
+that convenience method do not need an additional process-disposal call.
+
+MXC awaits `IsoSessionOps.StopSessionAsync` for stop and
+`IsoSessionOps.RemoveUserAsync` for deprovision, and checks each returned
+`IsoSessionResult.Error`. Transport failures and OS-reported errors propagate
+through the lifecycle error mapping below. Success means these checks passed;
+it is not independent verification that Windows has removed every associated
+profile resource.
+
+MXC does not enumerate or delete companion `Win32_UserProfile` entries,
+`ProfileList` registry keys, or profile directories after `RemoveUserAsync`.
+A successful response with `warnings: []` therefore does not establish that
+those resources are gone. MXC provides no companion-profile reclamation deadline
+or additional SDK cleanup operation. This is a cleanup limitation, not a
+documented policy of intentional retention or a guarantee of deferred removal.
+
+If an unloaded companion profile remains, do not retry a successfully consumed
+container ID or delete profiles based on an account-name pattern. The provision
+metadata's `agentUserSid` identifies the agent user, not a companion profile.
+Record the MXC version, Windows build and any experimental host changes, lifecycle
+results, and before/after profile observations with elapsed time for MXC/Windows
+investigation. Profile observations alone do not establish which component owns
+the defect. Manual profile or registry deletion is not an MXC-supported cleanup
+step.
+
 ## Concurrency
 
 ### Multiple sandboxes
diff --git a/docs/development/architecture/backends/isolation-session/state-aware-typescript.md b/docs/development/architecture/backends/isolation-session/state-aware-typescript.md
index 0253ab79fa..8bbc4ef042 100644
--- a/docs/development/architecture/backends/isolation-session/state-aware-typescript.md
+++ b/docs/development/architecture/backends/isolation-session/state-aware-typescript.md
@@ -100,6 +100,11 @@ optional initial terminal `size`, and returns `Promise<MxcPtyProcess>`.
 `StopOptions` and `DeprovisionOptions` carry optional experimental authorization
 and telemetry. Neither phase returns metadata.
 
+Success, including `warnings: []`, reports the Windows lifecycle API result;
+it does not verify companion-profile removal. No additional SDK profile-cleanup
+call is available. See the [cleanup contract and profile limitations](state-aware-rust.md#cleanup-contract-and-profile-limitations)
+for caller responsibilities and investigation guidance.
+
 ## End-to-end example
 
 ```typescript