@vibe-agent-toolkit/cli 0.1.41-rc.7 → 0.1.41-rc.8

package/dist/utils/command-error.d.ts

@@ -1,6 +1,12 @@
 /**
- * Shared command error handling utilities
+ * Shared command error handling utilities.
+ *
+ * THE single implementation of each failure exit. `commands/skills/` used to
+ * carry its own `handleCommandError` that logged to stderr and exited 2 having
+ * written nothing to stdout — same name, same signature, same documented
+ * contract, silently different behaviour. Every command family routes here.
  */
+import { type SeverityCounts, type ValidationIssue } from '@vibe-agent-toolkit/agent-schema';
 import type { Logger } from './logger.js';
 /**
  * Format duration for human readability
@@ -16,4 +22,31 @@ export declare function formatDuration(ms: number): string;
  * @param commandName - Name of the command (for error message)
  */
 export declare function handleCommandError(error: unknown, logger: Logger, startTime: number, commandName: string): never;
+/** The payload a command publishes when its own validation gate stops it. */
+export interface ValidationGateFailure {
+    status: 'error';
+    issueCounts: SeverityCounts;
+    /** What was being validated — a skill name or a path, whichever the lane has. */
+    skill: string;
+}
+/**
+ * Pure: the document {@link handleValidationGateFailure} writes.
+ *
+ * The per-severity distribution rides beside the status because `status: error`
+ * alone cannot say whether the run also carried warnings and info — and the
+ * findings themselves went to stderr, where a piped consumer never sees them.
+ */
+export declare function buildValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): ValidationGateFailure;
+/**
+ * Publish the documented failure payload for a command stopped by its OWN
+ * validation gate, then exit 1.
+ *
+ * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * covers the expected one, and `vat skills build` / `vat skills package` both
+ * exited it after writing zero bytes to stdout — while their `--help` texts
+ * document a YAML summary on stdout and reserve exit 1 for exactly this case.
+ * A consumer running `vat skills build | jq .status` got an empty document and
+ * a bare non-zero code.
+ */
+export declare function handleValidationGateFailure(subject: string, issues: readonly ValidationIssue[]): never;
 //# sourceMappingURL=command-error.d.ts.map

package/dist/utils/command-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,KAAK,CAWP"}
+{"version":3,"file":"command-error.d.ts","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAmB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,kCAAkC,CAAC;AAE9G,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAG1C;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQjD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,KAAK,CAWP;AAED,6EAA6E;AAC7E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB,WAAW,EAAE,cAAc,CAAC;IAC5B,iFAAiF;IACjF,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,qBAAqB,CAEvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,eAAe,EAAE,GACjC,KAAK,CAGP"}

package/dist/utils/command-error.js

@@ -1,6 +1,12 @@
 /**
- * Shared command error handling utilities
+ * Shared command error handling utilities.
+ *
+ * THE single implementation of each failure exit. `commands/skills/` used to
+ * carry its own `handleCommandError` that logged to stderr and exited 2 having
+ * written nothing to stdout — same name, same signature, same documented
+ * contract, silently different behaviour. Every command family routes here.
  */
+import { countBySeverity } from '@vibe-agent-toolkit/agent-schema';
 import { writeYamlOutput } from './output.js';
 /**
  * Format duration for human readability
@@ -33,4 +39,29 @@ export function handleCommandError(error, logger, startTime, commandName) {
     });
     process.exit(2);
 }
+/**
+ * Pure: the document {@link handleValidationGateFailure} writes.
+ *
+ * The per-severity distribution rides beside the status because `status: error`
+ * alone cannot say whether the run also carried warnings and info — and the
+ * findings themselves went to stderr, where a piped consumer never sees them.
+ */
+export function buildValidationGateFailure(subject, issues) {
+    return { status: 'error', issueCounts: countBySeverity(issues), skill: subject };
+}
+/**
+ * Publish the documented failure payload for a command stopped by its OWN
+ * validation gate, then exit 1.
+ *
+ * {@link handleCommandError} above covers the UNEXPECTED failure (exit 2). This
+ * covers the expected one, and `vat skills build` / `vat skills package` both
+ * exited it after writing zero bytes to stdout — while their `--help` texts
+ * document a YAML summary on stdout and reserve exit 1 for exactly this case.
+ * A consumer running `vat skills build | jq .status` got an empty document and
+ * a bare non-zero code.
+ */
+export function handleValidationGateFailure(subject, issues) {
+    writeYamlOutput(buildValidationGateFailure(subject, issues));
+    process.exit(1);
+}
 //# sourceMappingURL=command-error.js.map

package/dist/utils/command-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACd,OAAO,GAAG,EAAE,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IAEnG,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;QAC/D,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC;KACnC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"command-error.js","sourceRoot":"","sources":["../../src/utils/command-error.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAA6C,MAAM,kCAAkC,CAAC;AAG9G,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,IAAI,EAAE,GAAG,IAAI,EAAE,CAAC;QACd,OAAO,GAAG,EAAE,IAAI,CAAC;IACnB,CAAC;IACD,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;QACf,OAAO,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;IACtC,CAAC;IACD,OAAO,GAAG,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC;AACvC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAc,EACd,MAAc,EACd,SAAiB,EACjB,WAAmB;IAEnB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;IACxC,MAAM,CAAC,KAAK,CAAC,GAAG,WAAW,YAAY,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAAE,CAAC,CAAC;IAEnG,eAAe,CAAC;QACd,MAAM,EAAE,OAAO;QACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe;QAC/D,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC;KACnC,CAAC,CAAC;IAEH,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,0BAA0B,CACxC,OAAe,EACf,MAAkC;IAElC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACnF,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAe,EACf,MAAkC;IAElC,eAAe,CAAC,0BAA0B,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/utils/help-loader.d.ts

@@ -21,8 +21,12 @@ export declare function loadVerboseHelp(section?: string): string;
  * That directly violates this package's own rule that help must survive piping.
  *
  * `writeSync` in a drain loop is the fix: it cannot return before the bytes are
- * handed to the pipe, so `process.exit` has nothing left to lose. The loop is
- * required because a single `writeSync` may accept fewer bytes than offered.
+ * handed to the pipe, so `process.exit` has nothing left to lose.
+ *
+ * The loop itself now lives in `output.ts` as `writeStdoutSync`, because the very
+ * same defect was later found in `writeYamlOutput` — every command's YAML summary
+ * was being truncated at one pipe buffer. Two copies of this reasoning is exactly
+ * how the second lane went unfixed for so long, so there is one.
  */
 export declare function writeHelpSync(content: string): void;
 //# sourceMappingURL=help-loader.d.ts.map

package/dist/utils/help-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBxD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAYnD"}
+{"version":3,"file":"help-loader.d.ts","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAyBxD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/utils/help-loader.js

@@ -2,10 +2,11 @@
  * Help loader - reads verbose help from markdown files
  * Markdown docs are the source of truth for CLI help
  */
-import { readFileSync, writeSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { safePath } from '@vibe-agent-toolkit/utils';
+import { writeStdoutSync } from './output.js';
 /**
  * Load verbose help from markdown files in packages/cli/docs/
  *
@@ -49,22 +50,14 @@ Please report this issue at: https://github.com/jdutton/vibe-agent-toolkit/issue
  * That directly violates this package's own rule that help must survive piping.
  *
  * `writeSync` in a drain loop is the fix: it cannot return before the bytes are
- * handed to the pipe, so `process.exit` has nothing left to lose. The loop is
- * required because a single `writeSync` may accept fewer bytes than offered.
+ * handed to the pipe, so `process.exit` has nothing left to lose.
+ *
+ * The loop itself now lives in `output.ts` as `writeStdoutSync`, because the very
+ * same defect was later found in `writeYamlOutput` — every command's YAML summary
+ * was being truncated at one pipe buffer. Two copies of this reasoning is exactly
+ * how the second lane went unfixed for so long, so there is one.
  */
 export function writeHelpSync(content) {
-    const buffer = Buffer.from(content.endsWith('\n') ? content : `${content}\n`, 'utf8');
-    let written = 0;
-    while (written < buffer.length) {
-        try {
-            written += writeSync(1, buffer, written, buffer.length - written);
-        }
-        catch (error) {
-            // A non-blocking pipe whose buffer is momentarily full raises EAGAIN; the
-            // reader will drain it, so retry. Anything else is a genuine write failure.
-            if (error.code !== 'EAGAIN')
-                throw error;
-        }
-    }
+    writeStdoutSync(content.endsWith('\n') ? content : `${content}\n`);
 }
 //# sourceMappingURL=help-loader.js.map

package/dist/utils/help-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,qHAAqH;QACrH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,EAAE,MAAM,CAAC,CAAC;IACtF,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OAAO,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,IAAI,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,GAAG,OAAO,CAAC,CAAC;QACpE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,0EAA0E;YAC1E,4EAA4E;YAC5E,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ;gBAAE,MAAM,KAAK,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC"}
+{"version":3,"file":"help-loader.js","sourceRoot":"","sources":["../../src/utils/help-loader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,OAAgB;IAC9C,mCAAmC;IACnC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IAC1D,MAAM,WAAW,GAAG,QAAQ,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;IAEtD,wCAAwC;IACxC,MAAM,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,KAAK,CAAC,CAAC,CAAC,UAAU,CAAC;IACxD,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,CAAC;IAE9D,IAAI,CAAC;QACH,qHAAqH;QACrH,MAAM,OAAO,GAAG,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAChD,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,sCAAsC;QACtC,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5E,OAAO;;0BAEe,QAAQ;;EAEhC,YAAY;;;CAGb,CAAC;IACA,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,eAAe,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;AACrE,CAAC"}

package/dist/utils/issue-rendering.d.ts

@@ -42,6 +42,18 @@ export declare function formatIssueSetHeading(issues: readonly ValidationIssue[]
  * a unit test can assert over every line without capturing output.
  */
 export declare function formatIssueLines(issue: ValidationIssue, indent?: string): string[];
+/**
+ * Render the run-level findings section — findings that belong to the whole
+ * invocation rather than to any one skill (ALLOW_UNUSED is the only producer).
+ *
+ * Shared by `vat skills validate` and `vat skills build` so the two commands
+ * name the same concept the same way. Attributing these to a skill is the
+ * misreading the heading exists to prevent: `validation.allow` is declared once
+ * for the package, so an entry that matched nothing is a fact about the run.
+ *
+ * Returns `[]` for an empty set; callers own their surrounding blank lines.
+ */
+export declare function formatRunIssueLines(runIssues: readonly ValidationIssue[]): string[];
 /**
  * Every post-build finding a `PackageSkillResult` carries, from BOTH channels.
  *
@@ -56,6 +68,82 @@ export declare function formatIssueLines(issue: ValidationIssue, indent?: string
  * (see its doc comment — the name lies), so info findings survive here.
  */
 export declare function collectPostBuildIssues(result: PackageSkillResult): ValidationIssue[];
+/**
+ * A compact count-only projection of one asset's findings, for summary output.
+ *
+ * Deliberately does NOT carry the asset's name: the three commands that publish
+ * these rows (`vat skills validate`, `vat claude marketplace validate`,
+ * `vat resources validate`) each key their row by a different identity — a skill
+ * name, a plugin name, a file path. A projection that named the asset would have
+ * to pick one, and the two lanes it did not fit would fork their own copy, which
+ * is how the severity collapse came to be spelled five different ways.
+ *
+ * A zero bucket is an ABSENT key, never `0`. Serialized as YAML, three zero
+ * columns per asset is what makes a summary unreadable at corpus scale, and
+ * `errors: 0` beside a red exit code reads as a contradiction rather than as the
+ * "this asset is not the one" it means. `exactOptionalPropertyTypes` is on, so
+ * these are built by spread — assigning `undefined` would emit the key.
+ */
+export interface FindingCountSummary {
+    errors?: number;
+    warnings?: number;
+    info?: number;
+    /** Per-code tally, ordered descending by count then by code name. */
+    codes: Record<string, number>;
+}
+/**
+ * Project a set of issues onto its counts: severity buckets plus a per-code tally.
+ *
+ * Severity counting delegates to `countBySeverity` — there must be exactly one
+ * severity collapse in this codebase (see this module's header). That delegation
+ * carries its rule with it: `ignore` findings land in NO severity bucket, because
+ * the adopter's `validation.allow` config silenced them.
+ *
+ * They do still appear in `codes`, because they were emitted — a code the adopter
+ * allow-listed would otherwise be invisible in every summary, which is the one
+ * place a reviewer would look to notice an allow-list that has quietly grown.
+ *
+ * `codes` is ordered descending by count, ties broken by code name ascending.
+ * Insertion order is the YAML serialization order, so the ordering is the feature:
+ * the first row names the dominant finding without the reader tallying anything.
+ */
+export declare function summarizeFindings(issues: readonly ValidationIssue[]): FindingCountSummary;
+/**
+ * The findings a human-facing report renders IN FULL at a given verbosity.
+ *
+ * One policy, spelled once, because the three verbs that report findings —
+ * `vat skills validate`, `vat skills build`, `vat audit` — each grew their own
+ * answer and landed on three different ones: validate collapsed every severity
+ * into a per-skill count line, while build and audit printed every occurrence.
+ * On a 90-skill adopter that read as 804 lines against 6,552 and 26,480, for
+ * the same corpus.
+ *
+ * The rule is asymmetric on purpose, and the asymmetry is the whole point:
+ *
+ * - **`error` is always rendered in full**, at every verbosity. An error is what
+ *   failed the run, there are few of them, and every one is actionable. Collapsing
+ *   an error into a count means the reader must re-run with a flag to learn what
+ *   broke — which is strictly worse than the verbosity it was meant to fix. This
+ *   is the direction the module header warns about: a collapse that hides the
+ *   thing you needed produces silence, not a false alarm.
+ * - **`warning` and `info` collapse into the caller's summary line** unless
+ *   `verbose`. These are the high-cardinality findings (one adopter skill carries
+ *   348 `LINK_DROPPED_BY_DEPTH` warnings alone), and a count plus a per-code tally
+ *   answers "what is going on here?" without the reader scrolling past 348 near-
+ *   identical blocks.
+ * - **`ignore` never renders**, at any verbosity: the adopter's `validation.allow`
+ *   config silenced it deliberately. It stays visible in `summarizeFindings`'
+ *   `codes` tally, which is where a quietly-growing allow-list is noticed.
+ *
+ * This decides only WHICH findings are rendered, never HOW. Each lane keeps its
+ * own heading and summary line — those legitimately differ — so this can be shared
+ * without forcing one layout onto three commands.
+ *
+ * The machine-readable document is NOT filtered by this. `vat audit`'s YAML and
+ * `vat skills build`'s `issueCounts` carry every finding at every verbosity;
+ * anything else would silently break consumers that parse them.
+ */
+export declare function issuesToRenderAtVerbosity(issues: readonly ValidationIssue[], verbose: boolean): readonly ValidationIssue[];
 /** Sum severity counts across lanes (per-skill → per-plugin → per-run). */
 export declare function sumSeverityCounts(counts: readonly SeverityCounts[]): SeverityCounts;
 //# sourceMappingURL=issue-rendering.d.ts.map

package/dist/utils/issue-rendering.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"issue-rendering.d.ts","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAiB3E,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAY9E;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAapF;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,CASnF"}
+{"version":3,"file":"issue-rendering.d.ts","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAiB3E,gDAAgD;AAChD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,CAAC,UAAU,CAAC,GAAG,MAAM,CAE3E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAYtE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAKR;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,MAAM,SAAK,GAAG,MAAM,EAAE,CAY9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,EAAE,CAUnF;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,eAAe,EAAE,CAapF;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,GAAG,mBAAmB,CAuBzF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,SAAS,eAAe,EAAE,EAClC,OAAO,EAAE,OAAO,GACf,SAAS,eAAe,EAAE,CAI5B;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc,CASnF"}

package/dist/utils/issue-rendering.js

@@ -85,6 +85,29 @@ export function formatIssueLines(issue, indent = '') {
     }
     return lines;
 }
+/**
+ * Render the run-level findings section — findings that belong to the whole
+ * invocation rather than to any one skill (ALLOW_UNUSED is the only producer).
+ *
+ * Shared by `vat skills validate` and `vat skills build` so the two commands
+ * name the same concept the same way. Attributing these to a skill is the
+ * misreading the heading exists to prevent: `validation.allow` is declared once
+ * for the package, so an entry that matched nothing is a fact about the run.
+ *
+ * Returns `[]` for an empty set; callers own their surrounding blank lines.
+ */
+export function formatRunIssueLines(runIssues) {
+    if (runIssues.length === 0)
+        return [];
+    const lines = [
+        'Run-level (project config, not any one skill):',
+        `  ${formatIssueSetHeading(runIssues)}:`,
+    ];
+    for (const issue of runIssues) {
+        lines.push(...formatIssueLines(issue, '    '));
+    }
+    return lines;
+}
 /** Identity of an issue for de-duplication across the two post-build channels. */
 function issueIdentity(issue) {
     return [
@@ -124,6 +147,77 @@ export function collectPostBuildIssues(result) {
     }
     return merged;
 }
+/**
+ * Project a set of issues onto its counts: severity buckets plus a per-code tally.
+ *
+ * Severity counting delegates to `countBySeverity` — there must be exactly one
+ * severity collapse in this codebase (see this module's header). That delegation
+ * carries its rule with it: `ignore` findings land in NO severity bucket, because
+ * the adopter's `validation.allow` config silenced them.
+ *
+ * They do still appear in `codes`, because they were emitted — a code the adopter
+ * allow-listed would otherwise be invisible in every summary, which is the one
+ * place a reviewer would look to notice an allow-list that has quietly grown.
+ *
+ * `codes` is ordered descending by count, ties broken by code name ascending.
+ * Insertion order is the YAML serialization order, so the ordering is the feature:
+ * the first row names the dominant finding without the reader tallying anything.
+ */
+export function summarizeFindings(issues) {
+    const counts = countBySeverity(issues);
+    const tally = new Map();
+    for (const issue of issues) {
+        const code = String(issue.code);
+        tally.set(code, (tally.get(code) ?? 0) + 1);
+    }
+    // `Object.fromEntries` over a sorted array, rather than keyed assignment into a
+    // record: it preserves the sort as insertion order without a dynamic index write.
+    const codes = Object.fromEntries([...tally.entries()].sort(([codeA, countA], [codeB, countB]) => countB - countA || codeA.localeCompare(codeB)));
+    return {
+        ...(counts.errors > 0 ? { errors: counts.errors } : {}),
+        ...(counts.warnings > 0 ? { warnings: counts.warnings } : {}),
+        ...(counts.info > 0 ? { info: counts.info } : {}),
+        codes,
+    };
+}
+/**
+ * The findings a human-facing report renders IN FULL at a given verbosity.
+ *
+ * One policy, spelled once, because the three verbs that report findings —
+ * `vat skills validate`, `vat skills build`, `vat audit` — each grew their own
+ * answer and landed on three different ones: validate collapsed every severity
+ * into a per-skill count line, while build and audit printed every occurrence.
+ * On a 90-skill adopter that read as 804 lines against 6,552 and 26,480, for
+ * the same corpus.
+ *
+ * The rule is asymmetric on purpose, and the asymmetry is the whole point:
+ *
+ * - **`error` is always rendered in full**, at every verbosity. An error is what
+ *   failed the run, there are few of them, and every one is actionable. Collapsing
+ *   an error into a count means the reader must re-run with a flag to learn what
+ *   broke — which is strictly worse than the verbosity it was meant to fix. This
+ *   is the direction the module header warns about: a collapse that hides the
+ *   thing you needed produces silence, not a false alarm.
+ * - **`warning` and `info` collapse into the caller's summary line** unless
+ *   `verbose`. These are the high-cardinality findings (one adopter skill carries
+ *   348 `LINK_DROPPED_BY_DEPTH` warnings alone), and a count plus a per-code tally
+ *   answers "what is going on here?" without the reader scrolling past 348 near-
+ *   identical blocks.
+ * - **`ignore` never renders**, at any verbosity: the adopter's `validation.allow`
+ *   config silenced it deliberately. It stays visible in `summarizeFindings`'
+ *   `codes` tally, which is where a quietly-growing allow-list is noticed.
+ *
+ * This decides only WHICH findings are rendered, never HOW. Each lane keeps its
+ * own heading and summary line — those legitimately differ — so this can be shared
+ * without forcing one layout onto three commands.
+ *
+ * The machine-readable document is NOT filtered by this. `vat audit`'s YAML and
+ * `vat skills build`'s `issueCounts` carry every finding at every verbosity;
+ * anything else would silently break consumers that parse them.
+ */
+export function issuesToRenderAtVerbosity(issues, verbose) {
+    return issues.filter((issue) => issue.severity !== 'ignore' && (verbose || issue.severity === 'error'));
+}
 /** Sum severity counts across lanes (per-skill → per-plugin → per-run). */
 export function sumSeverityCounts(counts) {
     return counts.reduce((acc, c) => ({

package/dist/utils/issue-rendering.js.map

@@ -1 +1 @@
-{"version":3,"file":"issue-rendering.js","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"issue-rendering.js","sourceRoot":"","sources":["../../src/utils/issue-rendering.ts"],"names":[],"mappings":"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"}

package/dist/utils/output.d.ts

@@ -2,6 +2,60 @@
  * Output utilities for structured data
  * YAML output on stdout, logs on stderr
  */
+/**
+ * Write `content` to stdout SYNCHRONOUSLY, in a loop until every byte is handed
+ * over.
+ *
+ * `process.stdout.write` is asynchronous whenever stdout is a PIPE, and every
+ * command in this CLI calls `process.exit()` the moment it has written its
+ * summary. `process.exit` does not drain a pending write, so everything past the
+ * first pipe buffer (64 KB on Linux/macOS) was silently discarded — with exit
+ * code 0, so nothing signalled the loss. An interactive TTY is unbuffered and
+ * looked perfect, which is why this survived: it only bites the piped consumer
+ * this CLI's own docs recommend (`vat command | jq .status`).
+ *
+ * `writeSync` cannot return before the bytes reach the pipe, so `process.exit`
+ * has nothing left to lose. The loop is required because a single `writeSync`
+ * may accept fewer bytes than offered.
+ *
+ * This is the same fix `help-loader.ts` applied to `--help --verbose`; it lives
+ * here so both callers share one implementation rather than two copies of a
+ * subtle loop.
+ */
+export declare function writeStdoutSync(content: string): void;
+/**
+ * A synchronous write primitive: `(buffer, offset, length) => bytesWritten`.
+ *
+ * Matches `fs.writeSync`'s shape so the real one drops straight in, while a test
+ * can supply one that returns short counts or throws EAGAIN on demand.
+ */
+export type SyncWriter = (buffer: Buffer, offset: number, length: number) => number;
+export interface WriteAllSyncOptions {
+    /** Override {@link MAX_CONSECUTIVE_EAGAIN_RETRIES}. Tests use a tiny budget. */
+    maxConsecutiveRetries?: number;
+    /** Override the backoff. Tests pass a no-op to drive the bound instantly. */
+    waitBetweenRetries?: (consecutiveRetries: number) => void;
+}
+/**
+ * Drive `write` until every byte of `buffer` has been accepted.
+ *
+ * Split out from {@link writeStdoutSync} because the things that make this loop
+ * necessary — a short write, and an EAGAIN retry on a momentarily-full
+ * non-blocking pipe — are both hard to provoke on a real fd and trivial to state
+ * against an injected writer. The fd-1 wiring stays a one-liner above, so the
+ * only part with branching logic is the part that can be unit tested.
+ *
+ * The EAGAIN retry is BOUNDED. A reader that stops draining without closing the
+ * pipe (`vat … | consumer-that-wanders-off`) leaves it permanently full, so
+ * every retry raises EAGAIN forever; an unbounded loop turns that into a hang
+ * with no output and no error — strictly worse than the truncation this replaced.
+ * Exhausting the budget throws, so the failure is visible and the exit code is
+ * non-zero, rather than the bytes quietly going missing.
+ *
+ * @throws the underlying error for any failure other than EAGAIN; an `Error`
+ * naming the unwritten remainder when the retry budget is exhausted.
+ */
+export declare function writeAllSync(write: SyncWriter, buffer: Buffer, options?: WriteAllSyncOptions): void;
 /**
  * Write a single YAML document to stdout, opened with `---`.
  *
@@ -22,11 +76,6 @@
  * @param data - Data to serialize as YAML
  */
 export declare function writeYamlOutput(data: unknown): void;
-/**
- * Flush stdout before writing to stderr
- * Prevents output corruption when streams are merged
- */
-export declare function flushStdout(): Promise<void>;
 /**
  * Write a test-format finding to stderr.
  *

package/dist/utils/output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAOnD;AAED;;;GAGG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAQjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAKrD;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;AAoCpF,MAAM,WAAW,mBAAmB;IAClC,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,CAAC,kBAAkB,EAAE,MAAM,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,mBAAwB,GAChC,IAAI,CA+BN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAWnD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,GACd,IAAI,CAEN"}

package/dist/utils/output.js

@@ -2,7 +2,111 @@
  * Output utilities for structured data
  * YAML output on stdout, logs on stderr
  */
+import { writeSync } from 'node:fs';
 import * as yaml from 'yaml';
+/**
+ * Write `content` to stdout SYNCHRONOUSLY, in a loop until every byte is handed
+ * over.
+ *
+ * `process.stdout.write` is asynchronous whenever stdout is a PIPE, and every
+ * command in this CLI calls `process.exit()` the moment it has written its
+ * summary. `process.exit` does not drain a pending write, so everything past the
+ * first pipe buffer (64 KB on Linux/macOS) was silently discarded — with exit
+ * code 0, so nothing signalled the loss. An interactive TTY is unbuffered and
+ * looked perfect, which is why this survived: it only bites the piped consumer
+ * this CLI's own docs recommend (`vat command | jq .status`).
+ *
+ * `writeSync` cannot return before the bytes reach the pipe, so `process.exit`
+ * has nothing left to lose. The loop is required because a single `writeSync`
+ * may accept fewer bytes than offered.
+ *
+ * This is the same fix `help-loader.ts` applied to `--help --verbose`; it lives
+ * here so both callers share one implementation rather than two copies of a
+ * subtle loop.
+ */
+export function writeStdoutSync(content) {
+    writeAllSync((buffer, offset, length) => writeSync(1, buffer, offset, length), Buffer.from(content, 'utf8'));
+}
+/**
+ * How many CONSECUTIVE EAGAIN retries — retries during which the writer accepted
+ * zero bytes — are tolerated before the write is declared stalled.
+ *
+ * Consecutive, not cumulative: a large payload to a slow reader legitimately
+ * EAGAINs thousands of times in total, and every one of those is followed by
+ * progress. What is never legitimate is the pipe staying full while the process
+ * on the other end takes nothing at all. Combined with the wait below, the
+ * budget is roughly ten seconds of a completely stalled reader.
+ */
+const MAX_CONSECUTIVE_EAGAIN_RETRIES = 10_000;
+/** Consecutive retries to spin on before sleeping between attempts. */
+const EAGAIN_SPIN_RETRIES = 16;
+/**
+ * Sleep synchronously. Required because this whole path exists to run to
+ * completion before `process.exit`, so it cannot yield to the event loop; a
+ * timer would never fire. `Atomics.wait` on a never-notified buffer is the one
+ * primitive that blocks the thread without burning CPU.
+ */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * Spin for the first few retries — a draining pipe frees space in microseconds,
+ * and paying a millisecond for that would be absurd — then back off to a real
+ * sleep so a genuinely stalled reader is waited out rather than spun on.
+ */
+function defaultWaitBetweenRetries(consecutiveRetries) {
+    if (consecutiveRetries > EAGAIN_SPIN_RETRIES)
+        sleepSync(1);
+}
+/**
+ * Drive `write` until every byte of `buffer` has been accepted.
+ *
+ * Split out from {@link writeStdoutSync} because the things that make this loop
+ * necessary — a short write, and an EAGAIN retry on a momentarily-full
+ * non-blocking pipe — are both hard to provoke on a real fd and trivial to state
+ * against an injected writer. The fd-1 wiring stays a one-liner above, so the
+ * only part with branching logic is the part that can be unit tested.
+ *
+ * The EAGAIN retry is BOUNDED. A reader that stops draining without closing the
+ * pipe (`vat … | consumer-that-wanders-off`) leaves it permanently full, so
+ * every retry raises EAGAIN forever; an unbounded loop turns that into a hang
+ * with no output and no error — strictly worse than the truncation this replaced.
+ * Exhausting the budget throws, so the failure is visible and the exit code is
+ * non-zero, rather than the bytes quietly going missing.
+ *
+ * @throws the underlying error for any failure other than EAGAIN; an `Error`
+ * naming the unwritten remainder when the retry budget is exhausted.
+ */
+export function writeAllSync(write, buffer, options = {}) {
+    const maxRetries = options.maxConsecutiveRetries ?? MAX_CONSECUTIVE_EAGAIN_RETRIES;
+    const wait = options.waitBetweenRetries ?? defaultWaitBetweenRetries;
+    let written = 0;
+    let consecutiveRetries = 0;
+    while (written < buffer.length) {
+        try {
+            const n = write(buffer, written, buffer.length - written);
+            // A writer that reports no progress would spin forever. Treat it as a
+            // failure rather than hang the CLI.
+            if (n <= 0) {
+                throw new Error(`Refusing to loop forever: writer accepted ${n} bytes of ${buffer.length - written} remaining`);
+            }
+            written += n;
+            consecutiveRetries = 0;
+        }
+        catch (error) {
+            // A non-blocking pipe whose buffer is momentarily full raises EAGAIN; a
+            // reader that is draining will free space, so retry. Anything else is a
+            // genuine write failure.
+            if (error.code !== 'EAGAIN')
+                throw error;
+            consecutiveRetries++;
+            if (consecutiveRetries > maxRetries) {
+                throw new Error(`Write stalled: ${maxRetries} consecutive EAGAIN retries with no progress after ${written} of ${buffer.length} bytes. The reader is not draining the pipe.`);
+            }
+            wait(consecutiveRetries);
+        }
+    }
+}
 /**
  * Write a single YAML document to stdout, opened with `---`.
  *
@@ -23,26 +127,16 @@ import * as yaml from 'yaml';
  * @param data - Data to serialize as YAML
  */
 export function writeYamlOutput(data) {
-    process.stdout.write('---\n');
-    process.stdout.write(yaml.stringify(data, {
+    // Deliberately the ordinary stream write, NOT writeStdoutSync: this summary
+    // follows human-readable progress output written via console.log, and a
+    // synchronous fd-1 write would jump ahead of anything still buffered there.
+    // Completeness is guaranteed instead by makeStdioBlocking() at startup, which
+    // makes BOTH channels synchronous and keeps them in order.
+    process.stdout.write(`---\n${yaml.stringify(data, {
         indent: 2,
         lineWidth: 120,
         aliasDuplicateObjects: false,
-    }));
-}
-/**
- * Flush stdout before writing to stderr
- * Prevents output corruption when streams are merged
- */
-export async function flushStdout() {
-    return new Promise((resolve) => {
-        if (process.stdout.writableNeedDrain) {
-            process.stdout.once('drain', resolve);
-        }
-        else {
-            resolve();
-        }
-    });
+    })}`);
 }
 /**
  * Write a test-format finding to stderr.