The OpenAPI description names every refusal of POST …/builds and the fields of a build pin, so an agent reads them before it is refused #9102

The OpenAPI document now lists every refusal of POST /api/v1/repos/{owner}/{name}/builds and the fields of a build pin. tsc, scripts/gate.ts and the 41 test files scripts/fast.ts named (599 tests) pass. I did not run the full suite, which the forge's check does on push.

• POST refusals: the route now names forbidden (403, an agent is refused), not_found (404), invalid_label, invalid_parent, not_a_commit and git_failed (all 422), and exists and mirrored (409). Each has one plain line, worded like the PATCH and DELETE build routes.
• POST reply: the route now carries a reply naming the pin's fields: label, oid, note, parent, source, pinnedBy, pinnedAt. The summary lists them too. reply is typed Record<string, string> and the Route type has no optional-field marker, so parent shows as a plain string even though it can be undefined.
• GET: it now has a reply of { items, next_cursor }, a summary that names each item's fields, and a not_found refusal.
• New test: test/build-pin-refusals.test.ts drives the POST over the API with a bad label, a bad parent, a missing commit, a taken label, an agent token and a mirrored repository. It reads the codes the served openapi.json lists under responses.default.description and expects each error it got back to be among them. It fails on main (I stashed the route changes to check) and passes now.

I did not change what any route answers. Every code the handler answered could be named honestly, so none are left out.

I left notes out of the pin's reply: the POST pin carries no notes, and the GET's items only carry them when notes are requested, which the document doesn't describe. Only the two route files and the new test changed, so this should merge cleanly with #9087.

Closes #9094

The OpenAPI document now lists every refusal of POST /api/v1/repos/{owner}/{name}/builds and the fields of a build pin. tsc, scripts/gate.ts and the 41 test files scripts/fast.ts named (599 tests) pass. I did not run the full suite, which the forge's check does on push.

• POST refusals: the route now names forbidden (403, an agent is refused), not_found (404), invalid_label, invalid_parent, not_a_commit and git_failed (all 422), and exists and mirrored (409). Each has one plain line, worded like the PATCH and DELETE build routes.
• POST reply: the route now carries a reply naming the pin's fields: label, oid, note, parent, source, pinnedBy, pinnedAt. The summary lists them too. reply is typed Record<string, string> and the Route type has no optional-field marker, so parent shows as a plain string even though it can be undefined.
• GET: it now has a reply of { items, next_cursor }, a summary that names each item's fields, and a not_found refusal.
• New test: test/build-pin-refusals.test.ts drives the POST over the API with a bad label, a bad parent, a missing commit, a taken label, an agent token and a mirrored repository. It reads the codes the served openapi.json lists under responses.default.description and expects each error it got back to be among them. It fails on main (I stashed the route changes to check) and passes now.

I did not change what any route answers. Every code the handler answered could be named honestly, so none are left out.

I left notes out of the pin's reply: the POST pin carries no notes, and the GET's items only carry them when notes are requested, which the document doesn't describe. Only the two route files and the new test changed, so this should merge cleanly with #9087.