@ngockhoale/ukit 3.0.12 → 3.1.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to UKit are documented here.
 
+## 3.1.0 - 2026-09-26
+
+- **Flight recorder — Data Foundation wave (cycle C81)** — the observability pipeline grows from record/segment plumbing into a full local diagnostics surface; still opt-in behind `observability.stage` (default `off`, `off→shadow→canary→default` per seam, absolute kill switch):
+  - **Envelope v1.1 + sampling**: additive `agent_id`/`project_instance_id`/`sampling` stamp fields and new semantic names (`memory.write`, `memory.retrieved`, `retrieval.query`, `outcome.observed`, `anomaly.detected`, `telemetry.crashed`); `observability.sampling` seeded-bucket keep-rates per importance level with `SAMPLED_OUT`/`CONFIG_INVALID` reason codes — `critical` is never sampled.
+  - **Segments**: sealed segments compress to `.jsonl.zst` on Node ≥ 22.15 (plain `.jsonl` otherwise); readers, recovery, and quarantine handle both transparently.
+  - **Crash capture + lifecycle**: bounded `crashes/crash-<boot>-<seq>.json` capture on uncaughtException/unhandledRejection/SIGINT/SIGTERM (≤10 files, FIFO, never throws); `getRecorder` memoized per (root, boot) with interval flush and deadline-bounded exit flush.
+  - **Ingestion + instrumentation**: `ingestStoredTelemetry` pulls stored hook telemetry, route/decision ledgers, and memory/context items into segments; agentRuntime and memory/retrieval paths emit real trace/span ids with honest `UNKNOWN` resource provenance.
+  - **CLI**: `ukit telemetry` — `status`, `collect`, `digest`, `export-support`, `import <path>`, `evaluate` (`--json` on status/digest/evaluate; exit 0/2, usage 1). `ukit doctor` gains a flight-recorder section (stage, segments, support lag, crashes — `unknown` when unavailable). `ukit feedback` emits `outcome.observed`.
+  - **Support view**: `Documents/UKit Support` provisioned at install (never deleted by uninstall); support refresh is scheduled after collect and on the lifecycle interval, with crash list, anomaly section, and freshness lag stamped in `SUMMARY.md`; `import` validates bundles (manifest/checksums/traversal/decompression bounds).
+  - **Anomaly detection + evaluation**: deterministic detectors (duration outliers, retry storms, cache-miss/drop-rate spikes, verification-failure clusters) produce `anomaly.detected` records with evidence refs; `runEvaluation` dispatches to a configured `observability.evaluator` provider — `skipped/no-provider` is the honest default — and appends validated findings to the optimization KB; expanded golden corpus with `--anomalies` bench flag.
+  - **Docs**: `docs/OBSERVABILITY.md` — stages, privacy contract (what is never recorded), the support-folder zip-send flow, CLI and config reference.
+
 ## 3.0.12 - 2026-09-26
 
 - Re-publish of the 3.0.11 content: npm staged-publish left 3.0.11 in limbo (E409 "previously staged version"); re-published as 3.0.12 — same tree, version bump only.

package/README.md

@@ -95,6 +95,7 @@ Maintainer/debug commands (advanced workflows, not team onboarding):
 - `ukit memory ...` — inspect/export/forget shared memory items
 - `ukit update` — upgrade the global UKit CLI to the latest published version
 - `ukit index ...` — run repo indexing/query/triage tools directly
+- `ukit telemetry ...` — inspect the opt-in local flight recorder (segments, digests, `Documents/UKit Support` export) — see [docs/OBSERVABILITY.md](docs/OBSERVABILITY.md)
 - `ukit build index` — alias for `ukit index build`
 
 ## Development

package/manifests/documentation.yaml

@@ -296,6 +296,18 @@ entries:
     archive_policy: date-rotate
     budget: { max_lines: 150, enforcement: error }
     notes: enforcement flipped to error by TASK-005 (2026-09-19); TASK-217 audit — actual 83 lines (~55% headroom), value kept
+  - id: docs-observability
+    path: docs/OBSERVABILITY.md
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: docs/OBSERVABILITY.md
+    merge_strategy: none
+    load_policy: on-demand
+    validation: [manual]
+    archive_policy: never
+    notes: 'registered by C81 fix round 1 — Data Foundation/Flight Recorder surface doc'
+
   - id: docs-worklog
     path: docs/WORKLOG.md
     class: runtime

package/package.json

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

package/scripts/bench/data-foundation.mjs

@@ -9,6 +9,15 @@
 //                a fixed-seed variance report (TASK-014).
 //   --perturb    Inject seeded synthetic mutations into corpus summaries and measure
 //                detection through computeFingerprint/detectOpportunities (TASK-002).
+//   --anomalies  Replay the golden cases, summarize each run, and report anomaly
+//                detection counts per case (TASK-015). Degrades honestly to
+//                `detector: 'unavailable'` while analytics/anomalies.js
+//                (TASK-011) does not exist — never a stub detector.
+//
+// Flags run in argument order; the exit code is the first non-zero code.
+// --evaluate exits 1 by design while the corpus carries expected-negative
+// strata (a fail verdict is the honest scorecard), so a combined invocation
+// ending in --evaluate exits 1.
 //
 // The corpus is a synthetic, seeded fixture: no real user content. Records are
 // envelope-shaped per SPEC §7 (DF-FR01) but intentionally NOT schema-validated —
@@ -77,10 +86,9 @@ function makeCtx() {
     tokens: (lo, hi) => lo + Math.floor(rand() * (hi - lo + 1)),
   };
 }
-
-function record(ctx, { semanticName, traceId, spanId, parentSpanId, executionId, importance, privacyClass, payload, dtMs }) {
+function record(ctx, { semanticName, traceId, spanId, parentSpanId, executionId, agentId, importance, privacyClass, payload, dtMs }) {
   const t = ctx.tick(dtMs);
-  return {
+  const rec = {
     record_type: 'fact',
     semantic_name: semanticName,
     schema_version: SCHEMA_VERSION,
@@ -100,9 +108,13 @@ function record(ctx, { semanticName, traceId, spanId, parentSpanId, executionId,
     privacy_class: clampToRegistryFloor(semanticName, privacyClass),
     payload,
   };
+  // DF2-FR01 v1.1: agent_id is the optional multi-agent correlation field —
+  // emitted only when the scenario declares one.
+  if (typeof agentId === 'string' && agentId.length > 0) rec.agent_id = agentId;
+  return rec;
 }
 
-function execSpan(ctx, traceId, executionId, privacyClass) {
+function execSpan(ctx, traceId, executionId, privacyClass, agentId) {
   const spanId = ctx.spanId();
   return {
     spanId,
@@ -112,6 +124,7 @@ function execSpan(ctx, traceId, executionId, privacyClass) {
       spanId,
       parentSpanId: null,
       executionId,
+      agentId,
       importance: 'normal',
       privacyClass,
       payload: { operation: 'task', duration_ms: null },
@@ -120,7 +133,7 @@ function execSpan(ctx, traceId, executionId, privacyClass) {
   };
 }
 
-function modelAttempt(ctx, { traceId, parentSpanId, executionId, attemptIndex, status, resource, privacyClass, extra = {} }) {
+function modelAttempt(ctx, { traceId, parentSpanId, executionId, agentId, attemptIndex, status, resource, privacyClass, extra = {} }) {
   const spanId = ctx.spanId();
   const started = record(ctx, {
     semanticName: 'model.started',
@@ -128,6 +141,7 @@ function modelAttempt(ctx, { traceId, parentSpanId, executionId, attemptIndex, s
     spanId,
     parentSpanId,
     executionId,
+    agentId,
     importance: 'normal',
     privacyClass,
     payload: { attempt_index: attemptIndex, ...extra },
@@ -139,6 +153,7 @@ function modelAttempt(ctx, { traceId, parentSpanId, executionId, attemptIndex, s
     spanId,
     parentSpanId,
     executionId,
+    agentId,
     importance: 'normal',
     privacyClass,
     payload: {
@@ -152,14 +167,14 @@ function modelAttempt(ctx, { traceId, parentSpanId, executionId, attemptIndex, s
   });
   return [started, completed];
 }
-
-function execEnd(ctx, { traceId, spanId, executionId, status, privacyClass, extra = {} }) {
+function execEnd(ctx, { traceId, spanId, executionId, agentId, status, privacyClass, extra = {} }) {
   return record(ctx, {
     semanticName: `execution.${status}`,
     traceId,
     spanId,
     parentSpanId: null,
     executionId,
+    agentId,
     importance: 'normal',
     privacyClass,
     payload: { duration_ms: 0, ...extra },
@@ -174,11 +189,10 @@ function sumUsage(attempts) {
     .map((res) => res.value);
   return values.length ? values.reduce((a, b) => a + b, 0) : null;
 }
-
-function buildTrace(ctx, { scenario, privacyClass, build }) {
+function buildTrace(ctx, { scenario, privacyClass, agentId, build }) {
   const traceId = ctx.traceId();
   const executionId = `exec-${traceId}`;
-  const exec = execSpan(ctx, traceId, executionId, privacyClass);
+  const exec = execSpan(ctx, traceId, executionId, privacyClass, agentId);
   const { records, attempts, succeeded } = build({ traceId, executionId, execSpanId: exec.spanId });
   const all = [exec.started, ...records];
   return {
@@ -323,6 +337,109 @@ function buildCorpus() {
     }),
   );
 
+  // memory_outcome: retrieval.query → memory.retrieved hits → model →
+  // memory.write → execution.completed → outcome.observed — metadata-only
+  // payloads (counts, kinds, opaque refs), never content.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'memory_outcome',
+      privacyClass: 'sensitive',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const query = record(ctx, {
+          semanticName: 'retrieval.query',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'normal', privacyClass: 'internal',
+          payload: {
+            lane: 'v2', scope: 'all', indexed: true,
+            candidate_count: ctx.tokens(10, 40), returned_count: 3,
+            duration_ms: ctx.tokens(5, 20), freshness: {},
+          },
+          dtMs: 8,
+        });
+        const retrieved = [
+          { kind: 'fact' }, { kind: 'decision' }, { kind: 'decision' },
+        ].map((hit) => record(ctx, {
+          semanticName: 'memory.retrieved',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'normal', privacyClass: 'sensitive',
+          payload: { kind: hit.kind, record_ref: `memref-${ctx.tokens(1000, 9999)}` },
+          dtMs: 4,
+        }));
+        const resource = { value: ctx.tokens(800, 1200), source: 'PROVIDER' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          attemptIndex: 1, status: 'ok', resource, privacyClass: 'public',
+        });
+        const write = record(ctx, {
+          semanticName: 'memory.write',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'normal', privacyClass: 'sensitive',
+          payload: {
+            op: 'write', record_count: ctx.tokens(1, 5), changed_count: 1,
+            kinds: { fact: 1 }, record_refs: [`memref-${ctx.tokens(1000, 9999)}`],
+            tombstone_count: 0,
+          },
+          dtMs: 6,
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, status: 'completed',
+          privacyClass: 'public', extra: { outcome: 'success' },
+        });
+        const outcome = record(ctx, {
+          semanticName: 'outcome.observed',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          importance: 'high', privacyClass: 'internal',
+          payload: {
+            kind: 'feedback', verdict: 'accepted', source: 'user',
+            evidence_refs: [end.record_id],
+          },
+          dtMs: 30,
+        });
+        return {
+          records: [query, ...retrieved, ...attempts, write, end, outcome],
+          attempts,
+          succeeded: true,
+        };
+      },
+    }),
+  );
+
+  // multi_agent: one trace spanning two agents — orchestrator runs the
+  // retrieval query and owns the execution span, worker runs the model
+  // attempt. agent_id is the v1.1 correlation field; trace_id stays single.
+  traces.push(
+    buildTrace(ctx, {
+      scenario: 'multi_agent',
+      privacyClass: 'public',
+      agentId: 'agent-orchestrator',
+      build: ({ traceId, executionId, execSpanId }) => {
+        const query = record(ctx, {
+          semanticName: 'retrieval.query',
+          traceId, spanId: ctx.spanId(), parentSpanId: execSpanId, executionId,
+          agentId: 'agent-orchestrator',
+          importance: 'normal', privacyClass: 'internal',
+          payload: {
+            lane: 'v2', scope: 'all', indexed: true,
+            candidate_count: ctx.tokens(10, 40), returned_count: 2,
+            duration_ms: ctx.tokens(5, 20), freshness: {},
+          },
+          dtMs: 8,
+        });
+        const resource = { value: ctx.tokens(800, 1200), source: 'PROVIDER' };
+        const attempts = modelAttempt(ctx, {
+          traceId, parentSpanId: execSpanId, executionId,
+          agentId: 'agent-worker',
+          attemptIndex: 1, status: 'ok', resource, privacyClass: 'public',
+        });
+        const end = execEnd(ctx, {
+          traceId, spanId: execSpanId, executionId, agentId: 'agent-orchestrator',
+          status: 'completed', privacyClass: 'public', extra: { outcome: 'success' },
+        });
+        return { records: [query, ...attempts, end], attempts, succeeded: true };
+      },
+    }),
+  );
+
   return {
     metric_version: METRIC_VERSION,
     seed: SEED,
@@ -560,52 +677,253 @@ export async function runPerturb({ quiet = false } = {}) {
   return { code: outcome.missed.length > 0 ? 1 : 0, report };
 }
 
-function main(argv) {
-  const flag = argv[2];
+// --anomalies: replay every golden case under each pre-registered policy,
+// summarize each materialized run, and report per-case anomaly detection
+// counts keyed by detector kind. The detector is imported defensively:
+// while src/core/observability/analytics/anomalies.js (TASK-011) does not
+// exist the report degrades to `detector: 'unavailable'` — never a stub.
+// When a detector IS available, per-case declarations in
+// `expect.anomalies.expected_kinds` act as a regression gate: unmet or
+// over-fired kinds exit 1. Evaluation is offline — no model calls.
+async function loadAnomalyDetector() {
+  try {
+    const mod = await import('../../src/core/observability/analytics/anomalies.js');
+    return typeof mod.detectAnomalies === 'function' ? mod.detectAnomalies : null;
+  } catch {
+    return null;
+  }
+}
+
+function anomalyKind(record) {
+  const kind = record && record.payload && record.payload.kind !== undefined
+    ? record.payload.kind
+    : record && record.kind;
+  return typeof kind === 'string' && kind.length > 0 ? kind : 'unknown';
+}
+
+async function runAnomaliesBench() {
+  const { replayCase } = await import('../../src/core/observability/evaluation/replay.js');
+  const { summarizeTrace } = await import('../../src/core/observability/analytics/summary.js');
+  const detectAnomalies = await loadAnomalyDetector();
+
+  const goldenPath = path.join(repoRoot, 'tests/fixtures/observability/golden/cases.json');
+  let corpus;
+  try {
+    corpus = JSON.parse(fs.readFileSync(goldenPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`--anomalies: cannot load ${goldenPath}: ${err && err.message}\n`);
+    return 1;
+  }
+  const policies = Object.keys(
+    (corpus.pre_registered && corpus.pre_registered.policies) || {},
+  ).sort();
+  if (policies.length === 0) {
+    process.stderr.write('--anomalies: corpus declares no pre_registered.policies\n');
+    return 1;
+  }
+
+  const runs = [];
+  for (const goldenCase of corpus.cases || []) {
+    const expectedKinds = goldenCase && goldenCase.expect && goldenCase.expect.anomalies
+      && Array.isArray(goldenCase.expect.anomalies.expected_kinds)
+      ? goldenCase.expect.anomalies.expected_kinds
+      : null;
+    const run = { case_id: goldenCase && goldenCase.case_id, expected_kinds: expectedKinds, policies: {} };
+    for (const policyId of policies) {
+      const replay = replayCase(goldenCase, { policyId });
+      if (!replay.ok) {
+        run.policies[policyId] = { ok: false, reason: replay.reason };
+        continue;
+      }
+      const summary = summarizeTrace(replay.records);
+      run.policies[policyId] = {
+        ok: true,
+        trace_id: summary.trace_id,
+        summary,
+        record_ids: replay.records.map((r) => r.record_id),
+      };
+    }
+    runs.push(run);
+  }
+
+  // Detector wiring: one call over ALL materialized summaries (detectors are
+  // cohort-relative), then attribution back to cases by trace_id or any
+  // evidence_ref that resolves to a materialized record_id.
+  const summaries = runs.flatMap((run) => policies
+    .map((policyId) => run.policies[policyId])
+    .filter((entry) => entry && entry.ok)
+    .map((entry) => entry.summary));
+
+  const byCase = new Map(runs.map((run) => [run.case_id, new Map()]));
+  const byTrace = new Map();
+  const byRecordId = new Map();
+  for (const run of runs) {
+    for (const policyId of policies) {
+      const entry = run.policies[policyId];
+      if (!entry || !entry.ok) continue;
+      if (typeof entry.trace_id === 'string') byTrace.set(entry.trace_id, [run.case_id, policyId]);
+      for (const recordId of entry.record_ids) byRecordId.set(recordId, [run.case_id, policyId]);
+    }
+  }
+
+  let detection = null;
+  if (detectAnomalies) {
+    const anomalies = detectAnomalies(summaries) || [];
+    const unattributed = [];
+    for (const anomaly of anomalies) {
+      const refs = anomaly && anomaly.payload && Array.isArray(anomaly.payload.evidence_refs)
+        ? anomaly.payload.evidence_refs
+        : [];
+      const traceRef = anomaly && anomaly.payload && typeof anomaly.payload.trace_ref === 'string'
+        ? anomaly.payload.trace_ref
+        : (anomaly && typeof anomaly.trace_id === 'string' ? anomaly.trace_id : null);
+      let target = traceRef ? byTrace.get(traceRef) : null;
+      if (!target) {
+        for (const ref of refs) {
+          target = byRecordId.get(ref);
+          if (target) break;
+        }
+      }
+      if (!target) { unattributed.push(anomaly); continue; }
+      const [caseId, policyId] = target;
+      const policyMap = byCase.get(caseId);
+      if (!policyMap.has(policyId)) policyMap.set(policyId, {});
+      const counts = policyMap.get(policyId);
+      const kind = anomalyKind(anomaly);
+      counts[kind] = (counts[kind] || 0) + 1;
+    }
+    detection = { anomalies, unattributed };
+  }
+  // Per-case signals — the summary fields the detectors consume (TASK-011):
+  // attempt/retry counters, cache posture, drops, critical path. Reported
+  // per policy run so a detector regression is attributable to a case.
+  function signalsOf(entry) {
+    const s = entry && entry.summary;
+    if (!s) return null;
+    return {
+      model_attempts: s.retries.model_attempts,
+      retries: s.retries.retries,
+      failed_spans: s.retries.failed_spans,
+      cache_misses: s.cache.misses,
+      cache_hits: s.cache.hits,
+      hit_rate: s.cache.hit_rate,
+      dropped_events: s.drops.events,
+      dropped_count: s.drops.dropped_count,
+      critical_path_ms: s.critical_path_ms,
+      telemetry_complete: s.telemetry_complete,
+      spans: s.coverage.spans,
+    };
+  }
+
+  const casesReport = {};
+  for (const run of runs) {
+    const signals = {};
+    for (const policyId of policies) {
+      signals[policyId] = signalsOf(run.policies[policyId]);
+    }
+    let anomalies = null;
+    if (detection) {
+      anomalies = 0;
+      for (const counts of byCase.get(run.case_id)?.values() || []) {
+        for (const n of Object.values(counts)) anomalies += n;
+      }
+    }
+    casesReport[run.case_id] = { signals, anomalies };
+  }
+
+  // Regression gate — only meaningful when a real detector ran. A case that
+  // declares expect.anomalies.expected_kinds must see those kinds fire; a
+  // case declaring an empty list must stay clean.
+  const unmet = [];
+  if (detection) {
+    for (const run of runs) {
+      if (!Array.isArray(run.expected_kinds)) continue;
+      for (const [policyId, counts] of byCase.get(run.case_id) || []) {
+        for (const kind of run.expected_kinds) {
+          if (!counts[kind]) {
+            unmet.push({ case_id: run.case_id, policy: policyId, kind, expected: '>=1', got: 0 });
+          }
+        }
+        for (const kind of Object.keys(counts)) {
+          if (!run.expected_kinds.includes(kind)) {
+            unmet.push({ case_id: run.case_id, policy: policyId, kind, expected: 'absent', got: counts[kind] });
+          }
+        }
+      }
+    }
+    unmet.sort((a, b) => String(a.case_id).localeCompare(String(b.case_id))
+      || a.policy.localeCompare(b.policy) || a.kind.localeCompare(b.kind));
+  }
+
+  const report = {
+    metric_version: METRIC_VERSION,
+    bench: 'anomalies',
+    seed: SEED,
+    corpus: path.relative(repoRoot, goldenPath),
+    policies,
+    detector: detectAnomalies ? 'detectAnomalies' : 'unavailable',
+    summaries: summaries.length,
+    anomalies_total: detection ? detection.anomalies.length : null,
+    unattributed: detection ? detection.unattributed.length : null,
+    unmet_expectations: detection ? unmet : null,
+    cases: casesReport,
+  };
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  if (!detection) return 0; // degraded — nothing to gate on
+  return unmet.length > 0 ? 1 : 0;
+}
+
+const BENCH_FLAGS = Object.freeze([
+  '--fixture',
+  '--recorder',
+  '--analytics',
+  '--evaluate',
+  '--perturb',
+  '--anomalies',
+]);
+
+async function runFlag(flag) {
   switch (flag) {
-    case '--fixture':
-      return writeFixture();
-    case '--recorder':
-      return runRecorderBench().then(
-        (code) => code,
-        (err) => {
-          process.stderr.write(`--recorder failed: ${err && err.message}\n`);
-          return 1;
-        },
-      );
-    case '--analytics':
-      return runAnalyticsBench().then(
-        (code) => code,
-        (err) => {
-          process.stderr.write(`--analytics failed: ${err && err.message}\n`);
-          return 1;
-        },
-      );
-    case '--evaluate':
-      return runEvaluateBench().then(
-        (code) => code,
-        (err) => {
-          process.stderr.write(`--evaluate failed: ${err && err.message}\n`);
-          return 1;
-        },
-      );
-    case '--perturb':
-      return runPerturb().then(
-        ({ code }) => code,
-        (err) => {
-          process.stderr.write(`--perturb failed: ${err && err.message}\n`);
-          return 1;
-        },
-      );
+    case '--fixture': return writeFixture();
+    case '--recorder': return runRecorderBench();
+    case '--analytics': return runAnalyticsBench();
+    case '--evaluate': return runEvaluateBench();
+    case '--perturb': return runPerturb().then(({ code }) => code);
+    case '--anomalies': return runAnomaliesBench();
     default:
-      process.stderr.write(
-        `usage: node scripts/bench/data-foundation.mjs --fixture|--recorder|--analytics|--evaluate|--perturb\n`,
-      );
+      process.stderr.write(`unknown flag: ${flag}\n`);
       return 2;
   }
 }
+
+// Flags run in argument order; the exit code is the first non-zero result.
+// (PLAN §5 verification chains --recorder --analytics --evaluate.)
+async function main(argv) {
+  const flags = argv.slice(2).filter((arg) => arg.startsWith('--'));
+  if (flags.length === 0) {
+    process.stderr.write(
+      `usage: node scripts/bench/data-foundation.mjs ${BENCH_FLAGS.join('|')}\n`,
+    );
+    return 2;
+  }
+  let firstFailure = 0;
+  for (const flag of flags) {
+    try {
+      const code = await runFlag(flag);
+      if (code !== 0 && firstFailure === 0) firstFailure = code;
+    } catch (err) {
+      process.stderr.write(`${flag} failed: ${err && err.message}\n`);
+      if (firstFailure === 0) firstFailure = 1;
+    }
+  }
+  return firstFailure;
+}
 const invokedAs = process.argv[1] ? path.resolve(process.argv[1]) : '';
 if (invokedAs === fileURLToPath(import.meta.url)) {
-  Promise.resolve(main(process.argv)).then((code) => process.exit(code));
+  // Set the code then let the loop drain stdout — process.exit() hard-kills
+  // pending pipe writes, which truncates reports past the 64 KiB buffer.
+  Promise.resolve(main(process.argv)).then((code) => {
+    process.exitCode = code;
+  });
 }