fix: scan only subschema positions, await stderr, show the whole report

Copilot review round 6.

- Share one traversal between `walk` and `declaresAnyId`. The `$id` guard
  added last round descended through EVERY object value, including
  instance data — `examples: [{"$id": "x"}]`, a `default`, a `const` —
  where `$id` is a payload key declaring no embedded resource. Reading
  one there suppressed `remote-ref` for the whole document, turning last
  round's false-positive fix into a blanket false negative. Both passes
  now go through `forEachSubschema`, driven by the same keyword tables,
  so they cannot drift about what counts as a schema position.

- Await the stderr writes. `writeSchemaLintReport` used a bare
  `process.stderr.write`, but both CLI exit paths call `process.exit()`
  as soon as the work returns, which discards anything still buffered on
  a piped stderr — truncating or losing the multi-block `--strict`
  report on exactly the redirected-output runs a CI caller uses. Added
  `awaitableError` beside the existing `awaitableLog` and awaited it.
  The test's fake defers its callback so a synchronous one cannot make
  the assertion vacuous; two existing stderr stubs that never invoked
  their callbacks were fixed in the same pass.

- Show the CLI README's sample report in full. It printed one error
  block immediately followed by the summary, a shape the formatter
  cannot produce — every finding gets a block. Captured from a real run.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UL9retfvAXRgvi6EWk4SY4
Signed-off-by: cliffhall <cliff@futurescale.com>

clients/cli/src/handlers/emit-result.ts

@@ -46,7 +46,10 @@ export async function emitResult(
     await awaitableLog(JSON.stringify(result, null, 2) + "\n");
   }
 
-  if (lint) writeSchemaLintReport(lint, args.strict === true);
+  // Awaited: the throw below (and the CLI's own exit path) reaches
+  // `process.exit()` immediately, which discards anything still buffered on a
+  // piped stderr.
+  if (lint) await writeSchemaLintReport(lint, args.strict === true);
 
   if ((result as { isError?: unknown }).isError === true) {
     throw new CliExitCodeError(

clients/cli/src/handlers/schema-lint-report.ts

@@ -5,6 +5,7 @@ import {
   summarizeFindings,
   type ToolSchemaFindings,
 } from "@inspector/core/json/schemaLint.js";
+import { awaitableError } from "../utils/awaitable-log.js";
 import type { McpResponse } from "./method-types.js";
 
 /**
@@ -47,16 +48,16 @@ export function lintListResult(result: McpResponse): ToolSchemaFindings[] {
  * lint should still learn it found something, but a multi-page report nobody
  * requested would be worse than silence.
  */
-export function writeSchemaLintReport(
+export async function writeSchemaLintReport(
   results: readonly ToolSchemaFindings[],
   strict: boolean,
-): void {
+): Promise<void> {
   if (results.length === 0) return;
   if (!strict) {
-    process.stderr.write(
+    await awaitableError(
       `Schema portability: ${summarizeFindings(results)}. Re-run with --strict for details.\n`,
     );
     return;
   }
-  process.stderr.write(`${formatSchemaLintReport(results)}\n`);
+  await awaitableError(`${formatSchemaLintReport(results)}\n`);
 }

clients/cli/src/utils/awaitable-log.ts

@@ -5,3 +5,21 @@ export function awaitableLog(logValue: string): Promise<void> {
     });
   });
 }
+
+/**
+ * The stderr twin of {@link awaitableLog}.
+ *
+ * Both CLI exit paths call `process.exit()` as soon as the work returns
+ * (`src/index.ts`, and `handleError` in `src/error-handler.ts`). When stderr
+ * is a pipe or a file rather than a TTY, `write` is asynchronous, so anything
+ * still buffered at that moment is discarded — which for a multi-block
+ * `--strict` report means a truncated or entirely missing diagnostic on
+ * exactly the redirected-output runs a CI caller uses.
+ */
+export function awaitableError(logValue: string): Promise<void> {
+  return new Promise<void>((resolve) => {
+    process.stderr.write(logValue, () => {
+      resolve();
+    });
+  });
+}