Porting one Herdr integration

Sidecar installs its own hook, plugin and extension assets into other agents' configuration so those agents report their lifecycle state and their session identity back to Sidecar. The knowledge in those assets comes from Herdr, which ships seventeen of them. A port takes one provider's knowledge, keeps it verbatim, replaces Herdr's transport with Sidecar's, and lands it behind the same guards every existing adapter passes.

This is a procedure. Work through it in order for one provider at a time. Every step names the file to open and the test that gates it.

0. How Sidecar mirrors Herdr

Four things hold the mirror in place. Read them before you write anything.

The vendored tree. internal/agentintegration/upstream/<dir>/ holds byte-for-byte copies of Herdr's src/integration/assets. Nothing installs them and no runtime path reads them; they exist so re-porting a provider is a review of a diff rather than a fresh reading. internal/agentintegration/upstream/herdr-agent-state.test.ts at the root of that tree is upstream's own test, and its payloads are where your fixtures come from.

The lock. internal/agentintegration/upstream.lock.json pins every vendored file by SHA-256 and records each provider's HERDR_INTEGRATION_VERSION. It is keyed by Herdr's agent id, which is not always the directory name: agy is the id and antigravity_cli is the directory. TestVendoredIntegrationAssetsMatchLock fails if a vendored byte changes without a matching lock entry, so never hand-edit anything under upstream/.

The provenance record. internal/agentintegration/portedfrom.go holds one PortedFrom row per shipped asset: the Sidecar provider id, the Herdr agent id (UpstreamID, which must match the lock's key), the directory, the upstream version the port was written against, the commit, and prose evidence. It is Go data rather than a header comment because several Sidecar assets are Go values with no file to put a header in. TestEveryAdapterRecordsWhatItWasPortedFrom fails if an adapter ships without a row.

The sync tool and the weekly review. internal/tools/herdrsync re-vendors the tree, rewrites the lock, and renders internal/agentactivity/manifests/report.md. .github/workflows/herdr-sync.yml runs it every Monday, pushes bot/herdr-sync, and puts that report into the pull request body.

go run ./internal/tools/herdrsync performs a real sync. It fetches from Herdr and overwrites the vendored manifest and integration trees in your working directory. Do not run it to "see what it does". Read internal/agentactivity/manifests/report.md, and drive the renderer from tests when you need to see output. Name the package explicitly if you ever must run it, and never glob ./internal/tools/..., which expands to the sync tool and syncs.