Fix four defects, namespace the environment, add CI and publishing, and document the architecture

[leggetter]

Fixes #4.

Started as a review of the repo, became the work the review implied. Nineteen commits, each self-contained: three ingest defects, a fourth found by running against a real Hookdeck project, an environment rename, packaging and CI, and the docs to match.

Nothing here changes the design. It fixes things that were wrong, and writes down things that were true but unstated.

---

Functional changes, before and after

1. A malformed signature answered 500 instead of 401

Before	A non-ASCII byte in x-hookdeck-signature raised out of the verification path and became a 500. That skipped assert_declared_status — so the one status emitted without its retryability declared was the one an unauthenticated caller could trigger — and 500 sits inside the provisioned retry rule's 500-599 range, so Hookdeck retried the forged request ~10 times with backoff.
After	401, like any other forged signature. Dropped on the first refusal.

Reproduced over a raw socket before fixing; the test fails without the fix.

2. A proxy's X-Request-ID could become the delivery identity

Before	With no x-hookdeck-eventid, the adapter fell back to X-Request-ID. Anything in front of the gateway can set that; it is not subject to header_prefix; and it is not unique per delivery — one Hookdeck request fans out to one event per matching connection, so two routes sharing a source would collide and the second event would be dropped as a duplicate. It also silenced the warning it stood in for, while POST /events/{proxy-id}/retry 404s — so neither dedup nor retry actually worked.
After	No fallback. A delivery genuinely missing the header is processed with the existing loud warning that dedup and retry are unavailable, naming header_prefix as the likely cause.

3. The sync-ack marker only cleared on success

Before	_acked_before_completion survived an exhausted retry budget and an abandoned hand-back. Beyond the slow leak: a later sync run of the same event id would find its own id already in the set and be treated as acked-early when it was not, asking Hookdeck to redeliver an event the 5xx response was already asking it to redeliver.
After	Cleared on every terminal path — success, exhausted, and abandoned hand-back alike.

4. cli mode could forward from the wrong project, silently

Found by the first live run, and the reason live runs are worth doing.

Before	"Which project" was two independent settings. The API key decided what setup, status and the retry hand-back acted on; the Hookdeck CLI's own config decided what hookdeck listen forwarded from. Nothing reconciled them. When they differed: setup reported success, the adapter logged mode=cli listening on…, the gateway looked healthy — and the tunnel restart-looped on no connection found matching filter while every event became a CLI_DISCONNECTED ignored event (events: 0, ignored: 1). It also auto-created a stray source in the unintended project.
After	The gateway authenticates a CLI session it owns, from the API key it already has, at ~/.hermes/hookdeck/cli-config.toml, and passes --hookdeck-config to every CLI call. Two projects cannot drift apart when only one of them is configurable. doctor compares them regardless, because the no-API-key fallback still exists.

Deliberately not hookdeck ci against the shared config: that switches the CLI's active project for every other use on the machine, and does so even with --local, despite its help text (hookdeck-cli#332, filed with a reproduction and cause). cli_login is removed — its job is now done properly. Set cli_config_path: "" to opt back into your own ambient session.

CLI sessions also identify as hermes-<hostname> rather than inheriting the bare hostname, so a gateway's tunnels are distinguishable from an operator's own in the Hookdeck dashboard.

5. Environment variables are namespaced to the Event Gateway

Before	HOOKDECK_API_KEY, HOOKDECK_WEBHOOK_SECRET, HOOKDECK_MODE, … — a bare prefix claiming the whole namespace for whichever Hookdeck integration got there first.
After	HOOKDECK_EG_*. Breaking, with no fallback, because nothing is released.

HOOKDECK_API_KEY is the deliberate exception: it is the Hookdeck CLI's own variable and the adapter hands it to the subprocess it spawns, so HOOKDECK_EG_API_KEY wins when set and HOOKDECK_API_KEY stays a first-class alternative rather than a deprecated one.

6. A project can now be pinned — ahead of organisation-level keys

Before	Nothing said which project an API key should act on, because a key implies exactly one.
After	HOOKDECK_EG_PROJECT_ID (or project_id in config) sends X-Team-Id, the same header the Hookdeck CLI uses.

Optional today, required once an org-level key reaches several projects. Also a safety improvement now: the dashboard authorises pause/resume by matching connection names against configured routes, so an unscoped org key would let a same-named connection in an unrelated project satisfy that check.

---

Non-functional

Ruff, lint only — ruff format would rewrite nineteen files and bury the history for no correctness gain. Most of the diff is --fix. The one judgement call is selecting BLE001 rather than ignoring it: this adapter degrades instead of aborting in seven places, two already said so with a noqa, and now all seven carry a one-line justification at the point they are written.

CI — ruff, pytest on 3.10–3.13, and a packaging job that builds the wheel, opens it to confirm plugin.yaml, the dashboard bundle and the skill are inside, then installs it to check the hermes_agent.plugins entry point resolves. A wheel missing those installs perfectly and registers nothing.

Releases — tag-driven, PyPI Trusted Publishing, no stored token. The version lives only in hookdeck.__version__; the build refuses a tag that disagrees. Pre-release tags are marked as such.

scripts/check_upstream_contract.py — the suite runs entirely against tests/hermes_stub.py, which cannot notice the real WebhookAdapter renaming something underneath it. This parses upstream weekly and asserts every borrowed name still exists. A smoke alarm, not a type check.

Packaging metadata — the PyPI page would have been bare. Now an author, a [project.urls] sidebar, classifiers matching the tested Python versions, and PEP 639 License-Expression: MIT instead of the whole licence text inlined into a metadata field. Adds the [build-system] table the project never had.

Docs — an opening that says what Hermes Agent and Hookdeck Event Gateway are; that this is the Event Gateway and not Outpost, and that "platform" is Hermes' word rather than Hookdeck's; an architecture section with a topology diagram and a sequence diagram for the ack-and-hand-back; separation of the three different things called "CLI" here; and a section on what Hookdeck can do that this plugin does not ask it to.

---

Verification

Beyond 192 unit tests and green CI on a real runner:

Against a real Hermes install — 27/27. Plugin discovered through the hermes_agent.plugins entry point (hermes plugins list shows hookdeck | 0.1.0rc1 | entrypoint), every keyword register_platform is given is a real PlatformEntry field, Platform("hookdeck") mints its enum member, the adapter really subclasses core's WebhookAdapter, and a signed delivery comes out as a prompt rendered by Hermes' own templating.

Against a real Hookdeck project — 20/20, over a live hookdeck listen tunnel with events injected through the Publish API. The two claims no stub can prove:

Agent run failed for event evt_MhT0ps… (run 1 of 4) — asked Hookdeck to redeliver
dispatch route=livetest event_id=evt_MhT0ps… attempt=2
  → Hookdeck: status=SUCCESSFUL attempts=2

POST /events/evt_STfcra…/retry "HTTP/1.1 200 OK"
Found 1 run(s) interrupted by a previous shutdown; asked Hookdeck to redeliver 1 of them
dispatch route=livetest event_id=evt_STfcra… attempt=2 → succeeded

A failed run really is handed back and returns with a higher attempt number; a gateway killed mid-run really does recover its orphan at the next start. Both were previously stub-only, and they are why the plugin exists.

0.1.0rc1 published to PyPI as a dry run of the release path — trusted publishing, reviewer gate, v*-tags-only environment — then installed from PyPI into a clean venv to confirm the entry point and all four non-Python files survive packaging.

The README's "Verified end to end" section previously described a run made before this branch existed. It now describes these.

---

Known gaps

• tools.py is at 29% coverage with no test file — seven tools an LLM can invoke unsupervised against a live project. Tracked in Increase test coverage, starting with the agent-callable tools #2.
• pull_request events produce no CI runs in this repo. Push-triggered CI works. Most likely because main has no .github directory yet, which merging this fixes — open a trivial PR afterwards to confirm.
• Boot recovery and the retry hand-back are now live-verified; admission-control deferral (503) is not — it remains unit-tested only.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QiavrHa47c8mRR2kekHgVo