From 9303444135dd94eaf3ae48308bb98702a67a07c9 Mon Sep 17 00:00:00 2001
From: Vincent Grobler <vincent@vinash.co.za>
Date: Mon, 11 May 2026 17:07:28 +0100
Subject: [PATCH] feat: bidirectional Linear messaging channel

- Migration 081: add 'linear' to messaging_channels platform, create
  linear_issue_mappings table with RLS
- Edge Function channel-linear: inbound webhook handler with
  configurable triggers (create, state_change, label), HMAC signature
  verification, duplicate detection, priority mapping
- Edge Function linear-webhook-register: creates Linear webhook via
  GraphQL API and fetches team workflow states
- Task runner: replyLinear() posts comment on issue + optional state
  change to configured done state
- Frontend: Linear channel config form with API key, team ID, trigger
  modes, trigger states/labels, and done state fields
- ChannelPlatform type extended with 'linear'
---
 .../settings/MessagingChannelsSettings.tsx    |  41 +-
 src/db/messagingChannels.ts                   |   2 +-
 supabase/functions/channel-linear/index.ts    | 361 ++++++++++++++++++
 .../linear-webhook-register/index.ts          | 158 ++++++++
 supabase/migrations/081_linear_channel.sql    |  74 ++++
 task-runner/src/webhookDispatcher.ts          | 120 +++++-
 6 files changed, 749 insertions(+), 7 deletions(-)
 create mode 100644 supabase/functions/channel-linear/index.ts
 create mode 100644 supabase/functions/linear-webhook-register/index.ts
 create mode 100644 supabase/migrations/081_linear_channel.sql

diff --git a/src/components/settings/MessagingChannelsSettings.tsx b/src/components/settings/MessagingChannelsSettings.tsx
index 41fe25b4..988373a8 100644
--- a/src/components/settings/MessagingChannelsSettings.tsx
+++ b/src/components/settings/MessagingChannelsSettings.tsx
@@ -5,7 +5,7 @@ import { useState } from 'react'
 import {
     Send, MessageSquare, Hash, Mail, Plus, Trash2, Power, PowerOff,
     Loader2, ChevronDown, ChevronUp, ExternalLink, ArrowDownLeft, ArrowUpRight,
-    Copy, Check, Link2, Columns3,
+    Copy, Check, Link2, Columns3, Layers,
 } from 'lucide-react'
 import { useWorkspace } from '@/hooks/useWorkspace'
 import {
@@ -97,6 +97,22 @@ const PLATFORM_META: Record<ChannelPlatform, {
             { key: 'review_list_id', label: 'Review List ID (completed cards move here)', type: 'text', placeholder: '5f4e3d2c1b...', required: false },
         ],
     },
+    linear: {
+        label: 'Linear',
+        icon: Layers,
+        color: 'text-violet-300',
+        bgColor: 'bg-violet-500/10',
+        setupGuide: 'https://linear.app/settings/api',
+        connectCommand: '',
+        configFields: [
+            { key: 'api_key', label: 'Personal API Key', type: 'password', placeholder: 'lin_api_...', required: true },
+            { key: 'linear_team_id', label: 'Team ID', type: 'text', placeholder: 'Team UUID from Linear settings', required: true },
+            { key: 'trigger_on', label: 'Trigger On (comma-separated: create, state_change, label)', type: 'text', placeholder: 'create,state_change', required: true },
+            { key: 'trigger_states', label: 'Trigger States (comma-separated, e.g. Triage,Todo)', type: 'text', placeholder: 'Triage,Todo', required: false },
+            { key: 'trigger_labels', label: 'Trigger Labels (comma-separated)', type: 'text', placeholder: 'crewform,ai-task', required: false },
+            { key: 'done_state_name', label: 'Done State (move issue here on completion)', type: 'text', placeholder: 'Done', required: false },
+        ],
+    },
 }
 
 function generateConnectCode(): string {
@@ -131,7 +147,7 @@ export function MessagingChannelsSettings() {
                 <div>
                     <h2 className="text-lg font-medium text-gray-100">Messaging Channels</h2>
                     <p className="mt-1 text-sm text-gray-500">
-                        Send messages from Telegram, Discord, Slack, Email, or Trello to trigger your agents.
+                        Send messages from Telegram, Discord, Slack, Email, Trello, or Linear to trigger your agents.
                     </p>
                 </div>
                 <button
@@ -195,16 +211,31 @@ function CreateChannelForm({ workspaceId, onClose }: { workspaceId: string; onCl
     const meta = PLATFORM_META[platform]
     const isEmail = platform === 'email'
     const isTrello = platform === 'trello'
-    const skipManaged = isEmail || isTrello
+    const isLinear = platform === 'linear'
+    const skipManaged = isEmail || isTrello || isLinear
 
     const handleSubmit = (e: React.FormEvent) => {
         e.preventDefault()
         if (!selectedId) return
+
+        // For Linear, parse comma-separated fields into arrays
+        let resolvedConfig: Record<string, unknown> = isManaged && !skipManaged ? {} : { ...config }
+        if (isLinear) {
+            const csvToArray = (val: string | undefined): string[] =>
+                val ? val.split(',').map(s => s.trim()).filter(Boolean) : []
+            resolvedConfig = {
+                ...config,
+                trigger_on: csvToArray(config.trigger_on),
+                trigger_states: csvToArray(config.trigger_states),
+                trigger_labels: csvToArray(config.trigger_labels),
+            }
+        }
+
         const input: CreateChannelInput = {
             workspace_id: workspaceId,
             platform,
             name: name || `${meta.label} Channel`,
-            config: isManaged && !skipManaged ? {} : config,
+            config: resolvedConfig,
             is_managed: isManaged && !skipManaged,
             connect_code: isManaged && !skipManaged ? generateConnectCode() : undefined,
             default_agent_id: routeType === 'agent' ? selectedId : undefined,
@@ -223,7 +254,7 @@ function CreateChannelForm({ workspaceId, onClose }: { workspaceId: string; onCl
             <h3 className="text-sm font-medium text-gray-200">New Messaging Channel</h3>
 
             {/* Platform selector */}
-            <div className="grid grid-cols-3 gap-2 sm:grid-cols-5">
+            <div className="grid grid-cols-3 gap-2 sm:grid-cols-6">
                 {(Object.keys(PLATFORM_META) as ChannelPlatform[]).map(p => {
                     const m = PLATFORM_META[p]
                     const Icon = m.icon
diff --git a/src/db/messagingChannels.ts b/src/db/messagingChannels.ts
index 0e40893c..7112daf2 100644
--- a/src/db/messagingChannels.ts
+++ b/src/db/messagingChannels.ts
@@ -5,7 +5,7 @@ import { supabase } from '@/lib/supabase'
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
-export type ChannelPlatform = 'telegram' | 'discord' | 'slack' | 'email' | 'trello'
+export type ChannelPlatform = 'telegram' | 'discord' | 'slack' | 'email' | 'trello' | 'linear'
 
 export interface MessagingChannel {
     id: string
diff --git a/supabase/functions/channel-linear/index.ts b/supabase/functions/channel-linear/index.ts
new file mode 100644
index 00000000..4ee23997
--- /dev/null
+++ b/supabase/functions/channel-linear/index.ts
@@ -0,0 +1,361 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 CrewForm
+
+/**
+ * Linear Channel — Inbound Webhook Handler
+ *
+ * Receives Linear webhook events when an issue is created, state-changed,
+ * or labelled with a trigger label. Creates a CrewForm task and maps the
+ * Linear issue for bidirectional updates (results posted as comments).
+ *
+ *  How it works:
+ *  1. Linear sends POST with webhook payload (action, type, data)
+ *  2. Verify webhook signature via Linear-Signature header
+ *  3. Filter for relevant events (Issue create / state change / label)
+ *  4. Look up matching messaging_channel by team_id
+ *  5. Create a task and insert linear_issue_mappings record
+ */
+
+import { createClient } from 'https://esm.sh/@supabase/supabase-js@2';
+import { ok, serverError } from '../_shared/response.ts';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+interface LinearWebhookPayload {
+    action: 'create' | 'update' | 'remove';
+    type: string;
+    data: {
+        id: string;
+        title?: string;
+        description?: string;
+        state?: {
+            id: string;
+            name: string;
+            type: string;
+        };
+        team?: {
+            id: string;
+            key: string;
+            name: string;
+        };
+        labels?: Array<{
+            id: string;
+            name: string;
+        }>;
+        identifier?: string;
+        url?: string;
+        assignee?: {
+            id: string;
+            name: string;
+        };
+        priority?: number;
+        previousIdentifiers?: string[];
+    };
+    updatedFrom?: {
+        stateId?: string;
+        labelIds?: string[];
+        updatedAt?: string;
+    };
+    url?: string;
+    createdAt?: string;
+    organizationId?: string;
+    webhookTimestamp?: number;
+}
+
+interface ChannelRow {
+    id: string;
+    workspace_id: string;
+    config: Record<string, unknown>;
+    default_agent_id: string | null;
+    default_team_id: string | null;
+}
+
+// ─── Signature Verification ─────────────────────────────────────────────────
+
+async function verifyLinearSignature(
+    body: string,
+    signature: string | null,
+    secret: string,
+): Promise<boolean> {
+    if (!signature) return false;
+
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+        'raw',
+        encoder.encode(secret),
+        { name: 'HMAC', hash: 'SHA-256' },
+        false,
+        ['sign'],
+    );
+
+    const sig = await crypto.subtle.sign('HMAC', key, encoder.encode(body));
+    const hexSig = Array.from(new Uint8Array(sig))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+
+    return hexSig === signature;
+}
+
+// ─── Main Handler ───────────────────────────────────────────────────────────
+
+Deno.serve(async (req: Request) => {
+    if (req.method !== 'POST') {
+        return new Response('OK', { status: 200 });
+    }
+
+    try {
+        const rawBody = await req.text();
+        const payload = JSON.parse(rawBody) as LinearWebhookPayload;
+
+        // Only handle Issue events
+        if (payload.type !== 'Issue') {
+            return ok({ ok: true, skipped: true, reason: `ignored type: ${payload.type}` });
+        }
+
+        const issue = payload.data;
+        const teamId = issue.team?.id;
+
+        if (!teamId || !issue.id) {
+            return ok({ ok: true, skipped: true, reason: 'no team or issue id' });
+        }
+
+        const supabaseUrl = Deno.env.get('SUPABASE_URL')!;
+        const supabaseServiceKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!;
+        const supabase = createClient(supabaseUrl, supabaseServiceKey);
+
+        // Find matching Linear messaging channels
+        const { data: channels } = await supabase
+            .from('messaging_channels')
+            .select('id, workspace_id, config, default_agent_id, default_team_id')
+            .eq('platform', 'linear')
+            .eq('is_active', true);
+
+        const channelRows = (channels ?? []) as ChannelRow[];
+
+        // Match by team_id
+        const matchingChannels = channelRows.filter((c) => {
+            const cfgTeamId = c.config.linear_team_id as string | undefined;
+            return cfgTeamId === teamId;
+        });
+
+        if (matchingChannels.length === 0) {
+            return ok({ ok: true, skipped: true, reason: 'no matching channel' });
+        }
+
+        // Process each matching channel
+        for (const channel of matchingChannels) {
+            // Verify webhook signature if secret is configured
+            const webhookSecret = channel.config.webhook_secret as string | undefined;
+            if (webhookSecret) {
+                const signature = req.headers.get('linear-signature');
+                const valid = await verifyLinearSignature(rawBody, signature, webhookSecret);
+                if (!valid) {
+                    console.warn(`[channel-linear] Invalid signature for channel ${channel.id}`);
+                    continue;
+                }
+            }
+
+            // Check trigger conditions
+            const shouldTrigger = evaluateTrigger(payload, channel.config);
+            if (!shouldTrigger) continue;
+
+            if (!channel.default_agent_id && !channel.default_team_id) {
+                console.warn(`[channel-linear] Channel ${channel.id} has no agent or team configured`);
+                continue;
+            }
+
+            // Check for duplicate mapping (avoid re-triggering same issue)
+            const { data: existingMapping } = await supabase
+                .from('linear_issue_mappings')
+                .select('id')
+                .eq('linear_issue_id', issue.id)
+                .eq('workspace_id', channel.workspace_id)
+                .limit(1);
+
+            if (existingMapping && existingMapping.length > 0) {
+                console.log(`[channel-linear] Issue ${issue.id} already mapped, skipping`);
+                continue;
+            }
+
+            // Resolve workspace owner
+            const { data: ws } = await supabase
+                .from('workspaces')
+                .select('owner_id')
+                .eq('id', channel.workspace_id)
+                .single();
+
+            const ownerId = (ws as { owner_id: string } | null)?.owner_id;
+            if (!ownerId) {
+                console.error(`[channel-linear] Could not resolve workspace owner for ${channel.workspace_id}`);
+                continue;
+            }
+
+            // Build source_channel for reply-to-source
+            const sourceChannel = {
+                platform: 'linear',
+                linear_issue_id: issue.id,
+                linear_api_key: channel.config.api_key as string,
+                linear_done_state_name: (channel.config.done_state_name as string) || undefined,
+                channel_db_id: channel.id,
+            };
+
+            const taskTitle = `Linear: ${issue.identifier ?? ''} ${(issue.title ?? '').substring(0, 80)}`.trim();
+            const description = issue.description || issue.title || taskTitle;
+
+            let taskOrRunId: string;
+
+            if (channel.default_team_id) {
+                const { data: run, error: runErr } = await supabase
+                    .from('team_runs')
+                    .insert({
+                        team_id: channel.default_team_id,
+                        workspace_id: channel.workspace_id,
+                        input_task: description,
+                        created_by: ownerId,
+                        status: 'dispatched',
+                        source_channel: sourceChannel,
+                    })
+                    .select('id')
+                    .single();
+
+                if (runErr) {
+                    console.error(`[channel-linear] Failed to create team run: ${runErr.message}`);
+                    continue;
+                }
+                taskOrRunId = (run as { id: string }).id;
+
+                await supabase.from('linear_issue_mappings').insert({
+                    workspace_id: channel.workspace_id,
+                    linear_issue_id: issue.id,
+                    linear_team_id: teamId,
+                    team_run_id: taskOrRunId,
+                });
+            } else {
+                const { data: task, error: taskErr } = await supabase
+                    .from('tasks')
+                    .insert({
+                        title: taskTitle,
+                        description,
+                        workspace_id: channel.workspace_id,
+                        assigned_agent_id: channel.default_agent_id,
+                        created_by: ownerId,
+                        status: 'dispatched',
+                        priority: mapLinearPriority(issue.priority),
+                        source_channel: sourceChannel,
+                        metadata: {
+                            source: 'messaging_channel',
+                            platform: 'linear',
+                            linear_issue_id: issue.id,
+                            linear_team_id: teamId,
+                            linear_identifier: issue.identifier,
+                            channel_id: channel.id,
+                        },
+                    })
+                    .select('id')
+                    .single();
+
+                if (taskErr) {
+                    console.error(`[channel-linear] Failed to create task: ${taskErr.message}`);
+                    continue;
+                }
+                taskOrRunId = (task as { id: string }).id;
+
+                await supabase.from('linear_issue_mappings').insert({
+                    workspace_id: channel.workspace_id,
+                    linear_issue_id: issue.id,
+                    linear_team_id: teamId,
+                    task_id: taskOrRunId,
+                });
+            }
+
+            // Log to channel_message_log
+            await supabase.from('channel_message_log').insert({
+                channel_id: channel.id,
+                direction: 'inbound',
+                task_id: channel.default_team_id ? null : taskOrRunId,
+                team_run_id: channel.default_team_id ? taskOrRunId : null,
+                message_preview: (issue.title ?? '').substring(0, 200),
+                platform_ref: {
+                    issue_id: issue.id,
+                    team_id: teamId,
+                    identifier: issue.identifier,
+                    url: issue.url ?? payload.url,
+                },
+                status: 'delivered',
+            });
+
+            console.log(
+                `[channel-linear] Created ${channel.default_team_id ? 'team run' : 'task'} ${taskOrRunId} from issue ${issue.identifier ?? issue.id}`,
+            );
+        }
+
+        return ok({ ok: true });
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error('[channel-linear] Error:', message);
+        return serverError(message);
+    }
+});
+
+// ─── Trigger Evaluation ─────────────────────────────────────────────────────
+
+function evaluateTrigger(
+    payload: LinearWebhookPayload,
+    config: Record<string, unknown>,
+): boolean {
+    const triggerOn = (config.trigger_on as string[]) ?? ['create'];
+    const issue = payload.data;
+
+    // Trigger on issue creation
+    if (payload.action === 'create' && triggerOn.includes('create')) {
+        return true;
+    }
+
+    // Trigger on state change to a configured trigger state
+    if (payload.action === 'update' && triggerOn.includes('state_change')) {
+        const triggerStates = (config.trigger_states as string[]) ?? [];
+        const currentState = issue.state?.name?.toLowerCase();
+        if (currentState && triggerStates.some((s) => s.toLowerCase() === currentState)) {
+            // Only trigger if state actually changed (not other field updates)
+            if (payload.updatedFrom?.stateId) {
+                return true;
+            }
+        }
+    }
+
+    // Trigger on label addition
+    if (payload.action === 'update' && triggerOn.includes('label')) {
+        const triggerLabels = (config.trigger_labels as string[]) ?? [];
+        const issueLabels = (issue.labels ?? []).map((l) => l.name.toLowerCase());
+        const previousLabelIds = payload.updatedFrom?.labelIds ?? [];
+
+        // Check if any trigger label was just added
+        if (triggerLabels.some((tl) => issueLabels.includes(tl.toLowerCase()))) {
+            // Only trigger if labels changed
+            if (previousLabelIds.length !== (issue.labels ?? []).length) {
+                return true;
+            }
+        }
+    }
+
+    return false;
+}
+
+// ─── Priority Mapping ───────────────────────────────────────────────────────
+
+function mapLinearPriority(priority: number | undefined): string {
+    switch (priority) {
+        case 0:
+            return 'low'; // No priority
+        case 1:
+            return 'urgent';
+        case 2:
+            return 'high';
+        case 3:
+            return 'medium';
+        case 4:
+            return 'low';
+        default:
+            return 'medium';
+    }
+}
diff --git a/supabase/functions/linear-webhook-register/index.ts b/supabase/functions/linear-webhook-register/index.ts
new file mode 100644
index 00000000..f5a2d93f
--- /dev/null
+++ b/supabase/functions/linear-webhook-register/index.ts
@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (C) 2026 CrewForm
+
+/**
+ * Linear Webhook Register — Creates a Linear webhook via GraphQL API.
+ *
+ * Called from the frontend when setting up a Linear messaging channel.
+ * Creates a webhook subscription on the specified Linear team pointing
+ * to the channel-linear Edge Function.
+ */
+
+import { corsHeaders } from '../_shared/cors.ts';
+
+interface RegisterRequest {
+    api_key: string;
+    team_id: string;
+    label?: string;
+}
+
+Deno.serve(async (req: Request) => {
+    if (req.method === 'OPTIONS') {
+        return new Response('ok', { headers: corsHeaders });
+    }
+
+    if (req.method !== 'POST') {
+        return new Response(JSON.stringify({ error: 'Method not allowed' }), {
+            status: 405,
+            headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+        });
+    }
+
+    try {
+        // Verify caller is authenticated
+        const authHeader = req.headers.get('Authorization');
+        if (!authHeader) {
+            return new Response(JSON.stringify({ error: 'Unauthorized' }), {
+                status: 401,
+                headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+            });
+        }
+
+        const body = (await req.json()) as RegisterRequest;
+        const { api_key, team_id, label } = body;
+
+        if (!api_key || !team_id) {
+            return new Response(JSON.stringify({ error: 'api_key and team_id are required' }), {
+                status: 400,
+                headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+            });
+        }
+
+        const supabaseUrl = Deno.env.get('SUPABASE_URL')!;
+        const callbackUrl = `${supabaseUrl}/functions/v1/channel-linear`;
+
+        // Create webhook via Linear GraphQL API
+        const mutation = `
+            mutation WebhookCreate($input: WebhookCreateInput!) {
+                webhookCreate(input: $input) {
+                    success
+                    webhook {
+                        id
+                        enabled
+                        url
+                        secret
+                    }
+                }
+            }
+        `;
+
+        const variables = {
+            input: {
+                url: callbackUrl,
+                teamId: team_id,
+                label: label ?? 'CrewForm',
+                resourceTypes: ['Issue'],
+                enabled: true,
+            },
+        };
+
+        const resp = await fetch('https://api.linear.app/graphql', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: api_key,
+            },
+            body: JSON.stringify({ query: mutation, variables }),
+        });
+
+        const result = await resp.json();
+
+        if (result.errors) {
+            const errorMsg = result.errors.map((e: { message: string }) => e.message).join(', ');
+            console.error('[linear-webhook-register] GraphQL errors:', errorMsg);
+            return new Response(JSON.stringify({ error: errorMsg }), {
+                status: 400,
+                headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+            });
+        }
+
+        const webhookData = result.data?.webhookCreate;
+        if (!webhookData?.success) {
+            return new Response(JSON.stringify({ error: 'Failed to create webhook' }), {
+                status: 500,
+                headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+            });
+        }
+
+        // Also fetch available workflow states for the team (for trigger config)
+        let states: Array<{ id: string; name: string; type: string }> = [];
+        try {
+            const statesQuery = `
+                query TeamStates($teamId: String!) {
+                    team(id: $teamId) {
+                        states {
+                            nodes {
+                                id
+                                name
+                                type
+                            }
+                        }
+                    }
+                }
+            `;
+
+            const statesResp = await fetch('https://api.linear.app/graphql', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: api_key,
+                },
+                body: JSON.stringify({ query: statesQuery, variables: { teamId: team_id } }),
+            });
+
+            const statesResult = await statesResp.json();
+            states = statesResult.data?.team?.states?.nodes ?? [];
+        } catch {
+            console.warn('[linear-webhook-register] Failed to fetch team states');
+        }
+
+        return new Response(JSON.stringify({
+            webhook_id: webhookData.webhook.id,
+            webhook_secret: webhookData.webhook.secret,
+            callback_url: callbackUrl,
+            team_states: states,
+        }), {
+            status: 200,
+            headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+        });
+
+    } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error('[linear-webhook-register] Error:', message);
+        return new Response(JSON.stringify({ error: message }), {
+            status: 500,
+            headers: { ...corsHeaders, 'Content-Type': 'application/json' },
+        });
+    }
+});
diff --git a/supabase/migrations/081_linear_channel.sql b/supabase/migrations/081_linear_channel.sql
new file mode 100644
index 00000000..e0c7b1e5
--- /dev/null
+++ b/supabase/migrations/081_linear_channel.sql
@@ -0,0 +1,74 @@
+-- SPDX-License-Identifier: AGPL-3.0-or-later
+-- Copyright (C) 2026 CrewForm
+--
+-- 081_linear_channel.sql — Bidirectional Linear messaging channel
+--
+-- Adds 'linear' as a messaging channel platform and creates a mapping
+-- table to link Linear issues to CrewForm tasks/team runs.
+--
+
+-- ────────────────────────────────────────────────────────────────────────────
+-- 1. Add 'linear' to messaging_channels platform constraint
+-- ────────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.messaging_channels
+    DROP CONSTRAINT IF EXISTS messaging_channels_platform_check;
+
+ALTER TABLE public.messaging_channels
+    ADD CONSTRAINT messaging_channels_platform_check
+    CHECK (platform IN ('telegram', 'discord', 'slack', 'email', 'trello', 'linear'));
+
+-- ────────────────────────────────────────────────────────────────────────────
+-- 2. Linear issue ↔ CrewForm task/run mapping table
+--    Tracks the bidirectional link so agent results can be posted back as
+--    comments and issue state can be updated on completion.
+-- ────────────────────────────────────────────────────────────────────────────
+
+CREATE TABLE IF NOT EXISTS public.linear_issue_mappings (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    workspace_id    UUID NOT NULL REFERENCES public.workspaces(id) ON DELETE CASCADE,
+    linear_issue_id TEXT NOT NULL,
+    linear_team_id  TEXT NOT NULL,
+    task_id         UUID REFERENCES public.tasks(id) ON DELETE SET NULL,
+    team_run_id     UUID REFERENCES public.team_runs(id) ON DELETE SET NULL,
+    created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+
+    CONSTRAINT chk_linear_task_or_run CHECK (
+        task_id IS NOT NULL OR team_run_id IS NOT NULL
+    )
+);
+
+CREATE INDEX IF NOT EXISTS idx_linear_issue_mappings_workspace
+    ON public.linear_issue_mappings(workspace_id);
+
+CREATE INDEX IF NOT EXISTS idx_linear_issue_mappings_issue
+    ON public.linear_issue_mappings(linear_issue_id);
+
+CREATE INDEX IF NOT EXISTS idx_linear_issue_mappings_task
+    ON public.linear_issue_mappings(task_id)
+    WHERE task_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_linear_issue_mappings_run
+    ON public.linear_issue_mappings(team_run_id)
+    WHERE team_run_id IS NOT NULL;
+
+-- ────────────────────────────────────────────────────────────────────────────
+-- 3. RLS
+-- ────────────────────────────────────────────────────────────────────────────
+
+ALTER TABLE public.linear_issue_mappings ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "linear_issue_mappings_workspace_access"
+    ON public.linear_issue_mappings FOR ALL
+    USING (workspace_id IN (
+        SELECT id FROM public.workspaces WHERE owner_id = auth.uid()
+    ))
+    WITH CHECK (workspace_id IN (
+        SELECT id FROM public.workspaces WHERE owner_id = auth.uid()
+    ));
+
+-- Service role can read/write (for Edge Functions + task runner)
+CREATE POLICY "linear_issue_mappings_service_role"
+    ON public.linear_issue_mappings FOR ALL
+    USING (auth.role() = 'service_role')
+    WITH CHECK (auth.role() = 'service_role');
diff --git a/task-runner/src/webhookDispatcher.ts b/task-runner/src/webhookDispatcher.ts
index cb8358f3..f9a07c57 100644
--- a/task-runner/src/webhookDispatcher.ts
+++ b/task-runner/src/webhookDispatcher.ts
@@ -1999,7 +1999,7 @@ function sleep(ms: number): Promise<void> {
 // ─── Source Channel Reply ───────────────────────────────────────────────────
 
 interface SourceChannel {
-    platform: 'telegram' | 'discord' | 'slack' | 'email' | 'trello';
+    platform: 'telegram' | 'discord' | 'slack' | 'email' | 'trello' | 'linear';
     bot_token?: string;
     chat_id?: string;
     message_id?: string;
@@ -2014,6 +2014,10 @@ interface SourceChannel {
     trello_api_key?: string;
     trello_token?: string;
     trello_review_list_id?: string;
+    // Linear-specific
+    linear_issue_id?: string;
+    linear_api_key?: string;
+    linear_done_state_name?: string;
 }
 
 /**
@@ -2066,6 +2070,9 @@ export async function replyToSourceChannel(
                 case 'trello':
                     delivered = await replyTrello(sc, emoji, row.title, content);
                     break;
+                case 'linear':
+                    delivered = await replyLinear(sc, emoji, row.title, content);
+                    break;
                 default:
                     return;
             }
@@ -2263,6 +2270,117 @@ async function replyTrello(sc: SourceChannel, emoji: string, title: string, cont
     return resp.ok;
 }
 
+async function replyLinear(sc: SourceChannel, emoji: string, title: string, content: string): Promise<boolean> {
+    if (!sc.linear_api_key || !sc.linear_issue_id) return false;
+
+    const truncated = content.length > 10000
+        ? `${content.substring(0, 10000)}\n\n... truncated (${content.length} chars)`
+        : content;
+
+    const commentBody = `${emoji} **${title}**\n\n${truncated}`;
+
+    // Post comment on the issue
+    const commentMutation = `
+        mutation CommentCreate($input: CommentCreateInput!) {
+            commentCreate(input: $input) {
+                success
+                comment { id }
+            }
+        }
+    `;
+
+    const commentResp = await fetch('https://api.linear.app/graphql', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: sc.linear_api_key,
+        },
+        body: JSON.stringify({
+            query: commentMutation,
+            variables: {
+                input: {
+                    issueId: sc.linear_issue_id,
+                    body: commentBody,
+                },
+            },
+        }),
+        signal: AbortSignal.timeout(10000),
+    });
+
+    const commentResult = await commentResp.json();
+    const commentSuccess = commentResult.data?.commentCreate?.success === true;
+
+    if (!commentSuccess) {
+        const errors = commentResult.errors?.map((e: { message: string }) => e.message).join(', ') ?? 'unknown error';
+        console.error(`[Linear] Failed to post comment: ${errors}`);
+        return false;
+    }
+
+    // Optionally move issue to done state
+    if (sc.linear_done_state_name) {
+        try {
+            // Fetch the issue's team to find the target state
+            const stateQuery = `
+                query IssueTeamStates($issueId: String!) {
+                    issue(id: $issueId) {
+                        team {
+                            states { nodes { id name type } }
+                        }
+                    }
+                }
+            `;
+
+            const stateResp = await fetch('https://api.linear.app/graphql', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: sc.linear_api_key,
+                },
+                body: JSON.stringify({ query: stateQuery, variables: { issueId: sc.linear_issue_id } }),
+                signal: AbortSignal.timeout(10000),
+            });
+
+            const stateResult = await stateResp.json();
+            const states = stateResult.data?.issue?.team?.states?.nodes ?? [];
+            const targetState = states.find(
+                (s: { id: string; name: string }) => s.name.toLowerCase() === sc.linear_done_state_name!.toLowerCase(),
+            );
+
+            if (targetState) {
+                const updateMutation = `
+                    mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+                        issueUpdate(id: $id, input: $input) { success }
+                    }
+                `;
+
+                await fetch('https://api.linear.app/graphql', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        Authorization: sc.linear_api_key,
+                    },
+                    body: JSON.stringify({
+                        query: updateMutation,
+                        variables: {
+                            id: sc.linear_issue_id,
+                            input: { stateId: targetState.id },
+                        },
+                    }),
+                    signal: AbortSignal.timeout(10000),
+                });
+
+                console.log(`[Linear] Moved issue ${sc.linear_issue_id} to state "${sc.linear_done_state_name}"`);
+            } else {
+                console.warn(`[Linear] Done state "${sc.linear_done_state_name}" not found for issue ${sc.linear_issue_id}`);
+            }
+        } catch (err: unknown) {
+            console.warn('[Linear] Failed to update issue state:', err instanceof Error ? err.message : String(err));
+        }
+    }
+
+    return true;
+}
+
 function escapeHtml(text: string): string {
     return text
         .replace(/&/g, '&amp;')