upstream-radar 0.33.0 → 0.33.2

package/README.md

@@ -29,6 +29,7 @@
   <a href="#see-one-incident">See one incident</a> ·
   <a href="#install-in-dsh">Install in DSH</a> ·
   <a href="#notify-feishu-or-an-https-endpoint">Notify Feishu</a> ·
+  <a href="#observe-dsh-plugin-upstream-changes">Observe upstream changes</a> ·
   <a href="#run-the-proof">Run the proof</a> ·
   <a href="#run-it-in-github-actions">Run in GitHub Actions</a> ·
   <a href="https://github.com/MicroMilo/upstream-radar/issues/new?template=trial.yml">Share feedback</a> ·
@@ -51,10 +52,12 @@ It looks only at the current directory and local DSH profile metadata. It recomm
 | Your goal | Start here | What you get |
 | --- | --- | --- |
 | Keep a live DSH Agent informed | [`setup`](#install-in-dsh) | A profile-aware monitor that refreshes the installed graph and routes only changed incidents to the matching Agent. |
+| Observe DSH plugin upstream changes | [`observe`](#observe-dsh-plugin-upstream-changes) | A scheduled old → new comparison of GitHub commits, npm releases, manifests, and optional lockfile graphs; only meaningful changes wake an Agent. |
 | Respond to the first alert | [`radar next`](#install-in-dsh) | One read-only command selects the highest-priority incident and points to the DSH task, verified analysis, or next check. |
+| Check a DSH profile before starting it | [`profile-check`](#check-a-dsh-profile-before-starting-it) | Reads the actual lockfile and patch rows and blocks missing loader packages, duplicate loader ids, and release-age rollback risk. |
 | Add a scheduled CI gate | [GitHub Actions example](examples/github-actions/upstream-radar.yml) | A frozen check from a reviewed config or one lockfile, with a concise Job Summary and a machine-readable JSON report. |
 | Check a plugin before installing it | [`graph` / `init` for npm or pnpm lockfiles](#inspect-an-npm-or-pnpm-lockfile-before-installation) | Exact dependency paths and OSV/GitHub Advisory results without running the plugin or its lifecycle scripts. |
-| Review one exact published artifact | `upstream-radar inspect npm:<package>@<exact-version> --deep` | Package, dependency, vulnerability, and provenance evidence for one release. |
+| Review one exact published artifact | `upstream-radar inspect <package>@<exact-version> --deep` | Package, dependency, vulnerability, and provenance evidence for one release. |
 | Publish and maintain a DSH plugin | [Plugin author path](#for-dsh-plugin-authors) | Start from a real DSH scaffold, review its locked graph, and add a two-step CI gate before users install it. |
 | Send changed events to Feishu | [Feishu or HTTPS webhook](#notify-feishu-or-an-https-endpoint) | Native Feishu V2 text, environment-only secrets, durable acknowledgement, and retry. |
 
@@ -84,6 +87,28 @@ Next: Review the fixed version with the DSH Agent in this project.
 
 The useful part is the exact path and project-specific next step—not another generic list of vulnerable package names.
 
+Want to try it on a real published DSH plugin immediately?
+
+```bash
+npx --yes upstream-radar@0.33.2 inspect dsh-feishu-bot@0.15.4 --deep
+```
+
+This runs from an otherwise empty directory and returns a short admission,
+coverage, dependency-count, vulnerability-count, and next-step summary.
+
+Want to see a real author-actionable result? This exact published DSH plugin
+currently cannot produce a complete dependency graph in a clean npm resolver:
+
+```bash
+npx --yes upstream-radar@0.33.2 inspect \
+  @sanqi-normal/dsh-webui-market-plugin@0.5.4 \
+  --deep --fail-on never
+```
+
+The result is `review / incomplete`, with the concrete cause
+`@deepseek-ai/dsh-compact@^0.0.1-rc.1` not published. No DSH profile, plugin
+execution, or LLM is required. See the [reproducible author report](examples/dsh/reports/sanqi-market-plugin-dependency-resolution.md).
+
 Tried the demo or a real DSH setup? [Share a short trial result](https://github.com/MicroMilo/upstream-radar/issues/new?template=trial.yml) with the versions, path, and redacted outcome. Never include source code, secrets, or private paths.
 
 Every command has its own short guide: `npx --yes upstream-radar@latest setup --help`, `npx --yes upstream-radar@latest inspect --help`, and `npx --yes upstream-radar@latest radar status --help` are useful starting points when you are not sure which path to choose.
@@ -144,6 +169,177 @@ pnpm dlx --package=upstream-radar@latest upstream-radar radar watch ./upstream-r
 
 Remove `--once` to keep a local monitor alive. This is a lightweight CLI surface for demos, CI, and diagnosis; the native DSH bundle remains the recommended always-on path because it can deliver the task to a live Agent.
 
+## Check a DSH profile before starting it
+
+When the concern is “will this profile boot with the packages and patch rows it
+actually has?”, use the static profile check first:
+
+```bash
+pnpm run build
+node dist/src/cli.js profile-check "$DSH_HOME/profiles/web" \
+  --report ./dsh-profile-check.md
+```
+
+For the shortest answer, add `--summary`:
+
+```bash
+pnpm dlx --package=upstream-radar@latest upstream-radar profile-check \
+  "$DSH_HOME/profiles/web" --summary
+```
+
+When `DSH_HOME` contains exactly one profile with third-party bundles, the
+directory can be omitted:
+
+```bash
+npx --yes upstream-radar@latest profile-check --summary
+```
+
+With no eligible profile, or more than one, Radar prints the names it found and
+asks for an explicit directory; it never guesses between multiple profiles.
+
+It prints only the status, the important evidence, the reason, and the next
+repair. The exit code remains `2` for a blocked profile and `0` for a pass.
+
+It reads the profile manifest, pnpm/npm lockfile, package metadata,
+`pnpm-workspace.yaml`, and `cordis.patch.yml`. It catches the two concrete
+failure shapes from [dsh-web-ui #71](https://github.com/zhu1090093659/dsh-web-ui/issues/71)
+and [#35](https://github.com/zhu1090093659/dsh-web-ui/issues/35): a loader row
+that names a package absent from the locked profile, and the same loader id
+being inserted twice. It also points out a pnpm `minimumReleaseAge` policy that
+does not exempt the plugin, because that can keep a newly fixed plugin on an
+older release during its cooling window.
+
+This is deliberately a pre-start check: no network, installation, plugin code,
+DSH process, Agent, or LLM is involved. A blocked result exits with code `2`.
+The complete replay is `pnpm run showcase:dsh-profile-check`; it runs the
+public case before the fix, after the manual package workaround, and after the
+correct bundled-carrier fix.
+
+The short, author-facing result is `pnpm run showcase:dsh-case`. It turns the
+same three static checks into one repair story: the old profile is blocked,
+manually adding the missing package creates a duplicate loader, and the
+bundled-carrier update reaches `pass`. If an OpenAI-compatible `issue-locator`
+model is available, pass its env file with
+`ISSUE_LOCATOR_ENV_FILE=/path/to/issue-locator/.env`; the model only explains
+the already-checked facts. If the endpoint is unavailable, the command still
+prints the deterministic evidence explanation and records that the fallback was
+used. Add `:report` to write the [case analysis result](examples/dsh/reports/dsh-web-ui-issue-71-analysis.json).
+
+We also ran the current static checks against the first 50 entries in the DSH
+plugin registry. That batch found **0 confirmed runtime dependency
+vulnerabilities**. It did find real monitoring-quality problems—development-only
+dependencies mixed into source lockfiles, three plugin lockfiles whose root
+version lagged the source manifest, and a tarball format the scanner could not
+parse. The [batch report](examples/dsh/reports/dsh-batch-50-2026-08-17.md)
+keeps those results honest; it is not marketed as a vulnerability hit list.
+
+## Observe DSH plugin upstream changes
+
+This is the upstream-change loop: instead of polling every vulnerability source on
+every run, Radar remembers one observation point per plugin and asks what changed
+since then.
+
+```text
+targets.yml
+  ↓
+GitHub commit + npm package metadata + optional lockfile
+  ↓
+observations.json
+  ↓
+old → new comparison
+  ↓
+only meaningful changes → DSH Agent task → report
+```
+
+Start from the [copyable target example](examples/upstream-observer/targets.yml):
+
+```yaml
+schema: upstream-radar.observer-targets/v1alpha1
+targets:
+  - id: my-dsh-plugin
+    ecosystem: dsh
+    repository: acme/my-dsh-plugin
+    ref: main
+    package: my-dsh-plugin
+    packagePath: plugin/package.json
+    lockfile: plugin/pnpm-lock.yaml
+    lockfileType: pnpm
+```
+
+Then run one cycle:
+
+```bash
+export GITHUB_TOKEN='a read-only GitHub token'
+npx --yes upstream-radar@0.33.2 observe \
+  ./targets.yml \
+  --state ./observations.json \
+  --report ./upstream-radar-observer.md
+```
+
+This uses the published CLI; pin the exact version in CI rather than relying on
+`latest`. The first cycle only creates a baseline. Later cycles compare:
+
+- the source commit and changed files;
+- the published npm version and integrity value;
+- the package entrypoint, exports, Node requirement, DSH bundle metadata and dependency declarations;
+- the real npm or pnpm lockfile graph, when a lockfile is configured.
+
+README/docs/tests-only changes advance the observation point without waking the
+Agent. Runtime source, DSH bundle, package entry, dependency graph, npm version,
+or npm integrity changes create an old → new task. If the Agent is not configured,
+the task stays in `observations.json`; no plugin is installed or executed.
+
+If you do not have a DSH wrapper configured yet, you can point the observer at
+an existing issue-locator/OpenAI-compatible `.env` file instead:
+
+```bash
+upstream-radar observe ./targets.yml \
+  --state ./observations.json \
+  --llm-env-file /path/to/issue-locator/.env
+```
+
+Radar reads only the endpoint, API key, and model name for that call. It never
+writes the key or endpoint into the observation state or report. The model is
+called only after a meaningful upstream change; a baseline or docs-only change
+does not call it. If the endpoint is unavailable, the deterministic change
+record remains pending and can be retried with `--retry-pending`.
+
+The env file may use the issue-locator names (`ISSUE_LOCATOR_LLM_*`), the common
+OpenAI names (`OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL`), or `MODEL` /
+`CODEX_MODEL` for the model name.
+For ModelBest-style URLs, a 404 on `/llm/v1` also retries `/llm/openai/v1`.
+
+The scheduled workflow is [examples/github-actions/upstream-observer.yml](examples/github-actions/upstream-observer.yml).
+The checked-in workflow is a dogfood workflow for this repository: it checks out
+and builds Radar before running the observer. It persists only the observation
+point. A quiet run does not create a daily commit.
+
+The workflow also supports three optional repository secrets—
+`ISSUE_LOCATOR_LLM_BASE_URL`, `ISSUE_LOCATOR_LLM_API_KEY`, and
+`ISSUE_LOCATOR_LLM_MODEL`. When all three exist, the job sends meaningful tasks
+to the issue-locator/OpenAI-compatible model. When they do not exist, static
+upstream observation still runs and the job does not pretend that model analysis
+was performed.
+
+### The DSH Agent boundary
+
+The observer accepts an explicit executable through `--dsh-agent-command`. It
+writes one bounded, read-only task prompt to stdin and expects one JSON conclusion
+on stdout. The command is started without a shell, and the prompt treats every
+remote repository string and release field as untrusted evidence.
+
+```bash
+upstream-radar observe ./targets.yml \
+  --state ./observations.json \
+  --dsh-agent-command /path/to/reviewed-dsh-agent-wrapper \
+  --dsh-agent-arg --json
+```
+
+Radar does not guess an undocumented `dsh` CLI subcommand. A reviewed DSH
+headless wrapper is the integration boundary; this keeps the observer usable in
+GitHub Actions and lets the DSH adapter evolve without changing observation or
+diff logic. Use `--retry-pending` to deliver tasks left by a previous run.
+
 ## Notify Feishu or an HTTPS endpoint
 
 To also notify a team-owned HTTPS endpoint when an incident changes, keep the endpoint outside the reviewed config and state:
@@ -322,7 +518,7 @@ cd my-dsh-plugin
 pnpm install --ignore-scripts
 
 # Read the exact graph before adding the plugin to a DSH profile.
-pnpm dlx --package=upstream-radar@0.33.0 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
+pnpm dlx --package=upstream-radar@0.33.2 upstream-radar graph pnpm-lock pnpm-lock.yaml --json
 ```
 
 The graph includes the exact DSH package versions and keeps unresolved optional peers visible. It does not load the generated plugin or run lifecycle scripts. After reviewing it, copy this complete workflow into `.github/workflows/upstream-radar.yml`:
@@ -344,7 +540,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: MicroMilo/upstream-radar@v0.33.0
+      - uses: MicroMilo/upstream-radar@v0.33.2
         with:
           fail-on: high
           fail-on-compatibility: breaking
@@ -352,6 +548,22 @@ jobs:
 
 The Action auto-detects the one `pnpm-lock.yaml`, checks the same exact graph, and writes the result to the Job Summary. This is a pre-install and CI gate; it does not install the plugin into DSH. After the graph is reviewed, use the normal `dsh plugin` flow to install it and `upstream-radar setup` to start project-aware monitoring.
 
+To check a real published DSH artifact directly, run one command:
+
+```bash
+npx --yes upstream-radar@0.33.2 inspect dsh-feishu-bot@0.15.4 --deep
+```
+
+The checked result is `REVIEW`: registry integrity, signature, provenance, and
+89 resolved packages are verified; known vulnerabilities are `0`, while 12
+optional dependency edges remain unresolved. That is a useful author result:
+the empty vulnerability list is visible, but it is not mislabeled as a full
+`ALLOW` decision.
+
+The same exact tarball loads in both DSH `0.1.0-rc.6` and `0.1.0-rc.7` disposable
+profiles. See the [real compatibility probe](examples/dsh/reports/dsh-feishu-bot-0.15.4-probe.md)
+for the command and boundary.
+
 ## See one incident
 
 If an advisory affects only one of two installed `parser` versions, Radar reports the path that actually matched:
@@ -483,7 +695,11 @@ To demonstrate the host-runtime dependency path specifically, run `pnpm run show
 
 To see why one shared host bug should not page every plugin separately, run `pnpm run showcase:dsh-host-alert`. Two plugin roots share the same exact `@deepseek-ai/cordis` version; Radar emits one project event, keeps both exact paths, and creates one DSH analysis task. Add `:report` to refresh the checked-in [deduplication result](examples/dsh/reports/dsh-host-alert-dedup.json).
 
-To validate the actual first-use path against the real published [`dsh-cloudflare-browser-run@0.1.1`](https://www.npmjs.com/package/dsh-cloudflare-browser-run), run `pnpm run showcase:dsh-adoption`. It creates a disposable `DSH_HOME`, packs the exact Radar and plugin tarballs with lifecycle scripts disabled, lets DSH build its own host runtime, runs `setup --no-install`, `doctor`, a frozen OSV/npm/GitHub check, and the human-readable status surface. It does not start a DSH Agent or call a model, and it does not treat an empty finding list as a safety certificate. The checked-in [adoption result](examples/dsh/reports/adoption-smoke.json) records the last run's package counts and boundaries.
+To validate the actual first-use path against several real published DSH plugins, run `pnpm run showcase:dsh-adoption`. It creates a disposable `DSH_HOME`, packs exact Radar and plugin tarballs with lifecycle scripts disabled, lets DSH build its own host runtime, runs `setup --no-install`, `doctor`, a frozen OSV/npm/GitHub check, and the human-readable status surface. The checked-in trial covers [`dsh-cloudflare-browser-run@0.1.1`](https://www.npmjs.com/package/dsh-cloudflare-browser-run), [`@open-agfs/dsh-agfs@0.1.9`](https://www.npmjs.com/package/@open-agfs/dsh-agfs), and [`dsh-feishu-bot@0.14.0`](https://www.npmjs.com/package/dsh-feishu-bot). The first two install and become monitorable; the Feishu bridge is intentionally recorded as blocked because a clean DSH profile stops on its transitive `protobufjs` build script until a human approves it. A blocked install is not reported as a clean security result. The showcase does not start a DSH Agent or call a model; the separate `try:dsh` proof covers that handoff. The checked-in [adoption result](examples/dsh/reports/adoption-smoke.json) records each plugin's install state, graph coverage, source health, and boundary.
+
+The DSH Agent handoff is optional for dependency analysis. If you want to smoke-test that integration with a real published plugin, run `pnpm run try:dsh:real`. It installs the exact published `dsh-find-plugin@0.3.6` into a disposable headless profile and proves that a real DSH Agent receives, consumes, and writes back a Radar analysis task. The model is still a local deterministic stub; no plugin business action or paid endpoint is called. Set `DSH_REAL_PLUGINS` to another exact package only after checking its required profile and credentials.
+
+For a public compatibility case, run `pnpm run try:dsh:public-case`. It replays [`dsh-web-ui #35`](https://github.com/zhu1090093659/dsh-web-ui/issues/35) and [`#71`](https://github.com/zhu1090093659/dsh-web-ui/issues/71): the old profile is blocked by a missing loader, the manual package workaround is blocked by a duplicate loader id, and the maintainer's bundled-carrier fix passes. The same compatibility event is then admitted to a real DSH `headless` session and written back as one verified `analysisResult`; see the checked-in [case result](examples/dsh/reports/dsh-web-ui-public-case.json). This is an end-to-end delivery proof with a local deterministic model stub, not a claim about online model quality. The command does not use your DSH credentials or call a paid model endpoint.
 
 To see the two-source vulnerability contract without contacting the network, run `pnpm run showcase:github-advisories`. It feeds the same parser issue through OSV and a deterministic GitHub Advisory Database client, proves that two reports become one Radar incident with explicit source provenance and a visible fixed-version conflict, then simulates three GitHub failures and recovery. The existing vulnerability remains active throughout; only the GitHub source-health incident changes.
 
@@ -492,7 +708,7 @@ To see the two-source vulnerability contract without contacting the network, run
 Before wiring a project into a compatibility gate, run the offline rule benchmark:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.33.0 upstream-radar benchmark compatibility
+pnpm dlx --package=upstream-radar@0.33.2 upstream-radar benchmark compatibility
 ```
 
 It covers six contracts: a safe patch, a change that only needs project analysis, an incompatible DSH peer, a publisher-declared breaking release, a vulnerable candidate dependency, and an incomplete candidate graph. The command does not access the network, install a package, load a plugin, or start DSH. It checks the behavior of Radar's deterministic rules and the `breaking`/`any` gates; it is not a runtime compatibility proof.
@@ -505,7 +721,7 @@ When you have an exact plugin artifact and want to know whether one exact DSH re
 # Pack an exact npm release without running its lifecycle scripts.
 npm pack --ignore-scripts dsh-plugin@1.2.3
 
-pnpm dlx --package=upstream-radar@0.33.0 upstream-radar probe dsh-load \
+pnpm dlx --package=upstream-radar@0.33.2 upstream-radar probe dsh-load \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.6
 ```
@@ -531,7 +747,7 @@ It exercises a loadable bundle, a bundle patch DSH rejects, and a package that r
 To compare a plugin against more than one DSH release, use the matrix form:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.33.0 upstream-radar probe dsh-matrix \
+pnpm dlx --package=upstream-radar@0.33.2 upstream-radar probe dsh-matrix \
   ./dsh-plugin-1.2.3.tgz \
   --dsh-version 0.1.0-rc.3 \
   --dsh-version 0.1.0-rc.6 \
@@ -547,7 +763,7 @@ If your team wants the shortest scheduled CI gate before wiring a machine to a l
 ```yaml
 steps:
   - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-  - uses: MicroMilo/upstream-radar@v0.33.0
+  - uses: MicroMilo/upstream-radar@v0.33.2
     with:
       fail-on: high
       # Optional: also fail on deterministic DSH/plugin compatibility breaks.
@@ -556,12 +772,12 @@ steps:
       threat-intel: true
 ```
 
-The Action is a thin wrapper around `radar check --frozen --state :memory: --fail-on high --json`; when the optional compatibility input is enabled, it also passes `--fail-on-compatibility breaking` or `any`. `--frozen` is deliberate: it uses the graph in the reviewed config and does not try to read a developer's local DSH profile. `threat-intel` is false by default so an ordinary CI gate stays lean; set it to `true` when the Job Summary and raw JSON should include CISA KEV and FIRST EPSS prioritization evidence. Each run is independent, exits `2` when an active vulnerability or opted-in compatibility change meets its threshold, and exits `1` for an operational or source error. `breaking` catches confirmed or strong incompatibility signals; `any` catches every active compatibility event. The default is `never`, so vulnerability-only behavior stays unchanged. In addition to the raw JSON log, the Action writes a short escaped summary to the GitHub Job Summary so a scheduled failure immediately shows the affected package, exact path, published fix version when available, one-line priority evidence, and a suggested next step. The Action does not deliver a DSH Agent task or modify a branch; the native DSH bundle remains the always-on analysis path. Pin the Action to a release tag such as `v0.33.0`, and pin the checkout Action in your workflow according to your repository's policy.
+The Action is a thin wrapper around `radar check --frozen --state :memory: --fail-on high --json`; when the optional compatibility input is enabled, it also passes `--fail-on-compatibility breaking` or `any`. `--frozen` is deliberate: it uses the graph in the reviewed config and does not try to read a developer's local DSH profile. `threat-intel` is false by default so an ordinary CI gate stays lean; set it to `true` when the Job Summary and raw JSON should include CISA KEV and FIRST EPSS prioritization evidence. Each run is independent, exits `2` when an active vulnerability or opted-in compatibility change meets its threshold, and exits `1` for an operational or source error. `breaking` catches confirmed or strong incompatibility signals; `any` catches every active compatibility event. The default is `never`, so vulnerability-only behavior stays unchanged. In addition to the raw JSON log, the Action writes a short escaped summary to the GitHub Job Summary so a scheduled failure immediately shows the affected package, exact path, published fix version when available, one-line priority evidence, and a suggested next step. The Action does not deliver a DSH Agent task or modify a branch; the native DSH bundle remains the always-on analysis path. Pin the Action to a release tag such as `v0.33.2`, and pin the checkout Action in your workflow according to your repository's policy.
 
 If the repository has no committed Radar config yet, the smallest setup is to omit `config`, `pnpm-lock`, and `npm-lock`. After checkout, the Action automatically uses the only one of `pnpm-lock.yaml` or `package-lock.json` that exists, generates a temporary reviewed config, and runs the same frozen check:
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.0
+- uses: MicroMilo/upstream-radar@v0.33.2
   with:
     fail-on: high
 ```
@@ -571,7 +787,7 @@ An existing `config` wins over auto-detection. If both lockfiles exist, or neith
 To review the exact plugin artifact before it enters DSH, add `inspect-package`:
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.0
+- uses: MicroMilo/upstream-radar@v0.33.2
   with:
     inspect-package: dsh-cloudflare-browser-run@0.1.1
     # review is the safe default; use block only when incomplete coverage may pass.
@@ -583,7 +799,7 @@ This downloads that exact npm tarball, verifies the registry integrity/signature
 If the repository has a pnpm lockfile but no committed Radar config yet, the Action can generate the config in the same job. See the [copyable pnpm workflow](examples/github-actions/upstream-radar-pnpm.yml):
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.0
+- uses: MicroMilo/upstream-radar@v0.33.2
   with:
     pnpm-lock: pnpm-lock.yaml
     fail-on: high
@@ -597,7 +813,7 @@ See the [copyable npm workflow](examples/github-actions/upstream-radar-npm.yml)
 The Action requires the caller to check out the repository first. It does not install the project's dependencies or run their lifecycle scripts; it only reads the committed graph and queries the configured upstream sources. For a fully explicit, lower-level invocation, the equivalent command is:
 
 ```bash
-pnpm dlx --package=upstream-radar@0.33.0 upstream-radar radar check \
+pnpm dlx --package=upstream-radar@0.33.2 upstream-radar radar check \
   ./upstream-radar.config.json --frozen --state :memory: --fail-on high \
   --fail-on-compatibility breaking --json
 ```
@@ -605,7 +821,7 @@ pnpm dlx --package=upstream-radar@0.33.0 upstream-radar radar check \
 To add the optional DSH load matrix for a published plugin, provide an exact npm package and at least two exact DSH versions:
 
 ```yaml
-- uses: MicroMilo/upstream-radar@v0.33.0
+- uses: MicroMilo/upstream-radar@v0.33.2
   id: radar
   with:
     config: upstream-radar.config.json
@@ -749,7 +965,7 @@ The bounded pre-install scanner remains available as a supporting collector:
 
 ```bash
 pnpm dlx --package=upstream-radar@latest upstream-radar scan /path/to/dsh-plugin
-pnpm dlx --package=upstream-radar@latest upstream-radar inspect npm:dsh-cloudflare-browser-run@0.1.1 --deep
+pnpm dlx --package=upstream-radar@latest upstream-radar inspect dsh-cloudflare-browser-run@0.1.1 --deep
 ```
 
 The default text gate exits `2` for `review` or `block`, which is useful when every uncertainty needs a human decision. If CI should fail only on hard blocks while still printing review evidence, add `--fail-on block`.

package/dist/src/cli.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
-import { access, readFile } from 'node:fs/promises';
+import { access, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
 import { renderCompatibilityBenchmark, runCompatibilityBenchmark } from './compatibility-benchmark.js';
 import { assessCompatibilityChange } from './compatibility.js';
 import { probeDshLoad, probeDshLoadMatrix, renderDshLoadMatrix, renderDshLoadProbe } from './dsh-probe.js';
 import { createAnalysisTask, renderAgentAnalysisPrompt } from './dsh-analysis.js';
 import { createDoctorReport, renderDoctorReport } from './doctor.js';
+import { checkDshProfile, renderDshProfileCheck, renderDshProfileCheckSummary } from './dsh-profile-check.js';
 import { createDemoReport, renderDemo } from './demo.js';
 import { GitHubReleaseClient } from './github-release.js';
 import { parseNpmLockGraph, parsePnpmLockGraph } from './graph.js';
@@ -30,6 +31,7 @@ import { createRadarNext, createRadarStatus, renderRadarNext, renderRadarStatus
 import { renderTextReport } from './render.js';
 import { scanDirectory } from './scan.js';
 import { CisaKevClient, EpssClient } from './threat-intel.js';
+import { loadObservationState, parseObserverConfigText, renderObserverReport, runDshAgentCommand, runOpenAiCompatibleAgent, runObserver, saveObservationState, UpstreamObserverClient, } from './upstream-observer.js';
 import { TOOL_VERSION } from './version.js';
 import { eventsForRadarWebhookTarget, markRadarWebhookEventsDelivered, markRadarWebhookEventsDeliveredForRoute, normalizeRadarWebhookUrl, queueRadarWebhookEvents, queueRadarWebhookEventsForRoute, resolveRadarWebhookTargets, sendRadarWebhook, undeliveredRadarWebhookEvents, undeliveredRadarWebhookEventsForRoute, } from './webhook.js';
 const VALID_THRESHOLDS = new Set(['warn', 'review', 'block', 'never']);
@@ -177,7 +179,7 @@ are recorded as bounded evidence.
         inspect: `Upstream Radar — inspect one exact npm artifact before installation
 
 Usage:
-  upstream-radar inspect npm:<package>@<exact-version> [--deep] [--json]
+  upstream-radar inspect [npm:]<package>@<exact-version> [--deep] [--json]
     [--registry <https-url>] [--fail-on <warn|review|block|never>]
 
 --deep downloads the exact tarball, verifies npm integrity/signatures and
@@ -186,6 +188,26 @@ and queries the implemented vulnerability checks. An empty finding list is not
 a safety certificate; check the coverage verdict before admitting the package.
 The default gate exits 2 for review or block; use --fail-on block when review
 should remain visible without failing CI.
+`,
+        observe: `Upstream Radar — watch DSH plugin repositories and packages for meaningful upstream changes
+
+Usage:
+  upstream-radar observe <targets.yml> [--state <observations.json>]
+    [--report <report.md>] [--dsh-agent-command <executable>]
+    [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--json]
+
+The first run creates a baseline. Later runs compare source commits, published
+npm metadata, package manifests, and an optional npm/pnpm dependency graph. A
+DSH Agent is called only for meaningful changes. Safety: does not install packages, run lifecycle scripts, load plugin code, or invoke a shell.
+
+The Agent executable receives one read-only task prompt on stdin and should
+return one JSON conclusion on stdout. If it is not configured, the task stays
+in observations.json for a later explicit retry. As a simpler alternative,
+--llm-env-file reads an OpenAI-compatible issue-locator/.env-style file for
+only the model call. It accepts ISSUE_LOCATOR_LLM_*, OPENAI_*, or MODEL/CODEX_MODEL
+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.
 `,
         graph: `Upstream Radar — read a lockfile into the canonical dependency graph
 
@@ -195,6 +217,18 @@ Usage:
 
 This command is offline and does not install packages, run lifecycle scripts,
 load plugin code, or query vulnerability sources.
+`,
+        'profile-check': `Upstream Radar — check one DSH profile before starting it
+
+Usage:
+  upstream-radar profile-check [profile-directory] [--patch <path>] [--report <path>] [--summary] [--json]
+
+Reads the profile package manifest, lockfile, node_modules package metadata,
+pnpm release-age policy, and cordis.patch.yml. It reports loader rows that
+refer to missing packages and duplicate loader ids. It never installs packages,
+starts DSH, loads plugin code, contacts a vulnerability source, or invokes a
+DSH Agent/model. When the directory is omitted, the only DSH profile with
+third-party bundles is selected automatically.
 `,
         probe: `Upstream Radar — test whether a DSH bundle loads in disposable profiles
 
@@ -370,8 +404,10 @@ Usage:
   upstream-radar init --npm-lock <package-lock.json> [--root <package>@<exact-version>] [options]
   upstream-radar doctor [config.json] [options]
   upstream-radar scan <directory> [--json] [--fail-on <warn|review|block|never>]
-  upstream-radar inspect npm:<package>@<exact-version> [--deep] [--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> [--state <observations.json>] [--report <report.md>] [--dsh-agent-command <executable>] [--dsh-agent-arg <argument>] [--llm-env-file <path>] [--retry-pending] [--json]
   upstream-radar graph <npm-lock|pnpm-lock> <lockfile> [--root <package>@<exact-version>] [--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 demo [--json]
@@ -399,7 +435,9 @@ Commands:
   doctor   check local Radar/DSH wiring without polling upstream sources
   scan     bounded, read-only inspection of a local package directory
   inspect  fetch and verify the exact npm artifact before inspecting its contents
+  observe  compare upstream DSH plugin repositories and route only meaningful changes to a DSH Agent
   graph    read a lockfile into the canonical dependency graph without installing packages
+  profile-check  check a DSH profile's lockfile and patch rows without starting DSH
   probe    run a bounded DSH bundle-load check or version matrix in disposable profiles
   demo     show the exact-path-to-DSH handoff without network, DSH, or plugin installation
   quickstart choose the smallest first-use path without changing the environment
@@ -533,6 +571,57 @@ async function runGraph(args) {
     ].join('\n') + '\n');
     return 0;
 }
+async function runDshProfileCheck(args) {
+    let profileDirectory;
+    let firstOption = 0;
+    if (args[0] !== undefined && !args[0].startsWith('-')) {
+        profileDirectory = args[0];
+        firstOption = 1;
+    }
+    let json = false;
+    let summary = false;
+    let reportPath;
+    let patchPath;
+    for (let index = firstOption; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+        }
+        else if (argument === '--summary') {
+            summary = true;
+        }
+        else if (argument === '--patch' || argument === '--report') {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error(`${argument} requires a value`);
+            if (argument === '--patch')
+                patchPath = value;
+            else
+                reportPath = value;
+            index += 1;
+        }
+        else {
+            throw new Error(`unknown option for profile-check: ${argument}`);
+        }
+    }
+    if (profileDirectory === undefined) {
+        const profiles = await discoverDshProfiles();
+        if (profiles.length === 0) {
+            throw new Error('profile-check could not find a DSH profile with third-party bundles; pass <profile-directory> explicitly');
+        }
+        if (profiles.length > 1) {
+            throw new Error(`profile-check found multiple DSH profiles with third-party bundles (${profiles.join(', ')}); pass <profile-directory> explicitly`);
+        }
+        profileDirectory = resolveDshProfileDirectory(profiles[0]);
+    }
+    const report = await checkDshProfile({ profileDirectory, ...(patchPath === undefined ? {} : { patchFile: patchPath }) });
+    const jsonText = `${JSON.stringify(report, null, 2)}\n`;
+    if (reportPath !== undefined) {
+        await writeFile(resolve(reportPath), reportPath.endsWith('.json') ? jsonText : summary ? renderDshProfileCheckSummary(report) : renderDshProfileCheck(report));
+    }
+    process.stdout.write(json ? jsonText : summary ? renderDshProfileCheckSummary(report) : renderDshProfileCheck(report));
+    return report.status === 'blocked' ? 2 : 0;
+}
 async function runTask(args) {
     const subcommand = args[0];
     if (subcommand !== 'list' && subcommand !== 'show' && subcommand !== 'ack') {
@@ -1303,6 +1392,85 @@ async function runRadar(args) {
         : `${renderRadarEvents(events)}Prepared ${analysisTasks.length} DSH compatibility analysis task(s).\n`);
     return 0;
 }
+async function runObserve(args) {
+    const targetsPath = args[0];
+    if (targetsPath === undefined || targetsPath.startsWith('-'))
+        throw new Error('observe requires a targets.yml file');
+    let statePath = 'observations.json';
+    let reportPath;
+    let agentCommand;
+    let agentArgs = [];
+    let llmEnvFile;
+    let registry;
+    let retryPending = false;
+    let json = false;
+    for (let index = 1; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+        }
+        else if (argument === '--retry-pending') {
+            retryPending = true;
+        }
+        else if (argument === '--state' || argument === '--report' || 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'))
+                throw new Error(`${argument} requires a value`);
+            if (argument === '--state')
+                statePath = value;
+            else if (argument === '--report')
+                reportPath = value;
+            else if (argument === '--dsh-agent-command')
+                agentCommand = value;
+            else if (argument === '--dsh-agent-arg')
+                agentArgs.push(value);
+            else if (argument === '--llm-env-file')
+                llmEnvFile = value;
+            else
+                registry = value;
+            index += 1;
+        }
+        else {
+            throw new Error(`unknown option for observe: ${argument}`);
+        }
+    }
+    const targetText = await readBoundedFile(targetsPath, 256 * 1024);
+    const config = parseObserverConfigText(targetText);
+    const previousState = await loadObservationState(statePath);
+    const source = new UpstreamObserverClient({
+        ...(process.env.GITHUB_TOKEN === undefined ? {} : { githubToken: process.env.GITHUB_TOKEN }),
+        ...(registry === undefined ? {} : { registry }),
+    });
+    let agentOptions;
+    if (agentCommand !== undefined) {
+        agentOptions = {
+            command: agentCommand,
+            ...(agentArgs.length === 0 ? {} : { args: agentArgs }),
+        };
+    }
+    if (agentCommand !== undefined && llmEnvFile !== undefined) {
+        throw new Error('observe accepts either --dsh-agent-command or --llm-env-file, not both');
+    }
+    const result = await runObserver(config, previousState, {
+        source,
+        retryPending,
+        ...(agentOptions === undefined ? {} : {
+            agent: (task, prompt) => runDshAgentCommand(task, prompt, agentOptions),
+        }),
+        ...(llmEnvFile === undefined ? {} : {
+            agent: (task, prompt) => runOpenAiCompatibleAgent(task, prompt, { envFile: resolve(llmEnvFile) }),
+        }),
+    });
+    await saveObservationState(statePath, result.state);
+    const reportJson = `${JSON.stringify(result.report, null, 2)}\n`;
+    if (reportPath !== undefined) {
+        await writeFile(resolve(reportPath), reportPath.endsWith('.json') ? reportJson : renderObserverReport(result.report));
+    }
+    process.stdout.write(json ? reportJson : renderObserverReport(result.report));
+    if (result.report.errors.length > 0 || result.report.agent.failed > 0)
+        return 1;
+    return 0;
+}
 async function runQuickstart(args) {
     let directory = process.cwd();
     let json = false;
@@ -1766,10 +1934,14 @@ async function main(args) {
         return runDoctor(args.slice(1));
     if (command === 'graph')
         return runGraph(args.slice(1));
+    if (command === 'profile-check')
+        return runDshProfileCheck(args.slice(1));
     if (command === 'probe')
         return runProbe(args.slice(1));
     if (command === 'demo')
         return runDemo(args.slice(1));
+    if (command === 'observe')
+        return runObserve(args.slice(1));
     if (command === 'benchmark')
         return runBenchmark(args.slice(1));
     if (command === 'radar')