@calltelemetry/openclaw-linear 0.9.5 → 0.9.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.9.5",
+  "version": "0.9.6",
   "description": "Linear Agent plugin for OpenClaw — webhook-driven AI pipeline with OAuth, multi-agent routing, and issue triage",
   "type": "module",
   "license": "MIT",

package/src/__test__/fixtures/recorded-sub-issue-flow.ts

@@ -1,172 +1,254 @@
 /**
  * Recorded API responses from sub-issue decomposition smoke test.
- *
- * Initially seeded with placeholder data. Overwritten with real API responses
- * when the smoke test runs: npx vitest run src/__test__/smoke-linear-api.test.ts
- *
- * Last recorded: seed (placeholder)
+ * Auto-generated — do not edit manually.
+ * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts
+ * Last recorded: 2026-02-22T01:35:48.289Z
  */
 
 export const RECORDED = {
-  teamStates: [
-    { id: "state-backlog", name: "Backlog", type: "backlog" },
-    { id: "state-started", name: "In Progress", type: "started" },
-    { id: "state-done", name: "Done", type: "completed" },
-    { id: "state-canceled", name: "Canceled", type: "canceled" },
-  ],
-  createParent: { id: "parent-001", identifier: "UAT-100" },
-  createSubIssue1: { id: "sub1-001", identifier: "UAT-101" },
-  createSubIssue2: { id: "sub2-001", identifier: "UAT-102" },
-  parentDetails: {
-    id: "parent-001",
-    identifier: "UAT-100",
-    title: "[SMOKE TEST] Sub-Issue Parent: Search Feature",
-    description:
-      "Auto-generated by smoke test to verify sub-issue decomposition.\n\n" +
-      "This parent issue should have two sub-issues created under it.",
-    estimate: null,
-    state: { name: "Backlog", type: "backlog" },
-    creator: { name: "Test User", email: null as string | null },
-    assignee: null as { name: string } | null,
-    labels: { nodes: [] as Array<{ id: string; name: string }> },
-    team: { id: "team-uat", name: "UAT", issueEstimationType: "notUsed" },
-    comments: {
-      nodes: [] as Array<{
-        body: string;
-        user: { name: string } | null;
-        createdAt: string;
-      }>,
-    },
-    project: null as { id: string; name: string } | null,
-    parent: null as { id: string; identifier: string } | null,
-    relations: {
-      nodes: [] as Array<{
-        type: string;
-        relatedIssue: { id: string; identifier: string; title: string };
-      }>,
+  "teamStates": [
+    {
+      "id": "cf937197-a76e-4f36-9938-5013442f2137",
+      "name": "Todo",
+      "type": "unstarted"
+    },
+    {
+      "id": "9e40430a-5404-4fed-be64-544417c7c46c",
+      "name": "Duplicate",
+      "type": "canceled"
+    },
+    {
+      "id": "9bf913d6-f32d-452f-af43-3139cc8e5f3f",
+      "name": "Canceled",
+      "type": "canceled"
+    },
+    {
+      "id": "7510263f-555b-42c4-98c3-f4196d755c4b",
+      "name": "In Progress",
+      "type": "started"
+    },
+    {
+      "id": "6bcb2601-dc7b-487e-a407-416521aa235e",
+      "name": "Backlog",
+      "type": "backlog"
     },
+    {
+      "id": "69c39ddf-d135-47f7-8dbe-3fc6a539d504",
+      "name": "Done",
+      "type": "completed"
+    },
+    {
+      "id": "2a4c7f41-80cd-4798-91e7-0aa6656d73ca",
+      "name": "In Review",
+      "type": "started"
+    }
+  ],
+  "createParent": {
+    "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+    "identifier": "UAT-235"
+  },
+  "createSubIssue1": {
+    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
+    "identifier": "UAT-236"
   },
-  subIssue1Details: {
-    id: "sub1-001",
-    identifier: "UAT-101",
-    title: "[SMOKE TEST] Sub-Issue 1: Backend API",
-    description:
-      "Implement the backend search API endpoint.\n\n" +
-      "Given a search query, when the API is called, then matching results are returned.",
-    estimate: 2,
-    state: { name: "Backlog", type: "backlog" },
-    creator: { name: "Test User", email: null as string | null },
-    assignee: null as { name: string } | null,
-    labels: { nodes: [] as Array<{ id: string; name: string }> },
-    team: { id: "team-uat", name: "UAT", issueEstimationType: "notUsed" },
-    comments: {
-      nodes: [] as Array<{
-        body: string;
-        user: { name: string } | null;
-        createdAt: string;
-      }>,
-    },
-    project: null as { id: string; name: string } | null,
-    parent: { id: "parent-001", identifier: "UAT-100" },
-    relations: {
-      nodes: [] as Array<{
-        type: string;
-        relatedIssue: { id: string; identifier: string; title: string };
-      }>,
+  "createSubIssue2": {
+    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
+    "identifier": "UAT-237"
+  },
+  "subIssue1Details": {
+    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
+    "identifier": "UAT-236",
+    "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
+    "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
+    "estimate": 2,
+    "state": {
+      "name": "Backlog",
+      "type": "backlog"
+    },
+    "creator": {
+      "name": "jason.barbee@calltelemetry.com",
+      "email": "jason.barbee@calltelemetry.com"
     },
+    "assignee": null,
+    "labels": {
+      "nodes": []
+    },
+    "team": {
+      "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "name": "UAT",
+      "issueEstimationType": "tShirt"
+    },
+    "comments": {
+      "nodes": []
+    },
+    "project": null,
+    "parent": {
+      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+      "identifier": "UAT-235"
+    },
+    "relations": {
+      "nodes": []
+    }
   },
-  subIssue2Details: {
-    id: "sub2-001",
-    identifier: "UAT-102",
-    title: "[SMOKE TEST] Sub-Issue 2: Frontend UI",
-    description:
-      "Build the frontend search UI component.\n\n" +
-      "Given the search page loads, when the user types a query, then results display in real-time.",
-    estimate: 3,
-    state: { name: "Backlog", type: "backlog" },
-    creator: { name: "Test User", email: null as string | null },
-    assignee: null as { name: string } | null,
-    labels: { nodes: [] as Array<{ id: string; name: string }> },
-    team: { id: "team-uat", name: "UAT", issueEstimationType: "notUsed" },
-    comments: {
-      nodes: [] as Array<{
-        body: string;
-        user: { name: string } | null;
-        createdAt: string;
-      }>,
-    },
-    project: null as { id: string; name: string } | null,
-    parent: { id: "parent-001", identifier: "UAT-100" },
-    relations: {
-      nodes: [] as Array<{
-        type: string;
-        relatedIssue: { id: string; identifier: string; title: string };
-      }>,
+  "subIssue2Details": {
+    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
+    "identifier": "UAT-237",
+    "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
+    "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
+    "estimate": 3,
+    "state": {
+      "name": "Backlog",
+      "type": "backlog"
+    },
+    "creator": {
+      "name": "jason.barbee@calltelemetry.com",
+      "email": "jason.barbee@calltelemetry.com"
+    },
+    "assignee": null,
+    "labels": {
+      "nodes": []
+    },
+    "team": {
+      "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "name": "UAT",
+      "issueEstimationType": "tShirt"
+    },
+    "comments": {
+      "nodes": []
+    },
+    "project": null,
+    "parent": {
+      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+      "identifier": "UAT-235"
     },
+    "relations": {
+      "nodes": []
+    }
   },
-  createRelation: { id: "rel-001" },
-  subIssue1WithRelation: {
-    id: "sub1-001",
-    identifier: "UAT-101",
-    title: "[SMOKE TEST] Sub-Issue 1: Backend API",
-    description:
-      "Implement the backend search API endpoint.\n\n" +
-      "Given a search query, when the API is called, then matching results are returned.",
-    estimate: 2,
-    state: { name: "Backlog", type: "backlog" },
-    creator: { name: "Test User", email: null as string | null },
-    assignee: null as { name: string } | null,
-    labels: { nodes: [] as Array<{ id: string; name: string }> },
-    team: { id: "team-uat", name: "UAT", issueEstimationType: "notUsed" },
-    comments: {
-      nodes: [] as Array<{
-        body: string;
-        user: { name: string } | null;
-        createdAt: string;
-      }>,
-    },
-    project: null as { id: string; name: string } | null,
-    parent: { id: "parent-001", identifier: "UAT-100" },
-    relations: {
-      nodes: [
+  "parentDetails": {
+    "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+    "identifier": "UAT-235",
+    "title": "[SMOKE TEST] Sub-Issue Parent: Search Feature",
+    "description": "Auto-generated by smoke test to verify sub-issue decomposition.\n\nThis parent issue should have two sub-issues created under it.\n\nCreated: 2026-02-22T01:35:46.183Z",
+    "estimate": null,
+    "state": {
+      "name": "Backlog",
+      "type": "backlog"
+    },
+    "creator": {
+      "name": "jason.barbee@calltelemetry.com",
+      "email": "jason.barbee@calltelemetry.com"
+    },
+    "assignee": null,
+    "labels": {
+      "nodes": []
+    },
+    "team": {
+      "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "name": "UAT",
+      "issueEstimationType": "tShirt"
+    },
+    "comments": {
+      "nodes": [
         {
-          type: "blocks",
-          relatedIssue: {
-            id: "sub2-001",
-            identifier: "UAT-102",
-            title: "[SMOKE TEST] Sub-Issue 2: Frontend UI",
-          },
-        },
-      ],
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T01:35:47.210Z"
+        }
+      ]
     },
+    "project": null,
+    "parent": null,
+    "relations": {
+      "nodes": []
+    }
+  },
+  "createRelation": {
+    "id": "f2b33a57-b79a-4dcc-b973-a5453676a78f"
   },
-  subIssue2WithRelation: {
-    id: "sub2-001",
-    identifier: "UAT-102",
-    title: "[SMOKE TEST] Sub-Issue 2: Frontend UI",
-    description:
-      "Build the frontend search UI component.\n\n" +
-      "Given the search page loads, when the user types a query, then results display in real-time.",
-    estimate: 3,
-    state: { name: "Backlog", type: "backlog" },
-    creator: { name: "Test User", email: null as string | null },
-    assignee: null as { name: string } | null,
-    labels: { nodes: [] as Array<{ id: string; name: string }> },
-    team: { id: "team-uat", name: "UAT", issueEstimationType: "notUsed" },
-    comments: {
-      nodes: [] as Array<{
-        body: string;
-        user: { name: string } | null;
-        createdAt: string;
-      }>,
-    },
-    project: null as { id: string; name: string } | null,
-    parent: { id: "parent-001", identifier: "UAT-100" },
-    relations: {
-      nodes: [] as Array<{
-        type: string;
-        relatedIssue: { id: string; identifier: string; title: string };
-      }>,
+  "subIssue1WithRelation": {
+    "id": "2796434d-9c1e-4ee9-af70-6e0e14fe6109",
+    "identifier": "UAT-236",
+    "title": "[SMOKE TEST] Sub-Issue 1: Backend API",
+    "description": "Implement the backend search API endpoint.\n\nGiven a search query, when the API is called, then matching results are returned.",
+    "estimate": 2,
+    "state": {
+      "name": "Backlog",
+      "type": "backlog"
+    },
+    "creator": {
+      "name": "jason.barbee@calltelemetry.com",
+      "email": "jason.barbee@calltelemetry.com"
+    },
+    "assignee": null,
+    "labels": {
+      "nodes": []
+    },
+    "team": {
+      "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "name": "UAT",
+      "issueEstimationType": "tShirt"
+    },
+    "comments": {
+      "nodes": [
+        {
+          "body": "This thread is for an agent session with ctclaw.",
+          "user": null,
+          "createdAt": "2026-02-22T01:35:47.302Z"
+        }
+      ]
+    },
+    "project": null,
+    "parent": {
+      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+      "identifier": "UAT-235"
     },
+    "relations": {
+      "nodes": [
+        {
+          "type": "blocks",
+          "relatedIssue": {
+            "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
+            "identifier": "UAT-237",
+            "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI"
+          }
+        }
+      ]
+    }
   },
+  "subIssue2WithRelation": {
+    "id": "d1b939d0-33f1-4f6d-992a-95f2a3cb842a",
+    "identifier": "UAT-237",
+    "title": "[SMOKE TEST] Sub-Issue 2: Frontend UI",
+    "description": "Build the frontend search UI component.\n\nGiven the search page loads, when the user types a query, then results display in real-time.",
+    "estimate": 3,
+    "state": {
+      "name": "Backlog",
+      "type": "backlog"
+    },
+    "creator": {
+      "name": "jason.barbee@calltelemetry.com",
+      "email": "jason.barbee@calltelemetry.com"
+    },
+    "assignee": null,
+    "labels": {
+      "nodes": []
+    },
+    "team": {
+      "id": "08cba264-d774-4afd-bc93-ee8213d12ef8",
+      "name": "UAT",
+      "issueEstimationType": "tShirt"
+    },
+    "comments": {
+      "nodes": []
+    },
+    "project": null,
+    "parent": {
+      "id": "e49ed5fb-8068-41a8-9f4d-6d9b55a0c2b6",
+      "identifier": "UAT-235"
+    },
+    "relations": {
+      "nodes": []
+    }
+  }
 };

package/src/__test__/smoke-linear-api.test.ts

@@ -8,12 +8,15 @@
  *
  * Requires: ~/.openclaw/auth-profiles.json with a valid linear:api-key profile.
  */
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
 import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { LinearAgentApi } from "../api/linear-api.js";
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
 // ── Setup ──────────────────────────────────────────────────────────
 
 const AUTH_PROFILES_PATH = join(
@@ -479,6 +482,208 @@ describe("Linear API smoke tests", () => {
     });
   });
 
+  describe("sub-issue decomposition", () => {
+    let parentIssueId: string | null = null;
+    let parentIssueIdentifier: string | null = null;
+    let subIssue1Id: string | null = null;
+    let subIssue1Identifier: string | null = null;
+    let subIssue2Id: string | null = null;
+    let subIssue2Identifier: string | null = null;
+    const recorded: Record<string, unknown> = {};
+
+    let teamStates: Array<{ id: string; name: string; type: string }>;
+
+    it("fetches team states for sub-issue tests", async () => {
+      teamStates = await api.getTeamStates(TEAM_ID);
+      expect(teamStates.length).toBeGreaterThan(0);
+      recorded.teamStates = teamStates;
+    });
+
+    it("creates a parent issue", async () => {
+      const backlogState = teamStates.find((s) => s.type === "backlog");
+      expect(backlogState).toBeTruthy();
+
+      const result = await api.createIssue({
+        teamId: TEAM_ID,
+        title: "[SMOKE TEST] Sub-Issue Parent: Search Feature",
+        description:
+          "Auto-generated by smoke test to verify sub-issue decomposition.\n\n" +
+          "This parent issue should have two sub-issues created under it.\n\n" +
+          `Created: ${new Date().toISOString()}`,
+        stateId: backlogState!.id,
+        priority: 4,
+      });
+
+      expect(result.id).toBeTruthy();
+      expect(result.identifier).toBeTruthy();
+      parentIssueId = result.id;
+      parentIssueIdentifier = result.identifier;
+      recorded.createParent = result;
+      console.log(`Created parent issue: ${result.identifier} (${result.id})`);
+    });
+
+    it("creates sub-issue 1 under parent (Backend API)", async () => {
+      expect(parentIssueId).toBeTruthy();
+      const backlogState = teamStates.find((s) => s.type === "backlog");
+
+      const result = await api.createIssue({
+        teamId: TEAM_ID,
+        title: "[SMOKE TEST] Sub-Issue 1: Backend API",
+        description:
+          "Implement the backend search API endpoint.\n\n" +
+          "Given a search query, when the API is called, then matching results are returned.",
+        stateId: backlogState!.id,
+        parentId: parentIssueId!,
+        priority: 3,
+        estimate: 2,
+      });
+
+      expect(result.id).toBeTruthy();
+      expect(result.identifier).toBeTruthy();
+      subIssue1Id = result.id;
+      subIssue1Identifier = result.identifier;
+      recorded.createSubIssue1 = result;
+      console.log(`Created sub-issue 1: ${result.identifier} (parentId=${parentIssueId})`);
+    });
+
+    it("creates sub-issue 2 under parent (Frontend UI)", async () => {
+      expect(parentIssueId).toBeTruthy();
+      const backlogState = teamStates.find((s) => s.type === "backlog");
+
+      const result = await api.createIssue({
+        teamId: TEAM_ID,
+        title: "[SMOKE TEST] Sub-Issue 2: Frontend UI",
+        description:
+          "Build the frontend search UI component.\n\n" +
+          "Given the search page loads, when the user types a query, then results display in real-time.",
+        stateId: backlogState!.id,
+        parentId: parentIssueId!,
+        priority: 3,
+        estimate: 3,
+      });
+
+      expect(result.id).toBeTruthy();
+      expect(result.identifier).toBeTruthy();
+      subIssue2Id = result.id;
+      subIssue2Identifier = result.identifier;
+      recorded.createSubIssue2 = result;
+      console.log(`Created sub-issue 2: ${result.identifier} (parentId=${parentIssueId})`);
+    });
+
+    it("sub-issue 1 has parent field pointing to parent", async () => {
+      expect(subIssue1Id).toBeTruthy();
+      const details = await api.getIssueDetails(subIssue1Id!);
+
+      expect(details.parent).not.toBeNull();
+      expect(details.parent!.id).toBe(parentIssueId);
+      expect(details.parent!.identifier).toBe(parentIssueIdentifier);
+      recorded.subIssue1Details = details;
+      console.log(`Sub-issue 1 parent: ${details.parent!.identifier}`);
+    });
+
+    it("sub-issue 2 has parent field pointing to parent", async () => {
+      expect(subIssue2Id).toBeTruthy();
+      const details = await api.getIssueDetails(subIssue2Id!);
+
+      expect(details.parent).not.toBeNull();
+      expect(details.parent!.id).toBe(parentIssueId);
+      expect(details.parent!.identifier).toBe(parentIssueIdentifier);
+      recorded.subIssue2Details = details;
+      console.log(`Sub-issue 2 parent: ${details.parent!.identifier}`);
+    });
+
+    it("parent issue has no parent (it is the root)", async () => {
+      expect(parentIssueId).toBeTruthy();
+      const details = await api.getIssueDetails(parentIssueId!);
+
+      expect(details.parent).toBeNull();
+      recorded.parentDetails = details;
+    });
+
+    it("creates blocks relation (sub-issue 1 blocks sub-issue 2)", async () => {
+      expect(subIssue1Id).toBeTruthy();
+      expect(subIssue2Id).toBeTruthy();
+
+      const result = await api.createIssueRelation({
+        issueId: subIssue1Id!,
+        relatedIssueId: subIssue2Id!,
+        type: "blocks",
+      });
+
+      expect(result.id).toBeTruthy();
+      recorded.createRelation = result;
+      console.log(`Created blocks relation: ${subIssue1Identifier} blocks ${subIssue2Identifier}`);
+    });
+
+    it("sub-issue 1 shows blocks relation to sub-issue 2", async () => {
+      expect(subIssue1Id).toBeTruthy();
+      const details = await api.getIssueDetails(subIssue1Id!);
+      const blocksRels = details.relations.nodes.filter(
+        (r) => r.type === "blocks",
+      );
+
+      expect(blocksRels.length).toBeGreaterThan(0);
+      expect(
+        blocksRels.some((r) => r.relatedIssue.id === subIssue2Id),
+      ).toBe(true);
+      recorded.subIssue1WithRelation = details;
+      console.log(`Sub-issue 1 blocks: ${blocksRels.map((r) => r.relatedIssue.identifier).join(", ")}`);
+    });
+
+    it("sub-issue 2 shows inverse relation", async () => {
+      expect(subIssue2Id).toBeTruthy();
+      const details = await api.getIssueDetails(subIssue2Id!);
+
+      // Linear may or may not populate an inverse "is_blocked_by" relation.
+      // Record whatever we get — the mock test replays it as-is.
+      recorded.subIssue2WithRelation = details;
+      const rels = details.relations.nodes;
+      console.log(
+        `Sub-issue 2 relations: ${rels.length > 0 ? rels.map((r) => `${r.type} ${r.relatedIssue.identifier}`).join(", ") : "(none — inverse may not be returned)"}`,
+      );
+    });
+
+    it("saves recorded API responses to fixture file", () => {
+      // Only write if we actually ran the full flow
+      if (!parentIssueId || !subIssue1Id || !subIssue2Id) {
+        console.log("Skipping fixture write — not all issues were created.");
+        return;
+      }
+
+      const fixturePath = join(
+        __dirname,
+        "fixtures",
+        "recorded-sub-issue-flow.ts",
+      );
+      const content =
+        `/**\n` +
+        ` * Recorded API responses from sub-issue decomposition smoke test.\n` +
+        ` * Auto-generated — do not edit manually.\n` +
+        ` * Re-generate by running: npx vitest run src/__test__/smoke-linear-api.test.ts\n` +
+        ` * Last recorded: ${new Date().toISOString()}\n` +
+        ` */\n\n` +
+        `export const RECORDED = ${JSON.stringify(recorded, null, 2)};\n`;
+
+      writeFileSync(fixturePath, content, "utf8");
+      console.log(`Recorded fixture written to: ${fixturePath}`);
+    });
+
+    it("cleans up: cancels parent and sub-issues", async () => {
+      const canceledState = teamStates?.find(
+        (s) => s.type === "canceled" || s.name.toLowerCase().includes("cancel"),
+      );
+
+      for (const id of [subIssue1Id, subIssue2Id, parentIssueId]) {
+        if (!id || !canceledState) continue;
+        try {
+          await api.updateIssue(id, { stateId: canceledState.id });
+        } catch {
+          // Best effort
+        }
+      }
+    });
+  });
+
   describe("cleanup", () => {
     it("cancels the smoke test issue", async () => {
       if (!smokeIssueId) return;

package/src/pipeline/sub-issue-decomposition.test.ts

@@ -0,0 +1,388 @@
+/**
+ * sub-issue-decomposition.test.ts — Mock replay of sub-issue creation flow.
+ *
+ * Uses recorded API responses from the smoke test to verify parent-child
+ * hierarchy creation, parentId resolution, and issue relation handling.
+ *
+ * Run with: npx vitest run src/pipeline/sub-issue-decomposition.test.ts
+ * No credentials required — all API calls use recorded fixtures.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+
+// Mock external dependencies before imports
+vi.mock("openclaw/plugin-sdk", () => ({
+  jsonResult: (data: any) => ({ type: "json", data }),
+}));
+
+vi.mock("../api/linear-api.js", () => ({
+  LinearAgentApi: vi.fn(),
+}));
+
+import { RECORDED } from "../__test__/fixtures/recorded-sub-issue-flow.js";
+import {
+  createPlannerTools,
+  setActivePlannerContext,
+  clearActivePlannerContext,
+  detectCycles,
+  auditPlan,
+  buildPlanSnapshot,
+} from "../tools/planner-tools.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type ProjectIssue = Parameters<typeof detectCycles>[0][number];
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function createReplayApi() {
+  const api = {
+    getTeamStates: vi.fn().mockResolvedValue(RECORDED.teamStates),
+    createIssue: vi.fn(),
+    getIssueDetails: vi.fn(),
+    createIssueRelation: vi.fn().mockResolvedValue(RECORDED.createRelation),
+    getProjectIssues: vi.fn(),
+    getTeamLabels: vi.fn().mockResolvedValue([]),
+    updateIssue: vi.fn().mockResolvedValue(true),
+    updateIssueExtended: vi.fn().mockResolvedValue(true),
+    getViewerId: vi.fn().mockResolvedValue("viewer-1"),
+    createComment: vi.fn().mockResolvedValue("comment-id"),
+    emitActivity: vi.fn().mockResolvedValue(undefined),
+    updateSession: vi.fn().mockResolvedValue(undefined),
+    getProject: vi.fn().mockResolvedValue({
+      id: "proj-1",
+      name: "Test",
+      description: "",
+      state: "started",
+      teams: {
+        nodes: [
+          {
+            id: RECORDED.parentDetails.team.id,
+            name: RECORDED.parentDetails.team.name,
+          },
+        ],
+      },
+    }),
+  };
+
+  // Wire up getIssueDetails to return recorded response by ID
+  api.getIssueDetails.mockImplementation((id: string) => {
+    if (id === RECORDED.createParent.id)
+      return Promise.resolve(RECORDED.parentDetails);
+    if (id === RECORDED.createSubIssue1.id)
+      return Promise.resolve(RECORDED.subIssue1WithRelation);
+    if (id === RECORDED.createSubIssue2.id)
+      return Promise.resolve(RECORDED.subIssue2WithRelation);
+    throw new Error(`Unexpected issue ID in replay: ${id}`);
+  });
+
+  return api;
+}
+
+/** Build a ProjectIssue from recorded detail shapes. */
+function recordedToProjectIssue(
+  detail: typeof RECORDED.parentDetails,
+  overrides?: Partial<ProjectIssue>,
+): ProjectIssue {
+  return {
+    id: detail.id,
+    identifier: detail.identifier,
+    title: detail.title,
+    description: detail.description,
+    estimate: detail.estimate,
+    priority: 0,
+    state: detail.state,
+    parent: detail.parent,
+    labels: detail.labels,
+    relations: detail.relations,
+    ...overrides,
+  } as ProjectIssue;
+}
+
+// ===========================================================================
+// Group A: Direct API hierarchy (mock createIssue / getIssueDetails)
+// ===========================================================================
+
+describe("sub-issue decomposition (recorded replay)", () => {
+  describe("parent-child hierarchy via direct API", () => {
+    it("createIssue with parentId creates a sub-issue", async () => {
+      const api = createReplayApi();
+      api.createIssue.mockResolvedValueOnce(RECORDED.createSubIssue1);
+
+      const result = await api.createIssue({
+        teamId: RECORDED.parentDetails.team.id,
+        title: RECORDED.subIssue1Details.title,
+        parentId: RECORDED.createParent.id,
+        estimate: 2,
+        priority: 3,
+      });
+
+      expect(result.id).toBe(RECORDED.createSubIssue1.id);
+      expect(result.identifier).toBe(RECORDED.createSubIssue1.identifier);
+      expect(api.createIssue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          parentId: RECORDED.createParent.id,
+        }),
+      );
+    });
+
+    it("getIssueDetails of sub-issue returns parent reference", async () => {
+      const api = createReplayApi();
+      const details = await api.getIssueDetails(
+        RECORDED.createSubIssue1.id,
+      );
+
+      expect(details.parent).not.toBeNull();
+      expect(details.parent!.id).toBe(RECORDED.createParent.id);
+      expect(details.parent!.identifier).toBe(
+        RECORDED.createParent.identifier,
+      );
+    });
+
+    it("getIssueDetails of parent returns null parent (root)", async () => {
+      const api = createReplayApi();
+      const details = await api.getIssueDetails(RECORDED.createParent.id);
+
+      expect(details.parent).toBeNull();
+    });
+
+    it("createIssueRelation creates blocks dependency", async () => {
+      const api = createReplayApi();
+      const result = await api.createIssueRelation({
+        issueId: RECORDED.createSubIssue1.id,
+        relatedIssueId: RECORDED.createSubIssue2.id,
+        type: "blocks",
+      });
+
+      expect(result.id).toBe(RECORDED.createRelation.id);
+      expect(api.createIssueRelation).toHaveBeenCalledWith({
+        issueId: RECORDED.createSubIssue1.id,
+        relatedIssueId: RECORDED.createSubIssue2.id,
+        type: "blocks",
+      });
+    });
+
+    it("sub-issue details include blocks relation after linking", async () => {
+      const api = createReplayApi();
+      const details = await api.getIssueDetails(
+        RECORDED.createSubIssue1.id,
+      );
+
+      const blocksRels = details.relations.nodes.filter(
+        (r: any) => r.type === "blocks",
+      );
+      expect(blocksRels.length).toBeGreaterThan(0);
+      expect(
+        blocksRels.some(
+          (r: any) => r.relatedIssue.id === RECORDED.createSubIssue2.id,
+        ),
+      ).toBe(true);
+    });
+  });
+
+  // =========================================================================
+  // Group B: Planner tools (real tool code, mocked API)
+  // =========================================================================
+
+  describe("planner tools: parentIdentifier resolution", () => {
+    let tools: any[];
+    let mockApi: ReturnType<typeof createReplayApi>;
+
+    beforeEach(() => {
+      vi.clearAllMocks();
+      mockApi = createReplayApi();
+      setActivePlannerContext({
+        linearApi: mockApi as any,
+        projectId: "proj-1",
+        teamId: RECORDED.parentDetails.team.id,
+        api: { logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() } } as any,
+      });
+      tools = createPlannerTools();
+    });
+
+    afterEach(() => {
+      clearActivePlannerContext();
+    });
+
+    function findTool(name: string) {
+      const tool = tools.find((t: any) => t.name === name) as any;
+      if (!tool) throw new Error(`Tool '${name}' not found`);
+      return tool;
+    }
+
+    it("plan_create_issue resolves parentIdentifier to parentId", async () => {
+      // Mock getProjectIssues to return the parent issue
+      mockApi.getProjectIssues.mockResolvedValueOnce([
+        recordedToProjectIssue(RECORDED.parentDetails),
+      ]);
+      mockApi.createIssue.mockResolvedValueOnce(RECORDED.createSubIssue1);
+
+      const tool = findTool("plan_create_issue");
+      const result = await tool.execute("call-1", {
+        title: RECORDED.subIssue1Details.title,
+        description: RECORDED.subIssue1Details.description,
+        parentIdentifier: RECORDED.createParent.identifier,
+        estimate: 2,
+        priority: 3,
+      });
+
+      // Verify createIssue was called with resolved parentId (not identifier)
+      expect(mockApi.createIssue).toHaveBeenCalledWith(
+        expect.objectContaining({
+          parentId: RECORDED.createParent.id,
+        }),
+      );
+      expect(result.data.identifier).toBe(
+        RECORDED.createSubIssue1.identifier,
+      );
+    });
+
+    it("plan_link_issues creates blocks relation between resolved IDs", async () => {
+      // Mock getProjectIssues to return both sub-issues
+      mockApi.getProjectIssues.mockResolvedValueOnce([
+        recordedToProjectIssue(RECORDED.subIssue1WithRelation),
+        recordedToProjectIssue(RECORDED.subIssue2WithRelation),
+      ]);
+
+      const tool = findTool("plan_link_issues");
+      const result = await tool.execute("call-2", {
+        fromIdentifier: RECORDED.subIssue1WithRelation.identifier,
+        toIdentifier: RECORDED.subIssue2WithRelation.identifier,
+        type: "blocks",
+      });
+
+      expect(mockApi.createIssueRelation).toHaveBeenCalledWith({
+        issueId: RECORDED.subIssue1WithRelation.id,
+        relatedIssueId: RECORDED.subIssue2WithRelation.id,
+        type: "blocks",
+      });
+      expect(result.data.id).toBe(RECORDED.createRelation.id);
+      expect(result.data.type).toBe("blocks");
+    });
+
+    it("plan_get_project shows hierarchy with parent-child nesting", async () => {
+      // Return all 3 issues (parent + 2 subs)
+      mockApi.getProjectIssues.mockResolvedValueOnce([
+        recordedToProjectIssue(RECORDED.parentDetails),
+        recordedToProjectIssue(RECORDED.subIssue1WithRelation),
+        recordedToProjectIssue(RECORDED.subIssue2WithRelation),
+      ]);
+
+      const tool = findTool("plan_get_project");
+      const result = await tool.execute("call-3", {});
+      const snapshot = result.data?.snapshot ?? result.data?.plan ?? "";
+
+      // All three identifiers should appear
+      expect(snapshot).toContain(RECORDED.createParent.identifier);
+      expect(snapshot).toContain(RECORDED.createSubIssue1.identifier);
+      expect(snapshot).toContain(RECORDED.createSubIssue2.identifier);
+    });
+
+    it("plan_audit passes valid sub-issue hierarchy", async () => {
+      // Build issues that pass audit: descriptions >= 50 chars, estimate, priority set
+      const parent = recordedToProjectIssue(RECORDED.parentDetails, {
+        priority: 2,
+        estimate: 5,
+      });
+      const sub1 = recordedToProjectIssue(RECORDED.subIssue1WithRelation, {
+        priority: 3,
+        estimate: 2,
+      });
+      const sub2 = recordedToProjectIssue(RECORDED.subIssue2WithRelation, {
+        priority: 3,
+        estimate: 3,
+      });
+
+      mockApi.getProjectIssues.mockResolvedValueOnce([parent, sub1, sub2]);
+
+      const tool = findTool("plan_audit");
+      const result = await tool.execute("call-4", {});
+
+      expect(result.data.pass).toBe(true);
+      expect(result.data.problems).toHaveLength(0);
+    });
+  });
+
+  // =========================================================================
+  // Group C: auditPlan pure function with recorded data shapes
+  // =========================================================================
+
+  describe("auditPlan with parent-child relationships", () => {
+    it("issues with parent are not flagged as orphans", () => {
+      const parent = recordedToProjectIssue(RECORDED.parentDetails, {
+        priority: 2,
+        estimate: 5,
+      });
+      const sub1 = recordedToProjectIssue(RECORDED.subIssue1Details, {
+        priority: 3,
+        estimate: 2,
+      });
+      const sub2 = recordedToProjectIssue(RECORDED.subIssue2Details, {
+        priority: 3,
+        estimate: 3,
+      });
+
+      const result = auditPlan([parent, sub1, sub2]);
+
+      // Sub-issues have parent set, so they're not orphans.
+      // Parent may be flagged as orphan (no parent, no relations linking to it)
+      // but sub-issues definitely should NOT be orphans.
+      const orphanWarnings = result.warnings.filter((w) =>
+        w.includes("orphan"),
+      );
+      const subOrphans = orphanWarnings.filter(
+        (w) =>
+          w.includes(RECORDED.subIssue1Details.identifier) ||
+          w.includes(RECORDED.subIssue2Details.identifier),
+      );
+      expect(subOrphans).toHaveLength(0);
+    });
+
+    it("blocks relation between sub-issues produces valid DAG", () => {
+      const sub1 = recordedToProjectIssue(RECORDED.subIssue1WithRelation, {
+        priority: 3,
+        estimate: 2,
+      });
+      const sub2 = recordedToProjectIssue(RECORDED.subIssue2WithRelation, {
+        priority: 3,
+        estimate: 3,
+      });
+
+      const cycles = detectCycles([sub1, sub2]);
+      expect(cycles).toHaveLength(0);
+    });
+
+    it("buildPlanSnapshot nests sub-issues under parent", () => {
+      const parent = recordedToProjectIssue(RECORDED.parentDetails, {
+        priority: 2,
+        estimate: 5,
+      });
+      const sub1 = recordedToProjectIssue(RECORDED.subIssue1WithRelation, {
+        priority: 3,
+        estimate: 2,
+      });
+      const sub2 = recordedToProjectIssue(RECORDED.subIssue2WithRelation, {
+        priority: 3,
+        estimate: 3,
+      });
+
+      const snapshot = buildPlanSnapshot([parent, sub1, sub2]);
+
+      // Parent should appear
+      expect(snapshot).toContain(RECORDED.createParent.identifier);
+      // Sub-issues should appear
+      expect(snapshot).toContain(RECORDED.createSubIssue1.identifier);
+      expect(snapshot).toContain(RECORDED.createSubIssue2.identifier);
+      // Sub-issues should be indented (nested under parent)
+      const lines = snapshot.split("\n");
+      const sub1Line = lines.find((l) =>
+        l.includes(RECORDED.createSubIssue1.identifier),
+      );
+      expect(sub1Line).toBeTruthy();
+      expect(sub1Line!.startsWith("  ")).toBe(true);
+    });
+  });
+});

package/src/pipeline/webhook.test.ts

@@ -24,6 +24,9 @@ const {
   resetGuidanceCacheMock,
   setActiveSessionMock,
   clearActiveSessionMock,
+  getIssueAffinityMock,
+  configureAffinityTtlMock,
+  resetAffinityForTestingMock,
   readDispatchStateMock,
   getActiveDispatchMock,
   registerDispatchMock,
@@ -97,6 +100,9 @@ const {
   resetGuidanceCacheMock: vi.fn(),
   setActiveSessionMock: vi.fn(),
   clearActiveSessionMock: vi.fn(),
+  getIssueAffinityMock: vi.fn().mockReturnValue(null),
+  configureAffinityTtlMock: vi.fn(),
+  resetAffinityForTestingMock: vi.fn(),
   readDispatchStateMock: vi.fn().mockResolvedValue({ activeDispatches: {} }),
   getActiveDispatchMock: vi.fn().mockReturnValue(null),
   registerDispatchMock: vi.fn().mockResolvedValue(undefined),
@@ -167,9 +173,9 @@ vi.mock("./guidance.js", () => ({
 vi.mock("./active-session.js", () => ({
   setActiveSession: setActiveSessionMock,
   clearActiveSession: clearActiveSessionMock,
-  getIssueAffinity: vi.fn().mockReturnValue(null),
-  _configureAffinityTtl: vi.fn(),
-  _resetAffinityForTesting: vi.fn(),
+  getIssueAffinity: getIssueAffinityMock,
+  _configureAffinityTtl: configureAffinityTtlMock,
+  _resetAffinityForTesting: resetAffinityForTestingMock,
 }));
 
 vi.mock("./dispatch-state.js", () => ({
@@ -358,6 +364,9 @@ afterEach(() => {
   isGuidanceEnabledMock.mockReset().mockReturnValue(false);
   setActiveSessionMock.mockReset();
   clearActiveSessionMock.mockReset();
+  getIssueAffinityMock.mockReset().mockReturnValue(null);
+  configureAffinityTtlMock.mockReset();
+  resetAffinityForTestingMock.mockReset();
   readDispatchStateMock.mockReset().mockResolvedValue({ activeDispatches: {} });
   getActiveDispatchMock.mockReset().mockReturnValue(null);
   registerDispatchMock.mockReset().mockResolvedValue(undefined);

package/src/pipeline/webhook.ts

@@ -336,6 +336,7 @@ export async function handleLinearWebhook(
     const profiles = loadAgentProfiles();
     const mentionPattern = buildMentionPattern(profiles);
     let agentId = resolveAgentId(api);
+    let mentionOverride = false;
     if (mentionPattern && userMessage) {
       const mentionMatch = userMessage.match(mentionPattern);
       if (mentionMatch) {
@@ -344,11 +345,12 @@ export async function handleLinearWebhook(
         if (resolved) {
           api.logger.info(`AgentSession routed to ${resolved.agentId} via @${alias} mention`);
           agentId = resolved.agentId;
+          mentionOverride = true;
         }
       }
     }
     // Session affinity: if no @mention override, prefer the agent that last handled this issue
-    if (agentId === resolveAgentId(api) && issue?.id) {
+    if (!mentionOverride && issue?.id) {
       const affinityAgent = getIssueAffinity(issue.id);
       if (affinityAgent) {
         api.logger.info(`AgentSession routed to ${affinityAgent} via session affinity for ${issue.identifier ?? issue.id}`);
@@ -555,6 +557,7 @@ export async function handleLinearWebhook(
     const promptedProfiles = loadAgentProfiles();
     const promptedMentionPattern = buildMentionPattern(promptedProfiles);
     let agentId = resolveAgentId(api);
+    let mentionOverride = false;
     if (promptedMentionPattern && userMessage) {
       const mentionMatch = userMessage.match(promptedMentionPattern);
       if (mentionMatch) {
@@ -563,11 +566,12 @@ export async function handleLinearWebhook(
         if (resolved) {
           api.logger.info(`AgentSession prompted: routed to ${resolved.agentId} via @${alias} mention`);
           agentId = resolved.agentId;
+          mentionOverride = true;
         }
       }
     }
     // Session affinity: if no @mention override, prefer the agent that last handled this issue
-    if (agentId === resolveAgentId(api) && issue?.id) {
+    if (!mentionOverride && issue?.id) {
       const affinityAgent = getIssueAffinity(issue.id);
       if (affinityAgent) {
         api.logger.info(`AgentSession prompted: routed to ${affinityAgent} via session affinity for ${issue.identifier ?? issue.id}`);