@mndrk/agx 2.0.41 → 2.0.44

package/cloud-runtime/standalone/docs/superpowers/plans/2026-04-07-linear-integration.md

@@ -0,0 +1,1352 @@
+# Linear Integration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a Linear ticket browser to agx-cloud that lets users connect via OAuth, browse tickets (ID/title/status/assignee), execute them with agents, and steer the execution thread live — plus a setup flow for configuring Linear MCP on installed AI CLIs so agents can interact with Linear during execution.
+
+**Architecture:** Three-panel layout matching `PromptJobBoard`: ticket list (left, infinite scroll) | run history (middle) | steerable chat thread (right). Data layer uses `@linear/sdk` with OAuth for the app-side ticket list, and CLI-detected MCP configuration for agent-side access. New sidebar nav tab "Linear" alongside "Scheduled Tasks". Empty state shows OAuth connect + CLI MCP setup.
+
+**Tech Stack:** `@linear/sdk`, Next.js API routes, `useGroupChat`/`useProcessPolling` hooks (existing), `RunChatPanel` pattern (existing), `commandExists` from `lib/cli-runner.ts` (existing).
+
+---
+
+## File Map
+
+| Action | Path | Responsibility |
+|--------|------|----------------|
+| Create | `lib/linear-client.ts` | Linear SDK singleton, token management, issue queries |
+| Create | `app/api/linear/auth/route.ts` | Start OAuth flow (redirect to Linear) |
+| Create | `app/api/linear/callback/route.ts` | Handle OAuth callback, store token |
+| Create | `app/api/linear/issues/route.ts` | List/search issues (proxy to Linear SDK) |
+| Create | `app/api/linear/status/route.ts` | Check connection status + CLI detection |
+| Create | `hooks/useLinearIssues.ts` | Fetch issues with filters, infinite scroll |
+| Create | `hooks/useLinearConnection.ts` | Connection status, OAuth trigger |
+| Create | `components/LinearBoard.tsx` | Main three-panel component (ticket list + runs + thread) |
+| Create | `components/LinearSetup.tsx` | Empty state: OAuth connect + CLI MCP config |
+| Create | `app/projects/[slug]/linear/page.tsx` | Project-scoped Linear page |
+| Modify | `components/thread/WorkspaceSidebar.tsx` | Add "Linear" nav item |
+| Modify | `package.json` | Add `@linear/sdk` dependency |
+
+---
+
+## Task 1: Install Linear SDK and Create Client Module
+
+**Files:**
+- Modify: `package.json`
+- Create: `lib/linear-client.ts`
+
+- [ ] **Step 1: Install @linear/sdk**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud && npm install @linear/sdk
+```
+
+- [ ] **Step 2: Create `lib/linear-client.ts`**
+
+```typescript
+import { LinearClient } from "@linear/sdk";
+
+// Token stored in a JSON file alongside the SQLite DB
+const TOKEN_PATH = ".linear-token.json";
+
+interface LinearToken {
+  accessToken: string;
+  expiresAt?: number;
+}
+
+function getTokenPath(): string {
+  const fs = require("fs");
+  const path = require("path");
+  return path.join(process.cwd(), TOKEN_PATH);
+}
+
+export function getLinearToken(): LinearToken | null {
+  const fs = require("fs");
+  try {
+    const raw = fs.readFileSync(getTokenPath(), "utf8");
+    return JSON.parse(raw) as LinearToken;
+  } catch {
+    return null;
+  }
+}
+
+export function saveLinearToken(token: LinearToken): void {
+  const fs = require("fs");
+  fs.writeFileSync(getTokenPath(), JSON.stringify(token, null, 2));
+}
+
+export function deleteLinearToken(): void {
+  const fs = require("fs");
+  try {
+    fs.unlinkSync(getTokenPath());
+  } catch {
+    // already gone
+  }
+}
+
+export function getLinearClient(): LinearClient | null {
+  const token = getLinearToken();
+  if (!token) return null;
+  return new LinearClient({ accessToken: token.accessToken });
+}
+```
+
+- [ ] **Step 3: Add `.linear-token.json` to `.gitignore`**
+
+Append to `/Users/mendrika/Projects/Agents/agx-cloud/.gitignore`:
+
+```
+.linear-token.json
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add package.json package-lock.json lib/linear-client.ts .gitignore
+git commit -m "feat: add @linear/sdk and token management module"
+```
+
+---
+
+## Task 2: OAuth API Routes
+
+**Files:**
+- Create: `app/api/linear/auth/route.ts`
+- Create: `app/api/linear/callback/route.ts`
+- Create: `app/api/linear/status/route.ts`
+
+Linear OAuth uses authorization code flow. The app needs a `LINEAR_CLIENT_ID` and `LINEAR_CLIENT_SECRET` env var (from https://linear.app/settings/api/applications).
+
+- [ ] **Step 1: Create the auth start route**
+
+Create `app/api/linear/auth/route.ts`:
+
+```typescript
+import { NextResponse } from "next/server";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+const LINEAR_AUTH_URL = "https://linear.app/oauth/authorize";
+
+export async function GET() {
+  const clientId = process.env.LINEAR_CLIENT_ID;
+  if (!clientId) {
+    return NextResponse.json(
+      { error: "LINEAR_CLIENT_ID not configured" },
+      { status: 500 },
+    );
+  }
+
+  const redirectUri = `${process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000"}/api/linear/callback`;
+  const state = crypto.randomUUID();
+
+  const params = new URLSearchParams({
+    client_id: clientId,
+    redirect_uri: redirectUri,
+    response_type: "code",
+    scope: "read,write",
+    state,
+    prompt: "consent",
+  });
+
+  return NextResponse.redirect(`${LINEAR_AUTH_URL}?${params.toString()}`);
+}
+```
+
+- [ ] **Step 2: Create the callback route**
+
+Create `app/api/linear/callback/route.ts`:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { saveLinearToken } from "@/lib/linear-client";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const code = req.nextUrl.searchParams.get("code");
+  if (!code) {
+    return NextResponse.redirect("/?linear=error");
+  }
+
+  const clientId = process.env.LINEAR_CLIENT_ID;
+  const clientSecret = process.env.LINEAR_CLIENT_SECRET;
+  const redirectUri = `${process.env.NEXT_PUBLIC_APP_URL ?? "http://localhost:3000"}/api/linear/callback`;
+
+  const tokenRes = await fetch("https://api.linear.app/oauth/token", {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      client_id: clientId!,
+      client_secret: clientSecret!,
+      redirect_uri: redirectUri,
+    }),
+  });
+
+  if (!tokenRes.ok) {
+    return NextResponse.redirect("/?linear=error");
+  }
+
+  const data = await tokenRes.json();
+  saveLinearToken({
+    accessToken: data.access_token,
+    expiresAt: data.expires_in
+      ? Date.now() + data.expires_in * 1000
+      : undefined,
+  });
+
+  // Redirect back to the Linear tab
+  return NextResponse.redirect("/?linear=connected");
+}
+```
+
+- [ ] **Step 3: Create the status route (connection + CLI detection)**
+
+Create `app/api/linear/status/route.ts`:
+
+```typescript
+import { NextResponse } from "next/server";
+import { spawnSync } from "child_process";
+import { getLinearClient, deleteLinearToken } from "@/lib/linear-client";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+function commandExists(bin: string): boolean {
+  try {
+    if (process.platform === "win32") {
+      return spawnSync("where", [bin], { encoding: "utf8" }).status === 0;
+    }
+    return (
+      spawnSync("bash", ["-lc", `command -v ${bin} >/dev/null 2>&1`], {
+        encoding: "utf8",
+      }).status === 0
+    );
+  } catch {
+    return false;
+  }
+}
+
+export async function GET() {
+  const client = getLinearClient();
+  let connected = false;
+  let user: { name: string; email: string } | null = null;
+
+  if (client) {
+    try {
+      const viewer = await client.viewer;
+      connected = true;
+      user = { name: viewer.name, email: viewer.email };
+    } catch {
+      // Token expired or invalid
+      connected = false;
+    }
+  }
+
+  return NextResponse.json({
+    connected,
+    user,
+    clis: {
+      claude: commandExists("claude"),
+      codex: commandExists("codex"),
+      gemini: commandExists("gemini"),
+    },
+  });
+}
+
+export async function DELETE() {
+  deleteLinearToken();
+  return NextResponse.json({ disconnected: true });
+}
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add app/api/linear/
+git commit -m "feat: add Linear OAuth auth, callback, and status API routes"
+```
+
+---
+
+## Task 3: Issues API Route
+
+**Files:**
+- Create: `app/api/linear/issues/route.ts`
+
+- [ ] **Step 1: Create the issues list route**
+
+Create `app/api/linear/issues/route.ts`:
+
+```typescript
+import { NextRequest, NextResponse } from "next/server";
+import { getLinearClient } from "@/lib/linear-client";
+
+export const runtime = "nodejs";
+export const dynamic = "force-dynamic";
+
+export async function GET(req: NextRequest) {
+  const client = getLinearClient();
+  if (!client) {
+    return NextResponse.json({ error: "Not connected" }, { status: 401 });
+  }
+
+  const params = req.nextUrl.searchParams;
+  const teamId = params.get("teamId") ?? undefined;
+  const status = params.get("status") ?? undefined;
+  const search = params.get("search") ?? undefined;
+  const cursor = params.get("cursor") ?? undefined;
+  const limit = Number(params.get("limit") ?? "50");
+
+  try {
+    const filter: Record<string, unknown> = {};
+    if (teamId) filter.team = { id: { eq: teamId } };
+    if (status) filter.state = { name: { eqIgnoreCase: status } };
+    if (search) filter.searchableContent = { contains: search };
+
+    const result = await client.issues({
+      first: limit,
+      after: cursor,
+      filter,
+      orderBy: "updatedAt" as any,
+    });
+
+    const issues = await Promise.all(
+      result.nodes.map(async (issue) => {
+        const state = await issue.state;
+        const assignee = await issue.assignee;
+        return {
+          id: issue.id,
+          identifier: issue.identifier,
+          title: issue.title,
+          status: state?.name ?? "Unknown",
+          assignee: assignee?.name ?? null,
+          updatedAt: issue.updatedAt,
+        };
+      }),
+    );
+
+    return NextResponse.json({
+      issues,
+      pageInfo: {
+        hasNextPage: result.pageInfo.hasNextPage,
+        endCursor: result.pageInfo.endCursor,
+      },
+    });
+  } catch (err: any) {
+    return NextResponse.json(
+      { error: err.message ?? "Failed to fetch issues" },
+      { status: 500 },
+    );
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add app/api/linear/issues/route.ts
+git commit -m "feat: add Linear issues list API with team/status/search filters"
+```
+
+---
+
+## Task 4: React Hooks
+
+**Files:**
+- Create: `hooks/useLinearConnection.ts`
+- Create: `hooks/useLinearIssues.ts`
+
+- [ ] **Step 1: Create `hooks/useLinearConnection.ts`**
+
+```typescript
+import { useState, useEffect, useCallback } from "react";
+
+interface CliStatus {
+  claude: boolean;
+  codex: boolean;
+  gemini: boolean;
+}
+
+interface LinearConnectionState {
+  connected: boolean;
+  loading: boolean;
+  user: { name: string; email: string } | null;
+  clis: CliStatus;
+  connect: () => void;
+  disconnect: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export function useLinearConnection(): LinearConnectionState {
+  const [connected, setConnected] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [user, setUser] = useState<{ name: string; email: string } | null>(null);
+  const [clis, setClis] = useState<CliStatus>({ claude: false, codex: false, gemini: false });
+
+  const refresh = useCallback(async () => {
+    try {
+      const res = await fetch("/api/linear/status");
+      const data = await res.json();
+      setConnected(data.connected);
+      setUser(data.user ?? null);
+      setClis(data.clis ?? { claude: false, codex: false, gemini: false });
+    } catch {
+      setConnected(false);
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    refresh();
+  }, [refresh]);
+
+  const connect = useCallback(() => {
+    window.location.href = "/api/linear/auth";
+  }, []);
+
+  const disconnect = useCallback(async () => {
+    await fetch("/api/linear/status", { method: "DELETE" });
+    setConnected(false);
+    setUser(null);
+  }, []);
+
+  return { connected, loading, user, clis, connect, disconnect, refresh };
+}
+```
+
+- [ ] **Step 2: Create `hooks/useLinearIssues.ts`**
+
+```typescript
+import { useState, useEffect, useCallback, useRef } from "react";
+
+export interface LinearIssue {
+  id: string;
+  identifier: string;
+  title: string;
+  status: string;
+  assignee: string | null;
+  updatedAt: string;
+}
+
+interface Filters {
+  teamId?: string;
+  status?: string;
+  search?: string;
+}
+
+interface UseLinearIssuesReturn {
+  issues: LinearIssue[];
+  loading: boolean;
+  hasMore: boolean;
+  loadMore: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+export function useLinearIssues(filters: Filters): UseLinearIssuesReturn {
+  const [issues, setIssues] = useState<LinearIssue[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [hasMore, setHasMore] = useState(false);
+  const cursorRef = useRef(cursor);
+  cursorRef.current = cursor;
+
+  const fetchPage = useCallback(
+    async (append: boolean) => {
+      setLoading(true);
+      try {
+        const params = new URLSearchParams();
+        if (filters.teamId) params.set("teamId", filters.teamId);
+        if (filters.status) params.set("status", filters.status);
+        if (filters.search) params.set("search", filters.search);
+        if (append && cursorRef.current) params.set("cursor", cursorRef.current);
+
+        const res = await fetch(`/api/linear/issues?${params.toString()}`);
+        const data = await res.json();
+        const newIssues: LinearIssue[] = data.issues ?? [];
+
+        setIssues((prev) => (append ? [...prev, ...newIssues] : newIssues));
+        setCursor(data.pageInfo?.endCursor ?? null);
+        setHasMore(data.pageInfo?.hasNextPage ?? false);
+      } catch {
+        if (!append) setIssues([]);
+      } finally {
+        setLoading(false);
+      }
+    },
+    [filters.teamId, filters.status, filters.search],
+  );
+
+  useEffect(() => {
+    setCursor(null);
+    fetchPage(false);
+  }, [fetchPage]);
+
+  const loadMore = useCallback(() => fetchPage(true), [fetchPage]);
+  const refresh = useCallback(() => {
+    setCursor(null);
+    return fetchPage(false);
+  }, [fetchPage]);
+
+  return { issues, loading, hasMore, loadMore, refresh };
+}
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add hooks/useLinearConnection.ts hooks/useLinearIssues.ts
+git commit -m "feat: add useLinearConnection and useLinearIssues hooks"
+```
+
+---
+
+## Task 5: Linear Setup Component (Empty State)
+
+**Files:**
+- Create: `components/LinearSetup.tsx`
+
+- [ ] **Step 1: Create `components/LinearSetup.tsx`**
+
+```typescript
+"use client";
+
+import { ExternalLink } from "lucide-react";
+
+interface CliStatus {
+  claude: boolean;
+  codex: boolean;
+  gemini: boolean;
+}
+
+interface LinearSetupProps {
+  connected: boolean;
+  user: { name: string; email: string } | null;
+  clis: CliStatus;
+  onConnect: () => void;
+  onDisconnect: () => Promise<void>;
+}
+
+const CLI_PROVIDERS = [
+  { id: "claude" as const, label: "Claude", icon: "🟣", docsUrl: "https://linear.app/docs/mcp" },
+  { id: "codex" as const, label: "Codex", icon: "⚫", docsUrl: "https://linear.app/docs/mcp" },
+  { id: "gemini" as const, label: "Gemini", icon: "🔵", docsUrl: "https://linear.app/docs/mcp" },
+];
+
+export default function LinearSetup({
+  connected,
+  user,
+  clis,
+  onConnect,
+  onDisconnect,
+}: LinearSetupProps) {
+  return (
+    <div className="flex h-full items-center justify-center">
+      <div className="w-full max-w-md space-y-6 px-6">
+        {/* Section 1: App Connection */}
+        <div>
+          <h2 className="text-sm font-semibold text-[var(--foreground)]">
+            Connect to Linear
+          </h2>
+          <p className="mt-1 text-xs text-[var(--muted-foreground)]">
+            Connect your workspace to browse tickets and execute them with
+            agents.
+          </p>
+          <div className="mt-3">
+            {connected ? (
+              <div className="flex items-center justify-between rounded-md border border-[var(--card-border)] px-3 py-2">
+                <div className="text-xs text-[var(--foreground)]">
+                  Connected as{" "}
+                  <span className="font-medium">{user?.name}</span>
+                </div>
+                <button
+                  type="button"
+                  onClick={onDisconnect}
+                  className="text-[10px] text-[var(--muted-foreground)] hover:text-[var(--foreground)] transition-colors"
+                >
+                  Disconnect
+                </button>
+              </div>
+            ) : (
+              <button
+                type="button"
+                onClick={onConnect}
+                className="w-full rounded-md bg-[var(--foreground)] px-4 py-2 text-xs font-medium text-[var(--card-bg)] transition-opacity hover:opacity-90"
+              >
+                Connect with Linear
+              </button>
+            )}
+          </div>
+        </div>
+
+        {/* Section 2: Agent MCP Access */}
+        <div>
+          <h2 className="text-sm font-semibold text-[var(--foreground)]">
+            Agent Access
+          </h2>
+          <p className="mt-1 text-xs text-[var(--muted-foreground)]">
+            Configure Linear MCP on your AI providers so agents can interact
+            with tickets during execution.
+          </p>
+          <div className="mt-3 space-y-1">
+            {CLI_PROVIDERS.map((provider) => {
+              const installed = clis[provider.id];
+              return (
+                <div
+                  key={provider.id}
+                  className={`flex items-center justify-between rounded-md border border-[var(--card-border)] px-3 py-2 ${
+                    !installed ? "opacity-50" : ""
+                  }`}
+                >
+                  <div className="flex items-center gap-2 text-xs">
+                    <span>{provider.icon}</span>
+                    <span className="text-[var(--foreground)]">
+                      {provider.label}
+                    </span>
+                  </div>
+                  {installed ? (
+                    <a
+                      href={provider.docsUrl}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      className="flex items-center gap-1 text-[10px] text-[var(--muted-foreground)] hover:text-[var(--foreground)] transition-colors"
+                    >
+                      Setup
+                      <ExternalLink size={10} />
+                    </a>
+                  ) : (
+                    <span className="text-[10px] text-[var(--muted-foreground)]">
+                      Not installed
+                    </span>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add components/LinearSetup.tsx
+git commit -m "feat: add LinearSetup empty state component with OAuth + CLI detection"
+```
+
+---
+
+## Task 6: LinearBoard Component (Three-Panel Layout)
+
+**Files:**
+- Create: `components/LinearBoard.tsx`
+
+This is the main component. It follows the exact pattern of `PromptJobBoard.tsx` — three panels: ticket list (left), run history (middle), steerable thread (right). The ticket list uses infinite scroll. The run history and thread reuse `RunChatPanel`-style patterns with `useGroupChat` and `useProcessPolling`.
+
+- [ ] **Step 1: Create `components/LinearBoard.tsx`**
+
+```typescript
+"use client";
+
+import React, { useState, useEffect, useCallback, useMemo, useRef } from "react";
+import dynamic from "next/dynamic";
+import { Play, ExternalLink, Search } from "lucide-react";
+import { useLinearIssues, type LinearIssue } from "@/hooks/useLinearIssues";
+import { useLinearConnection } from "@/hooks/useLinearConnection";
+import { useGroupChat } from "@/hooks/useGroupChat";
+import { useProcessPolling } from "@/hooks/useProcessPolling";
+import { Markdown } from "@/components/chat-ui/Markdown";
+import { stripMarkers } from "@/lib/chat-utils";
+import type { GroupMessage } from "@/lib/types";
+import LinearSetup from "@/components/LinearSetup";
+
+const Composer = dynamic(
+  () => import("@/components/chat-ui/Composer").then((m) => m.Composer),
+  { ssr: false },
+);
+
+// ── Run types ─────────────────────────────────────────────────────────────────
+
+interface LinearRun {
+  id: string;
+  issueId: string;
+  status: "running" | "success" | "failed" | "cancelled";
+  agentId: string;
+  agentName: string;
+  durationMs: number | null;
+  startedAt: string;
+}
+
+const runStatusDot: Record<string, string> = {
+  success: "bg-emerald-500",
+  failed: "bg-red-500",
+  cancelled: "bg-zinc-500",
+  running: "bg-sky-400 animate-pulse",
+};
+
+function formatDate(dateStr: string): string {
+  const d = new Date(dateStr);
+  return d.toLocaleDateString(undefined, { month: "short", day: "numeric" }) +
+    ", " +
+    d.toLocaleTimeString(undefined, { hour: "numeric", minute: "2-digit" });
+}
+
+// ── Run Chat Panel ────────────────────────────────────────────────────────────
+
+function RunChatPanel({
+  run,
+  projectId,
+  agentMap,
+}: {
+  run: LinearRun;
+  projectId?: string;
+  agentMap: Record<string, { id: string; name: string; title?: string; provider?: string; model?: string; color?: string }>;
+}) {
+  const threadId = `linear-run:${run.id}`;
+  const rootMessageId = useMemo(() => `linear-run-root:${run.id}`, [run.id]);
+
+  const [projectAgentIds, setProjectAgentIds] = useState<Set<string>>(new Set());
+  useEffect(() => {
+    if (!projectId) return;
+    fetch(`/api/projects/${encodeURIComponent(projectId)}/agents`)
+      .then((r) => r.json())
+      .then((d) => {
+        setProjectAgentIds(new Set((d.agents ?? []).map((a: { agent_id: string }) => a.agent_id)));
+      })
+      .catch(() => {});
+  }, [projectId]);
+
+  const participants = useMemo(
+    () =>
+      Object.values(agentMap)
+        .filter((a) => projectAgentIds.has(a.id))
+        .map((a) => ({
+          id: a.id,
+          name: a.name,
+          title: a.title ?? undefined,
+          provider: (a.provider ?? "claude") as import("@/lib/types").ChatProvider,
+          model: a.model,
+          color: a.color,
+        })),
+    [agentMap, projectAgentIds],
+  );
+
+  const {
+    messages,
+    setMessages,
+    sendMessage,
+    loadHistory,
+    chatRuns,
+    stop,
+  } = useGroupChat(threadId);
+
+  const { processes, streaming, chatRuns: polledChatRuns } = useProcessPolling(
+    { workspaceId: threadId, threadId: rootMessageId },
+    { messages, setMessages },
+  );
+
+  const activeChatRuns = useMemo(() => {
+    const merged = [...chatRuns];
+    for (const pr of polledChatRuns) {
+      if (!merged.some((r) => r.chatRunId === pr.chatRunId)) merged.push(pr);
+    }
+    return merged;
+  }, [chatRuns, polledChatRuns]);
+
+  const isWorking =
+    activeChatRuns.some((r) => r.status === "queued" || r.status === "running") ||
+    processes.some((p) => p.state === "spawning" || p.state === "running");
+
+  const activityStatus: "ready" | "queued" | "working" = isWorking
+    ? activeChatRuns.some((r) => r.status === "queued")
+      ? "queued"
+      : "working"
+    : "ready";
+
+  // Load chat history on mount
+  useEffect(() => {
+    loadHistory(rootMessageId);
+  }, [loadHistory, rootMessageId]);
+
+  const scrollRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (scrollRef.current) {
+      scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+    }
+  }, [messages]);
+
+  const agentIds = useMemo(() => participants.map((p) => p.id), [participants]);
+
+  const handleSend = useCallback(
+    (
+      message: string,
+      maxRounds?: number,
+      attachmentIds?: string[],
+      _attachments?: any[],
+      pinnedParticipantId?: string,
+      promptPrefix?: string,
+    ) => {
+      sendMessage(
+        message,
+        maxRounds,
+        undefined,
+        rootMessageId,
+        attachmentIds,
+        undefined,
+        agentIds,
+        undefined,
+        promptPrefix,
+      );
+    },
+    [sendMessage, rootMessageId, agentIds],
+  );
+
+  return (
+    <div className="flex min-w-0 flex-1 flex-col overflow-hidden">
+      {/* Messages */}
+      <div ref={scrollRef} className="min-h-0 flex-1 overflow-y-auto px-4 py-3 space-y-3">
+        {messages.map((msg: GroupMessage) => {
+          const isUser = msg.role === "user";
+          const agent = !isUser && msg.agentId ? agentMap[msg.agentId] : null;
+          return (
+            <div key={msg.id} className="text-xs">
+              <div className="flex items-center gap-2 mb-0.5">
+                <span className="font-medium text-[var(--foreground)]">
+                  {isUser ? "You" : agent?.name ?? "Agent"}
+                </span>
+                <span className="text-[10px] text-[var(--muted-foreground)]">
+                  {msg.createdAt
+                    ? new Date(msg.createdAt).toLocaleTimeString(undefined, {
+                        hour: "numeric",
+                        minute: "2-digit",
+                      })
+                    : ""}
+                </span>
+              </div>
+              <div className="text-[var(--foreground)]/90 prose prose-xs dark:prose-invert max-w-none">
+                <Markdown content={stripMarkers(msg.content)} />
+              </div>
+            </div>
+          );
+        })}
+        {isWorking && (
+          <div className="flex items-center gap-2 text-[11px] text-[var(--muted-foreground)]">
+            <span className="inline-block size-2 rounded-full bg-sky-400 animate-pulse" />
+            Working...
+          </div>
+        )}
+      </div>
+
+      {/* Composer - floating at bottom */}
+      <div className="border-t border-[var(--card-border)] p-2">
+        <Composer
+          onSend={handleSend}
+          onStop={stop}
+          participants={participants}
+          activityStatus={activityStatus}
+          placeholder="Steer this run..."
+          compact
+        />
+      </div>
+    </div>
+  );
+}
+
+// ── Ticket List Panel ─────────────────────────────────────────────────────────
+
+function TicketRow({
+  issue,
+  selected,
+  onClick,
+}: {
+  issue: LinearIssue;
+  selected: boolean;
+  onClick: () => void;
+}) {
+  // Abbreviate status: "In Progress" -> "Prog", "Todo" -> "Todo", etc.
+  const shortStatus =
+    issue.status === "In Progress"
+      ? "Prog"
+      : issue.status.length > 6
+        ? issue.status.slice(0, 4)
+        : issue.status;
+
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      className={`flex w-full items-center gap-3 px-3 py-2 text-left text-xs transition-colors border-l-2 ${
+        selected
+          ? "bg-[var(--foreground)]/5 border-l-[var(--foreground)]"
+          : "border-l-transparent hover:bg-[var(--muted)]/30"
+      }`}
+    >
+      <span className="shrink-0 w-[72px] text-[var(--muted-foreground)] font-mono text-[10px]">
+        {issue.identifier}
+      </span>
+      <span className="min-w-0 flex-1 truncate text-[var(--foreground)]">
+        {issue.title}
+      </span>
+      <span className="shrink-0 w-[36px] text-right text-[10px] text-[var(--muted-foreground)]">
+        {shortStatus}
+      </span>
+      <span className="shrink-0 w-[56px] text-right text-[10px] text-[var(--muted-foreground)] truncate">
+        {issue.assignee ?? "\u2014"}
+      </span>
+    </button>
+  );
+}
+
+// ── Main Board ────────────────────────────────────────────────────────────────
+
+export default function LinearBoard({ projectId }: { projectId?: string }) {
+  const connection = useLinearConnection();
+  const [filters, setFilters] = useState<{
+    teamId?: string;
+    status?: string;
+    search?: string;
+  }>({});
+  const [searchInput, setSearchInput] = useState("");
+  const { issues, loading, hasMore, loadMore, refresh } = useLinearIssues(filters);
+
+  const [selectedIssueId, setSelectedIssueId] = useState<string | null>(null);
+  const [selectedRunId, setSelectedRunId] = useState<string | null>(null);
+  const [agentMap, setAgentMap] = useState<Record<string, any>>({});
+
+  // Fetch agents for thread context
+  useEffect(() => {
+    fetch("/api/prompt-jobs/agents")
+      .then((r) => r.json())
+      .then((d) => {
+        const map: Record<string, any> = {};
+        for (const a of d.agents ?? []) map[a.id] = a;
+        setAgentMap(map);
+      })
+      .catch(() => {});
+  }, []);
+
+  // Runs for the selected issue (stored locally for now — future: persist to DB)
+  const [runs, setRuns] = useState<LinearRun[]>([]);
+
+  const selectedIssue = issues.find((i) => i.id === selectedIssueId) ?? null;
+  const selectedRun = runs.find((r) => r.id === selectedRunId) ?? null;
+
+  // Infinite scroll sentinel
+  const sentinelRef = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    if (!sentinelRef.current || !hasMore) return;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries[0].isIntersecting && hasMore && !loading) {
+          loadMore();
+        }
+      },
+      { threshold: 0.1 },
+    );
+    observer.observe(sentinelRef.current);
+    return () => observer.disconnect();
+  }, [hasMore, loading, loadMore]);
+
+  // Debounced search
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      setFilters((prev) => ({ ...prev, search: searchInput || undefined }));
+    }, 300);
+    return () => clearTimeout(timer);
+  }, [searchInput]);
+
+  // Execute: create a new run for the selected issue
+  const handleExecute = useCallback(
+    (agentId: string) => {
+      if (!selectedIssue) return;
+      const run: LinearRun = {
+        id: crypto.randomUUID(),
+        issueId: selectedIssue.id,
+        status: "running",
+        agentId,
+        agentName: agentMap[agentId]?.name ?? "Agent",
+        durationMs: null,
+        startedAt: new Date().toISOString(),
+      };
+      setRuns((prev) => [run, ...prev]);
+      setSelectedRunId(run.id);
+    },
+    [selectedIssue, agentMap],
+  );
+
+  // ── Empty state ──
+  if (connection.loading) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-[var(--muted-foreground)]">
+        Loading...
+      </div>
+    );
+  }
+
+  if (!connection.connected) {
+    return (
+      <LinearSetup
+        connected={false}
+        user={null}
+        clis={connection.clis}
+        onConnect={connection.connect}
+        onDisconnect={connection.disconnect}
+      />
+    );
+  }
+
+  // ── Connected: three-panel layout ──
+  return (
+    <div className="flex h-full flex-col bg-[var(--card-bg)]">
+      {/* Header bar with filters */}
+      <div className="flex items-center gap-2 border-b border-[var(--card-border)] px-3 py-2">
+        <span className="text-[10px] font-bold uppercase tracking-[0.12em] text-[var(--muted-foreground)]">
+          Linear Tickets
+        </span>
+        <div className="flex-1" />
+        <div className="relative">
+          <Search
+            size={12}
+            className="absolute left-2 top-1/2 -translate-y-1/2 text-[var(--muted-foreground)]"
+          />
+          <input
+            type="text"
+            placeholder="Search..."
+            value={searchInput}
+            onChange={(e) => setSearchInput(e.target.value)}
+            className="h-6 w-40 rounded border border-[var(--card-border)] bg-transparent pl-6 pr-2 text-[11px] text-[var(--foreground)] placeholder:text-[var(--muted-foreground)] outline-none focus:border-[var(--foreground)]/30"
+          />
+        </div>
+      </div>
+
+      {/* Three-panel body */}
+      <div className="flex min-h-0 flex-1 overflow-hidden">
+        {/* LEFT: Ticket list (infinite scroll) */}
+        <div className="flex w-[340px] shrink-0 flex-col border-r border-[var(--card-border)] overflow-hidden">
+          <div className="min-h-0 flex-1 overflow-y-auto">
+            {issues.map((issue) => (
+              <TicketRow
+                key={issue.id}
+                issue={issue}
+                selected={selectedIssueId === issue.id}
+                onClick={() => {
+                  setSelectedIssueId(issue.id);
+                  // Load runs for this issue (filter local runs)
+                  setSelectedRunId(null);
+                }}
+              />
+            ))}
+            {hasMore && (
+              <div ref={sentinelRef} className="py-4 text-center text-[10px] text-[var(--muted-foreground)]">
+                {loading ? "Loading..." : ""}
+              </div>
+            )}
+            {!loading && issues.length === 0 && (
+              <div className="p-4 text-center text-[11px] text-[var(--muted-foreground)]">
+                No tickets found
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* MIDDLE: Run history */}
+        <div className="flex w-[200px] shrink-0 flex-col border-r border-[var(--card-border)] overflow-hidden">
+          <div className="border-b border-[var(--card-border)] px-3 py-2 flex items-center justify-between">
+            <div className="text-[10px] font-bold uppercase tracking-[0.12em] text-[var(--muted-foreground)]">
+              Runs{" "}
+              <span className="text-[var(--muted-foreground)]/50">
+                {runs.filter((r) => r.issueId === selectedIssueId).length}
+              </span>
+            </div>
+            {selectedIssue && Object.keys(agentMap).length > 0 && (
+              <button
+                type="button"
+                onClick={() => {
+                  // Execute with first available agent — later: agent picker
+                  const firstAgent = Object.values(agentMap)[0];
+                  if (firstAgent) handleExecute(firstAgent.id);
+                }}
+                className="flex items-center gap-1 rounded px-1.5 py-0.5 text-[10px] text-[var(--muted-foreground)] hover:text-[var(--foreground)] hover:bg-[var(--muted)]/30 transition-colors"
+                title="Execute with agent"
+              >
+                <Play size={10} />
+                Run
+              </button>
+            )}
+          </div>
+          <div className="min-h-0 flex-1 overflow-y-auto">
+            {runs
+              .filter((r) => r.issueId === selectedIssueId)
+              .map((run) => {
+                const isSelected = selectedRunId === run.id;
+                return (
+                  <button
+                    key={run.id}
+                    type="button"
+                    onClick={() => setSelectedRunId(run.id)}
+                    className={`flex items-start gap-2.5 px-3 py-2.5 w-full text-left transition-colors border-l-2 ${
+                      isSelected
+                        ? "bg-[var(--foreground)]/5 border-l-[var(--foreground)]"
+                        : "border-l-transparent hover:bg-[var(--muted)]/30"
+                    }`}
+                  >
+                    <span
+                      className={`mt-1 inline-block size-2 shrink-0 rounded-full ${runStatusDot[run.status] ?? "bg-zinc-500"}`}
+                    />
+                    <div className="min-w-0 flex-1">
+                      <div className="text-[11px] font-medium text-[var(--foreground)] truncate">
+                        {run.status === "running" ? "Running..." : run.status.charAt(0).toUpperCase() + run.status.slice(1)}
+                        {run.durationMs != null && ` \u00B7 ${(run.durationMs / 1000).toFixed(1)}s`}
+                      </div>
+                      <div className="mt-0.5 text-[10px] text-[var(--muted-foreground)]">
+                        {formatDate(run.startedAt)}
+                      </div>
+                    </div>
+                  </button>
+                );
+              })}
+            {selectedIssueId &&
+              runs.filter((r) => r.issueId === selectedIssueId).length === 0 && (
+                <div className="p-4 text-center text-[11px] text-[var(--muted-foreground)]">
+                  No runs yet
+                </div>
+              )}
+            {!selectedIssueId && (
+              <div className="p-4 text-center text-[11px] text-[var(--muted-foreground)]">
+                Select a ticket
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* RIGHT: Steerable thread */}
+        {selectedRun ? (
+          <RunChatPanel
+            key={selectedRun.id}
+            run={selectedRun}
+            projectId={projectId}
+            agentMap={agentMap}
+          />
+        ) : (
+          <div className="flex min-w-0 flex-1 items-center justify-center text-[var(--muted-foreground)] text-sm">
+            {selectedIssueId
+              ? 'No runs yet. Click "Run" to execute this ticket.'
+              : "Select a ticket to get started"}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add components/LinearBoard.tsx
+git commit -m "feat: add LinearBoard three-panel component (ticket list + runs + steerable thread)"
+```
+
+---
+
+## Task 7: Project-Scoped Linear Page + Sidebar Nav
+
+**Files:**
+- Create: `app/projects/[slug]/linear/page.tsx`
+- Modify: `components/thread/WorkspaceSidebar.tsx:61,431,476-486`
+
+- [ ] **Step 1: Create the project-scoped Linear page**
+
+Create `app/projects/[slug]/linear/page.tsx`:
+
+```typescript
+"use client";
+
+import { use } from "react";
+import { useProjects } from "@/hooks/useProjects";
+import LinearBoard from "@/components/LinearBoard";
+
+export default function ProjectLinearPage({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = use(params);
+  const { projects } = useProjects();
+  const project = projects.find((p) => p.slug === slug);
+
+  return <LinearBoard projectId={project?.id} />;
+}
+```
+
+- [ ] **Step 2: Add "linear" to the `activeProjectView` type**
+
+In `components/thread/WorkspaceSidebar.tsx`, update the prop type at line 61:
+
+```typescript
+// Before:
+activeProjectView?: "board" | "thread" | "knowledge" | "automations" | null;
+
+// After:
+activeProjectView?: "board" | "thread" | "knowledge" | "automations" | "linear" | null;
+```
+
+- [ ] **Step 3: Add `isActiveProjectLinear` variable**
+
+After line 431 in `WorkspaceSidebar.tsx`, add:
+
+```typescript
+const isActiveProjectLinear = isActiveProject && activeProjectView === "linear";
+```
+
+- [ ] **Step 4: Add Linear nav item in the sidebar**
+
+After the Automations nav item block (after line 486), add a new `<div>` block:
+
+```tsx
+{/* Linear */}
+<div className="workspace-sidebar__workspace-item">
+  <Link
+    href={`/projects/${project.slug}/linear`}
+    className={`workspace-sidebar__nav-item ${isActiveProjectLinear ? "workspace-sidebar__nav-item--active" : ""}`}
+    aria-current={isActiveProjectLinear ? "page" : undefined}
+  >
+    <ExternalLink size={12} className="flex-shrink-0 text-[var(--muted-foreground)]" />
+    <span className="workspace-sidebar__workspace-title text-xs">Linear</span>
+  </Link>
+</div>
+```
+
+Make sure to import `ExternalLink` from `lucide-react` at the top of the file if not already imported. (Check existing imports first — the file already imports from `lucide-react`.)
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add app/projects/\[slug\]/linear/page.tsx components/thread/WorkspaceSidebar.tsx
+git commit -m "feat: add Linear page route and sidebar nav item"
+```
+
+---
+
+## Task 8: Wire Up Execute Flow (Ticket -> Agent Run -> Thread)
+
+**Files:**
+- Modify: `components/LinearBoard.tsx`
+
+The `handleExecute` in Task 6 creates a local run object. This task wires it to actually send a message to the agent via the existing chat API, using the Linear ticket as context — the same way `PromptJobBoard` sends a prompt to an agent.
+
+- [ ] **Step 1: Update `handleExecute` to send the initial chat message**
+
+In `components/LinearBoard.tsx`, replace the `handleExecute` callback:
+
+```typescript
+const handleExecute = useCallback(
+  async (agentId: string) => {
+    if (!selectedIssue) return;
+    const runId = crypto.randomUUID();
+    const run: LinearRun = {
+      id: runId,
+      issueId: selectedIssue.id,
+      status: "running",
+      agentId,
+      agentName: agentMap[agentId]?.name ?? "Agent",
+      durationMs: null,
+      startedAt: new Date().toISOString(),
+    };
+    setRuns((prev) => [run, ...prev]);
+    setSelectedRunId(run.id);
+
+    // Send the initial message to kick off the agent
+    const threadId = `linear-run:${runId}`;
+    const rootMessageId = `linear-run-root:${runId}`;
+    const promptPrefix = `[Linear Ticket: ${selectedIssue.identifier}]\nTitle: ${selectedIssue.title}\nStatus: ${selectedIssue.status}\nAssignee: ${selectedIssue.assignee ?? "Unassigned"}\n\n`;
+    const prompt = `Work on this Linear ticket: ${selectedIssue.identifier} - ${selectedIssue.title}`;
+
+    await fetch("/api/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        prompt,
+        promptPrefix,
+        threadId,
+        rootMessageId,
+        agentIds: [agentId],
+      }),
+    });
+  },
+  [selectedIssue, agentMap],
+);
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add components/LinearBoard.tsx
+git commit -m "feat: wire execute flow to send initial chat message with ticket context"
+```
+
+---
+
+## Task 9: Smoke Test and Polish
+
+**Files:**
+- Various adjustments
+
+- [ ] **Step 1: Add env vars to `.env.local` (or `.env`)**
+
+Create or update `.env.local`:
+
+```
+LINEAR_CLIENT_ID=<your-linear-app-client-id>
+LINEAR_CLIENT_SECRET=<your-linear-app-client-secret>
+NEXT_PUBLIC_APP_URL=http://localhost:3000
+```
+
+(Create the Linear OAuth app at https://linear.app/settings/api/applications)
+
+- [ ] **Step 2: Run the dev server and verify the flow**
+
+```bash
+cd /Users/mendrika/Projects/Agents/agx-cloud && npm run dev
+```
+
+Verify:
+1. Navigate to a project in sidebar -> click "Linear" tab
+2. See the LinearSetup empty state with "Connect with Linear" button
+3. Click connect -> OAuth redirect -> callback -> token saved
+4. See the ticket list load with `ID | title | status | assignee` rows
+5. Click a ticket -> see empty runs panel
+6. Click "Run" -> see a run appear + chat thread start
+7. Type in composer -> message sends to agent thread
+8. Scroll ticket list to bottom -> infinite scroll loads more
+
+- [ ] **Step 3: Final commit**
+
+```bash
+git add -A
+git commit -m "feat: complete Linear integration — ticket browser, execute flow, steerable threads"
+```
+
+---
+
+## Summary
+
+| Task | What | Files |
+|------|------|-------|
+| 1 | SDK install + token module | `package.json`, `lib/linear-client.ts` |
+| 2 | OAuth routes (auth, callback, status) | `app/api/linear/auth,callback,status/route.ts` |
+| 3 | Issues list API | `app/api/linear/issues/route.ts` |
+| 4 | React hooks | `hooks/useLinearConnection.ts`, `hooks/useLinearIssues.ts` |
+| 5 | Setup empty state component | `components/LinearSetup.tsx` |
+| 6 | Three-panel LinearBoard | `components/LinearBoard.tsx` |
+| 7 | Page route + sidebar nav | `app/projects/[slug]/linear/page.tsx`, `WorkspaceSidebar.tsx` |
+| 8 | Execute flow wiring | `components/LinearBoard.tsx` |
+| 9 | Env setup + smoke test | `.env.local` |