Start here

GitHub → agent: failure-recovery walkthrough

Run a signed GitHub event through verification, filtering, a downed agent, a replay, and a duplicate redelivery — with every step labeled live, mock, or planned.

This walkthrough is a reproducible acceptance demo, not a customer story. It shows one workflow end to end and states plainly which parts are shipped today, which are mocked for the demo, and which are still planned.

Who it is for

Developers evaluating whether a GitHub event can reliably reach an AI agent and still be recoverable when the agent is down.

Suitable when you want to see signature verification, a label filter, failed-delivery records, replay recovery and duplicate suppression on a local stack before wiring a real agent.

Not suitable when you need proof of end-to-end agent completion, SLA numbers, or a hosted recording of a production incident. Those do not exist yet; the run id in this demo lives only in the mock agent.

What is live, mocked, or planned

Part of the flow	State	What that means
GitHub `X-Hub-Signature-256` verification	Live	A signed request is accepted; a wrong signature gets `401` and is not stored.
Label filter (`agent` label plus sender association)	Live	The same filter published in the GitHub → Grok Bot guide, evaluated by the server.
Delivery attempt record (`503` from the agent)	Live	The attempt, status code and retry state are visible in the delivery log.
Replay after recovery	Live	`hooks replay` settles the same delivery row; no second delivery is created.
Duplicate `X-GitHub-Delivery` suppression	Live	The repeat resolves to the original event and never reaches the agent twice.
The agent itself	Mock	A local HTTP server returns a run id, fails once on purpose, then accepts the replay. No LLM is called and nothing is charged.
Agent write-back into Hooks	Planned	Sessions, progress and completion callbacks depend on issue #95 and are not available yet. The demo stops at “agent accepted”.

Prerequisites

A local dev stack: pnpm dev (API :3000, web :3101).
A built CLI: pnpm --filter @hooks/cli build.
The published synthetic sample at public-repo/samples/github/issues.opened.json. It uses acme/example-service, issue 42, label agent, sender association MEMBER — no real repository, account, or secret.

Run it

pnpm dev
pnpm --filter @hooks/cli build
pnpm e2e:agent-recovery

The script creates a throwaway account, an endpoint that verifies GitHub signatures, a mock agent, and a CLI relay. It prints one block per step, tagged [live], [mock] or [planned].

Expected shape of a passing run:

[live] Create a throwaway developer account and API key
  ✔ account, workspace, API key and CLI login ready — prj_…
[live] Create a GitHub endpoint that verifies X-Hub-Signature-256
  ✔ endpoint ready — ep_…
[live] A signed GitHub event is accepted; an unsigned one is rejected
  ✔ signature verified — evt_…
[live] The published label filter keeps an unlabeled issue out
  ✔ filter decision verified — allowed=true / false
[mock] The agent is down: its 503 is recorded against the delivery
  ✔ 503 recorded — dlv_cli_…
[mock] The agent recovers; replay settles the same delivery
  ✔ replay settled the delivery — dlv_cli_…
[live] A repeated GitHub delivery id is suppressed before the agent
  ✔ duplicate suppressed — agent calls stayed at 2
[mock] Agent-side run state is mock data, not a Hooks record
[planned] Real agent write-back into Hooks

Trace: event evt_… → delivery dlv_cli_… → mock run_mock_…
7 checks passed (3.3s; states: live, live, live, live, mock, mock, live, mock, planned)

Ids and timings vary per run. Measured on the local stack on November 8, 2026: 7 checks, 3.3–3.5 s across repeated runs.

What each step proves

Signature verification

The request carries GitHub’s X-Hub-Signature-256 header, computed over the raw body with the endpoint secret. A request with sha256=00 is rejected with 401 and never becomes an event, so a forged delivery cannot reach the agent.

Label filtering

Filtering happens per destination. The demo sends the guide’s filter to POST /v1/destinations/filter-preview against two stored events: the labeled issue is allowed: true; the same issue with the agent label removed is allowed: false. This is the same evaluator a real destination uses before rendering a request.

An endpoint with no destination still stores the event, so “filtered out” means “no agent call”, not “not received”.

Accepted is not completed

A 2xx from the agent means the task was accepted. Hooks records the attempt and the status code. The mock agent mints a run id, but Hooks does not yet ingest agent progress or completion; the trace line shows where the Hooks-side record stops.

Failure and recovery

The mock agent returns 503 first. The delivery is recorded as failed with that status code. After the mock is healthy, hooks replay <eventId> re-delivers the stored event: the same delivery row settles as succeeded with the new status code. No event is lost and no second delivery row is created.

Automatic retries also exist; replay is used here so the demo is deterministic. See Retries & idempotency.

Duplicate suppression

Re-sending the same X-GitHub-Delivery id returns the original event id. The script counts agent calls for that delivery id before and after the repeat and requires the count not to move, so a relabeled or retried delivery cannot cause a second agent run.

Recording storyboard

For a screen recording or screenshot set, use this order and caption each frame with its state tag:

Run the command; show the [live] signature and filter steps.
Show the mock agent’s 503 and the failed delivery row in the log.
Show the replay output and the same delivery settling.
Show the duplicate repeat and the unchanged agent call count.
End on the [planned] write-back note and the trace line.

Do not cut the [mock] and [planned] tags out of the frames. Do not use a real customer repository, a real task body, or real agent output.

Publication checklist

Every displayed step keeps its live, mock, or planned tag.
Payloads are the published synthetic sample; no real issue bodies, secrets, internal URLs, or account ids appear.
The primary CTA is the free interactive /try experience; the demo does not imply a paid LLM cost is included.
The recording does not claim a measured SLA, conversion rate, or customer outcome.
Links to the GitHub → Grok Bot guide and this page resolve after deploy.
External posts and channel drafts are reviewed by the owner; nothing is auto-published.