@ngockhoale/ukit 2.4.1 → 2.4.2

package/CHANGELOG.md

@@ -2,6 +2,71 @@
 
 All notable changes to UKit are documented here.
 
+## 2.4.2 - 2026-09-16
+
+Fix: the gateway resilience posture disabled the only recovery path a buffering gateway
+leaves open — the direct client-side cause of the recurring "session stands still mid-turn
+until the user interrupts and re-prompts" freeze. Live probes of the stall-class gateway on
+2026-09-16 proved the full chain: the gateway still buffers entire streams (a 16-token
+probe returned 23 SSE events in ONE body read), so a long generation is silent until it
+finishes; the non-streaming route is healthy (HTTP 200 + valid Anthropic Message); and the
+managed env shipped since 2.3.16 kept the non-streaming fallback DISABLED with a 10-minute
+stream-idle watchdog — meaning the client sat in dead air and, on abort, had no recovery
+path at all. The managed posture now flips to fail-fast-and-recover.
+
+- **Posture flip** (`src/core/gatewayResilienceEnv.js`): `CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK`
+  managed default `'1'` → `'0'` (fallback stays enabled — on a buffering gateway a
+  non-streaming POST is the one request shape without an idle watchdog), and
+  `CLAUDE_STREAM_IDLE_TIMEOUT_MS` `'600000'` → `'120000'` (a silent stream aborts after
+  2 minutes and recovers via the healthy non-streaming route instead of hanging for 10).
+  Values equal to the previously shipped defaults are UKit's own earlier writes and are
+  migrated on the next `ukit install` (new `GATEWAY_RESILIENCE_ENV_LEGACY_DEFAULTS` map +
+  `migrated` report field, backup written as usual); genuinely user-tuned values are still
+  never touched.
+- **Probe misdiagnosis fixed** (`src/core/gatewayProbe.js`): the probe 404'd healthy
+  alias-based gateways because it POSTed the built-in default `claude-sonnet-4-5`, which is
+  not provisioned there ("No active credentials for provider: claude", `model_not_found`,
+  reproduced live) while real sessions run on the `ANTHROPIC_DEFAULT_*_MODEL` lane aliases.
+  The probe now resolves `ANTHROPIC_MODEL` → `ANTHROPIC_DEFAULT_OPUS/SONNET/HAIKU_MODEL`
+  before the built-in default and reports the probed model. `anthropic-version` is now sent
+  for the Bearer scheme too (live-verified accepted), and the API key is resolved through
+  the same 3-tier order as the base URL (env → project settings → home settings) so plain
+  terminals no longer probe keyless (`resolveGatewayApiKey`).
+- **request-id re-classified** (same file, `docs/GATEWAY.md` §3): a missing `request-id`
+  on an HTTP 200 + valid Anthropic Message is an advisory hint, not a FAIL — the real
+  gateway ships no request-id even on healthy responses and sessions complete fine. The
+  Message-shape hard gate still catches the 888-byte error-envelope class from 2.3.16.
+- **Docs**: `docs/GATEWAY.md` intro/§1/§2/§3/§4/§5 updated for the fail-fast posture,
+  the 2026-09-16 buffering reconfirmation, the legacy-value migration, and the probe's
+  alias-model + key resolution.
+- **Verification**: focused suites green (gatewayProbe 14, gatewayResilienceEnv 23,
+  packageVersion 3); full `yarn test` green; live re-probe after the fix reports the alias
+  model, a healthy non-streaming route, and the still-present buffering signature.
+- **Orphan-leak class closed for the remaining hooks (2.4.1 follow-up)**: the 2.4.1 watchdog
+  shipped in exactly one hook (`skill-router.sh`); the other 18 node-spawning hooks could still
+  orphan a node grandchild to launchd when their work hung (wedged import, stalled mount — this
+  repo lives on an external volume). Every remaining hook now arms the same wall-clock
+  self-deadline: inline heredoc/`node -e` blocks carry
+  `setTimeout(() => process.exit(0), HOOK_DEADLINE_MS).unref()` directly, wrapper hooks pass
+  `UKIT_HOOK_DEADLINE_MS` (default 3000 ms) and their runtime scripts (`execution-ledger`,
+  `output-compression`, `reinject-context`, `post-edit-verify`, `pre-edit-backup`,
+  `stale-spec-check`) self-exit only when that env var is present, so CLI usage is never
+  self-killed. Lock-mutation blocks with a 5000 ms bounded wait (auto-allow-bash,
+  auto-prune-bash, reset-compact-pressure) use an 8000 ms deadline so the watchdog can never
+  fire while the mutation is legally waiting for the lock.
+  `tests/consistency/hookWatchdogCoverage.test.js` enforces the coverage for every future hook.
+- **Bounded stdin transport for the hook chain (C19 wave 1, H01)**: hook payloads no longer
+  materialize unbounded in a shell variable or the exec environment — the exec-env path that
+  made large PreToolUse payloads fail `exec` outright (E2BIG) on macOS. New
+  `templates/.claude/ukit/runtime/hook-input.sh` (`ukit_stage_hook_input` via `mktemp` +
+  byte-capped `head`, drained producer, overflow policies `truncate`/`temp-file`/`refuse`)
+  and `hook-input.mjs` (streaming reader + CLI) stage every payload to a bounded temp file;
+  all 16 node-spawning wrapper hooks now pass `INPUT_FILE`, never the payload, with a
+  bounded inline fallback when the helper is absent. Sensitive-data-guard overflow is
+  fail-closed (`refuse`, silent exit 2); 32 MiB receipts verified < 10 s.
+
+- Machine-envelope lane in the sensitive-data gate: harness-injected notifications (task-notification / system-reminder / cross-session-message tags) now deliver with a redacted labels/counts advisory instead of being blocked when they quote secret-shaped test fixtures — ends the silent "Waiting for N background agents" stall. User-typed prompts, file/grep/bash channels, allowlist and overflow-refuse posture unchanged (fail-closed, default-ON, never echoes values).
+
 ## 2.4.1 - 2026-09-14
 
 Fix: the skill-router hook could hang the session and leak an orphaned process. `skill-router.sh`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex, OpenCode, and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",

package/scripts/index/refresh-index.mjs

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import {
   buildCodeIndex,
-  isIndexStale,
+  inspectIndexStaleness,
   DEFAULT_INDEX_CACHE_MAX_AGE_MS,
 } from '../../src/index/buildIndex.js';
 
@@ -19,9 +19,10 @@ const changedFiles = changedArg
 
 const force = readBooleanFlag(args, '--force');
 const lastRefreshMs = await getLastRefreshTime(rootDir);
-const stale = force
-  ? true
-  : await isIndexStale({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+const staleness = force
+  ? null
+  : await inspectIndexStaleness({ rootDir, maxAgeMs: DEFAULT_INDEX_CACHE_MAX_AGE_MS });
+const stale = force || staleness.stale;
 
 if (!stale) {
   console.log('[index:refresh] skipped (cache fresh)');
@@ -33,7 +34,11 @@ if (!stale) {
   }
   console.log(`root: ${rootDir}`);
 } else {
-  const summary = await buildCodeIndex({ rootDir });
+  // Reuse the staleness check's discovery snapshot: one enumeration per refresh.
+  const summary = await buildCodeIndex({
+    rootDir,
+    discoverySnapshot: staleness ? staleness.snapshot : null,
+  });
 
   console.log('[index:refresh] completed');
   if (lastRefreshMs !== null) {

package/src/cli/commands/doctor.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import { pathExists, readJsonIfExists } from '../../core/fileOps.js';
 import { buildPathConfig } from '../../core/paths.js';
 import { buildRuntimePaths } from '../../core/runtimePaths.js';
@@ -10,8 +11,13 @@ import { detectProviders } from '../../context/detectProviders.js';
 import { profileSkills } from '../../core/skillProfile.js';
 import {
   resolveGatewayBaseUrl,
+  resolveGatewayApiKey,
   probeGateway,
 } from '../../core/gatewayProbe.js';
+import {
+  GATEWAY_RESILIENCE_ENV_DEFAULTS,
+  scanProfileResilienceEnv,
+} from '../../core/gatewayResilienceEnv.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway']);
@@ -28,7 +34,7 @@ export function printDoctorHelp() {
   console.log('  --gateway       Live gateway probe (streaming + non-streaming); advisory only');
 }
 
-export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
+export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir = os.homedir() }) {
   const unknownFlags = argv.filter((flag) => !KNOWN_FLAGS.has(flag));
   if (unknownFlags.length > 0) {
     throw new Error(`Unknown option: ${unknownFlags[0]}. Supported: ${SUPPORTED_FLAGS_LIST}`);
@@ -158,6 +164,40 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
   if (argv.includes('--gateway')) {
     console.log('');
     console.log('[UKit] Gateway probe (advisory — does not affect exit code):');
+
+    // Per-profile resilience scan. A session launched with
+    // `--settings ~/.claude/profile/<name>.json` bypasses ~/.claude/settings.json, so the
+    // managed keys can be missing exactly where they matter while the main settings file
+    // looks healthy. Advisory only: this never enters `checks` and never touches exitCode.
+    console.log(
+      `[UKit]   Profile resilience scan (advisory) — managed keys: ${Object.keys(GATEWAY_RESILIENCE_ENV_DEFAULTS).join(', ')}`,
+    );
+    let profileScan = null;
+    try {
+      profileScan = await scanProfileResilienceEnv({ homeDir });
+    } catch {
+      profileScan = null;
+    }
+    if (!profileScan || profileScan.scanned.length === 0) {
+      console.log('[UKit]   -  No profile files found (nothing to check).');
+    } else {
+      for (const entry of profileScan.scanned) {
+        if (entry.missing.length === 0) {
+          console.log(`[UKit]   ✓  ${entry.file}`);
+          continue;
+        }
+        console.log(
+          `[UKit]   ✗  ${entry.file} — ${entry.validJson ? `missing ${entry.missing.join(', ')}` : 'not valid JSON (assuming every managed key missing)'}`,
+        );
+        console.log(
+          `[UKit]      remedy: add ${entry.missing.join(', ')} to the profile's "env" block; see docs/GATEWAY.md`,
+        );
+      }
+      if (profileScan.compliant) {
+        console.log('[UKit]   All scanned profile files carry the managed resilience keys.');
+      }
+    }
+
     let resolved;
     try {
       resolved = await resolveGatewayBaseUrl({ projectRoot });
@@ -168,9 +208,25 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
       console.log('[UKit]   -  Gateway probe skipped — no custom gateway configured (ANTHROPIC_BASE_URL not set in env, project .claude/settings.json, or ~/.claude/settings.json).');
     } else {
       console.log(`[UKit]   baseUrl: ${resolved.baseUrl} (source: ${resolved.source})`);
+      // Plain terminals do not export ANTHROPIC_* (the key lives in settings.json env and is
+      // only injected into Claude Code sessions), so resolve the key through the same 3-tier
+      // order as the baseUrl — otherwise the probe authenticates keyless and misreports.
+      let keyInfo = null;
+      try {
+        keyInfo = await resolveGatewayApiKey({ projectRoot });
+      } catch {
+        keyInfo = null;
+      }
+      if (!keyInfo?.value) {
+        console.log('[UKit]   -  No API key found (env, project settings, home settings) — probe runs unauthenticated and may 401/404.');
+      }
       let result;
       try {
-        result = await probeGateway({ baseUrl: resolved.baseUrl });
+        result = await probeGateway({
+          baseUrl: resolved.baseUrl,
+          apiKey: keyInfo?.value ?? null,
+          apiKeySource: keyInfo?.scheme ?? null,
+        });
       } catch (error) {
         result = null;
         console.log(`[UKit]   ✗  Gateway probe threw: ${error?.message ?? String(error)}`);
@@ -178,6 +234,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [] }) {
       if (result) {
         const s = result.streaming;
         const n = result.nonStreaming;
+        console.log(`[UKit]   probed model: ${result.model}`);
         const streamingLabel = s.ok
           ? `streaming OK (events=${s.eventsReceived}, chunks=${s.chunks})`
           : `streaming FAIL (events=${s.eventsReceived}, chunks=${s.chunks}, buffered=${s.buffered}${s.error ? `, error=${s.error}` : ''})`;

package/src/core/gatewayProbe.js

@@ -22,6 +22,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const GATEWAY_DOC = 'docs/GATEWAY.md';
+const SETTINGS_RELATIVE_PROBE_PATH = path.join('.claude', 'settings.json');
 
 function safeReadFile(filePath) {
   try {
@@ -96,6 +97,53 @@ export async function resolveGatewayBaseUrl({
   return { baseUrl: null, source: null };
 }
 
+function readSettingsEnvBlock(filePath) {
+  const json = safeReadJson(filePath);
+  if (!json || typeof json !== 'object') return null;
+  const envBlock = json.env;
+  if (!envBlock || typeof envBlock !== 'object' || Array.isArray(envBlock)) return null;
+  return envBlock;
+}
+
+/**
+ * Resolves the API key the probe should authenticate with, mirroring the same 3-tier probe
+ * order as `resolveGatewayBaseUrl`: env → project `.claude/settings.json` env → home
+ * `~/.claude/settings.json` env. Plain terminals do not export ANTHROPIC_* (Claude Code
+ * injects its settings env only into its own sessions), so without the settings tiers
+ * `ukit doctor --gateway` probes keyless and misreports an auth-gated gateway.
+ *
+ * The `scheme` field mirrors `pickApiKey`'s source (`'api-key'` → x-api-key,
+ * `'auth-token'` → Authorization: Bearer) so callers can pass it straight into
+ * `probeGateway` as `apiKeySource`. Never throws.
+ *
+ * @param {{ projectRoot: string, homeDir?: string, env?: object }} options
+ * @returns {{ value: string|null, scheme: 'api-key'|'auth-token'|null,
+ *             source: 'env'|'claude-settings'|null }}
+ */
+export function resolveGatewayApiKey({
+  projectRoot,
+  homeDir = os.homedir(),
+  env = process.env,
+} = {}) {
+  const envKey = pickApiKey(env ?? {});
+  if (envKey) {
+    return { value: envKey.value, scheme: envKey.source, source: 'env' };
+  }
+  const settingsPaths = [
+    ...(projectRoot ? [path.join(projectRoot, SETTINGS_RELATIVE_PROBE_PATH)] : []),
+    path.join(homeDir, SETTINGS_RELATIVE_PROBE_PATH),
+  ];
+  for (const settingsPath of settingsPaths) {
+    const envBlock = readSettingsEnvBlock(settingsPath);
+    if (!envBlock) continue;
+    const key = pickApiKey(envBlock);
+    if (key) {
+      return { value: key.value, scheme: key.source, source: 'claude-settings' };
+    }
+  }
+  return { value: null, scheme: null, source: null };
+}
+
 function pickApiKey(envLike) {
   if (!envLike || typeof envLike !== 'object') return null;
   // Source matters: ANTHROPIC_API_KEY is sent by Claude Code as `x-api-key`, while
@@ -112,7 +160,16 @@ function pickApiKey(envLike) {
 
 function pickModel(envLike) {
   if (!envLike || typeof envLike !== 'object') return null;
-  return pickString(envLike.ANTHROPIC_MODEL);
+  // ANTHROPIC_MODEL wins, then the per-lane alias mappings Claude Code itself resolves
+  // (2026-09-16 live evidence: alias-based gateways provision ONLY the mapped lane models;
+  // probing the built-in default `claude-sonnet-4-5` returned HTTP 404 `model_not_found` /
+  // "No active credentials for provider: claude" on a gateway whose real sessions work).
+  return pickString(
+    envLike.ANTHROPIC_MODEL,
+    envLike.ANTHROPIC_DEFAULT_OPUS_MODEL,
+    envLike.ANTHROPIC_DEFAULT_SONNET_MODEL,
+    envLike.ANTHROPIC_DEFAULT_HAIKU_MODEL,
+  );
 }
 
 // Minimal VALID Anthropic Messages API body. The probe only measures transport shape
@@ -132,11 +189,14 @@ function buildRequestBody({ stream, model }) {
 //   * ANTHROPIC_API_KEY     -> x-api-key (Anthropic-native)
 //   * ANTHROPIC_AUTH_TOKEN  -> Authorization: Bearer (OpenAI-style / proxy gateways)
 // Without this split, token-auth gateways 401 the probe even when transport shape is
-// valid (Reviewer Round-1 important finding #3).
+// valid (Reviewer Round-1 important finding #3). `anthropic-version` is sent for BOTH
+// schemes: it is required by Anthropic-native gateways and ignored by OpenAI-style proxies
+// (2026-09-16 live evidence: the token-auth UNIC gateway returns 200 + valid Message with
+// the header present).
 function buildAuthHeaders(keyValue, keySource) {
   if (!keyValue) return {};
   if (keySource === 'auth-token') {
-    return { Authorization: `Bearer ${keyValue}` };
+    return { Authorization: `Bearer ${keyValue}`, 'anthropic-version': '2023-06-01' };
   }
   // Default to the Anthropic-native scheme — covers explicit apiKey arg and
   // ANTHROPIC_API_KEY env (the dominant case).
@@ -161,6 +221,62 @@ function parseSseEvents(text) {
   return count;
 }
 
+// TASK-010 (error-body surfacing): on a non-OK response the gateway body often carries the
+// operator-actionable cause (2026-09-16 live evidence: HTTP 404 + `{"error":{"message":"No
+// active credentials for provider: anthropic"}}`). The read is bounded and the surfaced
+// message is capped at 300 chars (PLAN §3/§4 contract) so a giant HTML error page can never
+// flood the doctor output.
+const ERROR_DETAIL_MAX_CHARS = 300;
+const ERROR_BODY_MAX_CHARS = 4096;
+
+async function readBodyTextBounded(response) {
+  const body = response?.body;
+  if (!body || typeof body.getReader !== 'function') return '';
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let text = '';
+  try {
+    while (text.length < ERROR_BODY_MAX_CHARS) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      if (value) text += decoder.decode(value, { stream: true });
+    }
+  } catch {
+    // A failing/unreadable error body must never turn into a probe crash — fall back to
+    // whatever was collected so far (possibly empty).
+  } finally {
+    try {
+      reader.releaseLock();
+    } catch {
+      // reader may already be released
+    }
+  }
+  return text;
+}
+
+/**
+ * Extracts the gateway error message from a non-OK response body:
+ * `JSON.parse(text).error.message`, truncated to `ERROR_DETAIL_MAX_CHARS`. Returns `null`
+ * when the body is missing, unreadable, non-JSON, or carries no error message — callers
+ * then leave `errorDetail` unset and keep today's `HTTP <status>` wording. Never throws.
+ */
+async function extractErrorDetail(response) {
+  const text = await readBodyTextBounded(response);
+  if (!text) return null;
+  let parsed = null;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const message =
+    parsed && typeof parsed === 'object' && typeof parsed?.error?.message === 'string'
+      ? parsed.error.message
+      : null;
+  if (!message) return null;
+  return message.slice(0, ERROR_DETAIL_MAX_CHARS);
+}
+
 /**
  * Streaming probe: posts `stream: true` and counts SSE frames + distinct body reads.
  *
@@ -169,7 +285,8 @@ function parseSseEvents(text) {
  * buffering gateway dumps everything in one read.
  *
  * @returns {Promise<{ ok: boolean, eventsReceived: number, firstEventMs: number|null,
- *                    chunks: number, buffered: boolean, error?: string }>}
+ *                    chunks: number, buffered: boolean, error?: string,
+ *                    errorDetail?: string|null }>}
  */
 async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
   const controller = new AbortController();
@@ -190,6 +307,7 @@ async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, t
         chunks: 0,
         buffered: false,
         error: `HTTP ${response?.status ?? 'unknown'}`,
+        errorDetail: await extractErrorDetail(response),
       };
     }
     const body = response.body;
@@ -278,7 +396,8 @@ async function runStreamingProbe({ url, headers, body: requestBody, fetchImpl, t
  * gateway error envelope slip through Claude Code's retry path and kill the user's turn.
  *
  * @returns {Promise<{ ok: boolean, httpOk: boolean, isAnthropicMessage: boolean,
- *                    requestIdPresent: boolean, bodyBytes: number|null, error?: string }>}
+ *                    requestIdPresent: boolean, bodyBytes: number|null, error?: string,
+ *                    errorDetail?: string|null }>}
  */
 async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl, timeoutMs }) {
   const controller = new AbortController();
@@ -300,6 +419,7 @@ async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl
         requestIdPresent,
         bodyBytes: null,
         error: `HTTP ${response?.status ?? 'unknown'}`,
+        errorDetail: await extractErrorDetail(response),
       };
     }
     const body = response.body;
@@ -341,7 +461,12 @@ async function runNonStreamingProbe({ url, headers, body: requestBody, fetchImpl
       typeof parsed === 'object' &&
       parsed.type === 'message' &&
       Array.isArray(parsed.content);
-    const ok = isAnthropicMessage && requestIdPresent;
+    // 2026-09-16 live re-classification: the real UNIC gateway returns HTTP 200 + a valid
+    // Anthropic Message with NO request-id header, and real sessions complete fine — the
+    // hard pass/fail gate is the Message shape (which still catches the 888-byte error-
+    // envelope class). A missing request-id is reported as an advisory hint instead of a
+    // hard fail; see GATEWAY_DOC §3.
+    const ok = isAnthropicMessage;
     return {
       ok,
       httpOk: true,
@@ -406,11 +531,12 @@ export async function probeGateway({
   if (!streaming.ok) {
     if (streaming.buffered) {
       hints.push(
-        `Set CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000 in .claude/settings.json env — gateway appears to buffer the entire stream; see ${GATEWAY_DOC}.`,
+        `Gateway buffers the entire stream (the stall signature). Managed posture: keep CLAUDE_STREAM_IDLE_TIMEOUT_MS low so the idle watchdog fires, and keep the non-streaming fallback ENABLED so the aborted stream recovers via a non-streaming retry; see ${GATEWAY_DOC}.`,
       );
     } else if (streaming.error) {
+      const gatewayCause = streaming.errorDetail ? ` — ${streaming.errorDetail}` : '';
       hints.push(
-        `Streaming probe failed: ${streaming.error} — see ${GATEWAY_DOC}.`,
+        `Streaming probe failed: ${streaming.error}${gatewayCause} (probed model: ${effectiveModel}) — see ${GATEWAY_DOC}.`,
       );
     } else {
       hints.push(
@@ -421,21 +547,23 @@ export async function probeGateway({
   if (!nonStreaming.ok) {
     if (nonStreaming.httpOk && !nonStreaming.isAnthropicMessage) {
       hints.push(
-        `Set CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 in .claude/settings.json env — non-streaming route returned JSON but not an Anthropic Message; see ${GATEWAY_DOC}.`,
-      );
-    } else if (nonStreaming.httpOk && !nonStreaming.requestIdPresent) {
-      hints.push(
-        `Gateway must set the request-id (or anthropic-request-id) response header — see ${GATEWAY_DOC}.`,
+        `Non-streaming route returned JSON but not an Anthropic Message — leave CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1 (fallback must stay off); see ${GATEWAY_DOC}.`,
       );
     } else if (nonStreaming.error) {
+      const gatewayCause = nonStreaming.errorDetail ? ` — ${nonStreaming.errorDetail}` : '';
       hints.push(
-        `Non-streaming probe failed: ${nonStreaming.error} — see ${GATEWAY_DOC}.`,
+        `Non-streaming probe failed: ${nonStreaming.error}${gatewayCause} (probed model: ${effectiveModel}) — see ${GATEWAY_DOC}.`,
       );
     } else {
       hints.push(`Non-streaming probe failed — see ${GATEWAY_DOC}.`);
     }
   }
+  if (nonStreaming.httpOk && nonStreaming.isAnthropicMessage && !nonStreaming.requestIdPresent) {
+    hints.push(
+      `Gateway did not set a request-id (or anthropic-request-id) header — advisory only, diagnosability is degraded but transport works; see ${GATEWAY_DOC}.`,
+    );
+  }
 
   const verdict = streaming.ok && nonStreaming.ok ? 'pass' : 'fail';
-  return { streaming, nonStreaming, verdict, hints };
+  return { streaming, nonStreaming, verdict, hints, model: effectiveModel };
 }