@calltelemetry/openclaw-linear 0.3.1 → 0.4.1

package/src/webhook.ts

@@ -3,7 +3,11 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { LinearAgentApi, resolveLinearToken } from "./linear-api.js";
-import { runFullPipeline, resumePipeline, type PipelineContext } from "./pipeline.js";
+import { runFullPipeline, type PipelineContext } from "./pipeline.js";
+import { setActiveSession, clearActiveSession } from "./active-session.js";
+import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchStatus, completeDispatch, removeActiveDispatch } from "./dispatch-state.js";
+import { assessTier } from "./tier-assess.js";
+import { createWorktree, prepareWorkspace } from "./codex-worktree.js";
 
 // ── Agent profiles (loaded from config, no hardcoded names) ───────
 interface AgentProfile {
@@ -49,8 +53,8 @@ function resolveAgentFromAlias(alias: string, profiles: Record<string, AgentProf
   return null;
 }
 
-// Store active session plans so we can resume after user approval
-const activeSessions = new Map<string, { plan: string; ctx: PipelineContext }>();
+// Track issues with active agent runs to prevent concurrent duplicate runs.
+const activeRuns = new Set<string>();
 
 // Dedup: track recently processed keys to avoid double-handling
 const recentlyProcessed = new Map<string, number>();
@@ -212,6 +216,13 @@ export async function handleLinearWebhook(
         agentSessionId = sessionResult.sessionId;
         if (agentSessionId) {
           api.logger.info(`Created agent session ${agentSessionId} for notification`);
+          setActiveSession({
+            agentSessionId,
+            issueIdentifier: enrichedIssue?.identifier ?? issue.id,
+            issueId: issue.id,
+            agentId,
+            startedAt: Date.now(),
+          });
         } else {
           api.logger.warn(`Could not create agent session for notification: ${sessionResult.error ?? "unknown"}`);
         }
@@ -220,20 +231,11 @@ export async function handleLinearWebhook(
         if (agentSessionId) {
           await linearApi.emitActivity(agentSessionId, {
             type: "thought",
-            body: `Reviewing notification for ${enrichedIssue?.identifier ?? issue.id}...`,
+            body: `Reviewing ${enrichedIssue?.identifier ?? issue.id}...`,
           }).catch(() => {});
         }
 
-        // 3. Emit action
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "action",
-            action: "Processing notification",
-            parameter: notifType ?? "unknown",
-          }).catch(() => {});
-        }
-
-        // 4. Run agent
+        // 3. Run agent with streaming
         const sessionId = `linear-notif-${notification?.type ?? "unknown"}-${Date.now()}`;
         const { runAgent } = await import("./agent.js");
         const result = await runAgent({
@@ -242,6 +244,7 @@ export async function handleLinearWebhook(
           sessionId,
           message,
           timeoutMs: 3 * 60_000,
+          streaming: agentSessionId ? { linearApi, agentSessionId } : undefined,
         });
 
         const responseBody = result.success
@@ -284,13 +287,18 @@ export async function handleLinearWebhook(
             body: `Failed to process notification: ${String(err).slice(0, 500)}`,
           }).catch(() => {});
         }
+      } finally {
+        clearActiveSession(issue.id);
       }
     })();
 
     return true;
   }
 
-  // ── AgentSessionEvent.created — start the pipeline ──────────────
+  // ── AgentSessionEvent.created — direct agent run ─────────────────
+  // User chatted with @ctclaw in Linear's agent session. Run the agent
+  // DIRECTLY with the user's message. The plan→implement→audit pipeline
+  // is only triggered from Issue.update delegation, not from chat.
   if (
     (payload.type === "AgentSessionEvent" && payload.action === "created") ||
     (payload.type === "AgentSession" && payload.action === "create")
@@ -307,7 +315,7 @@ export async function handleLinearWebhook(
       return true;
     }
 
-    // Dedup: skip if we already handled this session (e.g. from Issue.update delegation)
+    // Dedup: skip if we already handled this session
     if (wasRecentlyProcessed(`session:${session.id}`)) {
       api.logger.info(`AgentSession ${session.id} already handled — skipping`);
       return true;
@@ -315,47 +323,147 @@ export async function handleLinearWebhook(
 
     const linearApi = createLinearApi(api);
     if (!linearApi) {
-      api.logger.error("No Linear access token configured — cannot start pipeline. Run OAuth flow or set LINEAR_ACCESS_TOKEN.");
+      api.logger.error("No Linear access token configured");
       return true;
     }
 
     const agentId = resolveAgentId(api);
-
     const previousComments = payload.previousComments ?? [];
     const guidance = payload.guidance;
 
     api.logger.info(`AgentSession created: ${session.id} for issue ${issue?.identifier ?? issue?.id} (comments: ${previousComments.length}, guidance: ${guidance ? "yes" : "no"})`);
 
-    const ctx: PipelineContext = {
-      api,
-      linearApi,
-      agentSessionId: session.id,
-      agentId,
-      issue: {
-        id: issue.id,
-        identifier: issue.identifier ?? issue.id,
-        title: issue.title ?? "(untitled)",
-        description: issue.description,
-      },
-      promptContext: payload.promptContext ?? session.context,
-    };
-
-    // Run pipeline (non-blocking). Stage 1 emits first thought within 10s.
+    // Guard: skip if an agent run is already active for this issue
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`Agent already running for ${issue?.identifier ?? issue?.id} — skipping session ${session.id}`);
+      return true;
+    }
+
+    // Extract the user's latest message from previousComments
+    // The last comment is the most recent user message
+    const lastComment = previousComments.length > 0
+      ? previousComments[previousComments.length - 1]
+      : null;
+    const userMessage = lastComment?.body ?? guidance ?? "";
+
+    // Fetch full issue details
+    let enrichedIssue: any = issue;
+    try {
+      enrichedIssue = await linearApi.getIssueDetails(issue.id);
+    } catch (err) {
+      api.logger.warn(`Could not fetch issue details: ${err}`);
+    }
+
+    const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
+
+    // Build conversation context from previous comments
+    const commentContext = previousComments
+      .slice(-5)
+      .map((c: any) => `**${c.user?.name ?? c.actorName ?? "User"}**: ${(c.body ?? "").slice(0, 300)}`)
+      .join("\n\n");
+
+    const message = [
+      `You are an AI agent responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
+      `You have access to tools including \`code_run\` for coding tasks, \`spawn_agent\`/\`ask_agent\` for delegation, and standard tools (exec, read, edit, write, web_search, etc.). To manage Linear issues (update status, close, assign, comment, etc.) use the \`linearis\` CLI via exec — e.g. \`linearis issues update API-123 --status done\` to close an issue, \`linearis issues update API-123 --status "In Progress"\` to change status, \`linearis issues list\` to list issues. Run \`linearis usage\` for full command reference.`,
+      ``,
+      `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+      `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
+      ``,
+      `**Description:**`,
+      description,
+      commentContext ? `\n**Conversation:**\n${commentContext}` : "",
+      userMessage ? `\n**Latest message:**\n> ${userMessage}` : "",
+      ``,
+      `Respond to the user's request. If they ask you to write code or make changes, use the \`code_run\` tool. Be concise and action-oriented.`,
+    ].filter(Boolean).join("\n");
+
+    // Run agent directly (non-blocking)
+    activeRuns.add(issue.id);
     void (async () => {
-      const { runPlannerStage } = await import("./pipeline.js");
-      const plan = await runPlannerStage(ctx).catch((err) => {
-        api.logger.error(`Planner stage error: ${err}`);
-        return null;
+      const profiles = loadAgentProfiles();
+      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
+      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
+
+      // Register active session for tool resolution (code_run, etc.)
+      setActiveSession({
+        agentSessionId: session.id,
+        issueIdentifier: enrichedIssue?.identifier ?? issue.identifier ?? issue.id,
+        issueId: issue.id,
+        agentId,
+        startedAt: Date.now(),
       });
-      if (plan) {
-        activeSessions.set(session.id, { plan, ctx });
+
+      try {
+        // Emit initial thought
+        await linearApi.emitActivity(session.id, {
+          type: "thought",
+          body: `Processing request for ${enrichedIssue?.identifier ?? issue.id}...`,
+        }).catch(() => {});
+
+        // Run agent with streaming to Linear
+        const sessionId = `linear-session-${session.id}`;
+        const { runAgent } = await import("./agent.js");
+        const result = await runAgent({
+          api,
+          agentId,
+          sessionId,
+          message,
+          timeoutMs: 5 * 60_000,
+          streaming: {
+            linearApi,
+            agentSessionId: session.id,
+          },
+        });
+
+        const responseBody = result.success
+          ? result.output
+          : `I encountered an error processing this request. Please try again.`;
+
+        // Post as comment
+        const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+        const brandingOpts = avatarUrl
+          ? { createAsUser: label, displayIconUrl: avatarUrl }
+          : undefined;
+
+        try {
+          if (brandingOpts) {
+            await linearApi.createComment(issue.id, responseBody, brandingOpts);
+          } else {
+            await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
+          }
+        } catch (brandErr) {
+          api.logger.warn(`Branded comment failed: ${brandErr}`);
+          await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
+        }
+
+        // Emit response (closes session)
+        const truncated = responseBody.length > 2000
+          ? responseBody.slice(0, 2000) + "\u2026"
+          : responseBody;
+        await linearApi.emitActivity(session.id, {
+          type: "response",
+          body: truncated,
+        }).catch(() => {});
+
+        api.logger.info(`Posted agent response to ${enrichedIssue?.identifier ?? issue.id} (session ${session.id})`);
+      } catch (err) {
+        api.logger.error(`AgentSession handler error: ${err}`);
+        await linearApi.emitActivity(session.id, {
+          type: "error",
+          body: `Failed: ${String(err).slice(0, 500)}`,
+        }).catch(() => {});
+      } finally {
+        clearActiveSession(issue.id);
+        activeRuns.delete(issue.id);
       }
     })();
 
     return true;
   }
 
-  // ── AgentSession.prompted — user replied (plan approval) ────────
+  // ── AgentSession.prompted — follow-up user messages in existing sessions
+  // Also fires when we emit activities (feedback loop). Use activeRuns guard
+  // and webhookId dedup to distinguish user follow-ups from our own emissions.
   if (
     (payload.type === "AgentSessionEvent" && payload.action === "prompted") ||
     (payload.type === "AgentSession" && payload.action === "prompted")
@@ -364,55 +472,160 @@ export async function handleLinearWebhook(
     res.end("ok");
 
     const session = payload.agentSession ?? payload.data;
-    if (!session?.id) {
-      api.logger.error("AgentSession.prompted missing session id");
+    const issue = session?.issue ?? payload.issue;
+    const activity = payload.agentActivity;
+
+    if (!session?.id || !issue?.id) {
+      api.logger.info(`AgentSession prompted: missing session or issue — ignoring`);
       return true;
     }
 
-    api.logger.info(`AgentSession prompted: ${session.id}`);
+    // If an agent run is already active for this issue, this is feedback from
+    // our own activity emissions — ignore to prevent loops.
+    if (activeRuns.has(issue.id)) {
+      api.logger.info(`AgentSession prompted: ${session.id} issue=${issue?.identifier ?? issue?.id} — agent active, ignoring (feedback)`);
+      return true;
+    }
 
-    const stored = activeSessions.get(session.id);
-    if (!stored) {
-      api.logger.warn(`No active session found for ${session.id} — may have been restarted`);
+    // Dedup by webhookId
+    const webhookId = payload.webhookId;
+    if (webhookId && wasRecentlyProcessed(`webhook:${webhookId}`)) {
+      api.logger.info(`AgentSession prompted: webhook ${webhookId} already processed — skipping`);
+      return true;
+    }
 
-      // Try to reconstruct context from payload
-      const linearApi = createLinearApi(api);
-      const issue = session?.issue ?? payload.issue;
-      if (!linearApi || !issue?.id) {
-        api.logger.error("Cannot reconstruct pipeline context for prompted session");
-        return true;
-      }
+    // Extract user message from the activity or prompt context
+    const promptContext = payload.promptContext;
+    const userMessage =
+      activity?.content?.body ??
+      activity?.body ??
+      promptContext?.message ??
+      promptContext ??
+      "";
+
+    if (!userMessage || typeof userMessage !== "string" || userMessage.trim().length === 0) {
+      api.logger.info(`AgentSession prompted: ${session.id} — no user message found, ignoring`);
+      return true;
+    }
 
-      const agentId = resolveAgentId(api);
+    const linearApi = createLinearApi(api);
+    if (!linearApi) {
+      api.logger.error("No Linear access token configured");
+      return true;
+    }
+
+    api.logger.info(`AgentSession prompted (follow-up): ${session.id} issue=${issue?.identifier ?? issue?.id} message="${userMessage.slice(0, 80)}..."`);
+
+    const agentId = resolveAgentId(api);
+
+    // Run agent for follow-up (non-blocking)
+    activeRuns.add(issue.id);
+    void (async () => {
+      const profiles = loadAgentProfiles();
+      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
+      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
 
-      // The user's reply is the prompt content — treat as approval with context
-      const userReply = session.context?.prompt ?? session.context?.body ?? "";
-      api.logger.info(`Prompted session ${session.id} — treating reply as new request`);
+      // Fetch full issue details for context
+      let enrichedIssue: any = issue;
+      try {
+        enrichedIssue = await linearApi.getIssueDetails(issue.id);
+      } catch (err) {
+        api.logger.warn(`Could not fetch issue details: ${err}`);
+      }
 
-      const ctx: PipelineContext = {
-        api,
-        linearApi,
+      const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
+
+      // Build context from recent comments
+      const recentComments = enrichedIssue?.comments?.nodes ?? [];
+      const commentContext = recentComments
+        .slice(-5)
+        .map((c: any) => `**${c.user?.name ?? "User"}**: ${(c.body ?? "").slice(0, 300)}`)
+        .join("\n\n");
+
+      const message = [
+        `You are an AI agent responding in a Linear issue session. Your text output will be posted as activities visible to the user.`,
+        `You have access to tools including \`code_run\` for coding tasks, \`spawn_agent\`/\`ask_agent\` for delegation, and standard tools (exec, read, edit, write, web_search, etc.). To manage Linear issues (update status, close, assign, comment, etc.) use the \`linearis\` CLI via exec — e.g. \`linearis issues update API-123 --status done\` to close an issue, \`linearis issues update API-123 --status "In Progress"\` to change status, \`linearis issues list\` to list issues. Run \`linearis usage\` for full command reference.`,
+        ``,
+        `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
+        `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Assignee:** ${enrichedIssue?.assignee?.name ?? "Unassigned"}`,
+        ``,
+        `**Description:**`,
+        description,
+        commentContext ? `\n**Recent conversation:**\n${commentContext}` : "",
+        `\n**User's follow-up message:**\n> ${userMessage}`,
+        ``,
+        `Respond to the user's follow-up. Be concise and action-oriented.`,
+      ].filter(Boolean).join("\n");
+
+      setActiveSession({
         agentSessionId: session.id,
+        issueIdentifier: enrichedIssue?.identifier ?? issue.identifier ?? issue.id,
+        issueId: issue.id,
         agentId,
-        issue: {
-          id: issue.id,
-          identifier: issue.identifier ?? issue.id,
-          title: issue.title ?? "(untitled)",
-          description: issue.description,
-        },
-        promptContext: session.context,
-      };
-
-      // Start fresh pipeline since we lost the plan
-      void runFullPipeline(ctx);
-      return true;
-    }
+        startedAt: Date.now(),
+      });
+
+      try {
+        await linearApi.emitActivity(session.id, {
+          type: "thought",
+          body: `Processing follow-up for ${enrichedIssue?.identifier ?? issue.id}...`,
+        }).catch(() => {});
+
+        const sessionId = `linear-session-${session.id}`;
+        const { runAgent } = await import("./agent.js");
+        const result = await runAgent({
+          api,
+          agentId,
+          sessionId,
+          message,
+          timeoutMs: 5 * 60_000,
+          streaming: {
+            linearApi,
+            agentSessionId: session.id,
+          },
+        });
+
+        const responseBody = result.success
+          ? result.output
+          : `I encountered an error processing this request. Please try again.`;
 
-    // Resume with stored plan
-    api.logger.info(`Resuming pipeline for session ${session.id}`);
-    activeSessions.delete(session.id);
+        const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
+        const brandingOpts = avatarUrl
+          ? { createAsUser: label, displayIconUrl: avatarUrl }
+          : undefined;
+
+        try {
+          if (brandingOpts) {
+            await linearApi.createComment(issue.id, responseBody, brandingOpts);
+          } else {
+            await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
+          }
+        } catch (brandErr) {
+          api.logger.warn(`Branded comment failed: ${brandErr}`);
+          await linearApi.createComment(issue.id, `**[${label}]** ${responseBody}`);
+        }
+
+        const truncated = responseBody.length > 2000
+          ? responseBody.slice(0, 2000) + "\u2026"
+          : responseBody;
+        await linearApi.emitActivity(session.id, {
+          type: "response",
+          body: truncated,
+        }).catch(() => {});
+
+        api.logger.info(`Posted follow-up response to ${enrichedIssue?.identifier ?? issue.id} (session ${session.id})`);
+      } catch (err) {
+        api.logger.error(`AgentSession prompted handler error: ${err}`);
+        await linearApi.emitActivity(session.id, {
+          type: "error",
+          body: `Failed: ${String(err).slice(0, 500)}`,
+        }).catch(() => {});
+      } finally {
+        clearActiveSession(issue.id);
+        activeRuns.delete(issue.id);
+      }
+    })();
 
-    void resumePipeline(stored.ctx, stored.plan);
     return true;
   }
 
@@ -526,6 +739,14 @@ export async function handleLinearWebhook(
         agentSessionId = sessionResult.sessionId;
         if (agentSessionId) {
           api.logger.info(`Created agent session ${agentSessionId} for @${mentionedAgent}`);
+          // Register active session so code_run can resolve it automatically
+          setActiveSession({
+            agentSessionId,
+            issueIdentifier: enrichedIssue.identifier ?? issue.id,
+            issueId: issue.id,
+            agentId: mentionedAgent,
+            startedAt: Date.now(),
+          });
         } else {
           api.logger.warn(`Could not create agent session for @${mentionedAgent}: ${sessionResult.error ?? "unknown"} — falling back to flat comment`);
         }
@@ -534,20 +755,11 @@ export async function handleLinearWebhook(
         if (agentSessionId) {
           await linearApi.emitActivity(agentSessionId, {
             type: "thought",
-            body: `Analyzing ${enrichedIssue.identifier ?? issue.id}...`,
-          }).catch(() => {});
-        }
-
-        // 3. Emit action
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "action",
-            action: "Processing mention",
-            parameter: `@${alias} by ${commentor}`,
+            body: `Reviewing ${enrichedIssue.identifier ?? issue.id}...`,
           }).catch(() => {});
         }
 
-        // 4. Run agent subprocess
+        // 3. Run agent subprocess with streaming
         const sessionId = `linear-comment-${comment.id ?? Date.now()}`;
         const { runAgent } = await import("./agent.js");
         const result = await runAgent({
@@ -556,6 +768,7 @@ export async function handleLinearWebhook(
           sessionId,
           message: taskMessage,
           timeoutMs: 3 * 60_000,
+          streaming: agentSessionId ? { linearApi, agentSessionId } : undefined,
         });
 
         const responseBody = result.success
@@ -592,13 +805,14 @@ export async function handleLinearWebhook(
         api.logger.info(`Posted @${mentionedAgent} response to ${issue.identifier ?? issue.id}`);
       } catch (err) {
         api.logger.error(`Comment mention handler error: ${err}`);
-        // 7. Emit error activity if session exists
         if (agentSessionId) {
           await linearApi.emitActivity(agentSessionId, {
             type: "error",
             body: `Failed to process mention: ${String(err).slice(0, 500)}`,
           }).catch(() => {});
         }
+      } finally {
+        clearActiveSession(issue.id);
       }
     })();
 
@@ -646,7 +860,7 @@ export async function handleLinearWebhook(
     }
 
     const trigger = isDelegatedToUs ? "delegated" : "assigned";
-    api.logger.info(`Issue ${trigger} to our app user (${viewerId}), processing`);
+    api.logger.info(`Issue ${trigger} to our app user (${viewerId}), executing pipeline`);
 
     // Dedup on assignment/delegation
     const dedupKey = `${trigger}:${issue.id}:${viewerId}`;
@@ -655,191 +869,11 @@ export async function handleLinearWebhook(
       return true;
     }
 
-    const agentId = resolveAgentId(api);
-
-    // Fetch full issue details + team labels for triage
-    let enrichedIssue: any = issue;
-    let teamLabels: Array<{ id: string; name: string }> = [];
-    try {
-      enrichedIssue = await linearApi.getIssueDetails(issue.id);
-      if (enrichedIssue?.team?.id) {
-        teamLabels = await linearApi.getTeamLabels(enrichedIssue.team.id);
-      }
-    } catch (err) {
-      api.logger.warn(`Could not fetch issue details: ${err}`);
-    }
-
-    const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
-    const comments = enrichedIssue?.comments?.nodes ?? [];
-    const commentSummary = comments
-      .slice(-5)
-      .map((c: any) => `  - **${c.user?.name ?? "Unknown"}**: ${c.body?.slice(0, 200)}`)
-      .join("\n");
-
-    const estimationType = enrichedIssue?.team?.issueEstimationType ?? "fibonacci";
-    const currentLabels = enrichedIssue?.labels?.nodes ?? [];
-    const currentLabelNames = currentLabels.map((l: any) => l.name).join(", ") || "None";
-    const availableLabelList = teamLabels.map((l) => `  - "${l.name}" (id: ${l.id})`).join("\n");
-
-    const message = [
-      `IMPORTANT: You are triaging a delegated Linear issue. You MUST respond with a JSON block containing your triage decisions, followed by your assessment as plain text.`,
-      ``,
-      `## Issue: ${enrichedIssue?.identifier ?? issue.identifier ?? issue.id} — ${enrichedIssue?.title ?? issue.title ?? "(untitled)"}`,
-      `**Status:** ${enrichedIssue?.state?.name ?? "Unknown"} | **Current Estimate:** ${enrichedIssue?.estimate ?? "None"} | **Current Labels:** ${currentLabelNames}`,
-      ``,
-      `**Description:**`,
-      description,
-      commentSummary ? `\n**Recent comments:**\n${commentSummary}` : "",
-      ``,
-      `## Your Triage Tasks`,
-      ``,
-      `1. **Story Points** — Estimate complexity using ${estimationType} scale (1=trivial, 2=small, 3=medium, 5=large, 8=very large, 13=epic)`,
-      `2. **Labels** — Select appropriate labels from the team's available labels`,
-      `3. **Assessment** — Brief analysis of what this issue needs`,
-      ``,
-      `## Available Labels`,
-      availableLabelList || "  (no labels configured)",
-      ``,
-      `## Response Format`,
-      ``,
-      `You MUST start your response with a JSON block, then follow with your assessment:`,
-      ``,
-      '```json',
-      `{`,
-      `  "estimate": <number>,`,
-      `  "labelIds": ["<id1>", "<id2>"],`,
-      `  "assessment": "<one-line summary of your sizing rationale>"`,
-      `}`,
-      '```',
-      ``,
-      `Then write your full assessment as markdown below the JSON block.`,
-    ].filter(Boolean).join("\n");
-
-    // Dispatch agent with session lifecycle (non-blocking)
-    void (async () => {
-      const profiles = loadAgentProfiles();
-      const defaultProfile = Object.entries(profiles).find(([, p]) => p.isDefault);
-      const label = defaultProfile?.[1]?.label ?? profiles[agentId]?.label ?? agentId;
-      const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
-      let agentSessionId: string | null = null;
-
-      try {
-        const sessionResult = await linearApi.createSessionOnIssue(issue.id);
-        agentSessionId = sessionResult.sessionId;
-        if (agentSessionId) {
-          // Mark session as processed so AgentSessionEvent handler skips it
-          wasRecentlyProcessed(`session:${agentSessionId}`);
-          api.logger.info(`Created agent session ${agentSessionId} for ${trigger}`);
-        } else {
-          api.logger.warn(`Could not create agent session for assignment: ${sessionResult.error ?? "unknown"}`);
-        }
-
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "thought",
-            body: `Reviewing assigned issue ${enrichedIssue?.identifier ?? issue.id}...`,
-          }).catch(() => {});
-        }
-
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "action",
-            action: "Triaging",
-            parameter: `${enrichedIssue?.identifier ?? issue.id} — estimating, labeling, sizing`,
-          }).catch(() => {});
-        }
-
-        const sessionId = `linear-assign-${issue.id}-${Date.now()}`;
-        const { runAgent } = await import("./agent.js");
-        const result = await runAgent({
-          api,
-          agentId,
-          sessionId,
-          message,
-          timeoutMs: 3 * 60_000,
-        });
-
-        const responseBody = result.success
-          ? result.output
-          : `I encountered an error reviewing this assignment. Please try again.`;
-
-        // Parse triage JSON from agent response and apply to issue
-        let commentBody = responseBody;
-        if (result.success) {
-          const jsonMatch = responseBody.match(/```json\s*\n?([\s\S]*?)\n?```/);
-          if (jsonMatch) {
-            try {
-              const triage = JSON.parse(jsonMatch[1]);
-              const updateInput: Record<string, unknown> = {};
-
-              if (typeof triage.estimate === "number") {
-                updateInput.estimate = triage.estimate;
-              }
-              if (Array.isArray(triage.labelIds) && triage.labelIds.length > 0) {
-                // Merge with existing labels
-                const existingIds = currentLabels.map((l: any) => l.id);
-                const allIds = [...new Set([...existingIds, ...triage.labelIds])];
-                updateInput.labelIds = allIds;
-              }
-
-              if (Object.keys(updateInput).length > 0) {
-                await linearApi.updateIssue(issue.id, updateInput);
-                api.logger.info(`Applied triage to ${enrichedIssue?.identifier ?? issue.id}: ${JSON.stringify(updateInput)}`);
-
-                if (agentSessionId) {
-                  await linearApi.emitActivity(agentSessionId, {
-                    type: "action",
-                    action: "Applied triage",
-                    result: `estimate=${triage.estimate ?? "unchanged"}, labels=${triage.labelIds?.length ?? 0} added`,
-                  }).catch(() => {});
-                }
-              }
-
-              // Strip the JSON block from the comment — post only the assessment
-              commentBody = responseBody.replace(/```json\s*\n?[\s\S]*?\n?```\s*\n?/, "").trim();
-            } catch (parseErr) {
-              api.logger.warn(`Could not parse triage JSON: ${parseErr}`);
-            }
-          }
-        }
-
-        // Post comment with assessment
-        const brandingOpts = avatarUrl
-          ? { createAsUser: label, displayIconUrl: avatarUrl }
-          : undefined;
-
-        try {
-          if (brandingOpts) {
-            await linearApi.createComment(issue.id, commentBody, brandingOpts);
-          } else {
-            await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
-          }
-        } catch (brandErr) {
-          api.logger.warn(`Branded comment failed, falling back to prefix: ${brandErr}`);
-          await linearApi.createComment(issue.id, `**[${label}]** ${commentBody}`);
-        }
-
-        if (agentSessionId) {
-          const truncated = commentBody.length > 2000
-            ? commentBody.slice(0, 2000) + "…"
-            : commentBody;
-          await linearApi.emitActivity(agentSessionId, {
-            type: "response",
-            body: truncated,
-          }).catch(() => {});
-        }
-
-        api.logger.info(`Posted assignment response to ${enrichedIssue?.identifier ?? issue.id}`);
-      } catch (err) {
-        api.logger.error(`Issue assignment handler error: ${err}`);
-        if (agentSessionId) {
-          await linearApi.emitActivity(agentSessionId, {
-            type: "error",
-            body: `Failed to process assignment: ${String(err).slice(0, 500)}`,
-          }).catch(() => {});
-        }
-      }
-    })();
+    // Assignment triggers the full dispatch pipeline:
+    // tier assessment → worktree → plan → implement → audit
+    void handleDispatch(api, linearApi, issue).catch((err) => {
+      api.logger.error(`Dispatch pipeline error for ${issue.identifier ?? issue.id}: ${err}`);
+    });
 
     return true;
   }
@@ -904,6 +938,13 @@ export async function handleLinearWebhook(
         if (agentSessionId) {
           wasRecentlyProcessed(`session:${agentSessionId}`);
           api.logger.info(`Created agent session ${agentSessionId} for Issue.create triage`);
+          setActiveSession({
+            agentSessionId,
+            issueIdentifier: enrichedIssue?.identifier ?? issue.identifier ?? issue.id,
+            issueId: issue.id,
+            agentId,
+            startedAt: Date.now(),
+          });
         }
 
         if (agentSessionId) {
@@ -964,6 +1005,7 @@ export async function handleLinearWebhook(
           sessionId,
           message,
           timeoutMs: 3 * 60_000,
+          streaming: agentSessionId ? { linearApi, agentSessionId } : undefined,
         });
 
         const responseBody = result.success
@@ -1047,6 +1089,8 @@ export async function handleLinearWebhook(
             body: `Failed to triage: ${String(err).slice(0, 500)}`,
           }).catch(() => {});
         }
+      } finally {
+        clearActiveSession(issue.id);
       }
     })();
 
@@ -1059,3 +1103,216 @@ export async function handleLinearWebhook(
   res.end("ok");
   return true;
 }
+
+// ── @dispatch handler ─────────────────────────────────────────────
+//
+// Triggered by `@dispatch` in a Linear comment. Assesses issue complexity,
+// creates a persistent worktree, registers the dispatch in state, and
+// launches the pipeline (plan → implement → audit).
+
+async function handleDispatch(
+  api: OpenClawPluginApi,
+  linearApi: LinearAgentApi,
+  issue: any,
+): Promise<void> {
+  const pluginConfig = (api as any).pluginConfig as Record<string, unknown> | undefined;
+  const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+  const worktreeBaseDir = pluginConfig?.worktreeBaseDir as string | undefined;
+  const baseRepo = (pluginConfig?.codexBaseRepo as string) ?? "/home/claw/ai-workspace";
+  const identifier = issue.identifier ?? issue.id;
+
+  api.logger.info(`@dispatch: processing ${identifier}`);
+
+  // 1. Check for existing active dispatch — reclaim if stale
+  const STALE_DISPATCH_MS = 30 * 60_000; // 30 min without a gateway holding it = stale
+  const state = await readDispatchState(statePath);
+  const existing = getActiveDispatch(state, identifier);
+  if (existing) {
+    const ageMs = Date.now() - new Date(existing.dispatchedAt).getTime();
+    const isStale = ageMs > STALE_DISPATCH_MS;
+    const inMemory = activeRuns.has(issue.id);
+
+    if (!isStale && inMemory) {
+      // Truly still running in this gateway process
+      api.logger.info(`dispatch: ${identifier} actively running (status: ${existing.status}, age: ${Math.round(ageMs / 1000)}s) — skipping`);
+      await linearApi.createComment(
+        issue.id,
+        `Already running as **${existing.tier}** (status: ${existing.status}, started ${Math.round(ageMs / 60_000)}m ago). Worktree: \`${existing.worktreePath}\``,
+      );
+      return;
+    }
+
+    // Stale or not in memory (gateway restarted) — reclaim
+    api.logger.info(
+      `dispatch: ${identifier} reclaiming stale dispatch (status: ${existing.status}, ` +
+      `age: ${Math.round(ageMs / 1000)}s, inMemory: ${inMemory}, stale: ${isStale})`,
+    );
+    await removeActiveDispatch(identifier, statePath);
+    activeRuns.delete(issue.id);
+  }
+
+  // 2. Prevent concurrent runs on same issue
+  if (activeRuns.has(issue.id)) {
+    api.logger.info(`@dispatch: ${identifier} has active agent run — skipping`);
+    return;
+  }
+
+  // 3. Fetch full issue details for tier assessment
+  let enrichedIssue: any;
+  try {
+    enrichedIssue = await linearApi.getIssueDetails(issue.id);
+  } catch (err) {
+    api.logger.error(`@dispatch: failed to fetch issue details: ${err}`);
+    enrichedIssue = issue;
+  }
+
+  const labels = enrichedIssue.labels?.nodes?.map((l: any) => l.name) ?? [];
+  const commentCount = enrichedIssue.comments?.nodes?.length ?? 0;
+
+  // 4. Assess complexity tier
+  const assessment = await assessTier(api, {
+    identifier,
+    title: enrichedIssue.title ?? "(untitled)",
+    description: enrichedIssue.description,
+    labels,
+    commentCount,
+  });
+
+  api.logger.info(`@dispatch: ${identifier} assessed as ${assessment.tier} (${assessment.model}) — ${assessment.reasoning}`);
+
+  // 5. Create persistent worktree
+  let worktree;
+  try {
+    worktree = createWorktree(identifier, { baseRepo, baseDir: worktreeBaseDir });
+    api.logger.info(`@dispatch: worktree ${worktree.resumed ? "resumed" : "created"} at ${worktree.path}`);
+  } catch (err) {
+    api.logger.error(`@dispatch: worktree creation failed: ${err}`);
+    await linearApi.createComment(
+      issue.id,
+      `Dispatch failed — could not create worktree: ${String(err).slice(0, 200)}`,
+    );
+    return;
+  }
+
+  // 5b. Prepare workspace: pull latest from origin + init submodules
+  const prep = prepareWorkspace(worktree.path, worktree.branch);
+  if (prep.errors.length > 0) {
+    api.logger.warn(`@dispatch: workspace prep had errors: ${prep.errors.join("; ")}`);
+  } else {
+    api.logger.info(
+      `@dispatch: workspace prepared — pulled=${prep.pulled}, submodules=${prep.submodulesInitialized}`,
+    );
+  }
+
+  // 6. Create agent session on Linear
+  let agentSessionId: string | undefined;
+  try {
+    const sessionResult = await linearApi.createSessionOnIssue(issue.id);
+    agentSessionId = sessionResult.sessionId ?? undefined;
+  } catch (err) {
+    api.logger.warn(`@dispatch: could not create agent session: ${err}`);
+  }
+
+  // 7. Register dispatch in persistent state
+  const now = new Date().toISOString();
+  await registerDispatch(identifier, {
+    issueId: issue.id,
+    issueIdentifier: identifier,
+    worktreePath: worktree.path,
+    branch: worktree.branch,
+    tier: assessment.tier,
+    model: assessment.model,
+    status: "dispatched",
+    dispatchedAt: now,
+    agentSessionId,
+  }, statePath);
+
+  // 8. Register active session for tool resolution
+  setActiveSession({
+    agentSessionId: agentSessionId ?? "",
+    issueIdentifier: identifier,
+    issueId: issue.id,
+    agentId: resolveAgentId(api),
+    startedAt: Date.now(),
+  });
+
+  // 9. Post dispatch confirmation comment
+  const prepStatus = prep.errors.length > 0
+    ? `Workspace prep: partial (${prep.errors.join("; ")})`
+    : `Workspace prep: OK (pulled=${prep.pulled}, submodules=${prep.submodulesInitialized})`;
+  const statusComment = [
+    `**Dispatched** as **${assessment.tier}** (${assessment.model})`,
+    `> ${assessment.reasoning}`,
+    ``,
+    `Worktree: \`${worktree.path}\` ${worktree.resumed ? "(resumed)" : "(fresh)"}`,
+    `Branch: \`${worktree.branch}\``,
+    prepStatus,
+  ].join("\n");
+
+  await linearApi.createComment(issue.id, statusComment);
+
+  if (agentSessionId) {
+    await linearApi.emitActivity(agentSessionId, {
+      type: "thought",
+      body: `Dispatching ${identifier} as ${assessment.tier}...`,
+    }).catch(() => {});
+  }
+
+  // 10. Apply tier label (best effort)
+  try {
+    if (enrichedIssue.team?.id) {
+      const teamLabels = await linearApi.getTeamLabels(enrichedIssue.team.id);
+      const tierLabel = teamLabels.find((l: any) => l.name === `developer:${assessment.tier}`);
+      if (tierLabel) {
+        const currentLabelIds = enrichedIssue.labels?.nodes?.map((l: any) => l.id) ?? [];
+        await linearApi.updateIssue(issue.id, {
+          labelIds: [...currentLabelIds, tierLabel.id],
+        });
+      }
+    }
+  } catch (err) {
+    api.logger.warn(`@dispatch: could not apply tier label: ${err}`);
+  }
+
+  // 11. Run pipeline (non-blocking)
+  const agentId = resolveAgentId(api);
+  const pipelineCtx: PipelineContext = {
+    api,
+    linearApi,
+    agentSessionId: agentSessionId ?? `dispatch-${identifier}-${Date.now()}`,
+    agentId,
+    issue: {
+      id: issue.id,
+      identifier,
+      title: enrichedIssue.title ?? "(untitled)",
+      description: enrichedIssue.description,
+    },
+    worktreePath: worktree.path,
+    codexBranch: worktree.branch,
+    tier: assessment.tier,
+    model: assessment.model,
+  };
+
+  activeRuns.add(issue.id);
+
+  // Update status to running
+  await updateDispatchStatus(identifier, "running", statePath);
+
+  runFullPipeline(pipelineCtx)
+    .then(async () => {
+      await completeDispatch(identifier, {
+        tier: assessment.tier,
+        status: "done",
+        completedAt: new Date().toISOString(),
+      }, statePath);
+      api.logger.info(`@dispatch: pipeline completed for ${identifier}`);
+    })
+    .catch(async (err) => {
+      api.logger.error(`@dispatch: pipeline failed for ${identifier}: ${err}`);
+      await updateDispatchStatus(identifier, "failed", statePath);
+    })
+    .finally(() => {
+      activeRuns.delete(issue.id);
+      clearActiveSession(issue.id);
+    });
+}