Show why a deploy was refused instead of "Deploy completed (no result payload)"

[dawsontoth]

harper deploy asks for an event stream so it can show deploy progress. When the server refused the request before that stream started — 401 from authentication, 403 from the role allowlist, 400 from validation — the operations server's content negotiation still chose the event-stream serializer and wrote the error body as one unnamed frame. The CLI found no done or error event and printed error: message: Deploy completed (no result payload)., so the reason for the refusal never reached the user. The server now answers such errors as JSON, and the CLI no longer parses a failed status as a stream and unwraps the frame older servers send.

Found on a customer's CI deploy against a cluster on 5.3.0-beta.2, where the role allowlist refused deploy_component (the refusal itself is #2175, fixed in #2809); the CI log showed only the "no result payload" line.

For the human reviewer

1. The CLI design changed after planning review. The plan read the last unnamed frame from any stream that ended without done/error. Gemini proposed never stream-parsing a failed status at all: read the body whole, unwrap an unnamed frame if there is one, and otherwise print it as it came. Adopted, because it also keeps a proxy's frameless error page (a 502 labeled text/event-stream) readable, where the plan would have printed the synthetic message. Codex rated the rest of the plan sound.
2. Requirement. The task preferred a server-side fix if other SSE clients hit the same thing, so I checked. Studio's streamOperation treats a non-OK or non-event-stream response as SSEUnsupportedError and falls back to a buffered request, which returns the JSON error, so it is not misreported. The CLI uses SSE only for deploy_component. I did both halves anyway: the CLI half is what fixes the reported case, since 5.3.0-beta.2 and every released server answer this way and the CLI version is independent of the cluster's; the server half makes the response truthful for anything else reading it (curl, custom CI scripts). Either half can be dropped on its own.
3. Scope of the server change. It is one condition in the operations server's preSerialization hook: an error-status reply that would negotiate text/event-stream goes out as JSON, even when the Accept header lists only SSE, since an error is not a stream. A route that set text/event-stream itself keeps it, and a stream payload never reaches the hook, so the progress stream's in-band event: error at status 200 is untouched. The hook is shared with the legacy custom-functions server (fastifyRoutes.ts), whose untyped errors to an SSE-preferring client become JSON too.
4. A successful stream that ends without done now returns its last unnamed frame instead of the synthetic message. That only happens when the CLI's version probe cannot route an older server to its legacy deploy path, for example when the role may not call registration_info. An empty done still wins over an earlier unnamed frame.
5. Declined review findings. Gemini claimed the failed-status branch could leave an IncomingMessage undrained and that a negotiated type could carry parameters. Both are contradicted by the code: the SSE branch drains the stream before unwrapping, and findBestSerializer splits parameters off before matching; Codex re-checked both the same way.

Changes

• server/serverHelpers/contentTypes.ts: the preSerialization hook answers an error-status reply that would negotiate text/event-stream as JSON, unless the route set that type itself (compared case-insensitively).
• bin/cliOperations.ts: a failed status is read whole instead of streamed; an unnamed frame is unwrapped, and a frameless body is printed as it came, through the existing error exit. On a successful stream, the last unnamed frame becomes the result when no done or error arrived.
• server/DESIGN.md: the rule, next to the REST layer's matching one for streaming startup errors.

Docs: none needed. The docs describe the deploy and get_deployment event streams, not how a request refused before one starts is answered, so nothing documented changes.

Verification

End-to-end route: extended an existing integration test. integrationTests/server/qa579-cli-exit-codes.test.ts gains Cell 6 (listed in the header): the real built CLI deploys, with auth_username/auth_password so ambient credentials cannot stand in, as a role whose allowlist omits deploy_component, against a real instance. It asserts a non-zero exit, the allowlist refusal in the output, no "no result payload" line, and no component directory. On base 30f8ff616 it fails with exactly the reported error: message: Deploy completed (no result payload).; on the branch the suite passes 6/6.

Unit, each half proved on its own:

• unitTests/server/serverHelpers/contentTypes.test.js: a real Fastify app with the ops server's negotiation hook and serverErrorHandler. 400, 401, 403 and 500 errors, and one raised from a request hook, now come back as JSON with their status and body; these five fail on base. Controls: a successful reply still negotiates an event stream, a stream that set its own type (with an event: error) and an error with an explicit type are untouched, a route that chose text/event-stream (either case) with its own serializer keeps it, and CBOR stays CBOR, including when it outranks SSE in the Accept header.
• unitTests/bin/cliOperations.test.js: the CLI against a loopback server writing what older servers send, with the real request path. A 403 as an unnamed frame prints the refusal and exits 1; a 502 HTML page labeled as an event stream prints the page; a successful stream with unnamed frames returns the last one, and one that is not JSON as text. These four fail on base. Controls: an empty done still wins over an earlier unnamed frame, and a stream that breaks after a frame still exits 1.

Other runs on the branch: the SSE-related integration suites (deploy-multipart-stream, deploy-tracking-events, qa702-sse-event-data, sse-throw-midstream, stream-error-contract, operations-server, with QA-579) 65/65; test:unit:bin 254 passing; test:unit:server 996 passing, with 10 failures that are the same machine-specific ones base shows (/tmp vs /private/tmp preload paths, process-group reclaim, a uWS 413); lint:required, check:design-docs, prettier --check and tsc pass. I did not run test:unit:main or test:integration:all locally: on this machine test:unit:main needs a sentinel HOME to keep suites that clear ROOTPATH off the installed Harper's config, and this session's worktree isolation refuses to set HOME. CI runs both.

Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; blocked=cursor-composer(no-receipt),domain(quota); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=2; full=1 @ 2fb1b7d}

_{Human-Review-Need: 4 @ a982e3c}

[gemini-code-assist]

Code Review

This pull request improves the handling of requests that are refused before their progress stream starts, particularly for deploy_component operations. It ensures that such errors are returned as JSON instead of an event stream, and updates the CLI to correctly unwrap unnamed frames sent by older servers in these scenarios. Comprehensive unit and integration tests, along with design documentation, have been added to support these changes. Feedback on the changes suggests simplifying a redundant content-type check in the preSerialization hook of contentTypes.ts since the hook already returns early if the header is set.

[claude]

Reviewed; no blockers found.