docs: the failure shapes a client cannot learn from the routes

[Wirasm]

Documentation only — no behaviour changes. Three distinctions the wire makes that the docs did not, all found by helm porting against the merged surface, and in two cases only after the wrong guess had shipped.

An empty changedFiles is not always "clean"

helm-migration.md tells clients to derive collidesWith from git.changedFiles and never mentioned git.error. There are three states, not two:

Shape	Means
git absent	not measured
git present, changedFiles: [], no error	measured, genuinely clean
git present, changedFiles: [], error set	measurement failed

worktree-status.ts captures git failures as data (error?: string, documented there as "any git failure captured here, NEVER thrown") and leaves the list empty when that fires. A client following the doc as written would report "collides with nothing" at exactly the moment it cannot tell — and that answer feeds a land gate.

The list itself is not optional; git is. A client guarding an optional changedFiles is guarding a state that never occurs while leaving the real one unguarded.

POST /land returns 409 from two places, with different bodies

refused merge        409  { ...full land report, dryRun: false }
unresolvable target  409  { error, code }

kildResultStatus maps every non-not_found failure to 409, so an archived or orphaned target answers with a bare {error, code} while a merge that would not apply answers with the entire report — which also contains an error. That field therefore cannot discriminate them; wouldMerge can.

A client decoding every 409 as a report throws on the bare one and replaces a message that names the fix with an opaque decode error:

{ "error": "kild c8971dd5 is archived (its agents are gone) — address its tree as 'sidebar-observe'",
  "code": "invalid_state" }

Losing that makes a correctly-behaving engine look broken. Documented rather than changed: the two really are different kinds of failure, and helm is mid-port against this surface.

The transcript route refuses for an attached agent

owned     200  { entries: [{ role, text, toolCalls? }], total }
attached  404  { error: "agent @claude has no pi session file (yet)" }

ownership decides the source, not the fidelity. Refusing is correct — an empty transcript would assert the agent had done nothing, when the truth is the question has no answer for a harness kild does not own. Those agents' history is the kild message log, a different source rather than a thinner view.

Also noted: an assistant turn that only calls tools has text: "" with the calls in toolCalls, so a renderer reading text alone silently drops precisely the turns that acted.

Verification

Every claim was checked against the source rather than transcribed from the report that raised it — server.ts:907-923 and kildResultStatus for the dual 409, server.ts:257-271 for the transcript refusal, worktree-status.ts for the error semantics.