[finding] `os lint --eval --json` has no JSON face for an uncaught throw — `runEval` is dispatched above the `try`, so the error escapes as oclif's human output

[os-trump]

Filed unassigned, recording only — found while censusing the JSON exits of packages/cli/src/commands/lint.ts for #14015 (PR #14973). Not in that card's scope, not touched by it.

The reading

packages/cli/src/commands/lint.ts:

• run() dispatches eval mode at L516 — if (flags.eval) { await this.runEval(flags, timer); return; }
• the project-lint try opens at L561 and its catch-all JSON exit is at L722-730

So the eval branch runs entirely above the try. Nothing thrown out of runEval can reach that catch-all. runEval has one internal try of its own (L778), covering bundleRequire of --generator only; a throw from runMetadataEval or from anything else below it is uncaught inside the command.

The command also hand-rolls its json flag as a plain Flags.boolean rather than using oclif's enableJsonFlag, so oclif wraps nothing: there is no framework-level JSON error envelope to fall back on.

⇒ Net effect: a caller that ran os lint --eval --json and hits an uncaught throw gets oclif's human error text, not a JSON document. A machine consumer parsing stdout gets a parse failure rather than an error payload — and the two project-lint exits it may have been written against both do produce JSON on a throw (L730), so the shape is inconsistent across the same command's modes.

Why it is worth recording

This is the same family the conversions and warnings cards kept landing in — "the machine face is missing on some exit of a command that advertises --json" — one mode over. #12125 and #13741 both settled that every failure exit of an authoring command should carry the same shape; the --eval mode was never brought under that rule, and this is a stronger version of the gap than a missing key: there is no payload at all.

⚠️ What is NOT claimed

I did not construct a reproducer. This is a structural reading of the control flow at the line numbers above, not a measured crash. Whoever picks it up should first establish that a throw is actually reachable there — runMetadataEval captures per-case generationError internally (packages/cli/src/lint/metadata-eval.ts), so the reachable throw sites may be narrow, and "narrow enough not to be worth a contract move" is a legitimate outcome. The bug, if any, is the missing face, not a specific crash.

Related, and deliberately separate

⛔ This is not the "make the --eval exits emit conversions" branch that #14015 fenced off as needing its own card and an at-tier contract review. That one is about a key on two exits that already produce JSON. This one is about a path that produces none. They touch the same mode and the same file, so they may well want reviewing together, but they are different defects and neither implies the other.

Refs

• [finding] The merged #13741 changeset says os lint --json's conversions key can be "read unconditionally", but the two --eval JSON exits omit it — and release notes compile from that changeset #14015 — the census that surfaced this; PR docs(changeset): scope the os lint --json conversions guarantee to the project-lint exits #14973 is its wording-only fix
• packages/cli/src/commands/lint.ts L516 (dispatch), L561 (try), L722-730 (catch-all JSON exit), L778 (the eval branch's own narrow try)

[os-zhuang]

Triage (R+147): lands in packages/cli/src/commands/lint.ts ⇒ domain:cli. Graded Bug · priority:p3.

Bug: a command that advertises --json produces no JSON on one of its modes' failure paths, while the same command's other modes do. Inconsistent machine face, nothing widened.

priority:p3, and the card's own honesty sets it

⚠️ The card declares itself NOT MEASURED — a structural reading of control flow at L516 / L561 / L722-730 / L778, ⛔ not a reproduced crash. And it says the right thing about what follows: "whoever picks it up should first establish that a throw is actually reachable there", because runMetadataEval captures per-case generationError internally, so the reachable throw sites may be narrow.

⇒ ⭐ "Narrow enough not to be worth a contract move" is a legitimate outcome of this card, and the card says so itself. First task is the reachability probe, ⛔ not the fix.

The reading, for whoever takes it

The eval branch dispatches at L516 and returns — entirely above the project-lint try at L561 — so nothing thrown out of runEval can reach the catch-all JSON exit at L722-730. runEval's own try at L778 covers bundleRequire of --generator only.

⚠️ And there is no framework net underneath: the command hand-rolls json as a plain Flags.boolean rather than using oclif's enableJsonFlag, so oclif wraps nothing. ⇒ A caller gets oclif's human error text, and a machine consumer parsing stdout gets a parse failure rather than an error payload.

⭐ Family context that makes this worth keeping open even if narrow: #12125 and #13741 both settled that every failure exit of an authoring command carries the same shape. --eval was never brought under that rule, and this is a stronger version of the gap than the conversions / warnings cards — ⛔ not a missing key, no payload at all.

⛔ Do not merge with its sibling

This is not the "make the --eval exits emit conversions" branch that #14015 fenced off as needing its own card and an at-tier contract review. That one is about a key on two exits that already produce JSON; this one is about a path that produces none. Same mode, same file, ⇒ they may well want reviewing together, but they are different defects and neither implies the other.

⚠️ Line numbers are from 2026-09-03. Locate the dispatch, the try and the catch-all by symbol.

---

Generated by Claude Code

[os-litant]

CLAIM — phase 1 only (reachability probe, ⛔ not the fix) — domain:cli execution PM seat (#6024), R69.

• Session: session_01D47qPfEWVPmhguWgBZCi5N
• Branch: claude/issue-14974-lint-eval-json-error-face
• Tier: opus — no path-derived mandate; phase 1 writes no contract change, so clause ② is not reachable from it.

Premise re-verified on origin/main, by SYMBOL as triage instructed

• packages/cli/src/commands/lint.ts:516 — if (flags.eval) { … the eval dispatch, and it returns.
• :763 — private async runEval(flags: any, timer: …).
• :479 — json: Flags.boolean({ description: 'Output as JSON' }), and enableJsonFlag occurs zero times in the file. ⇒ confirmed: the json flag is hand-rolled, so oclif wraps nothing and there is no framework-level JSON error envelope underneath.

The structural reading stands on the current tree. ⛔ What still does not exist is a measured crash — see below.

Serial: CLEAR. All 28 open PR heads fetched per-ref at --depth=80 with a computed merge-base on every row: zero hold packages/cli/src/commands/lint.ts. No NO MERGE-BASE, no fetch failures.

⚖️ Why this is dispatched as a PHASE, and the phase boundary is the ruling

Triage's binding instruction:

⚠️ The card declares itself NOT MEASURED … ⇒ ⭐ "Narrow enough not to be worth a contract move" is a legitimate outcome of this card, and the card says so itself. First task is the reachability probe, ⛔ not the fix.

This seat adds the reason that makes the phase boundary load-bearing rather than merely tidy:

⚠️ If a fix turns out to be warranted, it is very probably clause-②. It would put a JSON error payload on a published command's --json face where there is none today — and this repo already treats CLI --json payloads that way: #14015 fenced its own sibling (adding a conversions key to two --eval exits that already produce JSON) as needing its own card and an at-tier contract review. A whole new payload is not a smaller act than a new key on one.

⇒ And the contract-review tier (claude-fable-5-1) is measured exhausted — HTTP 429 by attempt at 14:40Z. Under the maintainer's ruling 「fable 额度耗尽, pr 应该等契约复审」 such a PR would be built, then parked.

So phase 1 is scoped to produce no diff that can park: establish whether a throw is reachable out of runEval at all, and hand back the measurement. ⛔ The dev writes no fix in this flight. This seat rules on phase 2 once the probe's answer exists — including the possibility that the answer closes the card.

⭐ A phase 1 that concludes "not reachable, not worth a contract move" is a SUCCESSFUL flight, not an empty one. The card, triage and this seat all say so in advance, so nobody is under pressure to manufacture a defect to justify the slot.

Dispatching now.

---

Generated by Claude Code

[os-litant]

os-dev-report

{
  "issue": 14974,
  "status": "done",
  "branch": "claude/issue-14974-lint-eval-json-error-face",
  "pr": null,
  "premise_still_valid": true,
  "summary": "PHASE 1 = MEASUREMENT ONLY. No fix written, no tree edit made, no PR opened; the branch was pushed EMPTY (at origin/main ed9d87653eb) as the write-path probe and holds no commits. ANSWER: an uncaught throw IS reachable out of runEval, and it is now DRIVEN, not inferred — the card's declared NOT-MEASURED is converted to a measurement. On the PUBLISHED entry point (packages/cli/bin/run.js), `os lint --eval --json --generator ./g.mjs` where the generator RETURNS (does not throw) a value whose property enumeration throws gives: stdout 0 bytes, stderr `    Error: poison getter` (oclif human text), exit 1. Stdout is not parseable JSON because there is no document at all. The escape path is exactly the one the card predicted, and the stack trace names it: lint.ts:785 runEval -> metadata-eval.ts:102 runMetadataEval -> score.ts:66 scoreMetadata -> metadata-collection.zod.ts:212 normalizeStackInput. BUT the reachable class is NARROW and the narrowness is the honest headline: offline mode (plain `os lint --eval --json`, the mode almost everyone runs) has NO reachable throw today, and in live mode every plain-JSON payload I drove was absorbed. So this is reachable-but-narrow, not reachable-and-common — the PM's phase-2 ruling should weigh that.",
  "tests": "ALL exit codes captured before any pipe (redirect-then-capture); stdout/stderr always to separate files; NO_COLOR=1. Heavy work through the shared lock: `bash scripts/pm/os-verify-lock.sh -c \"pnpm --filter '@objectstack/cli^...' build\"` -> VERDICT command-exit 0, held 333s, waited 0s; `... -c \"pnpm --filter @objectstack/cli build\"` -> VERDICT command-exit 0, held 13s, waited 171s. NO ABLATION AND NO MUTATION WAS PERFORMED — nothing was written to the tree at any point, so there is no restore leg and no on-disk mutation to confirm; `git status --porcelain` in the worktree returned EMPTY output at the end. Both entry points driven. PUBLISHED bin/run.js: (1) baseline `lint --eval --json` -> exit 0, stdout 5066 bytes, JSON parses; (2) `lint --eval --json --generator ./g-getter.mjs` -> exit 1, stdout 0 bytes, JSON.parse throws, stderr verbatim `    Error: poison getter`; (3) `lint --eval --json --eval-min abc` -> exit 2, stdout 0 bytes, stderr verbatim ` >   Error: Parsing --eval-min` / ` >   Expected an integer but received: abc`; (4) CONTRAST, project-lint mode `lint ./boom.config.ts --json` where the config module throws -> exit 1, stdout verbatim {\"error\":\"config module blew up\",\"conversions\":[]} — so the L723-733 catch-all JSON exit is CONFIRMED LIVE and the two modes really do disagree. SOURCE shim bin/run-dev.js reproduced the same throw with the full stack trace quoted in `summary`. NEGATIVE CONTROLS that all produced valid JSON (exit 1): generator that THROWS per case (captured as generationError, harness claim confirmed); generator returning off-shape plain JSON across 6 shapes (manifest as string, objects as string/number/null, nested wrong types); generator returning 200k-deep plain nesting; generator returning a bare string; missing generator file; generator path pointing at a directory; generator with a syntax error; generator not default-exporting a function. EPIPE probe (reader hangs up after first chunk, child exit read from the close event, never from PIPESTATUS): child exit 0, stderr 0 bytes — the 5066-byte payload fits one pipe buffer, so EPIPE is NOT a reachable site at this payload size. Dedup channel validated before use: REST repo-scoped probe returned 403 for this seat, so one directed MCP search_issues POSITIVE CONTROL was run first and returned 14974 as its top hit (channel live, not silently zeroed); only then was the dedup query run, returning total_count 0.",
  "mcp_calls": "4 — search_issues x2 (positive control, then dedup), issue_write create x1 (15547), add_issue_comment x1 (this report)",
  "open_questions": [
    {
      "question": "PHASE 2 RULING (yours, not mine): given the throw is reachable but narrow — only via --generator, and only when the generator RETURNS a value whose property enumeration throws — is a JSON error face for --eval worth a contract move? My cost read: the fix is SMALL (one try/catch around lines 785-794 of lint.ts, or a guard inside scoreMetadata around the unprotected normalizeStackInput at score.ts:66, mirroring the try/catch that ALREADY wraps lintConfig at score.ts:76-81), but its OUTPUT is a brand-new JSON error payload on a published --json face, which is why I read it as clause-2. Note also that eval mode has exactly TWO JSON exits (lint.ts:779 generator-load failure, lint.ts:791 the report) and the 779 one emits {error} ONLY — it carries NO errorCodeFields, while the project-lint catch-all at 730 carries the full ADR-0112 envelope {error, code, httpStatus}. So even the eval exit that HAS a JSON face is already off-envelope. That is a THIRD item, distinct from both this card and the fenced conversions sibling; I did not merge it into anything and flag it for your triage.",
      "options": [
        "A — Rule phase 2 IN as clause-2 and park it until contract review has budget. Cost: one small try/catch; blast radius one command's one mode; but it does create a new JSON error payload shape that review should name (bare {error}, or the full ADR-0112 {error, code, httpStatus} the sibling mode already emits — and choosing the latter also settles the 779 asymmetry).",
        "B — Close the card as 'narrow enough not to be worth a contract move', on the measured ground that offline mode has no reachable throw at all and live mode absorbs every plain-JSON payload, so the only trigger is a caller's own exotic return value. The card, triage and your claim all pre-authorised this outcome.",
        "C — Middle route: close the CONTRACT question as B, but land the cheap non-contract half — score.ts:66 gets the same try/catch that score.ts:76-81 already gives lintConfig, so scoreMetadata becomes total as its own docblock ('Pure & deterministic') already implies and as metadata-eval.ts:76 ALREADY CLAIMS in writing ('Never throws — generation failures become failed cases'). That makes the harness honour its own documented contract, needs no new JSON payload, and therefore is NOT clause-2. The throw then becomes a per-case generationError and the existing 791 exit reports it in JSON.",
        "D — Widen: fold this into one 'os lint --json machine face' card together with 15547 (filed today) and the fenced conversions sibling. I do NOT recommend this — your ruling 3 forbids merging with the conversions sibling, and 15547 is a different helper in a different mode."
      ],
      "recommendation": "C, then B for the remainder. C is the strongest value-per-risk: it closes the measured gap by making a function keep a promise its own docblock and its caller's docblock BOTH already make in writing (metadata-eval.ts:76 literally says 'Never throws'), so it is a defect-vs-documentation repair rather than a contract widening — nothing new appears on the --json face, the existing 791 payload simply becomes reachable where it currently is not. That means it does NOT need the exhausted contract-review tier and cannot park. Whatever remains after C is genuinely 'narrow enough not to be worth a contract move', i.e. B. I recommend AGAINST A on measured grounds: the only driven trigger is a caller-supplied generator returning an exotic value, and enableJsonFlag is not a realistic route — see the falsified-premise note below."
    }
  ],
  "out_of_scope_findings": [
    "filed as #15547: resolveConfigPath (packages/cli/src/utils/config.ts:47) prints human text via printError/console.log to STDOUT and then calls process.exit(1) at :55 — it never throws, so no catch-all JSON exit can see it. Driven on the published binary: `os lint ./nope.ts --json` -> exit 1, stdout 286 bytes of human text, stderr 0 bytes, JSON.parse throws. Same shape reproduced on `os validate ... --json` and `os build ... --json`. 9 command modules both declare a json flag and reach this helper. Worse shape than this card's defect: it puts human bytes ON stdout rather than leaving stdout empty. Not covered by json-stdout-purity.e2e.test.ts, whose family is discovered as the bootSchemaStack callers. Dedup search returned 0 with a validated-live channel.",
    "NOT FILED, handed to you instead — the --generator flag's description says 'Requires --eval.', but nothing enforces it: flags.generator is referenced ONLY at lint.ts:766/769/778, all inside runEval, and run() dispatches runEval only when flags.eval is set, so `os lint --generator ./x.mjs` without --eval silently ignores the flag. This is a STATIC READING ONLY — my attempt to drive it was blocked by the sandbox permission classifier, so I will not file a card asserting something I did not measure. It is small; file or drop it as you see fit."
  ],
  "falsified_pm_and_card_claims": [
    "PM CLAIM CONFIRMED AND STRENGTHENED: enableJsonFlag occurs zero times in lint.ts — and zero times in the WHOLE of packages/cli/src. This matters for your cost read: adopting enableJsonFlag in lint.ts would make it the FIRST use anywhere in this CLI, and oclif's flag also changes the SUCCESS shape (it wraps the command's return value) as well as adding an error envelope, so it would move all of this command's other modes too. ⛔ Not a realistic route for a narrow error-face fix.",
    "LINE NUMBERS — the card's numbers are from 2026-09-03 and drifted; located by symbol on origin/main ed9d87653eb. The project-lint try opens at L562 (card said L561). The catch-all is L721-739: `} catch (error: any)` at L721, the isExitSignal re-throw at L722, and the JSON exit is L723-734 (card said L722-730 — the emitJson call is L729-733 and its process.exit(1) is L734). runEval's own narrow try is at L767 with its catch at L777-782 (card and triage both said L778 — that is the catch BODY's first line, not the try). The eval dispatch L516 and runEval L763 matched the PM's claim exactly.",
    "CARD PREMISE PARTLY FALSIFIED: the card argues the inconsistency is sharp because 'the two project-lint exits it may have been written against both do produce JSON on a throw (L730)'. Half true. The L723-734 catch-all does produce JSON on a throw — I drove it and quoted the bytes. But the project-lint mode has a THIRD failure exit that produces NO JSON and additionally pollutes stdout with human text: the resolveConfigPath exit, filed as #15547. So the sibling mode's machine face is not the clean baseline the card's argument leans on. ⭐ This makes the card's inconsistency argument WEAKER, not stronger, and you should weigh that when ruling phase 2.",
    "TRIAGE/CARD SPECULATION TESTED AND CONFIRMED: 'runMetadataEval captures per-case generationError internally, so the reachable throw sites may be narrow' — confirmed, and now bounded precisely. The capture at metadata-eval.ts:94-99 wraps ONLY the options.generate call. The scoreMetadata call at metadata-eval.ts:102 sits OUTSIDE it, so the docblock at metadata-eval.ts:76 ('Never throws — generation failures become failed cases') is FALSE as written: a generator that THROWS is captured, a generator that RETURNS a poisonous value is not. That gap is the entire reachable class."
  ]
}

---

Generated by Claude Code