sandbox_review

把測過的版本交給人，等待回饋或驗收完成。卡片與產品入口會立即出現在人的 app。未宣告支援長等待的 client，預設等待上限是 25 秒；完成設定的 client 最多可等 30 分鐘。

先在人要用的地方測過流程：手機或桌面 App 在箱子畫面上點、打字（sandbox_shot 看結果），網頁則從全新瀏覽器 session 走過包含登入入口的流程，再回到產品起始畫面。以 what 建立卡片，用人讀的語言寫。卡片只顯示前兩行，所以先寫人要測什麼：從哪裡開始、點什麼或打什麼、成功時會看到什麼；最後用一句短話說你自己測了什麼。卡片包含這段文字（最多 400 字元）、產品畫面與開啟按鈕，按鈕打開你用 open 指定的入口（見下文）。每一版測過、值得人花時間的都可交件（收尾）。

{ "id": "<boxId>", "what": "新增一筆待辦，再返回清單：剛加的待辦還在。我自己在全新的瀏覽器 session 新增待辦並返回清單測過。", "open": "web", "port": 5173 }

呼叫在支援的等待上限內持續等待。等待上限協商、進度與取消轉送使用 stdio adapter parallelsandbox-mcp 0.4.2 以上。進度會立即帶出 reviewId、shareUrl 與 productUrl，之後每 15 秒更新。人送出回饋時，以 outcome: "report" 回傳完整 fromHuman：文字、帶重新簽署網址的檔案、圈選圖、錄影與時間逐字稿。先讀這些內容，再在目前對話繼續處理。其他結果為 done、superseded、cancelled、timed_out、wait_cancelled；完成與交付狀態描述的是交件流程，不代表產品獲准或 AI 已完成修改。

給人的是 shareUrl。交件還在等的時候，它在 ParallelSandbox app 裡打開這一輪驗收，不需要帳號也不用登入，有產品也有回報工具，同事也能用同一個連結；交件結束之後它是 app 裡的箱子頁，要登入帳號。productUrl 是產品本身：open: "web" 是 port 上的頁面，open: "box" 是同一個驗收頁。它沒有回報工具，不是要交給人的連結。

Codex 要完整等 30 分鐘，宿主工具逾時與 adapter 逾時都必須允許。使用者要求啟用長等待時，在既有 stdio server 項目加入以下設定；已設更長的逾時就保留，其他設定也保留：

[mcp_servers.parallelsandbox]
tool_timeout_sec = 1920
env = { PSBX_TOOL_TIMEOUT_SEC = "1920" }

已有 env 時，把 PSBX_TOOL_TIMEOUT_SEC 合併進去，再重新連線。adapter 會向伺服器宣告可安全等待的上限。只增加 waitSec 無法延長 client 支援的上限；未做設定時，短等待返回後，驗收卡片仍保留。

逾時或取消等待後，卡片與回饋仍保留。用原本的 reviewId 接續同一輪：

{ "id": "<boxId>", "reviewId": "<reviewId>" }

那一輪已經收到人的回饋時，不管 waitSec 是多少都馬上回：outcome: "report"、reportId 與完整的 fromHuman，不必先查 sandbox_status 再呼叫 sandbox_report。

新的 what 會換掉上一張卡片；reviewId 接續原卡片。明確要交件後立即返回時，設 waitSec: 0。還在等待的呼叫可以把回饋交回目前對話。

要在 AI 回完後自動接續，先用 parallelsandbox-agent 啟動原生對話（快速開始）。常駐執行器透過 Codex、Claude Code 或 Gemini driver 管理唯一的原生程序，將這次工具回傳的 reviewId 登記到原對話 ID。人在 App 送出回饋後，即使 AI 已回完，執行器仍會用同一個 ID 接續；上一輪還在執行就先排隊。接續中的 AI 呼叫 sandbox_report 讀取這份完整回饋，原生回合成功結束後才回報 read。這是已接收並完成該回合的收據，不代表要求的修改都完成。

一般未登記的 MCP 連線仍由使用者接續原對話：在 App 按「複製給 AI 的訊息」貼回原對話，或用原本的 reviewId 接續等待、已知的 reportId 重讀回饋。設定模型、工具權限與恢復原對話的方法見原生對話回饋設定。

傳入 id、what 與 open：卡片打開什麼由你指定，平台不替你選，也不探測。

• open: "web" 加 port：箱子裡在那個 port 上提供的頁面，也就是程式聽的 port（例如 dev server 的 5173）。人在自己的裝置上用自己的瀏覽器打開它，那裡沒有你在箱子裡測試時那個瀏覽器的登入狀態與 cookie。產品要登入的話，照人會用的方式用全新的瀏覽器工作階段測一遍，交出一個會自己登入的頁面：例如讓箱子裡的這份程式多一個只在 dev 用的登入路徑，登入 seed 好的測試帳號後轉到起始畫面，交那個 port（卡片打開的是 port 的根路徑，所以把這個路徑放在根路徑，或讓根路徑轉過去）。不然就把測試帳號與登入方式寫進 what。介面從 dev server 載入的桌面 App（例如 Electron 加 Vite）也可以這樣交，給那個 dev server 的 port。那個 port 還沒有網址時，同一次呼叫就給它一個：那個 port 上已宣告的服務會被標成 web；沒有的話就宣告一個名為 web-<port> 的服務並標成 web。舊版 boxd 的箱子給不了那個 port 網址時，呼叫會回 409，並提示開新箱子、在宣告服務時加上 web: true。
• open: "box"，不給 port：卡片打開箱子的畫面，人自己在上面點、滑、打字，用的是桌面 App（在 DISPLAY=:99 上的視窗：Electron、GTK、Qt 或遊戲），或是跑在 sandbox_device 裝置上的手機 App，不論 Android 還是 iPhone 模擬器都一樣。讓 App 持續跑在螢幕或裝置上。螢幕上什麼都沒有、也沒有已就緒的手機時，呼叫會回 nothing is on this box's screen for a person to use: …；啟動 App、測過，再呼叫 sandbox_review。瀏覽器裡的頁面則用 open: "web" 加它的 port。
• 人能在瀏覽器裡試的，就交 web：對人來說比較順。

{ "id": "<boxId>", "what": "打開 App，點「設定」再點「深色模式」：每個畫面立刻變深色。我自己在箱子畫面上切換測過。", "open": "box" }

open 與 port 在碰箱子之前就先檢查：給了 what 卻沒給 open 或值不對（open is required with what…）、open: "web" 沒給 port（open: web needs port…）、open: "box" 卻給了 port（port goes with open: web…）、reviewId 帶了 open 或 port（open and port go with what (a new review)…），都會回錯誤。sandbox_start.services 或 sandbox_wire 的 web: true 仍會給服務自己的網址與 app 的「使用」按鈕，但不決定 sandbox_review 打開什麼。

細節：

• 畫面是叫它的當下在箱子裡拍的截圖：web 拍那個頁面的網址，box 拍箱子的螢幕（接著裝置時就是手機本身的畫面）。拍不到的話卡片照樣送出，只是沒有圖。
• open 表示你指定的入口。web 的卡片留住交件當下的頁面網址，之後重新接線也不會改變它。觀看 AI 即時畫面是 app 的另一個入口；sandbox_takeover 讓人操作那個 session，完成只有本人能做的步驟。
• 人開著 box 的卡片時就是在操作箱子：那段時間對這個箱子的 sandbox_exec 會回 HTTP 423（有人在操作畫面），直到人離開；sandbox_shot 拍畫面照樣看得到人在做什麼（takeover: true）。那是人在試，不是箱子壞了；這時別重裝、重開 App。
• 等著的卡片不會讓任何東西保持醒著。箱子與它的裝置照一般閒置規則，10 分鐘沒有使用就凍結、到期就停掉（箱子狀態），跟沒有交件時一樣。人打開交件時，凍結的箱子會醒來，裝置跟著開回來（iPhone 模擬器的 App 會重新啟動）；這段期間箱子已經停掉的話，交件就結束，要在新的箱子重新交件。
• 卡片留到人送出回饋、按「驗完了」（POST /v1/boxes/{id}/review/done）、被你換掉，或箱子停掉為止。GET /v1/boxes 會把待驗收卡片放在 review（id、what、url、shotUrl、createdAt）。
• web 的時候，人的請求跟箱子網址上的任何使用一樣讓箱子醒著（箱子狀態），sandbox_scene 也碰得到人開著的那一頁。

所有工具與主題都列在工具參考。