[gabrielsayers1]

Elegance pass over infra/birdhouse, driven by four independent reviews: two over the package, then two over the resulting refactor (one adversarial, one on taste).

The main change: stop routing errors through prose

createWorkflowRun and claimWorkflowRun each threw Error("...unknown workflow..."), and the HTTP layer regex-matched that English to pick a status — /unknown workflow|is disabled/ in /run, matched separately in /claim to split 404 from 400. Three independently-worded messages, two independently-written regexes, nothing keeping them in sync: rewording a message to fix a typo would have turned a classified 4xx into a 500, with no test to catch it.

One shared lookup now raises a typed WorkflowLookupError carrying a machine-readable reason, and one app.onError maps reason to status. Both routes lost their identical catch blocks and read as happy paths.

That also fixes a contract split: /run answered 400 for both failures with the raw Error.message — internal function-name prefix and all — while /claim answered stable codes. They now agree (404 unknown, 400 disabled), verified live.

Deliberately not merged: the two insert paths. createWorkflowRun writes a pending row guarded by job idempotency and hands off to a launch job; claimWorkflowRun writes an already-running row guarded by the partial unique index, because the caller is the agent. Different lifecycles, different failure semantics — merging them would branch on trigger mid-insert and read worse. Only the validation prefix was accidental duplication.

/api/runs/:id/result had no error contract

It had no try/catch at all, so a database blip on the busiest route in the service fell through to Hono's default handler and answered plain text, breaking the JSON {error} contract every other route promises. The shared handler covers it, with a regression test.

Holes the first pass opened, found by review

• Deleting the routes' catch blocks removed a blanket net: Hono hands onError only what is instanceof Error and rethrows anything else past it, where the node adapter answers an empty 500 with no body and nothing logged. The logging middleware now normalises non-Error throws. The regression test claimed to cover this and didn't — it only threw Errors — so it now covers both shapes, and I verified it fails without the fix rather than assuming it would.
• parseJsonBody's emptyBody parameter is gone. It existed because the result callback fell back to undefined where the others fall back to {} — but that schema requires status, so an absent body is a 400 either way. The knob never changed an outcome and cost a caveat comment longer than the code it explained.
• Both routes now say where their failures become responses; a reader starting at a route couldn't see it could fail at all.

Smaller

Dead "schedule" member removed from WorkflowRunTrigger (claimWorkflowRun writes that row itself, so nothing could construct it); jobsPruned reported in the maintenance summary like its other two jobs; comments corrected that described a deleted scheduler, an input_schema validator that never existed, and a build-phase wave 2 marker.

Verification

pnpm typecheck clean; 121 tests pass under TZ=UTC and TZ=America/New_York. Both error contracts smoke-tested against the running worker on the box.

Worth knowing

Every DB-touching suite here is gated on BIRDHOUSE_TEST_DATABASE_URL, which CI does not set — so the tests in this PR, and all the existing ones, are invisible to the merge gate and rest on local runs. Fixing that means giving the CI test job a Postgres service; I've left it out of this PR since it touches shared CI, but it's the most valuable follow-up here.

🤖 Generated with Claude Code

---

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