upstream-radar 0.32.0 → 0.33.0

package/dist/src/cli.js

@@ -2,71 +2,414 @@
 import process from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { access, readFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+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 { createDemoReport, renderDemo } from './demo.js';
 import { GitHubReleaseClient } from './github-release.js';
-import { createRadarConfigFromDshProfile, discoverDshProfiles, refreshRadarConfigFromConfiguredProfile, resolveDshProfileDirectory, writeDshPatch, writeRadarConfig } from './init.js';
+import { parseNpmLockGraph, parsePnpmLockGraph } from './graph.js';
+import { createRadarConfigFromDshProfile, createRadarConfigFromNpmLock, createRadarConfigFromPnpmLock, discoverDshProfiles, refreshRadarConfigFromConfiguredProfile, resolveDshProfileDirectory, writeDshPatch, writeRadarConfig } from './init.js';
 import { parsePackageManifestSnapshot, parseRadarConfig } from './inventory.js';
 import { inspectNpmPackage } from './npm.js';
 import { NpmCandidateGraphClient } from './npm-candidate.js';
 import { NpmReleaseClient } from './npm-release.js';
+import { createNotificationPolicyMap, filterNotifiableRadarEvents } from './notification-policy.js';
 import { OsvClient } from './osv.js';
 import { verdictAtLeast } from './policy.js';
+import { createQuickstartReport, renderQuickstartReport } from './quickstart.js';
+import { GitHubAdvisoryClient } from './github-advisory.js';
 import { emptyRadarState, pollRadar } from './radar.js';
 import { evaluateRadarPolicy, RADAR_COMPATIBILITY_FAIL_THRESHOLDS, RADAR_FAIL_THRESHOLDS, renderRadarPolicy, } from './radar-policy.js';
 import { renderRadarEvents } from './radar-render.js';
+import { createRadarHistory, renderRadarHistory } from './radar-history.js';
 import { loadRadarState, saveRadarState } from './radar-state.js';
-import { createRadarStatus, renderRadarStatus } from './radar-status.js';
+import { createRadarNext, createRadarStatus, renderRadarNext, renderRadarStatus } from './radar-status.js';
 import { renderTextReport } from './render.js';
 import { scanDirectory } from './scan.js';
+import { CisaKevClient, EpssClient } from './threat-intel.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']);
 const VALID_RADAR_THRESHOLDS = new Set(RADAR_FAIL_THRESHOLDS);
 const VALID_RADAR_COMPATIBILITY_THRESHOLDS = new Set(RADAR_COMPATIBILITY_FAIL_THRESHOLDS);
+const VALID_NOTIFICATION_SEVERITIES = new Set(['info', 'low', 'medium', 'high', 'critical']);
 function safeErrorMessage(value, maxLength = 2_048) {
     return value.replace(/[\u0000-\u001f\u007f-\u009f]/g, character => (`\\u${character.codePointAt(0)?.toString(16).padStart(4, '0') ?? '0000'}`)).slice(0, maxLength);
 }
 function shellQuote(value) {
     return `'${value.replaceAll("'", "'\\''")}'`;
 }
+function parseNotificationPolicyArguments(minimumSeverity, quietHoursValue) {
+    if (minimumSeverity === undefined && quietHoursValue === undefined)
+        return undefined;
+    if (minimumSeverity !== undefined && !VALID_NOTIFICATION_SEVERITIES.has(minimumSeverity)) {
+        throw new Error('--minimum-severity must be info, low, medium, high or critical');
+    }
+    let quietHours;
+    if (quietHoursValue !== undefined) {
+        const comma = quietHoursValue.indexOf(',');
+        const interval = comma < 0 ? '' : quietHoursValue.slice(comma + 1);
+        const dash = interval.indexOf('-');
+        const timezone = comma < 1 ? '' : quietHoursValue.slice(0, comma);
+        const start = dash < 1 ? '' : interval.slice(0, dash);
+        const end = dash < 0 ? '' : interval.slice(dash + 1);
+        if (!/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(start)
+            || !/^(?:[01]\d|2[0-3]):[0-5]\d$/.test(end)
+            || start === end
+            || timezone.length === 0) {
+            throw new Error('--quiet-hours must use <IANA timezone>,<HH:MM>-<HH:MM> with different start and end times');
+        }
+        try {
+            new Intl.DateTimeFormat('en-US', { timeZone: timezone }).format();
+        }
+        catch {
+            throw new Error('--quiet-hours must start with a valid IANA timezone');
+        }
+        quietHours = { timezone, start, end };
+    }
+    return {
+        ...(minimumSeverity === undefined ? {} : { minimumSeverity: minimumSeverity }),
+        ...(quietHours === undefined ? {} : { quietHours }),
+    };
+}
+function commandUsage(key) {
+    const help = {
+        setup: `Upstream Radar — install the exact Radar bundle into DSH and prepare monitoring
+
+Usage:
+  upstream-radar setup [--profile <name>] [--start] [--project-name <name>]
+
+What it does:
+  Installs Radar into the selected DSH profile, writes a reviewable config and
+  --patch overlay, then runs the local doctor check. By default it does not
+  start DSH or execute plugin business actions; --start opts into launching DSH
+  only after the doctor check passes.
+
+Prerequisite:
+  Install DeepSeek Harness first and verify that \`dsh --help\` works.
+
+Common options:
+  --profile <name>       select a DSH profile (auto-selects the only candidate)
+  --project-name <name>  name shown in incidents and Agent tasks
+  --workspace <path>     project workspace used to route Agent follow-up
+  --repository <url>     repository evidence passed to the Agent task
+  --webhook-url-env <name>  env var containing this project's HTTPS webhook URL
+  --webhook-secret-env <name>  optional env var for a Feishu/Lark V2 signing secret
+  --output <path>        Radar config path (default: ./upstream-radar.config.json)
+  --dsh-patch <path>     DSH overlay path (default: ./upstream-radar.dsh.yml)
+  --minimum-severity <level>  minimum vulnerability notice level
+  --quiet-hours <tz,start-end>  e.g. Asia/Shanghai,22:00-08:00
+  --start                 start DSH after the local wiring check passes
+  --no-install            reuse an already installed Radar bundle
+  --no-dsh-patch          use legacy environment-variable wiring
+
+Notification controls:
+  Add an optional \`notificationPolicy\` block to a generated projects[] entry
+  to set \`minimumSeverity\` and timezone-aware \`quietHours\`. This changes only
+  delivery; active evidence and queued tasks remain durable.
+
+  Next:
+  Review the generated files, then run the printed doctor command and start DSH
+  with the printed --patch command. Pass --start only when you explicitly accept
+  starting DSH in the same invocation after the doctor check passes.
+
+If the profile has no third-party plugin yet:
+  dsh plugin --profile <name> add <package>@<exact-version>
+`,
+        init: `Upstream Radar — create a reviewable inventory
+
+Usage:
+  upstream-radar init --profile <name> [options]
+  upstream-radar init --pnpm-lock <pnpm-lock.yaml> [options]
+  upstream-radar init --npm-lock <package-lock.json> [options]
+
+What it does:
+  Reads a DSH profile or lockfile without executing plugin code. Lockfile mode
+  is the pre-install path; it writes a static graph for a later frozen check.
+
+Common options:
+  --root <package>@<exact-version>  explicit lockfile root when it cannot be inferred
+  --project-name <name>             name shown in incidents
+  --webhook-url-env <name>          env var containing this project's HTTPS webhook URL
+  --webhook-secret-env <name>       optional env var for a Feishu/Lark V2 signing secret
+  --output <path>                   config path (default: ./upstream-radar.config.json)
+  --dsh-patch <path>                write a self-contained DSH overlay (profile mode)
+  --minimum-severity <level>        minimum vulnerability notice level
+  --quiet-hours <tz,start-end>      e.g. Asia/Shanghai,22:00-08:00
+  --json                            print a compact machine-readable summary
+  --force                           replace an existing output file
+
+Notification controls:
+  Add an optional \`notificationPolicy\` block to a generated projects[] entry
+  to set \`minimumSeverity\` and timezone-aware \`quietHours\`. This changes only
+  delivery; active evidence and queued tasks remain durable.
+
+Project webhook routing:
+  Store only environment variable names in the config. Set the URL and optional
+  Feishu secret in the DSH process environment; each project's changed events
+  then use its own endpoint while the native DSH Agent route remains workspace-based.
+
+Next:
+  upstream-radar radar check ./upstream-radar.config.json --frozen
+`,
+        doctor: `Upstream Radar — verify local wiring without polling upstream sources
+
+Usage:
+  upstream-radar doctor [config.json] [--profile <name>] [--patch <path>] [--json]
+
+Checks:
+  config/state readability, Radar registration in DSH, overlay alignment,
+  dependency coverage, and local webhook configuration. It does not contact
+  OSV, npm, GitHub, DSH, or a model.
+`,
+        scan: `Upstream Radar — inspect a local package directory without running it
+
+Usage:
+  upstream-radar scan <directory> [--json] [--fail-on <warn|review|block|never>]
+
+Use this for an unpacked plugin before installation. Lifecycle scripts, remote
+shell patterns, unsafe symlinks, mutable dependencies, and DSH bundle metadata
+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]
+    [--registry <https-url>] [--fail-on <warn|review|block|never>]
+
+--deep downloads the exact tarball, verifies npm integrity/signatures and
+provenance when available, resolves the dependency graph with scripts disabled,
+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.
+`,
+        graph: `Upstream Radar — read a lockfile into the canonical dependency graph
+
+Usage:
+  upstream-radar graph pnpm-lock <pnpm-lock.yaml> [--root <package>@<exact-version>] [--json]
+  upstream-radar graph npm-lock <package-lock.json> [--root <package>@<exact-version>] [--json]
+
+This command is offline and does not install packages, run lifecycle scripts,
+load plugin code, or query vulnerability sources.
+`,
+        probe: `Upstream Radar — test whether a DSH bundle loads in disposable profiles
+
+Usage:
+  upstream-radar probe dsh-load <package.tgz> [--dsh-version <exact-version>] [--json]
+  upstream-radar probe dsh-matrix <package.tgz> --dsh-version <v1>,<v2>,... [--json]
+
+The probe is bounded and isolated. It is a compatibility/load check, not a
+semantic safety review or a substitute for dependency monitoring.
+`,
+        demo: `Upstream Radar — show the exact-path-to-DSH handoff without side effects
+
+Usage:
+  upstream-radar demo [--json]
+
+The demo is network-free and uses only a local fixture. It does not inspect your
+repository, install a plugin, start DSH, or claim that its advisory is real.
+`,
+        quickstart: `Upstream Radar — choose the smallest honest first-use path
+
+Usage:
+  upstream-radar quickstart [directory] [--json]
+
+What it does:
+  Inspects only the selected directory and local DSH profile metadata. It finds
+  an existing Radar config, one supported lockfile, or eligible DSH profiles,
+  then prints the next commands in the right order.
+
+Safety:
+  This command never installs packages, starts DSH, queries vulnerability
+  sources, or executes plugin code. It does not choose between two lockfiles or
+  multiple DSH profiles on your behalf.
+`,
+        benchmark: `Upstream Radar — run offline compatibility-rule contracts
+
+Usage:
+  upstream-radar benchmark compatibility [--json]
+`,
+        radar: `Upstream Radar — monitor a reviewed inventory
+
+Usage:
+  upstream-radar radar check <config.json> [options]
+  upstream-radar radar watch <config.json> [options]
+  upstream-radar radar status <config.json> [options]
+  upstream-radar radar history <config.json> [options]
+  upstream-radar radar compare <config.json> <before.json> <candidate.json> [options]
+
+Use 'radar status' and 'radar history' for local, no-network diagnosis. Use
+--frozen for CI or any run that must not read a live DSH profile.
+`,
+        'radar check': `Upstream Radar — run one vulnerability and compatibility check
+
+Usage:
+  upstream-radar radar check <config.json> [--state <state.json>] [--frozen]
+    [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>]
+    [--webhook <https-url>] [--threat-intel] [--json]
+
+One cycle queries the configured sources and persists changed incidents. Use
+--frozen when the config is the reviewed graph you want to enforce.
+
+--threat-intel adds CISA KEV and FIRST EPSS prioritization signals for matched
+CVEs. It is opt-in here; the native DSH bundle enables it by default.
+`,
+        'radar watch': `Upstream Radar — keep monitoring a reviewed inventory
+
+Usage:
+  upstream-radar radar watch <config.json> [--interval <seconds>] [--once]
+    [--state <state.json>] [--frozen] [--fail-on <severity>]
+    [--fail-on-compatibility <never|breaking|any>] [--webhook <https-url>]
+    [--threat-intel]
+
+Use --once in CI. A long-running watch keeps polling and should not be given a
+policy gate that would make it exit on the first incident.
+`,
+        'radar status': `Upstream Radar — see the local monitoring snapshot
+
+Usage:
+  upstream-radar radar status <config.json> [--state <state.json>]
+    [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
+
+This command never polls OSV, npm, GitHub, or DSH. It shows whether monitoring
+has run, coverage, active incidents, queued Agent tasks, and the next useful
+action.
+`,
+        'radar next': `Upstream Radar — show the one next action for the highest-priority incident
+
+Usage:
+  upstream-radar radar next <config.json> [--state <state.json>] [--json]
+
+This command is read-only and does not poll upstream sources. It selects the
+same first incident as 'radar status', then points to the pending DSH task,
+verified analysis, or the next check command.
+`,
+        'radar history': `Upstream Radar — inspect the durable transition ledger
+
+Usage:
+  upstream-radar radar history <config.json> [--state <state.json>] [--limit <n>] [--json]
+
+This command is local-only and shows new, updated, resolved, and source-health
+transitions, including their exact affected paths.
+`,
+        'radar compare': `Upstream Radar — compare one reviewed release candidate
+
+Usage:
+  upstream-radar radar compare <config.json> <before.json> <candidate.json>
+    [--notes <release-notes.txt>] [--json]
+
+The release notes are treated as untrusted evidence. This command does not
+install or execute the candidate.
+`,
+        task: `Upstream Radar — inspect or acknowledge the DSH analysis outbox
+
+Usage:
+  upstream-radar task list <state.json> [--json]
+  upstream-radar task show <state.json> [task-id] [--json]
+  upstream-radar task ack <state.json> <task-id>
+`,
+        analysis: `Upstream Radar — inspect verified DSH conclusions
+
+Usage:
+  upstream-radar analysis list <state.json> [--json]
+  upstream-radar analysis show <state.json> [incident-id] [--json]
+`,
+        mute: `Upstream Radar — pause delivery for one exact incident until a fixed expiry
+
+Usage:
+  upstream-radar mute <state.json> <incident-id> --until <ISO-8601> [--force] [--json]
+
+This pauses DSH and webhook delivery only. The active incident, dependency paths,
+history, and status remain visible. The mute expires automatically. Critical and
+malware incidents require --force.
+`,
+        unmute: `Upstream Radar — resume delivery for one incident immediately
+
+Usage:
+  upstream-radar unmute <state.json> <incident-id> [--json]
+`,
+        triage: `Upstream Radar — record human follow-up for one active incident
+
+Usage:
+  upstream-radar triage <state.json> <incident-id>
+    --status <open|in-progress|blocked|accepted-risk>
+    [--owner <name>] [--note <text>] [--due <ISO-8601>] [--json]
+
+This records ownership and work context without resolving, hiding, or changing
+the deterministic incident. A new event version requires a fresh follow-up.
+Blocked and accepted-risk states require a note.
+`,
+    };
+    return help[key];
+}
+function commandHelp(args) {
+    const helpIndex = args.findIndex(argument => argument === '--help' || argument === '-h');
+    if (helpIndex < 0)
+        return undefined;
+    const command = args[0];
+    if (command === undefined)
+        return undefined;
+    const nested = command === 'radar' || command === 'task' || command === 'analysis'
+        ? args[1]
+        : undefined;
+    const key = nested === undefined ? command : `${command} ${nested}`;
+    return commandUsage(key) ?? commandUsage(command);
+}
 function usage() {
     return `Upstream Radar — always-on dependency and compatibility monitoring for DSH plugins
 
 Usage:
-  upstream-radar setup [--profile <name>] [options]
+  upstream-radar <command> --help
+  upstream-radar setup [--profile <name>] [--start] [options]
   upstream-radar init [--profile <name>] [options]
+  upstream-radar init --pnpm-lock <pnpm-lock.yaml> [--root <package>@<exact-version>] [options]
+  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 graph <npm-lock|pnpm-lock> <lockfile> [--root <package>@<exact-version>] [--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]
+  upstream-radar quickstart [directory] [--json]
   upstream-radar benchmark compatibility [--json]
-  upstream-radar radar check <config.json> [--state <state.json>] [--frozen] [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
-  upstream-radar radar watch <config.json> [--state <state.json>] [--interval <seconds>] [--once] [--frozen] [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
+  upstream-radar radar check <config.json> [--state <state.json>] [--webhook <https-url>] [--threat-intel] [--frozen] [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
+  upstream-radar radar watch <config.json> [--state <state.json>] [--webhook <https-url>] [--threat-intel] [--interval <seconds>] [--once] [--frozen] [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
   upstream-radar radar status <config.json> [--state <state.json>] [--fail-on <severity>] [--fail-on-compatibility <never|breaking|any>] [--json]
+  upstream-radar radar next <config.json> [--state <state.json>] [--json]
+  upstream-radar radar history <config.json> [--state <state.json>] [--limit <n>] [--json]
   upstream-radar radar compare <config.json> <before.json> <candidate.json> [--notes <release-notes.txt>] [--json]
   upstream-radar task list <state.json> [--json]
   upstream-radar task show <state.json> [task-id] [--json]
   upstream-radar task ack <state.json> <task-id>
   upstream-radar analysis list <state.json> [--json]
   upstream-radar analysis show <state.json> [incident-id] [--json]
+  upstream-radar mute <state.json> <incident-id> --until <ISO-8601> [--force] [--json]
+  upstream-radar unmute <state.json> <incident-id> [--json]
+  upstream-radar triage <state.json> <incident-id> --status <open|in-progress|blocked|accepted-risk> [--owner <name>] [--note <text>] [--due <ISO-8601>] [--json]
   upstream-radar version
 
 Commands:
   setup    install the exact Radar bundle, generate DSH wiring, and run doctor
-  init     discover third-party bundles in a DSH profile and write a reviewable inventory
+  init     discover third-party bundles in DSH or initialize a reviewable lockfile inventory
   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
+  graph    read a lockfile into the canonical dependency graph without installing packages
   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
   benchmark run offline compatibility-rule contracts without network or plugin execution
-  radar    monitor vulnerability changes, watch continuously, inspect status, or assess a candidate compatibility change
+  radar    monitor vulnerability changes, watch continuously, find the next action, inspect status/history, or assess a candidate compatibility change
   task     inspect or acknowledge the durable DSH analysis outbox
   analysis inspect verified DSH conclusions stored in the Radar state
+  mute     pause delivery for one incident with a bounded expiry
+  unmute   resume delivery for one incident immediately
+  triage   record owner, work status, and handoff note for one incident
 
 Options:
   --deep               resolve the dependency graph with scripts disabled and ask npm to verify signatures/provenance
@@ -74,16 +417,29 @@ Options:
   --no-deep-candidates skip bounded transitive dependency graph checks for upgrade candidates
   --state <path>       persistent radar state (default: <config.json>.state.json)
   --osv-base-url <url> alternate HTTPS OSV API base URL
+  --no-github-advisories disable the independent GitHub Advisory Database check for radar check/watch
+  --threat-intel      radar check/watch: add CISA KEV and FIRST EPSS signals for matched CVEs
+  --webhook <https-url>  radar check/watch: POST changed events to an HTTPS endpoint
+  --webhook-url-env <name>  init/setup: env var containing a project's HTTPS webhook URL
+  --webhook-secret-env <name>  init/setup: optional Feishu/Lark V2 signing secret env var
   --interval <seconds> watch interval from 300 to 86400 seconds (default: 1800)
+  --limit <n>         radar history: show 1 to 1000 recent transitions (default: 20)
   --once               run one watch cycle and exit (useful for CI and demos)
   --frozen             radar check/watch: use the reviewed graph in config without reading a local DSH profile
   --fail-on <value>    scan/inspect verdict or radar severity: unknown|info|low|medium|high|critical|never
   --fail-on-compatibility <value>  CI gate: never|breaking|any (default: never)
   --notes <path>       release notes used as untrusted compatibility evidence
   --profile <name>     DSH profile for init or doctor (init auto-selects the only candidate when omitted)
+  --npm-lock <path>    init: build a static inventory from an npm v2/v3 package-lock.json
+  --pnpm-lock <path>   init: build a static inventory from a pnpm v6/v9 lockfile
+  --root <coordinate>  init/graph lockfiles: override the root; otherwise read package.json beside the lockfile
   --no-install          setup: reuse an already installed upstream-radar bundle
   --output <path>      init output path (default: ./upstream-radar.config.json)
-  --dsh-patch <path>   write a self-contained DSH --patch overlay (optional)
+  --dsh-patch <path>   write a self-contained DSH --patch overlay (setup default: ./upstream-radar.dsh.yml)
+  --minimum-severity <level>  init/setup notification threshold: info|low|medium|high|critical
+  --quiet-hours <tz,start-end>  init/setup window, e.g. Asia/Shanghai,22:00-08:00
+  --start              setup: start DSH after the local wiring check passes
+  --no-dsh-patch       setup: keep the legacy UPSTREAM_RADAR_* environment-variable wiring
   --patch <path>       DSH overlay to verify with doctor
   --force              allow init to replace an existing output file
   --json               emit the canonical JSON report
@@ -94,6 +450,89 @@ Exit codes:
   2  configured policy threshold was reached
 `;
 }
+function parseExactPackageCoordinate(value) {
+    const at = value.lastIndexOf('@');
+    if (at <= 0 || at === value.length - 1)
+        throw new Error(`--root must be an exact package coordinate: ${value}`);
+    const name = value.slice(0, at);
+    const version = value.slice(at + 1);
+    if (name.startsWith('@') && !name.includes('/'))
+        throw new Error(`--root must include a scoped package name: ${value}`);
+    return { name, version };
+}
+async function inferLockfileRoot(lockfile, kind) {
+    const manifestPath = join(dirname(resolve(lockfile)), 'package.json');
+    try {
+        const manifest = parsePackageManifestSnapshot(await readJson(manifestPath));
+        return { name: manifest.name, version: manifest.version };
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`could not infer the ${kind} lockfile root from ${manifestPath}; pass --root <package>@<exact-version>`);
+        }
+        throw error;
+    }
+}
+async function runGraph(args) {
+    const kind = args[0];
+    if (kind !== 'npm-lock' && kind !== 'pnpm-lock')
+        throw new Error('graph requires the npm-lock or pnpm-lock subcommand');
+    const lockfile = args[1];
+    if (lockfile === undefined || lockfile.startsWith('-'))
+        throw new Error(`graph ${kind} requires a lockfile path`);
+    let rootSpec;
+    let json = false;
+    for (let index = 2; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+        }
+        else if (argument === '--root') {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error('--root requires a value');
+            rootSpec = value;
+            index += 1;
+        }
+        else {
+            throw new Error(`unknown option for graph ${kind}: ${argument}`);
+        }
+    }
+    const packageRoot = rootSpec === undefined
+        ? await inferLockfileRoot(lockfile, kind === 'npm-lock' ? 'npm' : 'pnpm')
+        : parseExactPackageCoordinate(rootSpec);
+    const graph = kind === 'npm-lock'
+        ? parseNpmLockGraph(await readJson(lockfile), packageRoot)
+        : parsePnpmLockGraph(await readBoundedFile(lockfile, 16 * 1024 * 1024), packageRoot);
+    if (json) {
+        process.stdout.write(`${JSON.stringify(graph, null, 2)}\n`);
+        return 0;
+    }
+    const nodes = new Map(graph.nodes.map(node => [node.id, node]));
+    const root = nodes.get(graph.rootNodeId);
+    const display = (id) => {
+        const node = nodes.get(id);
+        return node === undefined ? id : `${node.name}@${node.version}`;
+    };
+    const unresolved = graph.unresolved ?? [];
+    process.stdout.write([
+        `Dependency graph: ${root === undefined ? graph.rootNodeId : `${root.name}@${root.version}`}`,
+        `Source: ${kind} (read-only; no install, no plugin execution)`,
+        `Nodes: ${graph.nodes.length}`,
+        `Edges: ${graph.edges.length}`,
+        `Unresolved: ${unresolved.length}`,
+        `Digest: ${graph.digest ?? '(none)'}`,
+        '',
+        'Edges:',
+        ...(graph.edges.length === 0 ? ['  (none)'] : graph.edges.map(edge => `  ${display(edge.from)} -[${edge.kind}]-> ${display(edge.to)}`)),
+        ...(unresolved.length === 0 ? [] : [
+            '',
+            'Unresolved dependencies:',
+            ...unresolved.map(item => `  ${display(item.from)} -[${item.kind}]-> ${item.name} (${item.spec})`),
+        ]),
+    ].join('\n') + '\n');
+    return 0;
+}
 async function runTask(args) {
     const subcommand = args[0];
     if (subcommand !== 'list' && subcommand !== 'show' && subcommand !== 'ack') {
@@ -162,6 +601,200 @@ async function runTask(args) {
     process.stdout.write(`Acknowledged ${safeErrorMessage(taskId)}.\n`);
     return 0;
 }
+const MAX_INCIDENT_MUTE_MS = 30 * 24 * 60 * 60 * 1_000;
+const VALID_INCIDENT_TRIAGE_STATUSES = new Set([
+    'open',
+    'in-progress',
+    'blocked',
+    'accepted-risk',
+]);
+function activeEventForIncident(state, incidentId) {
+    return [
+        ...Object.values(state.activeVulnerabilities),
+        ...Object.values(state.activeCompatibility),
+        ...Object.values(state.activeSourceHealth ?? {}),
+    ].map(item => item.event).find(event => event.incidentId === incidentId);
+}
+async function runIncidentMute(args) {
+    const statePath = args[0];
+    const incidentId = args[1];
+    if (statePath === undefined || statePath.startsWith('-'))
+        throw new Error('mute requires a state file');
+    if (incidentId === undefined || incidentId.startsWith('-'))
+        throw new Error('mute requires an incident id');
+    let untilValue;
+    let force = false;
+    let json = false;
+    for (let index = 2; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === undefined)
+            throw new Error('mute received an incomplete option');
+        if (argument === '--force')
+            force = true;
+        else if (argument === '--json')
+            json = true;
+        else if (argument === '--until') {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error('--until requires a value');
+            untilValue = value;
+            index += 1;
+        }
+        else if (argument.startsWith('-')) {
+            throw new Error(`unknown option for mute: ${argument}`);
+        }
+        else {
+            throw new Error(`mute received unexpected argument: ${argument}`);
+        }
+    }
+    if (untilValue === undefined)
+        throw new Error('mute requires --until <ISO-8601>');
+    const mutedUntilMs = Date.parse(untilValue);
+    const nowMs = Date.now();
+    if (!Number.isFinite(mutedUntilMs))
+        throw new Error('--until must be a valid ISO-8601 timestamp');
+    if (mutedUntilMs <= nowMs)
+        throw new Error('--until must be in the future');
+    if (mutedUntilMs > nowMs + MAX_INCIDENT_MUTE_MS)
+        throw new Error('--until cannot be more than 30 days away');
+    const state = await loadRadarState(statePath);
+    const event = activeEventForIncident(state, incidentId);
+    if (event === undefined)
+        throw new Error(`active incident not found: ${incidentId}`);
+    const forceRequired = event.kind === 'malware'
+        || (event.kind === 'vulnerability' && event.advisory.severity === 'critical');
+    if (forceRequired && !force)
+        throw new Error('critical or malware incidents require --force to mute');
+    const mutedUntil = new Date(mutedUntilMs).toISOString();
+    await saveRadarState(statePath, {
+        ...state,
+        incidentMutes: {
+            ...(state.incidentMutes ?? {}),
+            [incidentId]: { eventId: event.id, mutedUntil },
+        },
+    });
+    const result = { incidentId, eventId: event.id, mutedUntil, forced: force };
+    process.stdout.write(json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `Muted delivery for ${safeErrorMessage(incidentId)} until ${mutedUntil}. Active evidence and history remain visible.\n`);
+    return 0;
+}
+async function runIncidentUnmute(args) {
+    const statePath = args[0];
+    const incidentId = args[1];
+    if (statePath === undefined || statePath.startsWith('-'))
+        throw new Error('unmute requires a state file');
+    if (incidentId === undefined || incidentId.startsWith('-'))
+        throw new Error('unmute requires an incident id');
+    let json = false;
+    for (const argument of args.slice(2)) {
+        if (argument === '--json')
+            json = true;
+        else
+            throw new Error(`unknown option for unmute: ${argument}`);
+    }
+    const state = await loadRadarState(statePath);
+    if (state.incidentMutes?.[incidentId] === undefined)
+        throw new Error(`incident is not muted: ${incidentId}`);
+    const nextIncidentMutes = Object.fromEntries(Object.entries(state.incidentMutes).filter(([id]) => id !== incidentId));
+    await saveRadarState(statePath, { ...state, incidentMutes: nextIncidentMutes });
+    const result = { incidentId, unmuted: true };
+    process.stdout.write(json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `Resumed delivery for ${safeErrorMessage(incidentId)}.\n`);
+    return 0;
+}
+async function runIncidentTriage(args) {
+    const statePath = args[0];
+    const incidentId = args[1];
+    if (statePath === undefined || statePath.startsWith('-'))
+        throw new Error('triage requires a state file');
+    if (incidentId === undefined || incidentId.startsWith('-'))
+        throw new Error('triage requires an incident id');
+    let statusValue;
+    let ownerValue;
+    let noteValue;
+    let dueValue;
+    let json = false;
+    for (let index = 2; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === undefined)
+            throw new Error('triage received an incomplete option');
+        if (argument === '--json')
+            json = true;
+        else if (argument === '--status' || argument === '--owner' || argument === '--note' || argument === '--due') {
+            const value = args[index + 1];
+            if (value === undefined || value.startsWith('-'))
+                throw new Error(`${argument} requires a value`);
+            if (argument === '--status')
+                statusValue = value;
+            else if (argument === '--owner')
+                ownerValue = value;
+            else if (argument === '--note')
+                noteValue = value;
+            else
+                dueValue = value;
+            index += 1;
+        }
+        else if (argument.startsWith('-')) {
+            throw new Error(`unknown option for triage: ${argument}`);
+        }
+        else {
+            throw new Error(`triage received unexpected argument: ${argument}`);
+        }
+    }
+    if (statusValue === undefined)
+        throw new Error('triage requires --status <open|in-progress|blocked|accepted-risk>');
+    if (!VALID_INCIDENT_TRIAGE_STATUSES.has(statusValue)) {
+        throw new Error(`invalid triage --status value: ${statusValue}`);
+    }
+    const status = statusValue;
+    const owner = ownerValue?.trim();
+    const note = noteValue?.trim();
+    if (ownerValue !== undefined && (owner === undefined || owner.length === 0))
+        throw new Error('--owner cannot be empty');
+    if (owner !== undefined && owner.length > 512)
+        throw new Error('--owner must be 512 characters or fewer');
+    if (noteValue !== undefined && (note === undefined || note.length === 0))
+        throw new Error('--note cannot be empty');
+    if (note !== undefined && note.length > 2_048)
+        throw new Error('--note must be 2048 characters or fewer');
+    const dueAtMs = dueValue === undefined ? undefined : Date.parse(dueValue);
+    if (dueValue !== undefined && !Number.isFinite(dueAtMs))
+        throw new Error('--due must be a valid ISO-8601 timestamp');
+    const state = await loadRadarState(statePath);
+    const event = activeEventForIncident(state, incidentId);
+    if (event === undefined)
+        throw new Error(`active incident not found: ${incidentId}`);
+    const previous = state.incidentTriage?.[incidentId];
+    const inherited = previous?.eventId === event.id ? previous : undefined;
+    const recordNote = note ?? inherited?.note;
+    if ((status === 'blocked' || status === 'accepted-risk') && recordNote === undefined) {
+        throw new Error(`triage status ${status} requires --note <text>`);
+    }
+    const recordOwner = owner ?? inherited?.owner;
+    const recordDueAt = dueAtMs === undefined ? inherited?.dueAt : new Date(dueAtMs).toISOString();
+    const record = {
+        eventId: event.id,
+        status,
+        updatedAt: new Date().toISOString(),
+        ...(recordOwner === undefined ? {} : { owner: recordOwner }),
+        ...(recordNote === undefined ? {} : { note: recordNote }),
+        ...(recordDueAt === undefined ? {} : { dueAt: recordDueAt }),
+    };
+    await saveRadarState(statePath, {
+        ...state,
+        incidentTriage: {
+            ...(state.incidentTriage ?? {}),
+            [incidentId]: record,
+        },
+    });
+    const result = { incidentId, ...record };
+    process.stdout.write(json
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `Recorded ${status} follow-up for ${safeErrorMessage(incidentId)}${record.owner === undefined ? '' : ` (owner: ${safeErrorMessage(record.owner)})`}.\n`);
+    return 0;
+}
 async function runAnalysis(args) {
     const subcommand = args[0];
     if (subcommand !== 'list' && subcommand !== 'show')
@@ -258,6 +891,18 @@ async function runBenchmark(args) {
     process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderCompatibilityBenchmark(report));
     return report.summary.failed === 0 ? 0 : 1;
 }
+function runDemo(args) {
+    let json = false;
+    for (const argument of args) {
+        if (argument === '--json')
+            json = true;
+        else
+            throw new Error(`unknown option for demo: ${argument}`);
+    }
+    const report = createDemoReport();
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderDemo(report));
+    return 0;
+}
 async function runProbe(args) {
     const mode = args[0];
     if (mode !== 'dsh-load' && mode !== 'dsh-matrix')
@@ -337,8 +982,8 @@ async function fileExists(path) {
 }
 async function runRadar(args) {
     const subcommand = args[0];
-    if (subcommand !== 'check' && subcommand !== 'watch' && subcommand !== 'status' && subcommand !== 'compare') {
-        throw new Error('radar requires check, watch, status or compare');
+    if (subcommand !== 'check' && subcommand !== 'watch' && subcommand !== 'status' && subcommand !== 'next' && subcommand !== 'history' && subcommand !== 'compare') {
+        throw new Error('radar requires check, watch, status, next, history or compare');
     }
     const configPath = args[1];
     if (configPath === undefined || configPath.startsWith('-'))
@@ -348,11 +993,16 @@ async function runRadar(args) {
     let statePath;
     let osvBaseUrl;
     let registry;
+    let webhookUrl;
     let notesPath;
     let intervalSeconds = 1_800;
     let intervalProvided = false;
+    let historyLimit = 20;
+    let historyLimitProvided = false;
     let once = false;
     let deepCandidates = true;
+    let githubAdvisories = true;
+    let threatIntel = false;
     let frozen = false;
     let failOn = 'never';
     let failOnCompatibility = 'never';
@@ -367,11 +1017,17 @@ async function runRadar(args) {
         else if (argument === '--no-deep-candidates') {
             deepCandidates = false;
         }
+        else if (argument === '--no-github-advisories') {
+            githubAdvisories = false;
+        }
+        else if (argument === '--threat-intel') {
+            threatIntel = true;
+        }
         else if (argument === '--frozen') {
             frozen = true;
         }
-        else if (argument === '--state' || argument === '--osv-base-url' || argument === '--registry'
-            || argument === '--notes' || argument === '--interval' || argument === '--fail-on'
+        else if (argument === '--state' || argument === '--osv-base-url' || argument === '--registry' || argument === '--webhook'
+            || argument === '--notes' || argument === '--interval' || argument === '--limit' || argument === '--fail-on'
             || argument === '--fail-on-compatibility') {
             const value = args[index + 1];
             if (value === undefined || value.startsWith('-'))
@@ -382,6 +1038,8 @@ async function runRadar(args) {
                 osvBaseUrl = value;
             else if (argument === '--registry')
                 registry = value;
+            else if (argument === '--webhook')
+                webhookUrl = normalizeRadarWebhookUrl(value);
             else if (argument === '--notes')
                 notesPath = value;
             else if (argument === '--fail-on') {
@@ -396,6 +1054,14 @@ async function runRadar(args) {
                 }
                 failOnCompatibility = value;
             }
+            else if (argument === '--limit') {
+                historyLimitProvided = true;
+                const parsed = Number(value);
+                if (!Number.isSafeInteger(parsed) || parsed < 1 || parsed > 1_000) {
+                    throw new Error('--limit must be an integer between 1 and 1000');
+                }
+                historyLimit = parsed;
+            }
             else {
                 intervalProvided = true;
                 const parsed = Number(value);
@@ -417,10 +1083,13 @@ async function runRadar(args) {
     const readConfigForPoll = async () => frozen
         ? readConfig()
         : refreshRadarConfigFromConfiguredProfile(await readConfig());
-    if (subcommand === 'status') {
+    if (subcommand === 'status' || subcommand === 'next') {
         if (positional.length > 0 || notesPath !== undefined || once || intervalProvided
-            || osvBaseUrl !== undefined || registry !== undefined || !deepCandidates || frozen || statePath === ':memory:') {
-            throw new Error('radar status only accepts --state, --fail-on, --fail-on-compatibility and --json options');
+            || historyLimitProvided || osvBaseUrl !== undefined || registry !== undefined || webhookUrl !== undefined || !deepCandidates || !githubAdvisories || threatIntel || frozen || statePath === ':memory:'
+            || (subcommand === 'next' && (failOn !== 'never' || failOnCompatibility !== 'never'))) {
+            throw new Error(subcommand === 'next'
+                ? 'radar next only accepts --state and --json options'
+                : 'radar status only accepts --state, --fail-on, --fail-on-compatibility and --json options');
         }
         const config = await readConfig();
         const stateFile = statePath ?? `${resolve(configPath)}.state.json`;
@@ -433,6 +1102,11 @@ async function runRadar(args) {
         });
         const policy = evaluateRadarPolicy(state, failOn, failOnCompatibility);
         const policyEnabled = failOn !== 'never' || failOnCompatibility !== 'never';
+        if (subcommand === 'next') {
+            const next = createRadarNext(report, state);
+            process.stdout.write(json ? `${JSON.stringify(next, null, 2)}\n` : renderRadarNext(next));
+            return 0;
+        }
         if (json) {
             process.stdout.write(!policyEnabled
                 ? `${JSON.stringify(report, null, 2)}\n`
@@ -445,6 +1119,27 @@ async function runRadar(args) {
             return 1;
         return policy.status === 'fail' ? 2 : 0;
     }
+    if (subcommand === 'history') {
+        if (positional.length > 0 || notesPath !== undefined || once || intervalProvided
+            || osvBaseUrl !== undefined || registry !== undefined || webhookUrl !== undefined || !deepCandidates || !githubAdvisories || frozen
+            || failOn !== 'never' || failOnCompatibility !== 'never' || threatIntel) {
+            throw new Error('radar history only accepts --state, --limit and --json options');
+        }
+        // Parse the config as an input check, but deliberately do not refresh it
+        // or contact any upstream source. History is a local diagnosis command.
+        await readConfig();
+        const stateFile = statePath ?? `${resolve(configPath)}.state.json`;
+        const stateExists = await fileExists(stateFile);
+        const state = stateExists ? await loadRadarState(stateFile) : emptyRadarState();
+        const report = createRadarHistory(state, {
+            configFile: resolve(configPath),
+            stateFile: resolve(stateFile),
+            stateExists,
+            limit: historyLimit,
+        });
+        process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderRadarHistory(report));
+        return 0;
+    }
     const osv = new OsvClient({
         ...(osvBaseUrl === undefined ? {} : { baseUrl: osvBaseUrl }),
     });
@@ -455,14 +1150,60 @@ async function runRadar(args) {
         ? new NpmCandidateGraphClient({ ...(registry === undefined ? {} : { registry }) })
         : undefined;
     const releaseNotesSource = new GitHubReleaseClient();
+    const githubAdvisorySource = githubAdvisories
+        ? new GitHubAdvisoryClient({ ...(process.env.GITHUB_TOKEN === undefined ? {} : { token: process.env.GITHUB_TOKEN }) })
+        : undefined;
+    const threatIntelSources = threatIntel
+        ? [
+            { name: 'cisa-kev', source: new CisaKevClient() },
+            { name: 'epss', source: new EpssClient() },
+        ]
+        : [];
     const stateFile = statePath ?? `${resolve(configPath)}.state.json`;
+    if (webhookUrl !== undefined && statePath === ':memory:') {
+        throw new Error('radar --webhook requires a persistent --state file so successful deliveries can be remembered');
+    }
+    const feishuSecret = process.env.UPSTREAM_RADAR_FEISHU_SECRET?.trim() || undefined;
     const runCheck = async () => {
         const config = await readConfigForPoll();
+        const webhookTargets = resolveRadarWebhookTargets(config.projects, {
+            ...(webhookUrl === undefined ? {} : { globalUrl: webhookUrl }),
+            ...(feishuSecret === undefined ? {} : { globalFeishuSecret: feishuSecret }),
+        });
+        if (statePath === ':memory:' && webhookTargets.length > 0) {
+            throw new Error('radar webhook routes require a persistent --state file so successful deliveries can be remembered');
+        }
         const state = statePath === ':memory:' ? emptyRadarState() : await loadRadarState(stateFile);
-        const result = await pollRadar(config.projects, state, osv, new Date(), releases, releaseNotesSource, candidateGraphs);
+        const checkedAt = new Date();
+        const result = await pollRadar(config.projects, state, osv, checkedAt, releases, releaseNotesSource, candidateGraphs, githubAdvisorySource === undefined ? [] : [{ name: 'github-advisories', source: githubAdvisorySource }], threatIntelSources);
         if (statePath !== ':memory:')
             await saveRadarState(stateFile, result.state);
-        return result;
+        const notificationPolicies = createNotificationPolicyMap(config.projects);
+        let nextState = result.state;
+        for (const target of webhookTargets) {
+            const targetEvents = eventsForRadarWebhookTarget(result.events, target);
+            const isLegacyGlobal = webhookUrl !== undefined && target.projectIds === undefined;
+            const queuedState = isLegacyGlobal
+                ? queueRadarWebhookEvents(nextState, target.endpointHash, targetEvents)
+                : queueRadarWebhookEventsForRoute(nextState, target.endpointHash, targetEvents);
+            if (statePath !== ':memory:')
+                await saveRadarState(stateFile, queuedState);
+            const pendingWebhookEvents = filterNotifiableRadarEvents(isLegacyGlobal
+                ? undeliveredRadarWebhookEvents(queuedState, target.endpointHash, targetEvents)
+                : undeliveredRadarWebhookEventsForRoute(queuedState, target.endpointHash, targetEvents), notificationPolicies, checkedAt, queuedState);
+            if (pendingWebhookEvents.length === 0) {
+                nextState = queuedState;
+                continue;
+            }
+            const payload = await sendRadarWebhook(target.url, pendingWebhookEvents, target.feishuSecret === undefined ? {} : { feishuSecret: target.feishuSecret });
+            const deliveredIds = new Set(payload.events.map(event => event.id));
+            const deliveredEvents = pendingWebhookEvents.filter(event => deliveredIds.has(event.id));
+            nextState = isLegacyGlobal
+                ? markRadarWebhookEventsDelivered(queuedState, target.endpointHash, deliveredEvents)
+                : markRadarWebhookEventsDeliveredForRoute(queuedState, target.endpointHash, deliveredEvents);
+            await saveRadarState(stateFile, nextState);
+        }
+        return { ...result, state: nextState };
     };
     const writeCheckResult = (result, compactJson = false) => {
         const policy = evaluateRadarPolicy(result.state, failOn, failOnCompatibility);
@@ -478,7 +1219,7 @@ async function runRadar(args) {
         return policy;
     };
     if (subcommand === 'check') {
-        if (positional.length > 0 || notesPath !== undefined || once || intervalProvided) {
+        if (positional.length > 0 || notesPath !== undefined || once || intervalProvided || historyLimitProvided) {
             throw new Error('radar check received an option meant for watch or compare');
         }
         const result = await runCheck();
@@ -488,7 +1229,7 @@ async function runRadar(args) {
         return policy.status === 'fail' ? 2 : 0;
     }
     if (subcommand === 'watch') {
-        if (positional.length > 0 || notesPath !== undefined)
+        if (positional.length > 0 || notesPath !== undefined || historyLimitProvided)
             throw new Error('radar watch received unexpected arguments');
         if ((failOn !== 'never' || failOnCompatibility !== 'never') && !once)
             throw new Error('radar watch requires --once when a policy gate is used');
@@ -537,7 +1278,7 @@ async function runRadar(args) {
         }
         return 0;
     }
-    if (statePath !== undefined || osvBaseUrl !== undefined || registry !== undefined || once || intervalProvided || !deepCandidates || frozen || failOn !== 'never' || failOnCompatibility !== 'never') {
+    if (statePath !== undefined || osvBaseUrl !== undefined || registry !== undefined || webhookUrl !== undefined || once || intervalProvided || historyLimitProvided || !deepCandidates || !githubAdvisories || threatIntel || frozen || failOn !== 'never' || failOnCompatibility !== 'never') {
         throw new Error('radar compare does not accept check or watch options');
     }
     const config = await readConfig();
@@ -562,15 +1303,37 @@ async function runRadar(args) {
         : `${renderRadarEvents(events)}Prepared ${analysisTasks.length} DSH compatibility analysis task(s).\n`);
     return 0;
 }
+async function runQuickstart(args) {
+    let directory = process.cwd();
+    let json = false;
+    let positional = false;
+    for (const argument of args) {
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (argument.startsWith('-'))
+            throw new Error(`unknown option for quickstart: ${argument}`);
+        if (positional)
+            throw new Error('quickstart accepts at most one directory');
+        directory = argument;
+        positional = true;
+    }
+    const report = await createQuickstartReport(directory);
+    process.stdout.write(json ? `${JSON.stringify(report, null, 2)}\n` : renderQuickstartReport(report));
+    return 0;
+}
 async function runSetup(args) {
     let profile;
     let output = 'upstream-radar.config.json';
-    let patchFile;
+    let patchFile = 'upstream-radar.dsh.yml';
     let noInstall = false;
+    let startDsh = false;
     const initArgs = [];
     const valueOptions = new Set([
         '--profile', '--output', '--dsh-patch', '--project-id', '--project-name',
-        '--repository', '--workspace', '--channel', '--registry',
+        '--repository', '--workspace', '--channel', '--webhook-url-env', '--webhook-secret-env',
+        '--registry', '--minimum-severity', '--quiet-hours',
     ]);
     for (let index = 0; index < args.length; index += 1) {
         const argument = args[index];
@@ -578,6 +1341,14 @@ async function runSetup(args) {
             noInstall = true;
             continue;
         }
+        if (argument === '--no-dsh-patch') {
+            patchFile = undefined;
+            continue;
+        }
+        if (argument === '--start') {
+            startDsh = true;
+            continue;
+        }
         if (argument === '--json')
             throw new Error('setup does not accept --json; use init --json');
         if (argument === '--force') {
@@ -592,9 +1363,10 @@ async function runSetup(args) {
                 profile = value;
             else if (argument === '--output')
                 output = value;
-            else if (argument === '--dsh-patch')
+            if (argument === '--dsh-patch')
                 patchFile = value;
-            initArgs.push(argument ?? '', value);
+            else
+                initArgs.push(argument ?? '', value);
             index += 1;
             continue;
         }
@@ -604,7 +1376,7 @@ async function runSetup(args) {
     if (!noInstall && resolvedProfile === undefined) {
         const candidates = await discoverDshProfiles();
         if (candidates.length === 0) {
-            throw new Error('setup could not find a DSH profile with third-party bundles; pass --profile <name>');
+            throw new Error('setup could not find a DSH profile with third-party bundles; install one with `dsh plugin --profile <name> add <package>@<exact-version>`, then rerun setup');
         }
         if (candidates.length > 1) {
             throw new Error(`setup found multiple DSH profiles with third-party bundles (${candidates.join(', ')}); pass --profile <name>`);
@@ -614,6 +1386,12 @@ async function runSetup(args) {
     if (resolvedProfile !== undefined && profile === undefined) {
         initArgs.unshift('--profile', resolvedProfile);
     }
+    // Setup is the beginner-facing path: make the generated DSH overlay the
+    // default so a first run does not fall back to hidden environment variables.
+    // `init` remains available when a user deliberately wants the legacy
+    // environment-variable wiring instead.
+    if (patchFile !== undefined)
+        initArgs.push('--dsh-patch', patchFile);
     if (!noInstall) {
         if (resolvedProfile === undefined)
             throw new Error('setup could not select a DSH profile');
@@ -627,6 +1405,10 @@ async function runSetup(args) {
             stdio: 'inherit',
         });
         if (result.error !== undefined) {
+            const spawnError = result.error;
+            if (spawnError.code === 'ENOENT') {
+                throw new Error('setup could not find the `dsh` command; install DeepSeek Harness, verify `dsh --help` works, then rerun setup');
+            }
             throw new Error(`setup could not run ${dshCommand}: ${safeErrorMessage(result.error.message)}`);
         }
         if (result.status !== 0) {
@@ -650,17 +1432,47 @@ async function runSetup(args) {
         doctorOptions.patchFile = patchFile;
     const doctor = await createDoctorReport(doctorOptions);
     process.stdout.write(`\nLocal wiring check:\n${renderDoctorReport(doctor)}`);
-    return doctor.status === 'blocked' ? 1 : 0;
+    if (doctor.status === 'blocked')
+        return 1;
+    if (!startDsh)
+        return 0;
+    if (doctorProfile === undefined) {
+        throw new Error('setup --start could not determine the DSH profile; pass --profile <name>');
+    }
+    const dshCommand = process.platform === 'win32' ? 'dsh.cmd' : 'dsh';
+    const dshArgs = ['--profile', doctorProfile];
+    const dshEnvironment = patchFile === undefined
+        ? { ...process.env, UPSTREAM_RADAR_CONFIG: outputPath, UPSTREAM_RADAR_STATE: statePath }
+        : process.env;
+    if (patchFile !== undefined)
+        dshArgs.push('--patch', patchFile);
+    process.stdout.write(`\nStarting DSH profile ${doctorProfile}; press Ctrl-C to stop.\n`);
+    const result = spawnSync(dshCommand, dshArgs, { env: dshEnvironment, stdio: 'inherit' });
+    if (result.error !== undefined) {
+        const spawnError = result.error;
+        if (spawnError.code === 'ENOENT') {
+            throw new Error('setup --start could not find the `dsh` command; install DeepSeek Harness, verify `dsh --help` works, then rerun setup');
+        }
+        throw new Error(`setup --start could not run ${dshCommand}: ${safeErrorMessage(result.error.message)}`);
+    }
+    return result.status ?? 1;
 }
 async function runInit(args) {
     let profile;
+    let npmLockPath;
+    let pnpmLockPath;
+    let rootSpec;
     let output = 'upstream-radar.config.json';
     let dshPatch;
     let projectId;
     let projectName;
     let repository;
     let workspace;
+    let webhookUrlEnv;
+    let webhookSecretEnv;
     let registry;
+    let minimumSeverity;
+    let quietHoursValue;
     let force = false;
     let json = false;
     const channels = [];
@@ -670,14 +1482,21 @@ async function runInit(args) {
             force = true;
         else if (argument === '--json')
             json = true;
-        else if (argument === '--profile' || argument === '--output' || argument === '--dsh-patch' || argument === '--project-id'
+        else if (argument === '--profile' || argument === '--npm-lock' || argument === '--pnpm-lock' || argument === '--root' || argument === '--output' || argument === '--dsh-patch' || argument === '--project-id'
             || argument === '--project-name' || argument === '--repository' || argument === '--workspace'
-            || argument === '--channel' || argument === '--registry') {
+            || argument === '--channel' || argument === '--webhook-url-env' || argument === '--webhook-secret-env'
+            || argument === '--registry' || argument === '--minimum-severity' || argument === '--quiet-hours') {
             const value = args[index + 1];
             if (value === undefined || value.startsWith('-'))
                 throw new Error(`${argument} requires a value`);
             if (argument === '--profile')
                 profile = value;
+            else if (argument === '--npm-lock')
+                npmLockPath = value;
+            else if (argument === '--pnpm-lock')
+                pnpmLockPath = value;
+            else if (argument === '--root')
+                rootSpec = value;
             else if (argument === '--output')
                 output = value;
             else if (argument === '--dsh-patch')
@@ -692,6 +1511,14 @@ async function runInit(args) {
                 workspace = value;
             else if (argument === '--channel')
                 channels.push(value);
+            else if (argument === '--webhook-url-env')
+                webhookUrlEnv = value;
+            else if (argument === '--webhook-secret-env')
+                webhookSecretEnv = value;
+            else if (argument === '--minimum-severity')
+                minimumSeverity = value;
+            else if (argument === '--quiet-hours')
+                quietHoursValue = value;
             else
                 registry = value;
             index += 1;
@@ -700,6 +1527,68 @@ async function runInit(args) {
             throw new Error(`unknown option for init: ${argument}`);
         }
     }
+    const notificationPolicy = parseNotificationPolicyArguments(minimumSeverity, quietHoursValue);
+    if (npmLockPath !== undefined || pnpmLockPath !== undefined) {
+        if (npmLockPath !== undefined && pnpmLockPath !== undefined) {
+            throw new Error('init accepts only one of --npm-lock or --pnpm-lock');
+        }
+        const lockKind = npmLockPath === undefined ? 'pnpm-lock' : 'npm-lock';
+        const lockfile = npmLockPath ?? pnpmLockPath;
+        if (lockfile === undefined)
+            throw new Error('init lockfile path is missing');
+        if (profile !== undefined || dshPatch !== undefined || registry !== undefined) {
+            throw new Error(`init --${lockKind} does not accept --profile, --dsh-patch or --registry`);
+        }
+        const root = rootSpec === undefined
+            ? await inferLockfileRoot(lockfile, lockKind === 'npm-lock' ? 'npm' : 'pnpm')
+            : parseExactPackageCoordinate(rootSpec);
+        const config = lockKind === 'npm-lock'
+            ? await createRadarConfigFromNpmLock({
+                lockfile,
+                root,
+                ...(projectId === undefined ? {} : { projectId }),
+                ...(projectName === undefined ? {} : { projectName }),
+                ...(repository === undefined ? {} : { repository }),
+                ...(workspace === undefined ? {} : { workspace }),
+                ...(channels.length === 0 ? {} : { channels }),
+                ...(webhookUrlEnv === undefined ? {} : { webhookUrlEnv }),
+                ...(webhookSecretEnv === undefined ? {} : { webhookSecretEnv }),
+                ...(notificationPolicy === undefined ? {} : { notificationPolicy }),
+            })
+            : await createRadarConfigFromPnpmLock({
+                lockfile,
+                root,
+                ...(projectId === undefined ? {} : { projectId }),
+                ...(projectName === undefined ? {} : { projectName }),
+                ...(repository === undefined ? {} : { repository }),
+                ...(workspace === undefined ? {} : { workspace }),
+                ...(channels.length === 0 ? {} : { channels }),
+                ...(webhookUrlEnv === undefined ? {} : { webhookUrlEnv }),
+                ...(webhookSecretEnv === undefined ? {} : { webhookSecretEnv }),
+                ...(notificationPolicy === undefined ? {} : { notificationPolicy }),
+            });
+        const outputPath = await writeRadarConfig(config, { output: resolve(output), force });
+        const plugin = config.projects[0]?.plugins[0];
+        if (plugin === undefined)
+            throw new Error(`${lockKind} initialization produced no plugin`);
+        if (json) {
+            process.stdout.write(`${JSON.stringify({
+                output: outputPath,
+                source: plugin.graph.source,
+                root: plugin.package,
+                nodes: plugin.graph.nodes.length,
+                edges: plugin.graph.edges.length,
+                ...(plugin.graph.unresolved === undefined ? {} : { unresolved: plugin.graph.unresolved.length }),
+            }, null, 2)}\n`);
+        }
+        else {
+            const unresolved = plugin.graph.unresolved?.length ?? 0;
+            process.stdout.write(`Created ${outputPath}\nSource: ${plugin.graph.source ?? lockKind}\nRoot: ${plugin.package.name}@${plugin.package.version}\nGraph: ${plugin.graph.nodes.length} nodes, ${plugin.graph.edges.length} edges, ${unresolved} unresolved\nNext: upstream-radar radar check ${shellQuote(outputPath)} --frozen\n`);
+        }
+        return 0;
+    }
+    if (rootSpec !== undefined)
+        throw new Error('init --root is only valid with --npm-lock or --pnpm-lock');
     let autoSelected = false;
     let resolvedProfile = profile;
     if (resolvedProfile === undefined) {
@@ -742,6 +1631,9 @@ async function runInit(args) {
         ...(repository === undefined ? {} : { repository }),
         ...(workspace === undefined ? {} : { workspace }),
         ...(channels.length === 0 ? {} : { channels }),
+        ...(webhookUrlEnv === undefined ? {} : { webhookUrlEnv }),
+        ...(webhookSecretEnv === undefined ? {} : { webhookSecretEnv }),
+        ...(notificationPolicy === undefined ? {} : { notificationPolicy }),
         ...(registry === undefined ? {} : { registry }),
     });
     config.dshProfile = { name: resolvedProfile };
@@ -756,7 +1648,13 @@ async function runInit(args) {
         force,
     });
     const plugins = config.projects[0]?.plugins ?? [];
-    const doctorCommand = `pnpm dlx --package=upstream-radar@${TOOL_VERSION} upstream-radar doctor ${shellQuote(outputPath)} --profile ${shellQuote(resolvedProfile)}${patchPath === undefined ? '' : ` --patch ${shellQuote(patchPath)}`}`;
+    // Keep the printed recovery command independent of the package manager that
+    // happened to launch this copy. Node ships with npm/npx, while a user may
+    // have entered setup through pnpm, yarn, or a global binary. The command is
+    // deliberately exact-versioned so the doctor checks the same release that
+    // generated the config.
+    const doctorCommand = `npx --yes upstream-radar@${TOOL_VERSION} doctor ${shellQuote(outputPath)} --profile ${shellQuote(resolvedProfile)}${patchPath === undefined ? '' : ` --patch ${shellQuote(patchPath)}`}`;
+    const statusCommand = `npx --yes upstream-radar@${TOOL_VERSION} radar status ${shellQuote(outputPath)} --state ${shellQuote(statePath)}`;
     const startCommand = patchPath === undefined
         ? `dsh --profile ${shellQuote(resolvedProfile)}`
         : `dsh --profile ${shellQuote(resolvedProfile)} --patch ${shellQuote(patchPath)}`;
@@ -768,6 +1666,7 @@ async function runInit(args) {
                 edges: plugin.graph.edges.length,
                 ...(plugin.graph.source === undefined ? {} : { source: plugin.graph.source }),
                 ...(plugin.graph.hostRuntime === undefined ? {} : { hostRuntimeNodes: plugin.graph.hostRuntime.resolvedNodes }),
+                ...(plugin.graph.hostRuntime?.package === undefined ? {} : { hostRuntimePackage: plugin.graph.hostRuntime.package }),
                 ...(plugin.graph.unresolved === undefined ? {} : { unresolved: plugin.graph.unresolved.length }),
                 ...(plugin.graph.unresolved === undefined ? {} : {
                     requiredUnresolved: plugin.graph.unresolved.filter(item => item.kind !== 'optional').length,
@@ -784,13 +1683,14 @@ async function runInit(args) {
             const requiredUnresolved = plugin.graph.unresolved?.filter(item => item.kind !== 'optional').length ?? 0;
             const optionalUnresolved = unresolved - requiredUnresolved;
             const hostRuntime = plugin.graph.hostRuntime?.resolvedNodes ?? 0;
-            process.stdout.write(`  ${plugin.package.name}@${plugin.package.version} (${plugin.graph.nodes.length} dependency nodes${plugin.graph.source === undefined ? '' : `, ${plugin.graph.source}`}${hostRuntime === 0 ? '' : `, ${hostRuntime} DSH host`}${requiredUnresolved === 0 ? '' : `, ${requiredUnresolved} required unresolved`}${optionalUnresolved === 0 ? '' : `, ${optionalUnresolved} optional absent`})\n`);
+            const hostRuntimePackage = plugin.graph.hostRuntime?.package;
+            process.stdout.write(`  ${plugin.package.name}@${plugin.package.version} (${plugin.graph.nodes.length} dependency nodes${plugin.graph.source === undefined ? '' : `, ${plugin.graph.source}`}${hostRuntime === 0 ? '' : `, ${hostRuntime} DSH host`}${hostRuntimePackage === undefined ? '' : `, runtime ${hostRuntimePackage.name}@${hostRuntimePackage.version}`}${requiredUnresolved === 0 ? '' : `, ${requiredUnresolved} required unresolved`}${optionalUnresolved === 0 ? '' : `, ${optionalUnresolved} optional absent`})\n`);
         }
         if (patchPath === undefined) {
-            process.stdout.write(`\nReview the generated inventory, then verify the wiring:\n  ${doctorCommand}\n\nStart DSH (keep it running):\n  export UPSTREAM_RADAR_CONFIG=${shellQuote(outputPath)}\n  export UPSTREAM_RADAR_STATE=${shellQuote(statePath)}\n  ${startCommand}\n`);
+            process.stdout.write(`\nReview the generated inventory, then verify the wiring:\n  ${doctorCommand}\n\nStart DSH (keep it running):\n  export UPSTREAM_RADAR_CONFIG=${shellQuote(outputPath)}\n  export UPSTREAM_RADAR_STATE=${shellQuote(statePath)}\n  ${startCommand}\n\nAfter the first check, inspect the local result:\n  ${statusCommand}\n`);
         }
         else {
-            process.stdout.write(`Created ${patchPath}\n\nReview the generated inventory and DSH overlay, then verify the wiring:\n  ${doctorCommand}\n\nStart DSH (keep it running):\n  ${startCommand}\n`);
+            process.stdout.write(`Created ${patchPath}\n\nReview the generated inventory and DSH overlay, then verify the wiring:\n  ${doctorCommand}\n\nStart DSH (keep it running):\n  ${startCommand}\n\nAfter the first check, inspect the local result:\n  ${statusCommand}\n`);
         }
     }
     return 0;
@@ -842,6 +1742,11 @@ async function runDoctor(args) {
     return report.status === 'blocked' ? 1 : 0;
 }
 async function main(args) {
+    const help = commandHelp(args);
+    if (help !== undefined) {
+        process.stdout.write(help);
+        return 0;
+    }
     const command = args[0];
     if (command === undefined || command === '--help' || command === '-h' || command === 'help') {
         process.stdout.write(usage());
@@ -851,14 +1756,20 @@ async function main(args) {
         process.stdout.write(`${TOOL_VERSION}\n`);
         return 0;
     }
+    if (command === 'quickstart')
+        return runQuickstart(args.slice(1));
     if (command === 'setup')
         return runSetup(args.slice(1));
     if (command === 'init')
         return runInit(args.slice(1));
     if (command === 'doctor')
         return runDoctor(args.slice(1));
+    if (command === 'graph')
+        return runGraph(args.slice(1));
     if (command === 'probe')
         return runProbe(args.slice(1));
+    if (command === 'demo')
+        return runDemo(args.slice(1));
     if (command === 'benchmark')
         return runBenchmark(args.slice(1));
     if (command === 'radar')
@@ -867,6 +1778,12 @@ async function main(args) {
         return runTask(args.slice(1));
     if (command === 'analysis')
         return runAnalysis(args.slice(1));
+    if (command === 'mute')
+        return runIncidentMute(args.slice(1));
+    if (command === 'unmute')
+        return runIncidentUnmute(args.slice(1));
+    if (command === 'triage')
+        return runIncidentTriage(args.slice(1));
     if (command !== 'scan' && command !== 'inspect')
         throw new Error(`unknown command: ${command}`);
     const target = args[1];