From d09be9cfa2ee988bfba04b80f7b8d38297b7903c Mon Sep 17 00:00:00 2001
From: morluto <76467478+morluto@users.noreply.github.com>
Date: Sat, 17 Oct 2026 13:49:20 +0800
Subject: [PATCH] docs(browser): clarify scenario cleanup after termination

Document retained profile data, missing-executable Playwright artifacts, platform cancellation differences and the absence of later reclamation. Keep recovery work tracked in #4659.

Confirmed installed Playwright 1.58.2 preparation order and one public CLI missing-executable reproduction in a private fixture; an empty artifacts directory remained and was removed only with the owned experiment root. Forced termination was not rerun. docs:check passed.
---
 docs/browser-scenario-contract.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/browser-scenario-contract.md b/docs/browser-scenario-contract.md
index f6d6a40a7d..067fb94091 100644
--- a/docs/browser-scenario-contract.md
+++ b/docs/browser-scenario-contract.md
@@ -144,6 +144,18 @@ distinction: it closes and deletes provider-owned profiles, but only disconnects
 from an external CDP browser. Real-browser verification checks both outcomes and
 confirms that an attached external browser remains alive.
 
+That cleanup requires REA to remain running. Abrupt termination, including
+Windows process-tree termination or POSIX `SIGKILL`, can leave the launch
+profile and Playwright artifacts behind. A profile can retain cookies, history,
+cache and origin storage. Later REA runs currently do not reclaim these paths.
+Playwright 1.58.2 can also leave an artifacts directory when launch preparation
+fails before a browser process exists, such as for a missing executable.
+POSIX wrappers can request awaited cancellation with `SIGINT` or `SIGTERM`;
+Windows process termination is not an equivalent graceful-cancellation channel.
+Do not identify owned artifacts by directory prefix or creation time alone.
+See [#4659](https://github.com/morluto/rea/issues/4659) for the remaining recovery
+and wrapper-cancellation work.
+
 Keeping that browser alive does not guarantee its emulation state survives.
 Chromium can clear caller-owned `navigator.platform` emulation when a page CDP
 session disconnects, including sessions that sent no emulation commands. REA