docs(product): Linear Agent Session responder design (RIG-2717)

[rigel-mintaka]

This PR is part of a stack containing 2 PRs:

1. main
2. docs(concepts): capture the comms model (threads vs session log) (RIG-2717) #624
3. "docs(product): Linear Agent Session responder design (RIG-2717)" (this PR)

Production design record for making the installed Compass Linear app (RIG-2682) a live Linear Agent App: receive Agent Session webhooks, route a delegated issue to the right stable Compass Manager, carry the conversation as a topic in that Manager's home channel, and link the Linear session back out to Compass.

Stacked on #624 (the comms-model concept doc), which this record's premise cites.

All ten open questions were ruled by Matt on 2026-08-25 (RIG-2729); this record folds every ruling in and freezes with no live open questions.

The premise this record is built on

Matt's steer, captured in #624 and load-bearing here: Compass's comms model is deliberate, and Linear's Agent Session model is what it rejects. Compass has stable agents (Managers + peers) each with a home channel; communication rides Zulip-style threads (channel → named topics) and the agent's work stays out of the threads in a side-panel session log. Linear's Agent Session is the opposite — one ephemeral flat activity log per issue, no stable agent, no threads. So the Linear session is a doorway, not a home.

The decision — Option B (dumb link), Matt ruled RIG-2729

A hard constraint forces the mapping-depth choice: Linear's Agent Activity vocabulary is a fixed, server-validated set of five types (thought/action/elicitation/response/error) with no extension point, so Compass's typed comms blocks (a structured ask with discrete options) cannot round-trip through a Linear session.

• Option A — full relay (bidirectional). Mirror the Compass conversation into the Linear session. Richest, but shows a degraded conversation. Off-table until Linear makes the activity format configurable.
• Option B — dumb link (chosen). On created, emit one thought + an externalUrls "Open in Compass" deep link to the resolved Manager's home channel; all real interaction happens in Compass. Deletes the entire return relay.
• Option C — hybrid (ratified follow-up). Dumb link + a coarse one-way status back, no message-level mirroring.

What the bridge does

1. Receive — a plain POST /webhooks http.Handler on the network TLS door, fail-closed HMAC-SHA256 signature check (bad/missing → 400; stale-but-valid timestamp → 200-with-drop, never a retry-burning 400), ack 200 before any async work.
2. Route (Matt ruled routing is in scope, OQ-3) — resolve the delegated issue to a stable Manager keyed on Compass's recorded forge ownership index (forge_authored_artifacts, DL-055/DL-205), never a header parsed from forge text (DL-050/DL-094 forbid that reaching a routing decision). An unstamped issue routes to the supervisor via a dedicated routing channel, which decides the lane and stamps it.
3. Map (Matt ruled not 1-1, OQ-4) — the prompt lands in an issue-named comms topic in the Manager's home channel (sessions on one issue coalesce), delivered as @linear-authored messages on the durable deliver rail, deduped by PostAsAccount's client_request_id on the Linear-Delivery UUID. The deep link targets the home channel, not the topic.
4. Link back — the two created emits (the ack thought + the session external URL) are the whole return path. No relay, no settle observation, no session-lifecycle machine.

The public base URL (webhook host + deep-link base) is per-deployment (Matt ruled OQ-2): managed = compass.rigel.build, self-host = its own URL, dev/tailnet deploys need their own ingress.

Resolved decisions (all ten OQs, Matt 2026-08-25)

OQ-1 Option B (C follow-up, A off-table) · OQ-2 network door + per-deployment public URL · OQ-3 routing in scope, keyed on the recorded ownership index · OQ-4 not 1-1, link to the home channel · OQ-5 secret names as designed · OQ-6/8/9/10 dissolve under B (no relay → no streaming cadence, no Linear elicitation, no settle-edge observability, no session-lifecycle machine) · OQ-7 production, not a spike.

Ledger-impact

Adds DL-254 (webhook receiver on the network door + per-deployment URL), DL-255 (routing keyed on the recorded ownership index, never a parsed header), and DL-256 (Option-B dumb-link return path + not-1-1 topic mapping) to docs/designs/DECISIONS.md at freeze. Highest row on current main is DL-253; the driver re-verifies the next-free id at freeze.

Spec-impact: none.
Refs RIG-2717.
Co-authored-by: Matt Wilkinson matt@rigel.build

[linear-code]

RIG-2717

[github-actions]

Compass engineering docs preview: https://compass-server-rig-2717-resp.compass-eng-docs.pages.dev

Deployed from compass-server/rig-2717-responder-design at af39c93.

Changed pages:

• docs/designs/product/compass-linear-agent-responder/design.md