Add Linear Agent Sessions and team-aware routing

[michaelmwu]

Summary

• follow up the core Linear trigger support merged in Add Linear project triggers #84 with native Linear Agent Sessions
• route projectless Linear issues by structured team ID and support reply-only comment continuations
• report daemon termination as an idempotent native Agent Session error
• use Linear's live DateTimeOrDuration history contract for bounded issue and session context

Safety and behavior

• reactive comments, assignments, and Agent Sessions still require a non-empty from_users allowlist
• autonomous linear.issue_entered_scope triggers require an explicit filters.project or filters.team
• team and project IDs remain explicit configuration route keys; repository authority stays explicit per workflow step
• issue and Agent Session history is bounded, chronological, causally anchored before the triggering turn, and fails open as unavailable
• filters.replies_only: true selects nested comments while preserving the original comment as the workflow prompt
• native Agent Sessions require read, write, app:assignable, and app:mentionable

Verification

Current head (8aaf40f):

• npm run typecheck
• npm run lint
• focused format checks
• 112 focused compiler, configuration, Linear client/event/matcher/provider/webhook tests
• 3 production PostgreSQL trigger-acceptance integration tests, including projectless team routing
• npm run db:check
• npm run build

Community live-provider verification confirmed Agent Session creation, follow-up prompts, native activities, replies, and the corrected history scalar against a real Linear workspace. The new machine-termination and team/reply routing edges are contract- and integration-tested.

Documentation

Companion public-docs PR: getpaseo/paseo#3963

[ankhers]

Is there anything I can do to help get this merged? I would love to see linear support within the project.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dcd4fa0372

ℹ️ 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".

[michaelmwu]

Is there anything I can do to help get this merged? I would love to see linear support within the project.

You can pull this in and do local testing and verification, that would help! I haven't been able to put cycles into doing that.

As for @boudra I guess we'll have to wait for him

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3aa145d173

ℹ️ 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".

[as-cto]

Independent verification report — this branch works end to end

We self-host Hub and needed Linear, so we built this branch and ran it against a real Linear
workspace. As far as we can tell nobody had executed this code yet, so here is what we found.

Build: ea62e0d955 (branch head at time of writing), docker build from the branch
Dockerfile. npm run build — including tsgo -p tsconfig.json — passes clean.

Setup: Hub from this branch + Postgres 17 behind a reverse proxy on a public hostname. A real
Linear OAuth application (actor=app, scopes read,comments:create) with the app-level webhook,
in a real workspace. One daemon enrolled. Migrations, including drizzle/0040, applied on first
boot without intervention.

Verified end to end

Step	Result
Apps page shows Linear, reads LINEAR_* env, reports Managed by environment	✅
OAuth authorize URL well-formed (client_id, redirect_uri, scope, actor=app)	✅
state is single-use — replaying a consumed link is refused with a clear message	✅
Workspace connected; row written with app_user_id, scopes, slug	✅
Signed webhook → HMAC verified → normalized (Comment → linear.comment)	✅
Connection resolution: drop reason moves linear_unbound → no_project_route	✅
Trigger matching: outcome: matched, triggerNames: ["linear-comment"], accepted 1 / rejected 0	✅
Agent starts on the daemon with ${{ paseo.context }} populated (actor, issue, url)	✅
linear.reply posts a real comment via executeLinearReply → createComment	✅
Comment is authored by the app, not by the installing user — actor=app holds	✅
Genuine Linear-emitted payloads ingested, signature-verified and normalized	✅
No feedback loop: the agent's own comment re-fires a webhook, correctly filter-rejected	✅

The last three deserve a note. After the agent replied, Linear emitted two real webhooks of its own
(linear.comment and linear.issue) 250 ms and 480 ms later. Both passed signature verification,
normalized correctly, and were dropped with trigger_filters_rejected — so real payload shapes are
handled, and an agent replying into Linear does not retrigger itself.

Adversarial webhook suite

Ten crafted deliveries against /api/integrations/linear/events:

Case	Expected	Got
valid signature, fresh timestamp	accept	200 ✅
invalid signature	reject	401 ✅
malformed signature (not hex)	reject	401 ✅
missing signature header	reject	401 ✅
timestamp 2 min in the past	reject	401 ✅
timestamp 2 min in the future	reject	401 ✅
missing webhookTimestamp	reject	401 ✅
unsupported event type	ignore cleanly	200 ✅
invalid JSON	clear error	400 ✅
body > 1 MiB	413	502 — our reverse proxy truncates first, so Hub's own cap was not exercised

The replay window is Math.abs(...), so future-dating a delivery does not keep it valid
indefinitely, and the timestamp lives inside the HMAC-protected body. That is the right design and
worth stating explicitly, since it is easy to get wrong.

One gap we would suggest closing

matchesIssueScope's filters.connection → connectionId guard has no test exercising it — every
call in match.test.ts passes two arguments, so the third parameter defaults and the branch is
never taken. That is the check which stops one Linear workspace triggering another workspace's
workflows. Everything else we touched behaved correctly, so this stood out.

Notes

• The env-managed path (LINEAR_CLIENT_ID / _SECRET / _WEBHOOK_SECRET) works exactly as
  documented, and the UI is explicit that credentials cannot be edited there.
• Drop reasons are named rather than silent (linear_unbound, no_project_route,
  trigger_filters_rejected), which made this investigation straightforward. We had spent hours
  the same week on a different integration that failed silently — the contrast is stark.
• If it helps, we are happy to re-run this against any commit, share the probe scripts, or test a
  fix for the isolation gap above.

Verified by @as-cto.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 588cc49080

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d29ede37a9

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 84af15a8d3

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2e79525cb4

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9462696882

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 628f968d97

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 67946d27ca

ℹ️ 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".

[michaelmwu]

Thanks for the thorough real-workspace verification — especially the OAuth, genuine webhook, reply, and loop-prevention coverage. The connection-isolation gap you identified is covered in d29ede3: the regression exercises matching and mismatched connectionId values across issue-scope, assignment, and comment triggers. I reran that test at the current head (73e8703), and all 12 Linear matching tests pass. We really appreciate the offer to retest future updates.

@as-cto my agents auto-resolved your feedback, thanks for testing this live (haven't had cycles for this)! Feel free to open PRs against this branch or leave feedback on this branch (will be auto-acted on).

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c076cb53a

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f765dd367c

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f91c1f513d

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5eefd08077

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e61023d586

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3bd42902ba

ℹ️ 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".

[erikedhagen]

Where are we at with this?

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: d1fe2f003e

ℹ️ 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".

[michaelmwu]

Current status: the branch is up to date with main, mergeable, and all current review threads are resolved at 10dc01b. The base Linear OAuth/webhook/comment flow has been verified against a real workspace; native Agent Sessions were added afterward and have focused contract coverage but still need a real Agent install exercise. The full implementation suite passed, the final runtime routing fix passed its 21-test focused suite plus lint/typecheck, and the companion docs are in getpaseo/paseo#3963. GitHub exposes no checks or commit statuses for this PR, so its UNSTABLE label currently has no actionable failing check behind it. It is ready for maintainer review; I have not merged it.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 10dc01bc87

ℹ️ 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".

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8aaf40ff0c

ℹ️ 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".

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-08-29T01:46:05.789685Z	d6439af	New commits

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9d187a37ac

ℹ️ 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".

[michaelmwu]

Superseded by #84, which merged the core Linear trigger work. Native Linear Agent Sessions will continue in a focused follow-up PR based on current main.

[michaelmwu]

@as-cto Thank you again for the real-workspace verification and concrete follow-up reviews. I checked the reopened follow-up in #88 at d6439af; it incorporates the substantive #59 feedback:

• regression coverage now rejects mismatched Linear connection IDs, including issue-scope, assignment, and comment matching;
• issue-comment history is fetched only during context materialization, is causally anchored before the triggering comment, bounded to the root-plus-50-message convention, and fails open when optional history is unavailable;
• both Linear history queries now declare the cursor as DateTimeOrDuration;
• teamId is normalized, filterable through filters.team, and used for routing projectless issues;
• comment parentId is preserved and replies_only can select replies.

Focused validation on this head passed: 60 tests across matching, context materialization, Linear client queries, event normalization, and configuration routing. Would you be willing to review or retest #88 when you have time? #59 remains closed; #88 is the ready-for-review follow-up.