@calltelemetry/openclaw-linear 0.7.1 → 0.8.0

package/src/pipeline/planner.test.ts

@@ -251,7 +251,7 @@ describe("handlePlannerTurn", () => {
 
     await handlePlannerTurn(ctx, session, {
       issueId: "issue-1",
-      commentBody: "abandon",
+      commentBody: "abandon planning",
       commentorName: "Tester",
     });
 

package/src/pipeline/planner.ts

@@ -6,11 +6,8 @@
  * - handlePlannerTurn: processes each user comment during planning
  * - runPlanAudit: validates the plan before finalizing
  */
-import { readFileSync } from "node:fs";
-import { join, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parse as parseYaml } from "yaml";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { loadRawPromptYaml } from "./pipeline.js";
 import type { LinearAgentApi } from "../api/linear-api.js";
 import { runAgent } from "../agent/agent.js";
 import {
@@ -56,30 +53,15 @@ function loadPlannerPrompts(pluginConfig?: Record<string, unknown>): PlannerProm
     welcome: "Entering planning mode for **{{projectName}}**. What are the main feature areas?",
   };
 
-  try {
-    const customPath = pluginConfig?.promptsPath as string | undefined;
-    let raw: string;
-
-    if (customPath) {
-      const resolved = customPath.startsWith("~")
-        ? customPath.replace("~", process.env.HOME ?? "")
-        : customPath;
-      raw = readFileSync(resolved, "utf-8");
-    } else {
-      const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "../..");
-      raw = readFileSync(join(pluginRoot, "prompts.yaml"), "utf-8");
-    }
-
-    const parsed = parseYaml(raw) as any;
-    if (parsed?.planner) {
-      return {
-        system: parsed.planner.system ?? defaults.system,
-        interview: parsed.planner.interview ?? defaults.interview,
-        audit_prompt: parsed.planner.audit_prompt ?? defaults.audit_prompt,
-        welcome: parsed.planner.welcome ?? defaults.welcome,
-      };
-    }
-  } catch { /* use defaults */ }
+  const parsed = loadRawPromptYaml(pluginConfig);
+  if (parsed?.planner) {
+    return {
+      system: parsed.planner.system ?? defaults.system,
+      interview: parsed.planner.interview ?? defaults.interview,
+      audit_prompt: parsed.planner.audit_prompt ?? defaults.audit_prompt,
+      welcome: parsed.planner.welcome ?? defaults.welcome,
+    };
+  }
 
   return defaults;
 }
@@ -142,8 +124,8 @@ export async function initiatePlanningSession(
 // Interview turn
 // ---------------------------------------------------------------------------
 
-const FINALIZE_PATTERN = /\b(finalize\s+plan|finalize|done\s+planning|approve\s+plan|plan\s+looks\s+good)\b/i;
-const ABANDON_PATTERN = /\b(abandon|cancel\s+planning|stop\s+planning|exit\s+planning)\b/i;
+const FINALIZE_PATTERN = /\b(finalize\s+(the\s+)?plan\b|done\s+planning\b(?!\s+\w)|approve\s+(the\s+)?plan\b|plan\s+looks\s+good\b|ready\s+to\s+finalize\b|let'?s\s+finalize\b)/i;
+const ABANDON_PATTERN = /\b(abandon\s+plan(ning)?|cancel\s+plan(ning)?|stop\s+planning|exit\s+planning|quit\s+planning)\b/i;
 
 export async function handlePlannerTurn(
   ctx: PlannerContext,

package/src/pipeline/tier-assess.test.ts

@@ -172,4 +172,93 @@ describe("assessTier", () => {
     expect(result.model).toBe(TIER_MODELS.junior);
     expect(result.reasoning).toBe("Config tweak");
   });
+
+  it("handles null description gracefully", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"junior","reasoning":"Trivial"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue({ description: null }));
+
+    expect(result.tier).toBe("junior");
+  });
+
+  it("handles empty labels and no comments", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"medior","reasoning":"Standard feature"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue({ labels: [], commentCount: undefined }));
+
+    expect(result.tier).toBe("medior");
+  });
+
+  it("falls back to medior on malformed JSON (half JSON)", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"seni',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("medior");
+    expect(result.reasoning).toBe("Assessment failed — defaulting to medior");
+  });
+
+  it("provides default reasoning when missing from response", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"senior"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("senior");
+    expect(result.reasoning).toBe("no reasoning provided");
+  });
+
+  it("extracts JSON from output with success=false but valid JSON", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: false,
+      output: 'Agent exited early but: {"tier":"junior","reasoning":"Simple fix"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    const result = await assessTier(api, makeIssue());
+
+    expect(result.tier).toBe("junior");
+    expect(result.reasoning).toBe("Simple fix");
+  });
+
+  it("defaults agentId from pluginConfig when not passed", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"medior","reasoning":"Normal"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "zoe" });
+    await assessTier(api, makeIssue());
+
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    expect(callArgs.agentId).toBe("zoe");
+  });
+
+  it("uses 30s timeout for assessment", async () => {
+    mockRunAgent.mockResolvedValue({
+      success: true,
+      output: '{"tier":"medior","reasoning":"Normal"}',
+    });
+
+    const api = makeApi({ defaultAgentId: "mal" });
+    await assessTier(api, makeIssue());
+
+    const callArgs = mockRunAgent.mock.calls[0][0];
+    expect(callArgs.timeoutMs).toBe(30_000);
+  });
 });

package/src/pipeline/webhook.ts

@@ -8,8 +8,9 @@ import { setActiveSession, clearActiveSession } from "./active-session.js";
 import { readDispatchState, getActiveDispatch, registerDispatch, updateDispatchStatus, completeDispatch, removeActiveDispatch } from "./dispatch-state.js";
 import { createNotifierFromConfig, type NotifyFn } from "../infra/notify.js";
 import { assessTier } from "./tier-assess.js";
-import { createWorktree, prepareWorkspace } from "../infra/codex-worktree.js";
-import { ensureClawDir, writeManifest } from "./artifacts.js";
+import { createWorktree, createMultiWorktree, prepareWorkspace } from "../infra/codex-worktree.js";
+import { resolveRepos, isMultiRepo } from "../infra/multi-repo.js";
+import { ensureClawDir, writeManifest, writeDispatchMemory, resolveOrchestratorWorkspace } from "./artifacts.js";
 import { readPlanningState, isInPlanningMode, getPlanningSession } from "./planning-state.js";
 import { initiatePlanningSession, handlePlannerTurn } from "./planner.js";
 import { startProjectDispatch } from "./dag-dispatch.js";
@@ -262,7 +263,7 @@ export async function handleLinearWebhook(
 
         const responseBody = result.success
           ? result.output
-          : `I encountered an error processing this request. Please try again.`;
+          : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
         // 5. Post branded comment (fallback to prefix)
         const brandingOpts = avatarUrl
@@ -438,7 +439,7 @@ export async function handleLinearWebhook(
 
         const responseBody = result.success
           ? result.output
-          : `I encountered an error processing this request. Please try again.`;
+          : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
         // Post as comment
         const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
@@ -616,7 +617,7 @@ export async function handleLinearWebhook(
 
         const responseBody = result.success
           ? result.output
-          : `I encountered an error processing this request. Please try again.`;
+          : `Something went wrong while processing this. The system will retry automatically if possible. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
         const avatarUrl = defaultProfile?.[1]?.avatarUrl ?? profiles[agentId]?.avatarUrl;
         const brandingOpts = avatarUrl
@@ -683,7 +684,7 @@ export async function handleLinearWebhook(
             const planState = await readPlanningState(planStatePath);
 
             // Check if this is a plan initiation request
-            const isPlanRequest = /\b(plan|planning)\s+(this\s+)?(project|out)\b/i.test(commentBody);
+            const isPlanRequest = /\b(plan|planning)\s+(this\s+)(project|out)\b/i.test(commentBody) || /\bplan\s+this\s+out\b/i.test(commentBody);
             if (isPlanRequest && !isInPlanningMode(planState, projectId)) {
               api.logger.info(`Planning: initiation requested on ${issue.identifier ?? issue.id}`);
               void initiatePlanningSession(
@@ -697,7 +698,15 @@ export async function handleLinearWebhook(
             // Route to planner if project is in planning mode
             if (isInPlanningMode(planState, projectId)) {
               const session = getPlanningSession(planState, projectId);
-              if (session && comment?.id && !wasRecentlyProcessed(`plan-comment:${comment.id}`)) {
+              if (!session) {
+                api.logger.error(`Planning: project ${projectId} in planning mode but no session found — state may be corrupted`);
+                await linearApiForPlanning.createComment(
+                  issue.id,
+                  `**Planning mode is active** for this project, but the session state appears corrupted.\n\n**To fix:** Say **"abandon planning"** to exit planning mode, then start fresh with **"plan this project"**.`,
+                ).catch(() => {});
+                return true;
+              }
+              if (comment?.id && !wasRecentlyProcessed(`plan-comment:${comment.id}`)) {
                 api.logger.info(`Planning: routing comment to planner for ${session.projectName}`);
                 void handlePlannerTurn(
                   { api, linearApi: linearApiForPlanning, pluginConfig },
@@ -705,7 +714,7 @@ export async function handleLinearWebhook(
                   { issueId: issue.id, commentBody, commentorName: commentor },
                   {
                     onApproved: (approvedProjectId) => {
-                      const notify = createNotifierFromConfig(pluginConfig, api.runtime);
+                      const notify = createNotifierFromConfig(pluginConfig, api.runtime, api);
                       const hookCtx: HookContext = {
                         api,
                         linearApi: linearApiForPlanning,
@@ -875,7 +884,7 @@ export async function handleLinearWebhook(
 
         const responseBody = result.success
           ? result.output
-          : `I encountered an error processing this request. Please try again or check the logs.`;
+          : `Something went wrong while processing this. If this keeps happening, run \`openclaw openclaw-linear doctor\` to check for issues.`;
 
         // 5. Post branded comment (fall back to [Label] prefix if branding fails)
         const brandingOpts = profile?.avatarUrl
@@ -1029,6 +1038,27 @@ export async function handleLinearWebhook(
           api.logger.warn(`Could not fetch issue details for triage: ${err}`);
         }
 
+        // Skip triage for issues in projects that are actively being planned —
+        // the planner creates issues and triage would overwrite its estimates/labels.
+        const triageProjectId = enrichedIssue?.project?.id;
+        if (triageProjectId) {
+          const planStatePath = pluginConfig?.planningStatePath as string | undefined;
+          try {
+            const planState = await readPlanningState(planStatePath);
+            if (isInPlanningMode(planState, triageProjectId)) {
+              api.logger.info(`Issue.create: ${issue.identifier ?? issue.id} belongs to project in planning mode — skipping triage`);
+              return;
+            }
+          } catch { /* proceed with triage if planning state check fails */ }
+        }
+
+        // Skip triage for issues created by our own bot user
+        const viewerId = await linearApi.getViewerId();
+        if (viewerId && issue.creatorId === viewerId) {
+          api.logger.info(`Issue.create: ${issue.identifier ?? issue.id} created by our bot — skipping triage`);
+          return;
+        }
+
         const description = enrichedIssue?.description ?? issue?.description ?? "(no description)";
         const estimationType = enrichedIssue?.team?.issueEstimationType ?? "fibonacci";
         const currentLabels = enrichedIssue?.labels?.nodes ?? [];
@@ -1113,7 +1143,7 @@ export async function handleLinearWebhook(
 
         const responseBody = result.success
           ? result.output
-          : `I encountered an error triaging this issue. Please triage manually.`;
+          : `Something went wrong while triaging this issue. You may need to set the estimate and labels manually.`;
 
         // Parse triage JSON and apply to issue
         let commentBody = responseBody;
@@ -1237,7 +1267,7 @@ async function handleDispatch(
         api.logger.info(`dispatch: ${identifier} is in planning-mode project — skipping`);
         await linearApi.createComment(
           issue.id,
-          "This project is in planning mode. Finalize the plan before dispatching implementation.",
+          `**Can't dispatch yet** — this project is in planning mode.\n\n**To continue:** Comment on the planning issue with your requirements, then say **"finalize plan"** when ready.\n\n**To cancel planning:** Comment **"abandon"** on the planning issue.`,
         );
         return;
       }
@@ -1260,7 +1290,7 @@ async function handleDispatch(
       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}\``,
+        `**Already running** as **${existing.tier}** — status: **${existing.status}**, started ${Math.round(ageMs / 60_000)}m ago.\n\nWorktree: \`${existing.worktreePath}\`\n\n**Options:**\n- Check progress: \`/dispatch status ${identifier}\`\n- Force restart: \`/dispatch retry ${identifier}\` (only works when stuck)\n- Escalate: \`/dispatch escalate ${identifier} "reason"\``,
       );
       return;
     }
@@ -1292,6 +1322,9 @@ async function handleDispatch(
   const labels = enrichedIssue.labels?.nodes?.map((l: any) => l.name) ?? [];
   const commentCount = enrichedIssue.comments?.nodes?.length ?? 0;
 
+  // Resolve repos for this dispatch (issue body markers, labels, or config default)
+  const repoResolution = resolveRepos(enrichedIssue.description, labels, pluginConfig);
+
   // 4. Assess complexity tier
   const assessment = await assessTier(api, {
     identifier,
@@ -1304,28 +1337,51 @@ async function handleDispatch(
   api.logger.info(`@dispatch: ${identifier} assessed as ${assessment.tier} (${assessment.model}) — ${assessment.reasoning}`);
   emitDiagnostic(api, { event: "dispatch_started", identifier, tier: assessment.tier, issueId: issue.id });
 
-  // 5. Create persistent worktree
-  let worktree;
+  // 5. Create persistent worktree(s)
+  let worktreePath: string;
+  let worktreeBranch: string;
+  let worktreeResumed: boolean;
+  let worktrees: Array<{ repoName: string; path: string; branch: string }> | undefined;
+
   try {
-    worktree = createWorktree(identifier, { baseRepo, baseDir: worktreeBaseDir });
-    api.logger.info(`@dispatch: worktree ${worktree.resumed ? "resumed" : "created"} at ${worktree.path}`);
+    if (isMultiRepo(repoResolution)) {
+      const multi = createMultiWorktree(identifier, repoResolution.repos, { baseDir: worktreeBaseDir });
+      worktreePath = multi.parentPath;
+      worktreeBranch = `codex/${identifier}`;
+      worktreeResumed = multi.worktrees.some(w => w.resumed);
+      worktrees = multi.worktrees.map(w => ({ repoName: w.repoName, path: w.path, branch: w.branch }));
+      api.logger.info(`@dispatch: multi-repo worktrees ${worktreeResumed ? "resumed" : "created"} at ${worktreePath} (${repoResolution.repos.map(r => r.name).join(", ")})`);
+    } else {
+      const single = createWorktree(identifier, { baseRepo, baseDir: worktreeBaseDir });
+      worktreePath = single.path;
+      worktreeBranch = single.branch;
+      worktreeResumed = single.resumed;
+      api.logger.info(`@dispatch: worktree ${worktreeResumed ? "resumed" : "created"} at ${worktreePath}`);
+    }
   } 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)}`,
+      `**Dispatch failed** — couldn't create the worktree.\n\n> ${String(err).slice(0, 200)}\n\n**What to try:**\n- Check that the base repo exists\n- Re-assign this issue to try again\n- Check logs: \`journalctl --user -u openclaw-gateway --since "5 min ago"\``,
     );
     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("; ")}`);
+  // 5b. Prepare workspace(s)
+  if (worktrees) {
+    for (const wt of worktrees) {
+      const prep = prepareWorkspace(wt.path, wt.branch);
+      if (prep.errors.length > 0) {
+        api.logger.warn(`@dispatch: workspace prep for ${wt.repoName} had errors: ${prep.errors.join("; ")}`);
+      }
+    }
   } else {
-    api.logger.info(
-      `@dispatch: workspace prepared — pulled=${prep.pulled}, submodules=${prep.submodulesInitialized}`,
-    );
+    const prep = prepareWorkspace(worktreePath, worktreeBranch);
+    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
@@ -1339,16 +1395,16 @@ async function handleDispatch(
 
   // 6b. Initialize .claw/ artifact directory
   try {
-    ensureClawDir(worktree.path);
-    writeManifest(worktree.path, {
+    ensureClawDir(worktreePath);
+    writeManifest(worktreePath, {
       issueIdentifier: identifier,
       issueTitle: enrichedIssue.title ?? "(untitled)",
       issueId: issue.id,
       tier: assessment.tier,
       model: assessment.model,
       dispatchedAt: new Date().toISOString(),
-      worktreePath: worktree.path,
-      branch: worktree.branch,
+      worktreePath,
+      branch: worktreeBranch,
       attempts: 0,
       status: "dispatched",
       plugin: "openclaw-linear",
@@ -1363,8 +1419,8 @@ async function handleDispatch(
     issueId: issue.id,
     issueIdentifier: identifier,
     issueTitle: enrichedIssue.title ?? "(untitled)",
-    worktreePath: worktree.path,
-    branch: worktree.branch,
+    worktreePath,
+    branch: worktreeBranch,
     tier: assessment.tier,
     model: assessment.model,
     status: "dispatched",
@@ -1372,6 +1428,7 @@ async function handleDispatch(
     agentSessionId,
     attempt: 0,
     project: enrichedIssue?.project?.id,
+    worktrees,
   }, statePath);
 
   // 8. Register active session for tool resolution
@@ -1384,16 +1441,24 @@ async function handleDispatch(
   });
 
   // 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 worktreeDesc = worktrees
+    ? worktrees.map(wt => `\`${wt.repoName}\`: \`${wt.path}\``).join("\n")
+    : `\`${worktreePath}\``;
   const statusComment = [
     `**Dispatched** as **${assessment.tier}** (${assessment.model})`,
     `> ${assessment.reasoning}`,
     ``,
-    `Worktree: \`${worktree.path}\` ${worktree.resumed ? "(resumed)" : "(fresh)"}`,
-    `Branch: \`${worktree.branch}\``,
-    prepStatus,
+    worktrees
+      ? `Worktrees ${worktreeResumed ? "(resumed)" : "(fresh)"}:\n${worktreeDesc}`
+      : `Worktree: ${worktreeDesc} ${worktreeResumed ? "(resumed)" : "(fresh)"}`,
+    `Branch: \`${worktreeBranch}\``,
+    ``,
+    `**Status:** Worker is starting now. An independent audit runs automatically after implementation.`,
+    ``,
+    `**While you wait:**`,
+    `- Check progress: \`/dispatch status ${identifier}\``,
+    `- Cancel: \`/dispatch escalate ${identifier} "reason"\``,
+    `- All dispatches: \`/dispatch list\``,
   ].join("\n");
 
   await linearApi.createComment(issue.id, statusComment);
@@ -1425,7 +1490,7 @@ async function handleDispatch(
   activeRuns.add(issue.id);
 
   // Instantiate notifier (Discord, Slack, or both — config-driven)
-  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime);
+  const notify: NotifyFn = createNotifierFromConfig(pluginConfig, api.runtime, api);
 
   const hookCtx: HookContext = {
     api,
@@ -1450,6 +1515,18 @@ async function handleDispatch(
     .catch(async (err) => {
       api.logger.error(`@dispatch: pipeline v2 failed for ${identifier}: ${err}`);
       await updateDispatchStatus(identifier, "failed", statePath);
+      // Write memory for failed dispatches so they're searchable in dispatch history
+      try {
+        const wsDir = resolveOrchestratorWorkspace(api, pluginConfig);
+        writeDispatchMemory(identifier, `Pipeline failed: ${String(err).slice(0, 500)}`, wsDir, {
+          title: enrichedIssue.title ?? identifier,
+          tier: assessment.tier,
+          status: "failed",
+          project: enrichedIssue?.project?.id,
+          attempts: 1,
+          model: assessment.model,
+        });
+      } catch { /* best effort */ }
     })
     .finally(() => {
       activeRuns.delete(issue.id);

package/src/tools/cli-shared.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+// Mock the active-session module
+vi.mock("../pipeline/active-session.js", () => ({
+  getCurrentSession: vi.fn(() => null),
+  getActiveSessionByIdentifier: vi.fn(() => null),
+}));
+
+// Mock the linear-api module — LinearAgentApi must be a class (used with `new`)
+vi.mock("../api/linear-api.js", () => {
+  const MockClass = vi.fn(function (this: any) {
+    return this;
+  });
+  return {
+    resolveLinearToken: vi.fn(() => ({ accessToken: null, source: "none" })),
+    LinearAgentApi: MockClass,
+  };
+});
+
+// Mock the watchdog module (re-exported constants)
+vi.mock("../agent/watchdog.js", () => ({
+  DEFAULT_INACTIVITY_SEC: 120,
+  DEFAULT_MAX_TOTAL_SEC: 7200,
+  DEFAULT_TOOL_TIMEOUT_SEC: 600,
+}));
+
+import { getCurrentSession, getActiveSessionByIdentifier } from "../pipeline/active-session.js";
+import { resolveLinearToken, LinearAgentApi } from "../api/linear-api.js";
+import { extractPrompt, resolveSession, buildLinearApi } from "./cli-shared.js";
+import type { CliToolParams } from "./cli-shared.js";
+
+const mockedGetCurrentSession = vi.mocked(getCurrentSession);
+const mockedGetActiveByIdentifier = vi.mocked(getActiveSessionByIdentifier);
+const mockedResolveLinearToken = vi.mocked(resolveLinearToken);
+const MockedLinearAgentApi = vi.mocked(LinearAgentApi);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+// ---------------------------------------------------------------------------
+// extractPrompt
+// ---------------------------------------------------------------------------
+describe("extractPrompt", () => {
+  it("returns prompt field when present", () => {
+    const params: CliToolParams = { prompt: "do the thing" };
+    expect(extractPrompt(params)).toBe("do the thing");
+  });
+
+  it("falls back to text field", () => {
+    const params = { text: "text fallback" } as unknown as CliToolParams;
+    expect(extractPrompt(params)).toBe("text fallback");
+  });
+
+  it("falls back to message field", () => {
+    const params = { message: "message fallback" } as unknown as CliToolParams;
+    expect(extractPrompt(params)).toBe("message fallback");
+  });
+
+  it("falls back to task field", () => {
+    const params = { task: "task fallback" } as unknown as CliToolParams;
+    expect(extractPrompt(params)).toBe("task fallback");
+  });
+
+  it("returns undefined when no fields present", () => {
+    const params = {} as unknown as CliToolParams;
+    expect(extractPrompt(params)).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// resolveSession
+// ---------------------------------------------------------------------------
+describe("resolveSession", () => {
+  it("uses explicit session params when provided", () => {
+    const params: CliToolParams = {
+      prompt: "test",
+      agentSessionId: "sess-123",
+      issueIdentifier: "API-42",
+    };
+
+    const result = resolveSession(params);
+    expect(result.agentSessionId).toBe("sess-123");
+    expect(result.issueIdentifier).toBe("API-42");
+    // Should not consult the registry at all
+    expect(mockedGetCurrentSession).not.toHaveBeenCalled();
+    expect(mockedGetActiveByIdentifier).not.toHaveBeenCalled();
+  });
+
+  it("falls back to active session registry", () => {
+    mockedGetCurrentSession.mockReturnValue({
+      agentSessionId: "active-sess-456",
+      issueIdentifier: "API-99",
+      issueId: "issue-id-99",
+      startedAt: Date.now(),
+    });
+
+    const params: CliToolParams = { prompt: "test" };
+    const result = resolveSession(params);
+
+    expect(result.agentSessionId).toBe("active-sess-456");
+    expect(result.issueIdentifier).toBe("API-99");
+    expect(mockedGetCurrentSession).toHaveBeenCalled();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// buildLinearApi
+// ---------------------------------------------------------------------------
+describe("buildLinearApi", () => {
+  it("returns null when no agentSessionId provided", () => {
+    const api = { pluginConfig: {} } as any;
+    expect(buildLinearApi(api)).toBeNull();
+    expect(buildLinearApi(api, undefined)).toBeNull();
+  });
+
+  it("returns null when no token available", () => {
+    mockedResolveLinearToken.mockReturnValue({
+      accessToken: null,
+      source: "none",
+    });
+
+    const api = { pluginConfig: {} } as any;
+    expect(buildLinearApi(api, "sess-123")).toBeNull();
+  });
+
+  it("creates a LinearAgentApi when token is available", () => {
+    mockedResolveLinearToken.mockReturnValue({
+      accessToken: "lin_tok_abc",
+      refreshToken: "refresh_xyz",
+      expiresAt: 9999999999,
+      source: "profile",
+    });
+    MockedLinearAgentApi.mockImplementation(function (this: any) {
+      this.fake = true;
+      return this;
+    } as any);
+
+    const api = {
+      pluginConfig: {
+        clientId: "cid",
+        clientSecret: "csecret",
+      },
+    } as any;
+
+    const result = buildLinearApi(api, "sess-123");
+    expect(result).not.toBeNull();
+    expect(MockedLinearAgentApi).toHaveBeenCalledWith("lin_tok_abc", {
+      refreshToken: "refresh_xyz",
+      expiresAt: 9999999999,
+      clientId: "cid",
+      clientSecret: "csecret",
+    });
+  });
+});