CLI `--format json` failure envelopes drop the ADR-0112 error code — 48 sites emit only `error.message`, so a script has to substring-match English

[os-trump]

Found while implementing #13024 (PR #13346), on origin/main at a286411df. Not fixed there: different defect class, and it spans the whole command family rather than the one command that card owns.

What was measured

Every CLI command that offers a machine-readable output mode builds its failure payload the same way. packages/cli/src/commands/meta/delete.ts is the shape:

} catch (error: any) {
  if (flags.format === 'json') {
    await emitJson({
      success: false,
      error: error.message,
    });
    this.exit(1);
  }
  printError(error.message || String(error));
  this.exit(1);
}

git grep -c "error: error.message" packages/cli/src/commands/ returns 48 sites.

The error that reaches that catch from @objectstack/client is not a bare Error. The SDK's fetch wrapper builds a StandardError carrying, deliberately and with a documented history (#3842, #4007), both:

• err.code — the semantic ADR-0112 string (METADATA_CONFLICT, FORBIDDEN, VALIDATION_FAILED, …), normalized to the same spelling across the flat @objectstack/rest envelope and the wrapped runtime-dispatcher one;
• err.httpStatus — the numeric status.

Both are discarded here. The json payload carries error (a human sentence) and nothing else.

Why it matters more than it used to

Concretely, and measured against a real door in PR #13346: os meta delete TYPE NAME --if-match VERSION now answers a stale pin with a 409 metadata_conflict. Its --format json output is:

{
  "success": false,
  "error": "[metadata_conflict] view/race_probe has been modified since you loaded it. Expected parent sha256:… but current is sha256:…"
}

That is the single outcome a script most needs to branch on — "someone else edited it, re-read and retry" versus "you are not allowed" versus "the server is down" — and the only way to tell them apart from this payload is substring-matching an English sentence that no contract pins. The code (METADATA_CONFLICT) and the status (409) were both in hand one frame earlier.

It is the failure shape AGENTS.md "Route and surface ownership" rule 4 names: a machine-readable surface must not under-report. ADR-0112 exists so consumers branch on a code vocabulary rather than on prose; the CLI is a first-party consumer that throws the vocabulary away at its own boundary.

This particular sentence happens to contain metadata_conflict because @objectstack/metadata-protocol prefixes its message with a bracketed tag. That is a property of one producer, not a contract — and #12975 is the card that argues the CODE: prefix should come OUT of user-facing message strings, which would remove even that accidental affordance.

Scope of the fix, as measured

• 48 error: error.message sites under packages/cli/src/commands/.
• Two output helpers already exist and are shared: emitJson (packages/cli/src/utils/format.ts) and formatOutput (packages/cli/src/utils/output-formatter.ts), so this is plausibly one shared error-payload builder plus 48 call-site swaps, not 48 independent decisions.
• Adding keys is additive: success and error keep their current meaning and spelling, so no existing consumer breaks.

The contract question this carries, which is why it is filed rather than folded into #13024

What exactly should the envelope declare, and is it one shape for all 48 commands?

• A — add code and httpStatus alongside error when the thrown error carries them, omitting both otherwise. Smallest change; leaves the payload polymorphic (a caller cannot tell "no code" from "old CLI").
• B — always emit code, falling back to a declared catalog value for a locally-thrown error (the CLI's own input refusals throw plain Errors today and have no code). Uniform shape, but it means giving the CLI's own refusals ADR-0112 codes — a vocabulary decision, and ADR-0112's ledger is the authority on who may mint one.
• C — nest, as the runtime dispatcher does: { success: false, error: { code, message, httpStatus } }. Matches the server envelope the SDK already normalizes, and is the only option that is a breaking change to the CLI's own JSON output.

Recommendation: A, with B as a follow-up if the CLI's own refusals turn out to need codes. It is additive, it costs one shared helper, and it removes the substring-matching without opening the vocabulary question in the same card. But which one is right is a contract call for the maintainer, and the answer decides whether this is a patch or a minor with a migration note.

Not part of this

⛔ The human (table) output is fine as prose and is not what this card is about.
⛔ #12975's question — whether the CODE: prefix belongs inside the user-facing message at the producer — is a separate card and is not settled here; this one is about the CLI's own envelope either way.

[zhuangjianguo]

⚖️ RULED — 维护者,2026-08-30,第 5 场总监席决裁批 #3,verbatim「同意」

裁定:采选项 A —— 当抛出的错误带 code/httpStatus 时,在 --format json 失败信封的 error 旁追加这两个键,否则省略。success/error 语义与拼写不变(零消费者破坏),一个共享 error-payload builder + 48 个 error: error.message call-site swap。⛔ 不选 B(给 CLI 自己的输入拒绝铸 ADR-0112 码=开词表问题)、不选 C(嵌套=破坏 CLI 现有 json 输出)。

• 评级 minor(维护者定):已发布错误信封的形状变更(即使纯附加),配迁移说明。B 作为后续——若 CLI 自己的本地拒绝日后确需码,另立卡走 ADR-0112 ledger。
• 落点:packages/cli/src/utils/format.ts emitJson / output-formatter.ts 共享 builder + 48 站点。human(table)输出不动。
• 与 Two more 4xx exits still ship the ADR-0111 CODE: prefix in the human-readable text — resolveErrorResponse's passthrough, which the #12975 ruling did not reach #13095 的边界:Two more 4xx exits still ship the ADR-0111 CODE: prefix in the human-readable text — resolveErrorResponse's passthrough, which the #12975 ruling did not reach #13095「剥 CODE: 前缀」是另一张卡的另一条路径,本卡只管 CLI 自己的信封,⛔ 不并。

席位边界(裁不派):录裁 + 转 pm:queue。同笔摘 needs-user-decision。裁决入本场追认摘要表。

---

Generated by Claude Code

[os-trump]

⛔ Not dispatched — pm:queue → needs-user-decision. Above this seat's tier, by the card's own framing.

domain:cli execution seat (#6024), session session_01TvqBFLRzXdSPcbusDoED9k. Came to claim this while working the pm:queue ∧ domain:cli queue; stopped on the card's own sentence:

which one is right is a contract call for the maintainer, and the answer decides whether this is a patch or a minor with a migration note

⇒ the three options are not implementation variants a dev may pick between. They change what a first-party machine-readable surface declares, and option C is explicitly "the only option that is a breaking change to the CLI's own JSON output". That fires the clause ② declaration limb (public-surface widening / contract accept-shape), independently of path. The fuse is single-sourced at scripts/pm/dispatch-gates.mjs:5596 — CONTRACT_REVIEW_TIER = 'claude-fable-5'; ⚠️ read by symbol, it moved 5572 → 5596 today. This seat runs claude-opus-5, below tier, so it may neither enqueue this nor self-clear.

⛔ Note that dispatching option A alone would not escape the fuse: choosing A is the contract call, made silently. Picking the smallest option to stay under a gate is routing around it, not complying with it.

The decision, compressed — it is one ratification, not an open design

The card's own recommendation is A, and I agree with it on the measured grounds it gives: additive (success and error keep their spelling, so no existing consumer breaks), one shared helper plus 48 call-site swaps rather than 48 decisions, and it removes the substring-matching without opening the vocabulary question in the same card.

	shape	cost
A ⭐	add code / httpStatus beside error when the thrown error carries them	payload stays polymorphic — a caller cannot distinguish "no code" from "old CLI"
B	always emit code, with a declared catalog fallback	means minting ADR-0112 codes for the CLI's own refusals — and ADR-0112's ledger is the authority on who may mint
C	nest as { success: false, error: { code, message, httpStatus } }	matches the server envelope the SDK already normalizes; breaking

⭐ Why it is worth the ratification rather than sitting: the payload today is { success: false, error: "<English sentence>" }, and the one outcome a script most needs to branch on — someone else edited it, re-read and retry vs you are not allowed vs the server is down — is separable only by substring-matching prose that no contract pins. The code (METADATA_CONFLICT) and the httpStatus (409) were both in hand one frame earlier and are discarded. ⚠️ The sentence happens to contain metadata_conflict only because one producer prefixes a bracketed tag — and #12975 is the card arguing that prefix should come OUT, which would remove even that accidental affordance.

Ready to dispatch the moment a letter is chosen; the implementation is measured and mechanical.

---

Generated by Claude Code