upstream-radar 0.43.5 → 0.45.0

package/README-zh-CN.md

@@ -1,6 +1,6 @@
 <h1 align="center">Upstream Radar</h1>
 
-<p align="center"><strong>在 DeepSeek Harness 生态变化后，找出哪些插件需要维护者关注。</strong></p>
+<p align="center"><strong>持续验证 DeepSeek Harness 插件兼容性——覆盖 headless、Web 和 TUI。</strong></p>
 
 <p align="center">
   <a href="README.md">English</a> ·
@@ -10,9 +10,9 @@
   <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
 </p>
 
-Upstream Radar 持续检查三者之间的真实关系：精确的 DSH 插件发布物、DSH 宿主和依赖图。
-当 DSH 或插件发布新版本改变这层关系时，Radar 告诉你变了什么、实际观测到了什么，以及维护者
-可以修什么。
+Upstream Radar 把精确的插件发布物、DSH 宿主和运行环境绑定在一起，让 Agent 根据仓库说明和
+已有失败证据推导受限环境，再放进一次性 GitHub VM 中实际验证。生态发生变化或证据过期后都会
+重跑，因此它检查的是**当前版本是否仍然可用**，而不只是比较一次 diff。
 
 它面向 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 插件生态。
 静态检查是关于发布包的证据；隔离运行检查是关于某个精确的
@@ -38,31 +38,38 @@ Upstream Radar 持续检查三者之间的真实关系：精确的 DSH 插件发
 
 ## Radar 做什么
 
-1. **锁定真实输入。** 读取精确 npm 发布物、DSH 版本、Node 运行时、profile、lockfile 和依赖路径。
-2. **比较真实关系。** 发现上游变化、发布/源码漂移、依赖图不完整和 DSH 契约不一致。
-3. **需要执行时再观察。** 在全新的、无密钥的环境中安装、注册并加载精确发布物，记录结果和边界。
-4. **完成闭环。** 生成有边界的证据，把重要变化交给可选的 DSH Agent，并在干净复测后更新或关闭一条面向维护者的 Issue。
+1. **建立统一兼容记录（IR）。** 对齐 npm 发布物、源码 commit、DSH 宿主、运行环境/profile、依赖路径和漏洞情报。
+2. **推导运行环境。** Agent 读取作者声明的安装说明和失败证据，只输出边界明确的安装计划。
+3. **验证不同执行平面。** 全新、无密钥的 runner 分别验证 headless 加载、Chromium Web 启动或真实 PTY TUI 交互。
+4. **让结果持续有效。** DSH/插件/依赖变化以及证据过期都会触发复测；确认的问题变成可修报告，干净复测后完成闭环。
 
 ```mermaid
 flowchart TB
-  Change["定时运行 / DSH 或插件变化"] --> Agent["Agent 规划受限的 headless 重试"]
-  Agent --> Runtime["一次性虚拟机：安装 → 注册 → 加载"]
-  Runtime -->|"出现下一层门槛"| Agent
-  Runtime -->|"兼容 / 超出 headless"| Evidence["发布精确证据"]
-  Runtime -->|"复现真实失败"| Issue["创建一条可修复的 Issue"]
-  Issue -->|"作者发布修复"| Change
+  Trigger["定时运行 / 上游变化 / 证据过期"] --> IR["精确 IR：插件字节 ↔ DSH ↔ 运行环境 ↔ 依赖"]
+  IR --> Agent["Agent 推导受限安装计划"]
+  Agent --> VM{"全新、无密钥的 GitHub VM"}
+  VM --> Headless["Headless：安装 → 注册 → 加载"]
+  VM --> Web["Web：Chromium → 启动交接 → 客户端包"]
+  VM --> TUI["TUI：PTY → 画面 → 输入 → 声明的退出方式"]
+  Headless --> Ledger["版本化证据账本 + 反向影响索引"]
+  Web --> Ledger
+  TUI --> Ledger
+  Ledger --> Decision{"能归责于插件吗？"}
+  Decision -->|"能"| Issue["生成一条可修复的维护者报告"]
+  Decision -->|"不能 / 检测器缺口"| Hold["暂扣报告并校准"]
+  Issue -->|"作者发布修复"| Trigger
+  Hold --> Trigger
 ```
 
-Agent 读取仓库说明和最新运行证据，决定 headless 是否重试、重试时允许哪些安装条件。
-真正的结果由一次性虚拟机执行得出，而不是模型判断。模型不能凭空增加安装包、不能进入目标
-虚拟机执行，也不能把缺失证据说成通过。
+Agent 可以选择作者声明的构建包、profile 设置和下一次受限重试。精确指纹决定一份报告能填入
+哪个测试格子；真正的结果由一次性虚拟机执行得出，而不是模型判断。缺失证据永远不能变成通过。
 
 ## 试试一个真实检查
 
 第一次检查不需要本地 DSH profile，也不会执行插件代码：
 
 ```bash
-npx --yes upstream-radar@0.43.5 inspect \
+npx --yes upstream-radar@0.45.0 inspect \
   @sanqi-normal/dsh-webui-market-plugin@0.5.4 \
   --deep --fail-on never
 ```
@@ -73,7 +80,7 @@ npx --yes upstream-radar@0.43.5 inspect \
 如果要检查自己的公开仓库，而不安装它：
 
 ```bash
-npx --yes upstream-radar@0.43.5 scan \
+npx --yes upstream-radar@0.45.0 scan \
   https://github.com/owner/dsh-plugin \
   --fail-on never
 ```
@@ -88,14 +95,33 @@ npx --yes upstream-radar@0.43.5 scan \
 - [每天观察一个插件仓库](examples/github-actions/upstream-observer-minimal.yml)：比较 commit、发布版本、manifest 和依赖图，只有发生重要变化才唤起 Agent。
 - [在 CI 中运行依赖门禁](examples/github-actions/upstream-radar.yml)：在合并前检查 lockfile 或审查过的 Radar 配置。
 
-[隔离观察 workflow](.github/workflows/observe-dsh-plugin-install.yml) 会为需要执行代码的检查使用全新的 GitHub 托管 runner。
-它不是你的电脑，也不会接收项目密钥。
+隔离的 [headless](.github/workflows/observe-dsh-plugin-install.yml) 和
+[Web/TUI](.github/workflows/observe-dsh-plugin-surface.yml) workflow 都使用全新的 GitHub 托管 runner。
+它们不是你的电脑，也不会接收项目或模型密钥。
 
 ## 来自真实生态的结果
 
-当前的[100 插件兼容性 feed](feeds/dsh-plugin-compatibility.md)记录了 74 个精确 headless
-通过、22 个仅待复核结果、0 个已复现不兼容和 4 个仅仓库条目。在真正观测所需的
-Web/client 或仓库安装平面之前，待复核项不会被包装成插件故障。
+当前的[100 插件兼容性 feed](feeds/dsh-plugin-compatibility.md)记录了 **87 个已观测兼容、
+9 个待复核、0 个已复现不兼容和 4 个尚未观测**。执行平面账本包含 22 个精确 Web/TUI
+格子；目前 22 个都已在隔离 GitHub VM 中通过。
+
+剩余 9 个待复核格子不是被藏起来的失败：其中 7 个已有绿色 Web 证明，但仍保留独立的
+headless 宿主/peer 契约证据；另 2 个仍声明旧 DSH 宿主包范围，并已有维护者 Issue 跟踪。
+Radar 会保留这些事实，但不会把能正常运行的浏览器插件说成坏了。
+
+首批非 headless 测试已经在 GitHub 托管 VM 中跑通：
+
+| 精确测试格子 | 实际证据 | 结果 |
+| --- | --- | --- |
+| [`dsh-univer-office@0.2.9 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32823035297/job/97726205358) | HTTP 200、DSH 启动完成交接、客户端下载成功、浏览器和页面无错误 | **兼容** |
+| [`@deepseek-harness-tui/dsh-tui@0.9.2 × DSH 0.1.1-rc.2 × TUI`](https://github.com/MicroMilo/upstream-radar/actions/runs/32823035297/job/97726205289) | 真实 PTY 画面、键盘输入、按文档双击 Ctrl-C 后以 code 0 退出 | **兼容** |
+| [`@linxin666/dsh-web-all@0.3.3 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32828788296/job/97742850608) | Agent 批准 4 个依赖构建；聚合客户端包返回 200；启动清单、应用挂载和插件实体相互吻合 | **兼容** |
+| [`dsh-better-sidebar@0.16.1 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32835449819/job/97763410354) | VM 发现 `node-pty` 构建门槛；DeepSeek 只批准这个精确依赖；无密钥重试通过安装、宿主、浏览器交互和关闭阶段 | **兼容** |
+
+`better-sidebar` 展示了完整闭环：动态证据发现 headless 计划没遇到的构建要求；DeepSeek 核对
+精确 manifest、README 和 VM 日志；与指纹绑定的策略只批准 `node-pty`；随后另一台不带模型密钥
+的 runner 给出通过结论。这是 Radar 的环境缺口，因此没有向插件作者提交 Issue。此前 TUI 与 Web
+检测器自身的错误也按同样方式处理：先暂扣、修正并复测，而不是发给作者。
 
 截至 2026-08-25，Radar 共向维护者提交了 13 条报告。比数量更重要的是处理结果：
 

package/README.md

@@ -1,6 +1,6 @@
 <h1 align="center">Upstream Radar</h1>
 
-<p align="center"><strong>Find the DeepSeek Harness plugins that need attention when the ecosystem moves.</strong></p>
+<p align="center"><strong>Always-on compatibility testing for DeepSeek Harness plugins—across headless, Web, and TUI.</strong></p>
 
 <p align="center">
   <a href="README-zh-CN.md">简体中文</a> ·
@@ -10,10 +10,11 @@
   <a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue.svg"></a>
 </p>
 
-Upstream Radar continuously checks the relationship between an exact published
-DSH plugin, its DSH host, and its dependency graph. When a DSH or plugin release
-changes that relationship, Radar shows what changed, what was actually observed,
-and what a maintainer can fix.
+Upstream Radar binds exact plugin bytes to an exact DSH host and runtime, lets an
+Agent derive a bounded environment from repository instructions and prior
+evidence, then proves the relationship in disposable GitHub VMs. It runs again
+when the ecosystem changes **or evidence expires**, so it tests the current
+version—not only the diff.
 
 It is built for the [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness)
 plugin ecosystem. A static review is evidence about a package; an isolated
@@ -41,30 +42,38 @@ repositories are checked separately.
 
 ## What Radar does
 
-1. **Pin the real inputs.** Read the exact npm artifact, DSH version, Node
-   runtime, profile, lockfile, and dependency paths.
-2. **Compare the relationship.** Detect upstream changes, package/release drift,
-   incomplete graphs, and DSH contract mismatches.
-3. **Observe when execution matters.** In a fresh, secret-free runner, install,
-   register, and load the exact artifact; record the result and its boundary.
-4. **Close the loop.** Produce bounded evidence, route meaningful changes to an
-   optional DSH Agent, and update or close one maintainer-facing issue after a
-   clean retest.
+1. **Build one exact compatibility record (IR).** Align the npm artifact,
+   source commit, DSH host, runtime/profile, dependency paths, and advisories.
+2. **Derive the environment.** An Agent reads declared installation guidance
+   and failed evidence, then emits only a bounded install plan.
+3. **Prove each execution plane.** Fresh, secret-free runners exercise headless
+   load, Chromium Web boot, or a real PTY TUI interaction.
+4. **Keep the result alive.** DSH/plugin/dependency changes and evidence expiry
+   trigger retests; confirmed failures become fixable reports and clean retests
+   close the loop.
 
 ```mermaid
 flowchart TB
-  Change["Schedule / DSH or plugin change"] --> Agent["Agent plans a bounded headless retry"]
-  Agent --> Runtime["Disposable VM: install → register → load"]
-  Runtime -->|"next observed gate"| Agent
-  Runtime -->|"compatible / outside headless"| Evidence["Publish exact evidence"]
-  Runtime -->|"reproduced failure"| Issue["Open one fixable issue"]
-  Issue -->|"author ships a fix"| Change
+  Trigger["Schedule / upstream change / evidence expiry"] --> IR["Exact IR: plugin bytes ↔ DSH ↔ runtime ↔ dependencies"]
+  IR --> Agent["Agent derives a bounded install plan"]
+  Agent --> VM{"Fresh secret-free GitHub VM"}
+  VM --> Headless["Headless: install → register → load"]
+  VM --> Web["Web: Chromium → boot handoff → client bundle"]
+  VM --> TUI["TUI: PTY → frame → input → declared shutdown"]
+  Headless --> Ledger["Versioned evidence ledger + reverse impact index"]
+  Web --> Ledger
+  TUI --> Ledger
+  Ledger --> Decision{"Plugin-attributable failure?"}
+  Decision -->|"yes"| Issue["Produce one fixable maintainer report"]
+  Decision -->|"no / detector gap"| Hold["Hold the report and calibrate"]
+  Issue -->|"author ships a fix"| Trigger
+  Hold --> Trigger
 ```
 
-The Agent interprets repository instructions and the latest runtime evidence,
-then chooses whether and how headless should retry. The disposable runner—not
-the model—establishes the result. A model cannot invent a build package, execute
-inside the target VM, or turn missing evidence into a pass.
+The Agent may choose declared build packages, profile setup, and the next bounded
+retry. Exact fingerprints decide which cell a report can satisfy, and the
+disposable runner—not the model—establishes the result. Missing evidence can
+never become a pass.
 
 ## Try a real check
 
@@ -72,7 +81,7 @@ No local DSH profile is needed for this first check. It reviews one exact
 published artifact without executing plugin code:
 
 ```bash
-npx --yes upstream-radar@0.43.5 inspect \
+npx --yes upstream-radar@0.45.0 inspect \
   @sanqi-normal/dsh-webui-market-plugin@0.5.4 \
   --deep --fail-on never
 ```
@@ -85,7 +94,7 @@ behavior. See the [full evidence report](examples/dsh/reports/sanqi-market-plugi
 To review your own public repository without installing it:
 
 ```bash
-npx --yes upstream-radar@0.43.5 scan \
+npx --yes upstream-radar@0.45.0 scan \
   https://github.com/owner/dsh-plugin \
   --fail-on never
 ```
@@ -106,17 +115,39 @@ Copy one of the maintained workflows into your repository:
 - [Run the dependency gate in CI](examples/github-actions/upstream-radar.yml)
   — checks the lockfile or reviewed Radar configuration before merge.
 
-The [isolated observer workflow](.github/workflows/observe-dsh-plugin-install.yml)
-uses a fresh GitHub-hosted runner for code-executing checks. The runner is not
-your workstation and does not receive project secrets.
+The isolated [headless](.github/workflows/observe-dsh-plugin-install.yml) and
+[Web/TUI](.github/workflows/observe-dsh-plugin-surface.yml) observers use fresh
+GitHub-hosted runners. They are not your workstation and receive no project or
+model secrets.
 
 ## Evidence from the ecosystem
 
 The current [100-plugin compatibility feed](feeds/dsh-plugin-compatibility.md)
-records 74 exact headless passes, 22 review-only results, zero reproduced
-incompatibilities, and four repository-only entries. The review-only group is
-kept separate from failures until the required Web/client or repository install
-plane is actually observed.
+records **87 observed compatible, 9 needs review, 0 reproduced incompatible,
+and 4 not observed**. Its execution-plane ledger contains 22 exact Web/TUI
+cells; all 22 now pass in isolated GitHub VMs.
+
+The nine review cells are not hidden failures. Seven have a green Web proof but
+retain separate headless host/peer-contract evidence; two retain known old DSH
+host-package ranges tracked by existing maintainer issues. Radar keeps those
+facts visible without calling a working browser plugin broken.
+
+The first non-headless cells now run in GitHub-hosted VMs:
+
+| Exact cell | Observed proof | Result |
+| --- | --- | --- |
+| [`dsh-univer-office@0.2.9 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32823035297/job/97726205358) | HTTP 200, DSH boot handoff, declared client bundle fetched, no browser/page errors | **Compatible** |
+| [`@deepseek-harness-tui/dsh-tui@0.9.2 × DSH 0.1.1-rc.2 × TUI`](https://github.com/MicroMilo/upstream-radar/actions/runs/32823035297/job/97726205289) | Real PTY frame, keyboard input, documented double-Ctrl-C exit, code 0 | **Compatible** |
+| [`@linxin666/dsh-web-all@0.3.3 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32828788296/job/97742850608) | Agent-approved four dependency builds; aggregate client bundle returned 200; boot manifest, app mount, and plugin materialization matched | **Compatible** |
+| [`dsh-better-sidebar@0.16.1 × DSH 0.1.1-rc.2 × Web`](https://github.com/MicroMilo/upstream-radar/actions/runs/32835449819/job/97763410354) | VM observed a `node-pty` build gate; DeepSeek approved only that exact dependency; the secret-free retry passed install, host, browser interaction, and shutdown | **Compatible** |
+
+The `better-sidebar` run demonstrates the closed loop: dynamic evidence found a
+build requirement absent from the headless plan; DeepSeek checked the exact
+manifest, README, and VM log; a fingerprint-bound policy approved only
+`node-pty`; then a separate runner with no model secrets established the pass.
+This was Radar's environment gap, so no plugin issue was filed. Earlier TUI and
+Web detector mistakes were handled the same way: held, corrected, and rerun
+instead of being sent to authors.
 
 As of 2026-08-25, Radar has filed 13 maintainer-facing reports. The outcome is
 more useful than the raw count:

package/dist/src/cli.js

@@ -7,6 +7,7 @@ import { renderCompatibilityBenchmark, runCompatibilityBenchmark } from './compa
 import { assessCompatibilityChange } from './compatibility.js';
 import { probeDshLoad, probeDshLoadMatrix, renderDshLoadMatrix, renderDshLoadProbe } from './dsh-probe.js';
 import { observeDshPluginInstall, renderDshInstallObservation, } from './dsh-install-observation.js';
+import { observeDshPluginSurface, renderDshSurfaceObservation, } from './dsh-surface-observation.js';
 import { renderDshPluginReview, reviewDshPlugin } from './dsh-review.js';
 import { createAnalysisTask, renderAgentAnalysisPrompt } from './dsh-analysis.js';
 import { createDshCaseReport, renderDshCase } from './dsh-case.js';
@@ -281,6 +282,14 @@ Usage:
   upstream-radar probe dsh-install [npm:]<package>@<exact-version>
     --dsh-version <exact-version> --isolation-provider <provider> --execute
     [--allow-build <package>]... [--timeout <seconds>] [--report <report.json>] [--json]
+  upstream-radar probe dsh-surface [npm:]<package>@<exact-version>
+    --dsh-version <exact-version> --case-id <id> --source-case-id <id>
+    --source-fingerprint <sha256:...> --contract-fingerprint <sha256:...>
+    --plane <web|tui> --profile <name> --runtime-id <id>
+    --artifact-sha256 <hex> --isolation-provider <provider> --execute
+    [--allow-build <package>]...
+    [--driver-root <path>] [--chromium-executable <path>]
+    [--artifacts <directory>] [--timeout <seconds>] [--report <report.json>] [--json]
 
 The load probes disable lifecycle scripts and check bundle registration/load.
 The dsh-install probe deliberately executes the exact plugin's lifecycle scripts
@@ -288,6 +297,10 @@ and loads the bundle while recording Linux process, network, and file-change
 evidence. Run it only inside a disposable, secret-free Linux environment. It
 requires both --execute and UPSTREAM_RADAR_ISOLATED_RUNNER=1.
 Radar records the caller's isolation-provider claim but cannot verify it.
+The dsh-surface probe adds plane-specific proof: Chromium must observe DSH hand
+off from its boot page after activating the client graph, or a real PTY must observe a
+TUI frame, bounded input, and controlled shutdown. It has the same disposable,
+secret-free execution requirement.
 `,
         review: `Upstream Radar — review one exact published DSH plugin in one command
 
@@ -484,6 +497,7 @@ Usage:
   upstream-radar probe dsh-load <package.tgz> [--dsh-version <exact-version>] [--timeout <seconds>] [--keep-profile] [--json]
   upstream-radar probe dsh-matrix <package.tgz> --dsh-version <v1>[,<v2>,...] [--timeout <seconds>] [--keep-profile] [--json]
   upstream-radar probe dsh-install [npm:]<package>@<exact-version> --dsh-version <exact-version> [--case-id <stable-label>] --isolation-provider <github-actions-hosted-runner|firecracker|other> --execute [--allow-build <package>]... [--timeout <seconds>] [--report <report.json>] [--json]
+  upstream-radar probe dsh-surface [npm:]<package>@<exact-version> --dsh-version <exact-version> --case-id <stable-label> --source-case-id <stable-label> --source-fingerprint <sha256:...> --contract-fingerprint <sha256:...> --plane <web|tui> --profile <name> --runtime-id <id> --artifact-sha256 <hex> --isolation-provider <github-actions-hosted-runner|firecracker|other> --execute [--allow-build <package>]... [--driver-root <path>] [--chromium-executable <path>] [--artifacts <directory>] [--timeout <seconds>] [--report <report.json>] [--json]
   upstream-radar review dsh-plugin [npm:]<package>@<exact-version> --dsh-version <v1>,<v2>,... [--json]
   upstream-radar demo [--json]
   upstream-radar case dsh-web-ui [--json]
@@ -1220,8 +1234,10 @@ async function runProbe(args) {
     const mode = args[0];
     if (mode === 'dsh-install')
         return runDshInstallObservation(args.slice(1));
+    if (mode === 'dsh-surface')
+        return runDshSurfaceObservation(args.slice(1));
     if (mode !== 'dsh-load' && mode !== 'dsh-matrix')
-        throw new Error('probe requires dsh-load or dsh-matrix');
+        throw new Error('probe requires dsh-load, dsh-matrix, dsh-install or dsh-surface');
     const packagePath = args[1];
     if (packagePath === undefined || packagePath.startsWith('-'))
         throw new Error(`probe ${mode} requires a package.tgz file`);
@@ -1372,6 +1388,144 @@ async function runDshInstallObservation(args) {
     process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderDshInstallObservation(report));
     return report.result === 'compatible' ? 0 : report.result === 'unknown' ? 1 : 2;
 }
+async function runDshSurfaceObservation(args) {
+    const packageSpec = args[0];
+    if (packageSpec === undefined || packageSpec.startsWith('-')) {
+        throw new Error('probe dsh-surface requires an exact npm package');
+    }
+    let dshVersion;
+    let caseId;
+    let sourceCaseId;
+    let sourceFingerprint;
+    let contractFingerprint;
+    let plane;
+    let profile;
+    let runtimeId;
+    let artifactSha256;
+    let isolationProvider;
+    let timeoutSeconds = 300;
+    let reportPath;
+    let artifactsDirectory;
+    let driverRoot;
+    let chromiumExecutable;
+    const allowedBuilds = [];
+    let execute = false;
+    let json = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--execute')
+            execute = true;
+        else if (argument === '--json')
+            json = true;
+        else if (argument === '--dsh-version' || argument === '--case-id' || argument === '--source-case-id'
+            || argument === '--source-fingerprint' || argument === '--contract-fingerprint' || argument === '--plane'
+            || argument === '--profile' || argument === '--runtime-id' || argument === '--artifact-sha256'
+            || argument === '--isolation-provider' || argument === '--timeout' || argument === '--report'
+            || argument === '--artifacts' || argument === '--driver-root' || argument === '--chromium-executable'
+            || argument === '--allow-build') {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error(`${argument} requires a value`);
+            if (argument === '--dsh-version')
+                dshVersion = value;
+            else if (argument === '--case-id')
+                caseId = value;
+            else if (argument === '--source-case-id')
+                sourceCaseId = value;
+            else if (argument === '--source-fingerprint')
+                sourceFingerprint = value;
+            else if (argument === '--contract-fingerprint')
+                contractFingerprint = value;
+            else if (argument === '--plane') {
+                if (value !== 'web' && value !== 'tui')
+                    throw new Error('--plane must be web or tui');
+                plane = value;
+            }
+            else if (argument === '--profile')
+                profile = value;
+            else if (argument === '--runtime-id')
+                runtimeId = value;
+            else if (argument === '--artifact-sha256')
+                artifactSha256 = value;
+            else if (argument === '--isolation-provider') {
+                if (value !== 'github-actions-hosted-runner' && value !== 'firecracker' && value !== 'other') {
+                    throw new Error('--isolation-provider must be github-actions-hosted-runner, firecracker or other');
+                }
+                isolationProvider = value;
+            }
+            else if (argument === '--timeout') {
+                const parsed = Number(value);
+                if (!Number.isSafeInteger(parsed) || parsed < 30 || parsed > 600)
+                    throw new Error('--timeout must be an integer between 30 and 600 seconds');
+                timeoutSeconds = parsed;
+            }
+            else if (argument === '--report')
+                reportPath = value;
+            else if (argument === '--artifacts')
+                artifactsDirectory = value;
+            else if (argument === '--driver-root')
+                driverRoot = value;
+            else if (argument === '--chromium-executable')
+                chromiumExecutable = value;
+            else
+                allowedBuilds.push(value);
+            index += 1;
+        }
+        else {
+            throw new Error(`unknown option for probe dsh-surface: ${argument}`);
+        }
+    }
+    const required = [
+        ['--dsh-version', dshVersion],
+        ['--case-id', caseId],
+        ['--source-case-id', sourceCaseId],
+        ['--source-fingerprint', sourceFingerprint],
+        ['--contract-fingerprint', contractFingerprint],
+        ['--plane', plane],
+        ['--profile', profile],
+        ['--runtime-id', runtimeId],
+        ['--artifact-sha256', artifactSha256],
+        ['--isolation-provider', isolationProvider],
+    ];
+    const missing = required.find(([, value]) => value === undefined);
+    if (missing !== undefined)
+        throw new Error(`probe dsh-surface requires ${missing[0]}`);
+    if (!execute)
+        throw new Error('probe dsh-surface requires --execute because third-party code may run');
+    if (process.env.UPSTREAM_RADAR_ISOLATED_RUNNER !== '1') {
+        throw new Error('probe dsh-surface requires UPSTREAM_RADAR_ISOLATED_RUNNER=1 in the disposable environment');
+    }
+    const report = await observeDshPluginSurface({
+        packageSpec,
+        dshVersion: dshVersion,
+        caseId: caseId,
+        sourceCaseId: sourceCaseId,
+        sourceFingerprint: sourceFingerprint,
+        contractFingerprint: contractFingerprint,
+        plane: plane,
+        profile: profile,
+        runtimeId: runtimeId,
+        expectedArtifactSha256: artifactSha256,
+        allowedBuilds,
+        allowExecution: true,
+        isolationProvider: isolationProvider,
+        timeoutMs: timeoutSeconds * 1_000,
+        ...(artifactsDirectory === undefined ? {} : { artifactsDirectory }),
+        ...(driverRoot === undefined ? {} : { driverRoot }),
+        ...(chromiumExecutable === undefined ? {} : { chromiumExecutable }),
+    });
+    if (reportPath !== undefined) {
+        const absoluteReportPath = resolve(reportPath);
+        await mkdir(dirname(absoluteReportPath), { recursive: true });
+        // Surface reports are an explicit hand-off from the unprivileged observer
+        // container to the GitHub runner. They contain bounded compatibility
+        // evidence and no inherited secrets, so the runner must be able to read
+        // and upload them even when the container uses a different uid.
+        await writeFile(absoluteReportPath, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o644 });
+    }
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderDshSurfaceObservation(report));
+    return report.result === 'compatible' ? 0 : report.result === 'surface-incompatible' ? 2 : 1;
+}
 async function runDshPluginReview(args) {
     if (args[0] !== 'dsh-plugin')
         throw new Error('review requires dsh-plugin');