fix(mcp): separate log cutoffs from backend failures

[roodboi]

HACK-1134 (unit Y1).

Final behavior

hack.project.logs.tail and hack.project.logs.snapshot now end in exactly one outcome:

• Complete: the backend ended the stream and exited 0. ok: true, data.cutoff: null.
• Cutoff: the server stopped collection at one of its own bounds. This is a success: ok: true, no isError, and data.cutoff = { bound, limit }:
  • events: maxEvents reached. Only type: "log" events count. start, heartbeat, error and end events are still returned.
  • time: maxMs for tail, or the 120 s command timeout for snapshot.
  • bytes: the shared 8 MiB stdout+stderr budget. outputTruncated: true, and data now keeps the events parsed before the cut. The cut backs off to a UTF-8 code point boundary.
• Backend failure: an error event, an end event whose reason is not eof/closed, or a non-zero exit at end of stream. ok: false, isError, and the closed error: { code: "E_UNEXPECTED", reason: "backend_error", message: <fixed> }. The message never repeats backend output, caller input or the query.

Failure evidence counts only before the server stops the child. A child that writes error/end(error) or exits non-zero in response to the server's own SIGTERM still produces a cutoff. The byte bound is the exception for events: every retained byte was written before the child was signalled, and nothing after the cut is parsed, so an error or failing end event inside the returned prefix is still a backend_error. For the events and time bounds, an error the backend wrote just before the stop but that the server read after it is reported as a cutoff; the server cannot tell it apart from a reply to the stop, and the doc says so. After a cutoff exitCode is the child's real status, which is often non-zero. data.stop_reason keeps its values.

Implementation:

• src/mcp/logs-contract.ts: pure event classification and outcome mapping.
• src/mcp/server.ts: both tools go through one collector (runHackLogCollect) and buildLogToolResult. The output schema now admits backend_error/E_UNEXPECTED.
• src/mcp/output-budget.ts: opt-in codePointSafe mode, used only by the logs collector. The default byte-exact mode and its existing tests are unchanged.

Docs: docs/guides/agent-first-setup.md now scopes the "8 MiB budget is an error with data omitted" rule to non-log tools, and links the logs contract for the log tools' bytes cutoff. The maxEvents input description says only type:log events count (this changes the tool's schema text).

Decision doc: docs/reference/mcp-logs.md records no-go on stream handles, resume cursors and idempotency keys, with the conditions for revisiting. No cursor code is added.

Validation

Rework at e2c41a98 (after independent verification of 42e7b3b7):

• bun test tests/mcp-logs-contract.test.ts tests/mcp-lifetime.test.ts: 28 pass, 0 fail, 3 consecutive runs
• bun test tests/mcp.test.ts tests/mcp-session-context.test.ts tests/mcp-output-budget.test.ts tests/mcp-command-admission.test.ts tests/mcp-prompts.test.ts tests/mcp-startup-contract.test.ts tests/integration-ownership.test.ts tests/agent-plugin-generation.test.ts: 50 pass, 0 fail. No guidance render changed, so no fingerprint was appended.
• bun run --cwd packages/cli typecheck: exit 0. bun run --cwd packages/cli check: exit 0, 0 errors, 34 warnings (unchanged); changed files lint clean.
• No new macOS DiagnosticReports entry after the runs.

Original head 42e7b3b7:

• bun test tests/mcp-logs-contract.test.ts tests/mcp.test.ts tests/mcp-lifetime.test.ts tests/mcp-output-budget.test.ts tests/mcp-command-admission.test.ts tests/mcp-session-context.test.ts tests/mcp-socket-backend.test.ts: 62 pass, 0 fail
• bun test tests/integration-ownership.test.ts tests/agent-plugin-generation.test.ts: 20 pass, 0 fail. No guidance render changed, so no fingerprint was appended.
• bun run --cwd packages/cli typecheck: clean
• bun run --cwd packages/cli check: 0 errors, 34 warnings (the base branch also has 34; the changed files have none)
• The CLI surface is unchanged, so docs:cli-reference was not regenerated.

New tests (tests/mcp-logs-contract.test.ts) use in-process sessions against a scripted stub backend (HACK_MCP_COMMAND), with a temp HOME, HACK_HOME and registry. They do not touch Docker/OrbStack or agent client config:

• Each outcome for tail and snapshot, including heartbeat-interleaved maxEvents, a post-stop error, an error event that ends 8 bytes before the byte limit in the same write as the over-limit bytes, and a byte cut 3 bytes into a 4-byte emoji (asserts no U+FFFD and the exact retained byte count).
• No replay: consecutive calls each start a new stream. A mid-tail disconnect stops the backend process, and a reconnected session sees only its own invocation's events. A cancelled tail stops its backend, and the retry in the same session starts fresh.

Negative controls

• Mutating the collector (code-point-safe off, count all events toward maxEvents, accept failure events after a stop) fails 6 of the new tests. Restoring it passes them.
• Rework: restoring the old gate (ignore all failure events once any stop fires) fails the new "error event read in the same chunk as the byte cut" test on 3 of 3 runs. Dropping the gate entirely fails the post-stop error test. Both restored afterwards.
• A unit test shows that the byte-exact default capture does split a code point (it emits U+FFFD), so the UTF-8 assertion can detect the bug.

Contract change to an existing assertion

tests/mcp-lifetime.test.ts "hack.project.logs.tail bounds oversized stdout/stderr" asserted ok: false, isError, and no data after the byte limit. This unit's brief requires that result to be a cutoff success with partial data. For logs.tail only, the test now asserts ok: true and data.cutoff = {bound: "bytes"}. The outputTruncated assertion, the bounded capture size, the stopped child and the usable session are still asserted. hack.projects.list keeps the original assertions unchanged. The timeout lifetime test now also asserts ok: true and cutoff: {bound: "time"}.

Remaining gaps

• Not exercised against real Docker Compose or Loki backends. Only the stub stream is tested. The classification follows the end reasons the CLI writes (eof, exit:N, closed, error).
• The native/authored logs path writes one JSON result object, not typed stream events. It completes as eof, and maxEvents does not apply to it.
• The events/time race described above is accepted and documented, not closed.
• The time-window tests use a 2 s window (was 300 ms) so Bun stub startup on a loaded host cannot flake them.
• Hosted CI has not run yet on this head.

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[blacksmith-sh]

Found 2 test failures on Blacksmith runners:

Failures

Test	View Logs
native-config-build (133.3s) — Native --profile must succeed/ native-config-build (133.3s) — Native --profile must succeed	View Logs
native-config-down-hooks (19.0s) — Each finite down mode starts a ready owned generatio n/ native-config-down-hooks (19.0s) — Each finite down mode starts a ready owned generatio n	View Logs

^{Need help on this PR? Tag @codesmith-bot with what you need.}