fix(vex): honest machine diagnostics, stale-doc removal, out-of-sync disclosure; offline proxy-notice suppression

[Mikola Lysenko (mikolalysenko)]

Problems (found by the 2026-08-18 pnpm e2e campaign's vex/offline probes; all ecosystem-independent)

1. Machine-invisible Property-7 drops: a byte-verified applied patch omitted from the VEX doc only because its ecosystem has no install hook (and no setup.manual) made vex --json exit 1 with events: [] and the factually wrong error "No applied patches with vulnerability metadata to attest." — indistinguishable from "not patched". The explanatory note was human-mode-only.
2. Stale attestations: a failed vex run left the previous run's fully-valid document byte-untouched at --output — a pipeline reusing one path could ship yesterday's attestation for a now-unpatched tree.
3. --output write failures reported a bare OS error with no path; --product accepted arbitrary non-IRI strings verbatim into the OpenVEX product @id; a healthy vendored attestation said nothing when the live installed tree was out of sync with the patched bytes.
4. apply/vendor/rollback --offline runs printed the "using the public patch API proxy" notice — network-implying output under strict airgap — and the SOCKET_OFFLINE parse was duplicated between the client and telemetry.

Fixes

• Setup-filter drops now emit per-purl skipped events with errorCode ecosystem_not_setup; when all omissions are filter drops, the error message names the filter and both remediations.
• Failed runs remove a recognizably-OpenVEX file at the output path (JSON @context naming openvex.dev) — unrelated files are never touched; the contract is pinned by tests both ways.
• write_failed names the path; a non-purl/non-IRI product override warns (product_not_iri, honored verbatim); vendored attestations gain a vendored_tree_out_of_sync warning when the present installed tree hash-mismatches (attestation basis unchanged — the committed artifact is the product; the warning says to reinstall).
• The offline gate suppresses the proxy notice; is_offline_env() is hoisted to utils/env_compat and shared by the client (both gates) and telemetry.

The core attestation invariant is untouched and was verified healthy throughout the probes: verified: true only ever appears when on-disk bytes hash to afterHash; every tamper flipped the attestation. The stable (vendored)/(redirected) impact-marker strings are unchanged (contract-pinned).

Verification

New tests: stale-doc removal + non-OpenVEX preservation, write-failure path naming, setup-filter skipped events + specific message, product_not_iri warn + purl control, out-of-sync warn with absent-tree and pristine controls (core), offline proxy-notice suppression. Suites: cli_parse_vex 7, e2e_embedded_vex 12, e2e_vex_vendor 13, cli_apply_silent 5, core vex 241 — all green; verified against main in an isolated worktree before opening.

🤖 Generated with Claude Code

---

Note

Medium Risk
Changes VEX JSON contracts, failure cleanup at output paths, and offline messaging—high impact for CI pipelines consuming envelopes, but core attestation rules (hash-to-afterHash, vendored precedence) are preserved and heavily tested.

Overview
VEX --json and envelopes now expose ecosystem-setup (Property 7) drops as per-purl skipped events with errorCode ecosystem_not_setup, with clearer top-level errors when every omission is that filter—not the generic “nothing to attest.” Run-level warnings[] covers non-IRI --product overrides (product_not_iri, still emitted verbatim) and vendored patches whose live node_modules tree hash-mismatches the committed artifact (vendored_tree_out_of_sync; attestation still based on .socket/vendor).

Failed runs delete a recognizably OpenVEX file at --output/--vex so CI cannot ship a prior not_affected doc; unrelated paths are untouched. write_failed names the path and operation.

Core verification adds VerifyOutcome.vendored_out_of_sync when a healthy vendored attestation sees a present installed tree with wrong bytes.

Offline / airgap: tokenless “public patch API proxy” stderr is suppressed when SOCKET_OFFLINE is set; is_offline_env() is shared across API client and telemetry instead of duplicated parses.

^{Reviewed by Cursor Bugbot for commit dfdc94b. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 2 potential issues.

^{Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issues.}

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit dfdc94b. Configure here.}