Report the unresolved-org proxy run on every get --json and vex --json path (#648)

get <uuid> --json (agent save, paid_required, not_found) and the search
path's not_found / paid_required envelopes now carry the
api_auth_fallback warning like the other get paths. Standalone
vex --json notes it when it built the run's client itself; a host that
seeded its client reports it and adds no duplicate. Human mode still
warns once, from client construction. Tests pin the warning count and
the new JSON entries.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

Author: mikolalysenko

crates/socket-patch-cli/CLI_CONTRACT.md

@@ -329,7 +329,7 @@ Contract details:
 * **JSON success surface**: `apply` adds a top-level `vex` object to its envelope; `scan` adds a top-level `vex` key to its result. Both carry `{ path, statements, format: "openvex-0.2.0" }`.
 * `apply`'s no-manifest early exit (the `noManifest` success no-op; v5.0: its human line is `No patch manifest found; nothing to apply.` — it names the missing `.socket/manifest.json`, not the folder, since `.socket/` may legitimately hold vendored state) and `vendor`'s (`No manifest found, nothing to vendor.` — a project with hosted pins ejects instead, v5.0) still generate the document from the lockfiles and the vendor ledger (manifest-less VEX: hosted / vendored checkouts carry no manifest). Nothing referenced anywhere keeps the calm exit 0 (a stale document at the path is removed; `--json` carries any discovery diagnostics in `warnings[]`); any other VEX failure fails the command with exit 1 — including a run whose only candidates are omitted `record_unavailable` (an `--offline` run over a lockfile-wired checkout with no local records), so an ambient `SOCKET_VEX` there fails the install. `--dry-run` skips generation on both, and so does `apply --check` — it stays read-only and offline-safe, leaving the output path untouched. `scan` has no such early exit: with no manifest and nothing wired anywhere its `--vex` fails with `manifest_not_found`.
 * **Stale-doc removal (v3.5)**: a run that ends in a VEX error removes a recognizably-OpenVEX file (JSON whose `@context` names openvex.dev) already sitting at the output path — a pipeline reusing one path can never ship yesterday's attestation for a now-unpatched tree. Unrelated files at the path are never touched; a mid-write partial that no longer parses as JSON is left for downstream parsers to reject loudly.
-* **Additive warnings (v3.5)**: `product_not_iri` (the `--product`/`--vex-product` override is neither a `pkg:` purl nor an absolute IRI; honored verbatim, warned) and `vendored_tree_out_of_sync` (a healthy vendored attestation stands on the committed artifact + lock wiring while the PRESENT installed tree hash-mismatches the patched bytes — run the package manager's install (for a project with Hatch environments the detail also names `hatch env remove <env>`, since Hatch keeps an installed release); the attestation itself is unchanged). Both ride stderr in human mode and `warnings[]` in the standalone `vex --json` envelope. Same channel for `product_multiple_manifests` (auto-detect found several project manifests and names the one it used), `vex_stale_doc_removed` (the stale-doc removal above happened), the manifest-less plan's advisories — `vex_wiring_conflict` (the lockfiles wire a package to different patches: which files, which uuids, how to fix it), `vex_record_superseded` (a recorded patch replaced by the lockfile-wired one), `vex_claim_unwired` (a ledger claim whose patch the lockfiles still mention, but not as wiring), `vex_record_offline` / `vex_record_not_found` / `vex_record_fetch_failed` (why a lockfile-wired patch has no record — the detail behind a `record_unavailable` skip) and `api_auth_fallback` (the public proxy served free patches only: the authenticated API refused the credentials, `get` / `scan`'s warning text; or, v5.0, a token was set with no `--org` / `SOCKET_ORG_SLUG` / socket-cli `defaultOrg` and the org could not be resolved, so the whole run used the proxy — `scan --json` and `get --json` also report this case in their top-level `warnings[]`) — and, standalone only, `org_looks_like_path` (`-o`/`--org` given a file-shaped value — `-O` is `--output`). The standalone error envelope carries `warnings[]` too. An embedded `--vex` that fails also folds each omitted patch into the host command's `warnings[]` as `vex_omitted` (`<purl>: <why> (<errorCode>)` — standalone `vex` lists them as `skipped` events), and `--silent` lists them as `omitted: <purl> (<errorCode>)` lines under the error. A corrupt `.socket/vendor/state.json` is no longer degraded with a warning: every form of vex fails with `vendor_ledger_corrupt` (see the error-code table). A malformed pre-v5 `redirect-state.json` is, as of v5.0, only the `redirect_ledger_corrupt` warning (hosted mode keeps no ledger; the file is an optional migration record source).
+* **Additive warnings (v3.5)**: `product_not_iri` (the `--product`/`--vex-product` override is neither a `pkg:` purl nor an absolute IRI; honored verbatim, warned) and `vendored_tree_out_of_sync` (a healthy vendored attestation stands on the committed artifact + lock wiring while the PRESENT installed tree hash-mismatches the patched bytes — run the package manager's install (for a project with Hatch environments the detail also names `hatch env remove <env>`, since Hatch keeps an installed release); the attestation itself is unchanged). Both ride stderr in human mode and `warnings[]` in the standalone `vex --json` envelope. Same channel for `product_multiple_manifests` (auto-detect found several project manifests and names the one it used), `vex_stale_doc_removed` (the stale-doc removal above happened), the manifest-less plan's advisories — `vex_wiring_conflict` (the lockfiles wire a package to different patches: which files, which uuids, how to fix it), `vex_record_superseded` (a recorded patch replaced by the lockfile-wired one), `vex_claim_unwired` (a ledger claim whose patch the lockfiles still mention, but not as wiring), `vex_record_offline` / `vex_record_not_found` / `vex_record_fetch_failed` (why a lockfile-wired patch has no record — the detail behind a `record_unavailable` skip) and `api_auth_fallback` (the public proxy served free patches only: the authenticated API refused the credentials, `get` / `scan`'s warning text; or, v5.0, a token was set with no `--org` / `SOCKET_ORG_SLUG` / socket-cli `defaultOrg` and the org could not be resolved, so the whole run used the proxy — standalone `vex --json` carries it when it fetched records, and `scan --json` / `get --json` report this case in their top-level `warnings[]`) — and, standalone only, `org_looks_like_path` (`-o`/`--org` given a file-shaped value — `-O` is `--output`). The standalone error envelope carries `warnings[]` too. An embedded `--vex` that fails also folds each omitted patch into the host command's `warnings[]` as `vex_omitted` (`<purl>: <why> (<errorCode>)` — standalone `vex` lists them as `skipped` events), and `--silent` lists them as `omitted: <purl> (<errorCode>)` lines under the error. A corrupt `.socket/vendor/state.json` is no longer degraded with a warning: every form of vex fails with `vendor_ledger_corrupt` (see the error-code table). A malformed pre-v5 `redirect-state.json` is, as of v5.0, only the `redirect_ledger_corrupt` warning (hosted mode keeps no ledger; the file is an optional migration record source).
 
 ### VEX provenance markers (contract)
 

crates/socket-patch-cli/src/commands/get.rs

@@ -2805,6 +2805,7 @@ pub async fn run(args: GetArgs) -> i32 {
                         &patch.uuid,
                         fallback_to_proxy,
                         &telemetry,
+                        &org_warnings,
                     )
                     .await;
                 }
@@ -2843,7 +2844,7 @@ pub async fn run(args: GetArgs) -> i32 {
                 return match mode {
                     // Save to manifest and apply in place.
                     super::scan::ScanMode::Agent => {
-                        save_and_apply_patch(&args, &api_client, &patch).await
+                        save_and_apply_patch(&args, &api_client, &patch, &org_warnings).await
                     }
                     super::scan::ScanMode::Hosted => {
                         let selected = vec![search_result_from_response(&patch)];
@@ -2875,6 +2876,7 @@ pub async fn run(args: GetArgs) -> i32 {
                     &args.identifier,
                     fallback_to_proxy,
                     &telemetry,
+                    &org_warnings,
                 )
                 .await;
             }
@@ -2887,7 +2889,9 @@ pub async fn run(args: GetArgs) -> i32 {
                 )
                 .await;
                 if args.common.json {
-                    print_json(&empty_result_json("not_found"));
+                    let mut result = empty_result_json("not_found");
+                    fold_narrowing_into_result(&mut result, &[], &org_warnings);
+                    print_json(&result);
                 } else if !args.common.silent {
                     println!("No patch found with UUID: {}", args.identifier);
                 }
@@ -3000,7 +3004,9 @@ pub async fn run(args: GetArgs) -> i32 {
 
     if search_response.patches.is_empty() {
         if args.common.json {
-            print_json(&empty_result_json("not_found"));
+            let mut result = empty_result_json("not_found");
+            fold_narrowing_into_result(&mut result, &[], &org_warnings);
+            print_json(&result);
         } else if !args.common.silent {
             println!("No patches found for {}: {}", id_type, args.identifier);
         }
@@ -3019,7 +3025,7 @@ pub async fn run(args: GetArgs) -> i32 {
 
     if accessible.is_empty() {
         if args.common.json {
-            print_json(&serde_json::json!({
+            let mut result = serde_json::json!({
                 "status": "paid_required",
                 "found": search_response.patches.len(),
                 "downloaded": 0,
@@ -3029,7 +3035,9 @@ pub async fn run(args: GetArgs) -> i32 {
                     "uuid": p.uuid,
                     "tier": p.tier,
                 })).collect::<Vec<_>>(),
-            }));
+            });
+            fold_narrowing_into_result(&mut result, &[], &org_warnings);
+            print_json(&result);
         } else if !args.common.silent {
             let all: Vec<&PatchSearchResult> = search_response.patches.iter().collect();
             if id_type == IdentifierType::Package && !quiet {
@@ -3309,20 +3317,23 @@ async fn report_paid_required_uuid(
     patch_id: &str,
     fallback_to_proxy: bool,
     telemetry: &TelemetryAuth,
+    org_warnings: &[(String, String)],
 ) -> i32 {
     track_patch_fetch_failed(patch_id, "paid_required", fallback_to_proxy, telemetry).await;
     if args.common.json {
         let mut record = serde_json::json!({ "uuid": patch_id, "tier": "paid" });
         if let Some(purl) = purl {
             record["purl"] = serde_json::json!(purl);
         }
-        print_json(&serde_json::json!({
+        let mut result = serde_json::json!({
             "status": "paid_required",
             "found": 1,
             "downloaded": 0,
             "applied": 0,
             "patches": [record],
-        }));
+        });
+        fold_narrowing_into_result(&mut result, &[], org_warnings);
+        print_json(&result);
     } else if !args.common.silent {
         let name = purl.map(|p| normalize_purl(p).into_owned());
         println!(
@@ -3514,7 +3525,12 @@ async fn save_patch_record(
 /// `--save-only`, apply it — under ONE apply lock, on the `client` the
 /// fetch used (a fresh client could re-hit the 401/403 its proxy fallback
 /// just recovered from).
-async fn save_and_apply_patch(args: &GetArgs, client: &ApiClient, patch: &PatchResponse) -> i32 {
+async fn save_and_apply_patch(
+    args: &GetArgs,
+    client: &ApiClient,
+    patch: &PatchResponse,
+    org_warnings: &[(String, String)],
+) -> i32 {
     // Same "errors only" gate as `run` — informational prints respect
     // `--silent`; errors and the JSON envelope do not.
     let quiet = args.common.json || args.common.silent;
@@ -3657,6 +3673,7 @@ async fn save_and_apply_patch(args: &GetArgs, client: &ApiClient, patch: &PatchR
         if !warnings.is_empty() {
             result_json["warnings"] = serde_json::json!(warnings);
         }
+        fold_narrowing_into_result(&mut result_json, &[], org_warnings);
         print_json(&result_json);
     }
 

crates/socket-patch-cli/src/commands/vex_sources.rs

@@ -187,8 +187,9 @@ pub(crate) const NOTE_RECORD_OFFLINE: &str = "vex_record_offline";
 pub(crate) const NOTE_RECORD_NOT_FOUND: &str = "vex_record_not_found";
 /// A record fetch failed (transport, server, paid-only, ...).
 pub(crate) const NOTE_RECORD_FETCH_FAILED: &str = "vex_record_fetch_failed";
-/// The authenticated API refused the credentials; the public proxy served
-/// the retry (free patches only) — `get` / `scan`'s fallback.
+/// The public proxy served free patches only: the authenticated API refused
+/// the credentials (`get` / `scan`'s fallback), or a token was set but its
+/// org could not be resolved, so the run's client is on the proxy.
 pub(crate) const NOTE_API_AUTH_FALLBACK: &str = "api_auth_fallback";
 
 /// Omission tag and note: a hosted Gradle pin is wired, but a lock file
@@ -937,10 +938,20 @@ async fn fetch_records(
     }
     let overrides = common.api_client_overrides();
     // The run's client: the host's, or built here once (standalone `vex`).
+    let built_here = !api_client.initialized();
     let mut client = api_client
         .get_or_init(|| async { get_api_client_with_overrides(overrides.clone()).await.0 })
         .await
         .clone();
+    // A client built here whose org could not be resolved put the run on
+    // the proxy. Its construction already warned on stderr, so only the
+    // `--json` envelope needs the note (a host that seeded its client
+    // reports this itself).
+    if built_here && common.json {
+        if let Some(reason) = client.org_unresolved() {
+            notes.push(note(NOTE_API_AUTH_FALLBACK, reason.to_string()));
+        }
+    }
     let mut use_public_proxy = client.uses_public_proxy();
     let mut pending: Vec<String> = uuids.to_vec();
     // Each view is a heavy response: say what the run is waiting on (a live
@@ -1178,6 +1189,91 @@ mod tests {
         assert!(out.contains_key(U1) && out.contains_key(U2), "{out:?}");
     }
 
+    /// Standalone `vex --json` (no host client): a token whose org cannot
+    /// be resolved builds a proxy client here, the records come from the
+    /// proxy, and the envelope gets one `api_auth_fallback` note. A client
+    /// seeded by a host adds no note (the host reports it).
+    #[tokio::test]
+    #[serial_test::serial]
+    async fn unresolved_org_client_built_here_notes_the_fallback_once() {
+        use wiremock::matchers::{method, path as wm_path, path_regex};
+        use wiremock::{Mock, MockServer, ResponseTemplate};
+
+        let keys = ["SOCKET_ORG_SLUG", "SOCKET_OFFLINE", "SOCKET_NO_CONFIG"];
+        let saved: Vec<(&str, Option<String>)> = keys
+            .into_iter()
+            .map(|k| (k, std::env::var(k).ok()))
+            .collect();
+        std::env::remove_var("SOCKET_ORG_SLUG");
+        std::env::remove_var("SOCKET_OFFLINE");
+        std::env::set_var("SOCKET_NO_CONFIG", "1");
+
+        let mock = MockServer::start().await;
+        Mock::given(method("GET"))
+            .and(wm_path("/v0/organizations"))
+            .respond_with(ResponseTemplate::new(500))
+            .expect(1)
+            .mount(&mock)
+            .await;
+        Mock::given(path_regex("^/v0/orgs/"))
+            .respond_with(ResponseTemplate::new(500))
+            .expect(0)
+            .mount(&mock)
+            .await;
+        Mock::given(method("GET"))
+            .and(wm_path(format!("/patch/view/{U1}")))
+            .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!({
+                "uuid": U1,
+                "purl": "pkg:npm/vexorg@1.0.0",
+                "publishedAt": "2026-01-01T00:00:00Z",
+                "files": {},
+                "vulnerabilities": {},
+                "description": "",
+                "license": "MIT",
+                "tier": "free",
+            })))
+            .mount(&mock)
+            .await;
+
+        let tmp = tempfile::tempdir().unwrap();
+        let common = GlobalArgs {
+            cwd: tmp.path().to_path_buf(),
+            json: true,
+            silent: true,
+            api_url: Some(mock.uri()),
+            api_token: Some("sktsec_placeholder_value_for_tests_api".into()),
+            proxy_url: Some(mock.uri()),
+            ..GlobalArgs::default()
+        };
+        let run_client = RunApiClient::new();
+        let mut notes: Vec<PlanNote> = Vec::new();
+        let out = fetch_records(&common, &run_client, &[U1.to_string()], &mut notes).await;
+        // A second fetch on the same run reuses the client: no second
+        // resolution (the mock's `.expect(1)`) and no second note.
+        let _ = fetch_records(&common, &run_client, &[U1.to_string()], &mut notes).await;
+
+        for (k, v) in saved {
+            match v {
+                Some(v) => std::env::set_var(k, v),
+                None => std::env::remove_var(k),
+            }
+        }
+
+        assert!(out.contains_key(U1), "{out:?}");
+        let fallbacks: Vec<_> = notes
+            .iter()
+            .filter(|n| n.code == NOTE_API_AUTH_FALLBACK)
+            .collect();
+        assert_eq!(fallbacks.len(), 1, "{notes:?}");
+        assert!(
+            fallbacks[0]
+                .detail
+                .contains("Pass --org or set SOCKET_ORG_SLUG"),
+            "{}",
+            fallbacks[0].detail
+        );
+    }
+
     fn discovery(refs: Vec<PatchedRef>) -> Discovery {
         let mut d = Discovery::default();
         for r in refs {

crates/socket-patch-cli/tests/cli/covgap_api_client.rs

@@ -104,6 +104,13 @@ fn assert_hash_token_warnings(stderr: &str, mode: &str) {
         ),
         "[{mode}] the warning must say what the run does and how to fix it; stderr={stderr}"
     );
+    assert_eq!(
+        stderr
+            .matches("Could not determine your organization")
+            .count(),
+        1,
+        "[{mode}] the run warns once; stderr={stderr}"
+    );
     assert!(
         stderr.contains("Hint: --api-token starts with `sha512-`"),
         "[{mode}] the 401 + hash-shaped token must trigger the stored-hash \
@@ -157,6 +164,17 @@ async fn get_with_hash_shaped_token_under_json_keeps_warnings_and_envelope() {
         "404 after failed org resolution maps to not_found, got: {v}"
     );
     assert_eq!(v["found"], 0, "not_found envelope reports zero found: {v}");
+    // The UUID path reports the startup downgrade in `warnings[]` too.
+    let warnings = v["warnings"]
+        .as_array()
+        .unwrap_or_else(|| panic!("no warnings[]: {v}"));
+    let prefix = "(api_auth_fallback) Could not determine your organization";
+    assert!(
+        warnings
+            .iter()
+            .any(|w| w.as_str().is_some_and(|w| w.starts_with(prefix))),
+        "api_auth_fallback missing from warnings[]: {v}"
+    );
 }
 
 /// `--silent` is "errors only": the same misconfiguration prints neither

docs/migrating-to-v5.md

@@ -31,8 +31,8 @@ existing scripts against the new CLI; the [changelog](../CHANGELOG.md) and
 - A token whose organization cannot be resolved no longer queries
   `/v0/orgs/default/…`. When no `--org`, `SOCKET_ORG_SLUG` or socket-cli
   `defaultOrg` is set and `GET /v0/organizations` fails, the whole run uses the
-  public proxy anonymously (free patches only) and warns once; `scan --json` and
-  `get --json` report it as `api_auth_fallback` in `warnings[]`. Set `--org` or
+  public proxy anonymously (free patches only) and warns once; `scan --json`,
+  `get --json` and `vex --json` report it as `api_auth_fallback` in `warnings[]`. Set `--org` or
   `SOCKET_ORG_SLUG` to get org patches. The org is resolved once per run, so an
   embedded `--vex` no longer resolves it again.