Skip to content

feat(team-relay): Linear issue feed on the existing event rails - #69

Merged
ThinkOffApp merged 3 commits into
mainfrom
feat/linear-issue-feed
Aug 27, 2026
Merged

ThinkOffApp merged 3 commits into
mainfrom
feat/linear-issue-feed

Conversation

@ThinkOffApp

Copy link
Copy Markdown
Owner

Puts Linear issues on the rails GitHub PRs already ride, so they reach CodeWatch without any consumer needing a special case.

What it does

startLinearPoller(config, onEvent) emits the same event shape webhook-server.mjs produces: {trace_id, source, kind, timestamp, actor, refs, payload}. Kinds are linear.issue.created and linear.issue.updated.

Why polling, not a webhook

A webhook needs a stable public URL. This fleet reaches the outside through a tunnel whose URL rotates on every restart, so the hook would die silently at each rotation and nobody would notice until issues quietly stopped arriving — we already live with that failure mode elsewhere. Polling owns its own liveness: no inbound URL, nothing to re-point, and a failed poll is in the log immediately. Issue tracking does not need sub-minute latency, so the trade costs nothing that matters.

Safety

  • Read-only by construction. It holds a Linear key and never calls a mutation, so the worst a bug here can do is emit a wrong event.
  • Token from a file, never config or argv (~/.config/linear.token by default). The precommand gate has echoed a command into the room and leaked a key exactly that way. A path is safe to commit; a key is not.
  • Missing token disables the feed rather than failing the relay — most installs have no Linear.
  • Cursor starts at now, not epoch, so a cold start does not replay the whole backlog into the room.
  • Cursor only advances past emitted issues, so a throwing consumer causes a retry rather than a silent loss.

Verification

  • 7 unit tests, all passing (node --test test/linear-poller.test.mjs).
  • Smoke-tested against the live Linear API: 15 issues in the last hour, correctly split into created vs updated (THI-17 had been edited and came through as updated; THI-16/18/19 as created).
  • Neighbouring webhook.test.mjs suite still passes (4/4).

Not included

Chaining a Linear state change to a PR merge. That is a write action against GitHub and wants an explicit decision plus gating (linked PR, mergeable, CI green, explicit "Merge approved" state) — deliberately out of scope here.

🤖 Generated with Claude Code

Emits the same event shape webhook-server.mjs produces, so Linear issues
reach CodeWatch the way GitHub PRs already do and no consumer needs a
special case.

Polls rather than taking a webhook, deliberately: a webhook needs a stable
public URL, and this fleet's tunnel URL rotates on every restart, so the
hook would die silently at each rotation and nobody would notice until
issues stopped arriving. Polling owns its liveness and a failed poll shows
up in the log at once. Issue tracking does not need sub-minute latency.

Read-only by construction: it holds a key and never calls a mutation.

The token is read from a file (~/.config/linear.token by default), never
from config or argv, because the precommand gate has echoed a command into
the room and leaked a key exactly that way. A path is safe to commit; a key
is not. Missing token disables the feed instead of failing the relay, since
most installs have no Linear at all.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

@ThinkOffApp ThinkOffApp left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adversarial review findings:

  1. Blocking: the poller is not wired into the live relay or CLI. This PR adds src/team-relay/linear-poller.mjs and tests only; no import or startLinearPoller(...) call appears in src/team-relay/webhook-server.mjs, src/team-relay/index.mjs, or the CLI. A merged PR would pass its unit tests but emit no Linear events in production.

  2. The created-versus-updated heuristic is not reliable. createdAt === updatedAt is an implementation detail, and Linear can assign distinct timestamps during creation. Conversely, an update can preserve or normalize timestamps in ways that make equality misleading. Query the issue event/activity or use a persisted seen-id cursor if the distinction matters.

  3. actor.login is populated from assignee, then creator. Neither is the actor who changed the issue. The emitted event can attribute a Petrus assignment or creator to the person who performed a later edit. The query needs the actual activity actor, or the event contract should call this field something else.

The cursor retry behavior looks sound for consumer exceptions, and missing-token disablement is reasonable. I would fix the production wiring before merge and add tests for the timestamp and actor semantics.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c38c5550f7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

return { cursor, count: nodes.length };
}

export function startLinearPoller(config = {}, onEvent) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Wire the poller into a production entry point

The new poller is unreachable in every production path: a repo-wide reference search finds startLinearPoller only in this module and its test, while ide-agent-kit serve starts only startWebhookServer and src/team-relay/index.mjs does not export the poller. Consequently, placing a Linear token at the documented default path never starts polling, so this feature emits no events until it is integrated with a long-running command and the event queue.

Useful? React with 👍 / 👎.

Comment on lines +83 to +85
return {
trace_id: randomUUID(),
source: 'linear',

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve the issue ID in normalized events

Add event_id: issue.id to this object. schemas/event.normalized.json requires event_id as the inbound event's idempotency key, and every existing normalized adapter supplies it; omitting it makes Linear events violate that contract and leaves downstream processing unable to identify or deduplicate retries of the same issue update.

Useful? React with 👍 / 👎.

Comment on lines +60 to +64
issues(
filter: { updatedAt: { gt: $since } }
orderBy: updatedAt
first: $first
) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Page before advancing the timestamp cursor

When more than first matching issues exist, this query discards the connection's pagination information and pollOnce advances directly to the greatest returned updatedAt. For example, if 51 issues from a bulk operation share timestamp T, the first 50 are emitted, the cursor becomes T, and the next poll's updatedAt > T filter permanently excludes the remaining issue; consume all pages with an after cursor before advancing the time cursor.

Useful? React with 👍 / 👎.

@ThinkOffApp ThinkOffApp left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adversarial review: request changes before merge.

  1. src/team-relay/linear-poller.mjs:36 sends Authorization: Bearer ${token}, but this code and the PR describe linear.token as a personal API key. Linear's API docs require personal keys as Authorization: <API_KEY>; Bearer is for OAuth access tokens. As written, the documented/default installation will get 401s on every poll. Either send the personal key raw or make the credential type explicit and test both paths. The claimed live smoke test should be reproduced with the exact token-file path and header.

  2. src/team-relay/linear-poller.mjs:123-125 uses only a timestamp cursor with a strict updatedAt > since filter. If more than 50 issues share the page-boundary timestamp, or two issues have the same timestamp as the last emitted issue, the next poll skips the remainder forever. Use a stable (updatedAt, id) cursor or ensure pagination includes timestamp ties, and add a regression test.

The created-vs-updated equality heuristic is acceptable only if the API contract guarantees identical creation timestamps; please add a fixture/test for a newly-created issue whose timestamps differ in precision or document that invariant. CI is green, but these runtime cases are not covered.

…erve

Both found by @codexmb reviewing #69, and both were real.

1. actor.login was taken from assignee then creator, neither of which is who
   made the change. An issue assigned to Petrus and edited by an agent was
   attributed to Petrus, and 'who did what' is the entire reason this feed
   exists. Linear's issue history would carry the true actor but comes back
   empty for issues created through an API token, so it cannot be relied on.
   A created issue now credits its creator, which is genuinely the actor. An
   update reports 'unknown' rather than a plausible lie, and assignee and
   creator travel in the payload labelled as what they actually are.

2. startLinearPoller was exported and called by nothing. Merging as it stood
   would have shipped a feed that emitted no events. It is now started from
    alongside the webhook server, sharing the same onEvent, and a
   test asserts the wiring so this cannot silently regress.

Also covered: the cursor stays put when a consumer throws, so the issue is
retried rather than lost. 11 tests, all passing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ThinkOffApp

Copy link
Copy Markdown
Owner Author

Follow-up after 1e93472: the personal-key header and live wiring findings are fixed. The timestamp cursor issue remains: pollOnce still advances only a timestamp and queries with strict updatedAt > since, so issues tied at the page boundary can be skipped. Please add a stable (updatedAt, id) cursor or tie-safe pagination before merge.

The current 18.x check is still running; 20.x and 22.x pass.

Found by @codexmb on #69. The cursor is a timestamp and the filter is
strictly updatedAt > cursor, so stopping at a page boundary excluded any
issue sharing that last timestamp from the NEXT poll as well. Those issues
were lost permanently, not merely delayed: one bulk edit touching more than
a page of issues in the same second would silently drop the remainder.

pollOnce now follows pageInfo.hasNextPage to exhaustion, so the cursor only
lands past a timestamp whose issues have all been emitted. maxPages is a
runaway guard rather than a limit; if it trips the cursor holds at the last
fully-emitted position and the next tick resumes instead of skipping.

Adds regression tests for the tied-boundary case, the maxPages guard, and
the created-vs-updated timestamp invariant.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@ThinkOffApp
ThinkOffApp merged commit 2568b23 into main Aug 27, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant