upstream-radar 0.43.4 → 0.44.0

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';
@@ -205,7 +206,8 @@ Usage:
     [--report <report.md>] [--dsh-version <v1>,<v2>,...]
     [--reverse-index <index.json>]
     [--dsh-agent-command <executable>]
-    [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending]
+    [--dsh-agent-arg <argument>] [--llm-env-file <path>]
+    [--retry-pending | --retry-pending-only]
     [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>]
     [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>]
     [--ref <branch>] [--json]
@@ -238,6 +240,11 @@ keys; it never writes the key or endpoint to observations.json.
 If a ModelBest-style base URL ends in /llm/v1, a 404 also retries the known
 /llm/openai/v1 path.
 
+--retry-pending-only consumes durable Agent tasks from observations.json
+without reading GitHub/npm, reviewing artifacts, or changing source observation
+points. It requires an Agent or model configuration and fails while any retry
+still remains pending.
+
 The exact npm artifact review is independent of the DSH Agent/model. It runs
 when a meaningful change has a published package, and its dependency findings
 remain in the report even when no model is configured or the model endpoint is
@@ -275,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
@@ -282,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
 
@@ -471,13 +490,14 @@ Usage:
   upstream-radar doctor [config.json] [options]
   upstream-radar scan <directory-or-github-url> [--json] [--fail-on <warn|review|block|never>]
   upstream-radar inspect [npm:]<package>@<exact-version> [--deep] [--json] [--fail-on <warn|review|block|never>]
-  upstream-radar observe <targets.yml|github-url> [--state <observations.json>] [--report <report.md>] [--dsh-version <v1>,<v2>,...] [--reverse-index <index.json>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>] [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>] [--ref <branch>] [--json]
+  upstream-radar observe <targets.yml|github-url> [--state <observations.json>] [--report <report.md>] [--dsh-version <v1>,<v2>,...] [--reverse-index <index.json>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending | --retry-pending-only] [--ecosystem <dsh|codex|pi>] [--id <id>] [--package <name>] [--package-path <path>] [--lockfile <path>] [--lockfile-type <npm|pnpm>] [--ref <branch>] [--json]
   upstream-radar graph <npm-lock|pnpm-lock> <lockfile> [--root <package>@<exact-version>] [--json]
   upstream-radar graph reverse <reports-directory> [--package <name>@<exact-version>] [--output <index.json>] [--json]
   upstream-radar profile-check [profile-directory] [--patch <path>] [--report <path>] [--summary] [--json]
   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]
@@ -1214,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`);
@@ -1366,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');
@@ -1852,6 +2012,7 @@ async function runObserve(args) {
     let reverseIndexPath;
     let registry;
     let retryPending = false;
+    let retryPendingOnly = false;
     let json = false;
     let inlineEcosystem;
     let inlineId;
@@ -1870,6 +2031,9 @@ async function runObserve(args) {
         else if (argument === '--retry-pending') {
             retryPending = true;
         }
+        else if (argument === '--retry-pending-only') {
+            retryPendingOnly = true;
+        }
         else if (argument === '--ecosystem' || argument === '--id' || argument === '--package' || argument === '--package-path' || argument === '--lockfile' || argument === '--lockfile-type' || argument === '--ref' || argument === '--dsh-version' || argument === '--state' || argument === '--report' || argument === '--reverse-index' || argument === '--dsh-agent-command' || argument === '--dsh-agent-arg' || argument === '--llm-env-file' || argument === '--registry') {
             const value = args[index + 1];
             if (value === undefined || (value.startsWith('-') && argument !== '--dsh-agent-arg'))
@@ -1959,10 +2123,17 @@ async function runObserve(args) {
     if (agentCommand !== undefined && llmEnvFile !== undefined) {
         throw new Error('observe accepts either --dsh-agent-command or --llm-env-file, not both');
     }
+    if (retryPending && retryPendingOnly) {
+        throw new Error('observe accepts either --retry-pending or --retry-pending-only, not both');
+    }
+    if (retryPendingOnly && agentCommand === undefined && llmEnvFile === undefined) {
+        throw new Error('--retry-pending-only requires --dsh-agent-command or --llm-env-file');
+    }
     const result = await runObserver(config, previousState, {
         source,
         ...(reverseDependencyIndex === undefined ? {} : { reverseDependencyIndex }),
         retryPending,
+        retryPendingOnly,
         artifactReviewer: async (spec, target) => reviewObserverArtifact(spec, target, registry),
         ...(agentOptions === undefined ? {} : {
             agent: (task, prompt) => runDshAgentCommand(task, prompt, agentOptions),
@@ -1978,10 +2149,11 @@ async function runObserve(args) {
     }
     process.stdout.write(json ? reportJson : renderObserverReport(result.report));
     const observerExit = observerExitCode(result.report);
+    const pendingRetryExit = retryPendingOnly && result.report.pendingTasks.length > 0 ? 1 : 0;
     if (result.report.agent.failed > 0) {
-        process.stderr.write('upstream-radar: static observation completed; DSH Agent/model analysis remains pending. See the report and rerun with --retry-pending.\n');
+        process.stderr.write(`upstream-radar: DSH Agent/model analysis remains pending. See the report and rerun with ${retryPendingOnly ? '--retry-pending-only' : '--retry-pending'}.\n`);
     }
-    return observerExit;
+    return observerExit === 0 && pendingRetryExit === 0 ? 0 : 1;
 }
 async function runQuickstart(args) {
     let directory = process.cwd();