docs(integrations): linear live e2e + closeout (LT2)

[madarco]

Summary

Final task in the Linear integration session — verified the LT1 surface
against the live waldosai Linear workspace end-to-end from inside an
AgentBox box, and closed out the Linear backlog with the captured evidence.
No source changes: the LT1 connector + shim + GraphQL mutation gate
worked as-shipped.

E2E evidence (live waldosai workspace)

All commands ran from inside this box (in-box agent → host relay → host linear v2.0.0 → Linear API).

Reads — no prompt

• linear whoami → Workspace: waldosai … User: Marco D'Alia … Role: admin (exit 0).
• linear issue mine --team WAL --sort priority / linear issue list --team WAL --sort priority → exit 0 (empty result on unstarted filter, valid filtered read).
• linear team list → WAL Waldosai (team UUID 09ca67e1-…).
• linear api '{ viewer { id name email } }' → {"data":{"viewer":{"id":"85d5fa14-…","name":"Marco D'Alia","email":"accounts@waldos.ai"}}} — refuseGraphqlNonQuery classifies the { … } shorthand as a query and passes it.

GraphQL mutation gate — refused locally (exit 65)

• linear api 'mutation { issueDelete(id:"x") { success } }' exits 65 with:
  linear api: only GraphQL queries are proxied (use issue.create / issue.update / issue.comment for writes); detected operation 'mutation'
• Verified through both the shim path and the direct agentbox-ctl integration linear api path — the gate lives in the connector, not the shim.

auth token — refused at the shim (exit 2)

• linear auth token exits 2 with 'auth token' leaks the raw API key — refused. Use 'linear whoami' for identity.
• Three defenses in series: shim allowlist → connector op allowlist → relay dispatch. The shim is the first.

Gated writes — three approve→succeed→ground-truth cycles

1. linear issue create --team WAL --title "agentbox LT2 e2e 20260607T000618Z" -d "…" → host approval prompt → orchestrator approves → created WAL-5 (https://linear.app/waldosai/issue/WAL-5/agentbox-lt2-e2e-20260607t000618z). Ground-truth linear issue view WAL-5 confirms title + description + Backlog state.
2. linear issue comment add WAL-5 -b "agentbox LT2 e2e comment via host relay (gated write)" → approved → comment added (URL with #comment-3e8fe4e2 fragment). Ground-truth linear api '{ issue(id:"WAL-5") { … comments { nodes { body } } } }' confirms the body matches verbatim.
3. linear issue update WAL-5 -s "Canceled" → approved → state moved. Post-update linear issue view WAL-5 shows **State:** Canceled and the comment thread.

No-token assertion (the security property)

• printenv | grep -E '^LINEAR' returns nothing ((no LINEAR_* keys present)).
• The only token-shaped env var in the box is AGENTBOX_RELAY_TOKEN.
• The carried ~/.config/linear/credentials.toml sits on disk for the nested-box scenario (where THIS box would host a nested-box's relay), but no agent process reads it during the primary e2e — the host's own linear does, host-side, via its own ~/.config/linear/.

Nested-box e2e — deferred, not blocking

Same architectural reason as Notion's T4 deferral: the in-box agentbox-ctl
daemon forwards /rpc to the original host relay
(host.docker.internal:8787), not to a relay running in this box — so a
nested box's linear issue create would terminate at the original host's
relay spawn regardless of whether this box has a real linear installed.
Additionally, installing the real linear here would land it at
/usr/bin/linear (npm prefix /usr), but the shim at /usr/local/bin/linear
precedes it on $PATH and keeps winning resolution — the test setup would
break the primary e2e. Documented in docs/integrations.md under
"Linear → Nested-box e2e — deferred, not blocking", mirroring the Notion
sub-section.

Closeout

• docs/linear_backlog.md — LT2 flipped to done (2026-06-07) with the
  full evidence log appended.
• docs/integrations_backlog.md — Linear path marked COMPLETE (LT1–LT2
  done) with the shipped-surface summary and the e2e evidence.
• docs/integrations.md — new "Verification / live e2e results" and
  "Nested-box e2e — deferred, not blocking" sub-sections under Linear; the
  shared Open-follow-ups "Nested-box e2e" bullet now covers both Notion and
  Linear.

Verification

• pnpm typecheck ✅ (25/25 cached + fresh)
• pnpm test ✅ (494 + 245 + 174 + … all passing)
• pnpm build ✅ (FULL TURBO)
• /simplify ✅ (no findings — docs-only diff)
• /review high ✅ (1 finding fixed: corrected the npm-prefix-collision claim to the accurate PATH-shadowing mechanic; all other claims verified against ground truth)

Test plan

• Reads (whoami, issue mine/list, team list, api { viewer … }) round-trip with no prompt
• GraphQL mutation refused locally via refuseGraphqlNonQuery (shim path + direct ctl path)
• linear auth token refused at the shim with the raw-key-leak message
• Three gated writes approved by the orchestrator and ground-truth-confirmed
• printenv | grep -E '^LINEAR' returns nothing in the box
• pnpm typecheck && pnpm test && pnpm build all green

---

Note

Low Risk
Documentation-only updates with no runtime, auth, or relay behavior changes.

Overview
Documentation-only closeout for Linear integration LT2 — records live end-to-end verification against the waldosai workspace and marks the Linear path complete in the integration trackers. No application or connector code changes.

docs/integrations.md gains Linear Verification / live e2e results (reads, GraphQL mutation refusal, shim auth token refusal, gated create/comment/update on WAL-5, no LINEAR_* in the box) and Nested-box e2e — deferred, not blocking, aligned with Notion. The shared Open follow-ups nested-box bullet now covers both Notion and Linear.

docs/integrations_backlog.md promotes Linear from not started to COMPLETE (LT1–LT2 done) with a shipped-surface and e2e summary; Trello/ClickUp remain not started.

docs/linear_backlog.md sets LT2 to done (2026-06-07) and appends the full LT2 evidence log (including nested-box deferral rationale).

^{Reviewed by Cursor Bugbot for commit 23cb623. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview, Comment	Jun 7, 2026 12:15am