diff --git a/test/unit/miner-cli-json-error-coverage.test.ts b/test/unit/miner-cli-json-error-paths.test.ts
similarity index 93%
rename from test/unit/miner-cli-json-error-coverage.test.ts
rename to test/unit/miner-cli-json-error-paths.test.ts
index 019c568a9c..a5a9a368f1 100644
--- a/test/unit/miner-cli-json-error-coverage.test.ts
+++ b/test/unit/miner-cli-json-error-paths.test.ts
@@ -69,7 +69,12 @@ async function expectJsonErrorAsync(
   stderr.mockRestore();
 }
 
-describe("miner CLI --json error coverage (#4836)", () => {
+// Shared --json error-envelope contract across the miner CLI's subcommands (#4836): every run* entry
+// point must fail with { ok: false, error: string } on stdout, exit code 2, and nothing on stderr.
+// Grouped by CLI surface (not split per-sibling file) because the thing under test IS the shared
+// envelope, exercised via expectJsonError/expectJsonErrorAsync above -- splitting it apart would
+// duplicate that helper and lose the "one contract, many entry points" narrative.
+describe("miner CLI --json error paths (#4836)", () => {
   it("portfolio queue list/next/done/claim-batch failures", () => {
     expectJsonError(() => runQueueList(["--verbose", "--json"]), /Unknown option/);
     expectJsonError(