CLI: retire the flat `fail()` accommodation in `readErrorMessage` once the control plane finishes converting (cloud#944)

[os-elon]

Filed unassigned from the work on #10763, and deliberately not folded into it — that card's subject is the [object Object] read in os package publish, and this is the scheduled removal of the accommodation that fix had to carry.

What was measured

#10763's dispatch condition was to measure the real failure envelope of the /api/v1/cloud/** publish routes before choosing a read shape. The result:

• Those routes are served by the sibling cloud repo. This repo's dispatcher explicitly refuses those paths, so no in-repo ledger can vouch for them — stated in docs/audits/2026-07-dispatcher-client-route-coverage.md §10. The cloud repo is not readable from an agent session, and the live host is refused by egress policy, so the producer cannot be driven from here.

• The measurement therefore came from the closest first-hand reader of the same service-cloud family: readApiError in objectui, packages/app-shell/src/console/marketplace/marketplaceApi.ts. Its docblock records that those routes answer failures in two shapes and are mid-conversion from one to the other, tracked as cloud#944:

  • { success: false, error: 'a sentence' } — today, written by the cloud's fail() helper
  • { success: false, error: { code, message } } — the declared envelope

Both arms are live today. That is why #10763 could not reuse the strict readEnvelope landed by #10675 (which was measured against the in-repo /api/v1/datasources/** routes): against the dialect the control plane still emits, a strict envelope-only read would have replaced one unreadable failure with another.

The producer half is not ours

The non-envelope failure is a producer defect and it is already tracked at the producer, as cloud#944. Nothing is asked of this repo for that half, and it is recorded here only so the consumer half has a stated trigger. Per #10763's triage condition, it is named rather than folded in.

The consumer half, which is ours

readErrorMessage in packages/cli/src/utils/response-envelope.ts accepts the flat dialect in exactly one branch, written so it is deletable on its own. When cloud#944 lands and the control plane emits only the declared envelope:

1. Delete the flat branch in readErrorMessage and the unit case that drives it.
2. Re-check the two sibling readings, which os package publish renders a failed publish as [object Object] — it reads the flat body.error, not error.message #10763 deliberately left untouched because both are correct on both measured arms today:
   • packages/cli/src/commands/plugin/publish.ts — hits the same two routes; once one dialect remains, its hand-rolled read can move to readErrorMessage.
   • packages/cli/src/commands/package/install.ts — targets the runtime's /api/v1/marketplace/install-local, a different route family; it is not governed by cloud#944 and should be re-judged on its own evidence, not swept in.
3. objectui's readApiError carries the same accommodation for the same reason and can be narrowed in step.

⚠️ Do not act on this before cloud#944 is confirmed complete. Removing the flat branch early restores the defect #10763 fixed, on the most common failure path, and the CLI suite would stay green — nothing in this repo can drive the real producer.

Related

• os package publish renders a failed publish as [object Object] — it reads the flat body.error, not error.message #10763 — the [object Object] read this accommodation was introduced for.
• os datasource list-tables/introspect/validate are non-functional — CLI reads pre-#3843 flat envelope #10675 — the strict reader, measured against the in-repo datasource routes.
• [tracking] Envelope-position convergence line for packages/rest's flat dialect — the live ratchet owner #9559 — the convergence line for packages/rest's own flat dialect. Same defect class, a different producer (in-repo); tracked separately and not blocked on cloud#944.

[huangyiirene]

Blocked-by: objectstack-ai/cloud#944

Concentration-round first-touch: graded Task, parked pm:blocked — the card's own ⚠️ is the grading: acting before cloud#944 completes restores the #10763 defect on the most common failure path, and nothing in this repo can drive the real producer to prove otherwise. Cross-repo machine-readable line above for the unlock scan (cloud is outside this session's authorization face — a cloud-capable triage fire verifies the close). On release: the three-step scope in the card stands as written, including the ⛔ against sweeping package/install.ts in (different route family, re-judged on its own evidence).

---

Generated by Claude Code