@calltelemetry/openclaw-linear 0.8.8 → 0.9.1

package/README.md

@@ -1,5 +1,8 @@
 # @calltelemetry/openclaw-linear
 
+[![CI](https://github.com/calltelemetry/openclaw-linear-plugin/actions/workflows/ci.yml/badge.svg)](https://github.com/calltelemetry/openclaw-linear-plugin/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/calltelemetry/openclaw-linear-plugin/graph/badge.svg)](https://codecov.io/gh/calltelemetry/openclaw-linear-plugin)
+[![npm](https://img.shields.io/npm/v/@calltelemetry/openclaw-linear)](https://www.npmjs.com/package/@calltelemetry/openclaw-linear)
 [![OpenClaw](https://img.shields.io/badge/OpenClaw-v2026.2+-blue)](https://github.com/calltelemetry/openclaw)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
@@ -7,6 +10,55 @@ Connect Linear to AI agents. Issues get triaged, implemented, and audited — au
 
 ---
 
+## Why This Exists
+
+Linear is a great project tracker. But it doesn't orchestrate AI agents — it just gives you issues, comments, and sessions. Without something bridging that gap, every stage of an AI-driven workflow requires a human in the loop: copy the issue context, start an agent, wait, read the output, decide what's next, start another agent, paste in the feedback, repeat. That's not autonomous — that's babysitting.
+
+This plugin makes the full lifecycle hands-off:
+
+```mermaid
+sequenceDiagram
+    actor You
+    participant Linear
+    participant Plugin
+    participant Worker as Worker Agent
+    participant Auditor as Auditor Agent
+
+    You->>Linear: Create issue
+    Note over Plugin: auto-triage
+    Linear-->>You: Estimate, labels, priority
+
+    You->>Linear: Assign to agent
+    Plugin->>Worker: dispatch (isolated worktree)
+    Worker-->>Plugin: implementation done
+    Plugin->>Auditor: audit (automatic, hard-enforced)
+    alt Pass
+        Auditor-->>Plugin: ✅ verdict
+        Plugin-->>Linear: Done
+    else Fail (retries left)
+        Auditor-->>Plugin: ❌ gaps
+        Plugin->>Worker: rework (gaps injected)
+    else Fail (no retries)
+        Auditor-->>Plugin: ❌ stuck
+        Plugin-->>You: 🚨 needs your help
+    end
+```
+
+**What Linear can't do on its own — and what this plugin handles:**
+
+| Problem | What the plugin does |
+|---|---|
+| **No agent orchestration** | Assigns complexity tiers, picks the right model, creates isolated worktrees, runs workers, triggers audits, processes verdicts — all from a single issue assignment |
+| **No independent verification** | Hard-enforces a worker → auditor boundary in plugin code. The worker cannot mark its own work done. The audit is not optional and not LLM-mediated. |
+| **No failure recovery** | Watchdog kills hung agents after configurable silence. Retries once automatically. Feeds audit failures back as context for rework. Escalates when retries are exhausted. |
+| **No multi-agent routing** | Routes `@mentions` and natural language ("hey kaylee look at this") to specific agents. Intent classifier handles plan requests, questions, close commands, and work requests. |
+| **No webhook deduplication** | Linear sends events from two separate webhook systems that can overlap. The plugin deduplicates across session IDs, comment IDs, and assignment events with a 60s sliding window. |
+| **No project-scale planning** | Planner interviews you, creates issues with user stories and acceptance criteria, runs a cross-model review, then dispatches the full dependency graph — up to 3 issues in parallel. |
+
+The end result: you work in Linear. You create issues, assign them, comment in plain English. The agents do the rest — or tell you when they can't.
+
+---
+
 ## What It Does
 
 - **New issue?** Agent estimates story points, adds labels, sets priority.
@@ -29,7 +81,127 @@ Connect Linear to AI agents. Issues get triaged, implemented, and audited — au
 openclaw plugins install @calltelemetry/openclaw-linear
 ```
 
-### 2. Create a Linear OAuth app
+### 2. Expose the gateway (Cloudflare Tunnel)
+
+Linear sends webhook events over the public internet, so the gateway must be reachable via HTTPS. A [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is the recommended approach — no open ports, no TLS cert management, no static IP required.
+
+```mermaid
+flowchart TB
+    subgraph Internet
+        LW["Linear Webhooks<br/><i>Comment, Issue, AgentSession</i>"]
+        LO["Linear OAuth<br/><i>callback redirect</i>"]
+        You["You<br/><i>browser, curl</i>"]
+    end
+
+    subgraph CF["Cloudflare Edge"]
+        TLS["TLS termination<br/>DDoS protection"]
+    end
+
+    subgraph Server["Your Server"]
+        CD["cloudflared<br/><i>outbound-only tunnel</i>"]
+        GW["openclaw-gateway<br/><i>localhost:18789</i>"]
+    end
+
+    LW -- "POST /linear/webhook" --> TLS
+    LO -- "GET /linear/oauth/callback" --> TLS
+    You -- "HTTPS" --> TLS
+    TLS -- "tunnel" --> CD
+    CD -- "HTTP" --> GW
+```
+
+**How it works:** `cloudflared` opens an outbound connection to Cloudflare's edge and keeps it alive. Cloudflare routes incoming HTTPS requests for your hostname back through the tunnel to `localhost:18789`. No inbound firewall rules needed.
+
+#### Install cloudflared
+
+```bash
+# RHEL / Rocky / Alma
+sudo dnf install -y cloudflared
+
+# Debian / Ubuntu
+curl -fsSL https://pkg.cloudflare.com/cloudflare-main.gpg | sudo tee /usr/share/keyrings/cloudflare-main.gpg >/dev/null
+echo "deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared $(lsb_release -cs) main" \
+  | sudo tee /etc/apt/sources.list.d/cloudflared.list
+sudo apt update && sudo apt install -y cloudflared
+
+# macOS
+brew install cloudflare/cloudflare/cloudflared
+```
+
+#### Authenticate with Cloudflare
+
+```bash
+cloudflared tunnel login
+```
+
+This opens your browser. You must:
+1. Log in to your Cloudflare account
+2. **Select the domain** (zone) for the tunnel (e.g., `yourdomain.com`)
+3. Click **Authorize**
+
+Cloudflare writes an origin certificate to `~/.cloudflared/cert.pem`. This cert grants `cloudflared` permission to create tunnels and DNS records under that domain.
+
+> **Prerequisite:** Your domain must already be on Cloudflare (nameservers pointed to Cloudflare). If it's not, add it in the Cloudflare dashboard first.
+
+#### Create a tunnel
+
+```bash
+cloudflared tunnel create openclaw-linear
+```
+
+This outputs a **Tunnel ID** (UUID like `da1f21bf-856e-...`) and writes credentials to `~/.cloudflared/<TUNNEL_ID>.json`.
+
+#### DNS — point your hostname to the tunnel
+
+```bash
+cloudflared tunnel route dns openclaw-linear linear.yourdomain.com
+```
+
+This creates a CNAME record in Cloudflare DNS: `linear.yourdomain.com → <TUNNEL_ID>.cfargotunnel.com`. You can verify it in the Cloudflare dashboard under **DNS > Records**. You can also create this record manually.
+
+The hostname you choose here is what you'll use for **both** webhook URLs and the OAuth redirect URI in Linear. Make sure they all match.
+
+#### Configure the tunnel
+
+Create `/etc/cloudflared/config.yml` (system-wide) or `~/.cloudflared/config.yml` (user):
+
+```yaml
+tunnel: <TUNNEL_ID>
+credentials-file: /home/<user>/.cloudflared/<TUNNEL_ID>.json
+
+ingress:
+  - hostname: linear.yourdomain.com
+    service: http://localhost:18789
+  - service: http_status:404    # catch-all, reject unmatched requests
+```
+
+The `ingress` rule routes all traffic for your hostname to the gateway on localhost. The catch-all `http_status:404` rejects requests for any other hostname.
+
+#### Run as a service
+
+```bash
+# Install as system service (recommended for production)
+sudo cloudflared service install
+sudo systemctl enable --now cloudflared
+```
+
+To test without installing as a service:
+
+```bash
+cloudflared tunnel run openclaw-linear
+```
+
+#### Verify end-to-end
+
+```bash
+curl -s https://linear.yourdomain.com/linear/webhook \
+  -X POST -H "Content-Type: application/json" \
+  -d '{"type":"test","action":"ping"}'
+# Should return: "ok"
+```
+
+> **Tip:** Keep the tunnel running at all times. If `cloudflared` stops, Linear webhook deliveries will fail silently — the gateway won't know about new issues, comments, or agent sessions until the tunnel is restored.
+
+### 3. Create a Linear OAuth app
 
 Go to **Linear Settings > API > Applications** and create an app:
 
@@ -40,7 +212,7 @@ Go to **Linear Settings > API > Applications** and create an app:
 
 > You also need a **workspace webhook** — run `openclaw openclaw-linear webhooks setup` to auto-provision it, or manually create one in Settings > API > Webhooks pointing to the same URL with **Comment + Issue** events enabled. Both webhooks are required.
 
-### 3. Set credentials
+### 4. Set credentials
 
 ```bash
 export LINEAR_CLIENT_ID="your_client_id"
@@ -57,7 +229,7 @@ Environment=LINEAR_CLIENT_SECRET=your_client_secret
 
 Then reload: `systemctl --user daemon-reload && systemctl --user restart openclaw-gateway`
 
-### 4. Authorize
+### 5. Authorize
 
 ```bash
 openclaw openclaw-linear auth
@@ -69,7 +241,7 @@ This opens your browser. Approve the authorization, then restart:
 systemctl --user restart openclaw-gateway
 ```
 
-### 5. Verify
+### 6. Verify
 
 ```bash
 openclaw openclaw-linear status
@@ -96,24 +268,48 @@ That's it. Create an issue in Linear and watch the agent respond.
 
 ## How It Works — Step by Step
 
-Every issue moves through a clear pipeline. Here's exactly what happens at each stage and what you'll see in Linear.
-
+Every issue moves through a clear pipeline. Here's the full interaction flow between you, Linear, the plugin, and the agents:
+
+```mermaid
+sequenceDiagram
+    participant You
+    participant Linear
+    participant Plugin
+    participant Agents
+
+    You->>Linear: Create issue
+    Linear->>Plugin: Webhook (Issue.create)
+    Plugin->>Agents: Triage agent
+    Agents-->>Plugin: Estimate + labels
+    Plugin-->>Linear: Update issue
+    Plugin-->>Linear: Post assessment
+
+    You->>Linear: Assign to agent
+    Linear->>Plugin: Webhook (Issue.update)
+    Plugin->>Agents: Worker agent
+    Agents-->>Linear: Streaming status
+    Plugin->>Agents: Audit agent (automatic)
+    Agents-->>Plugin: JSON verdict
+    Plugin-->>Linear: Result comment
+
+    You->>Linear: Comment "@kaylee review"
+    Linear->>Plugin: Webhook (Comment)
+    Plugin->>Agents: Kaylee agent
+    Agents-->>Plugin: Response
+    Plugin-->>Linear: Branded comment
 ```
- ┌─────────┐    ┌──────────┐    ┌────────┐    ┌───────┐    ┌──────────┐
- │ Triage  │───▶│ Dispatch │───▶│ Worker │───▶│ Audit │───▶│  Done ✔  │
- │(auto)   │    │(you      │    │(auto)  │    │(auto) │    │          │
- │         │    │ assign)  │    │        │    │       │    └──────────┘
- └─────────┘    └──────────┘    └────────┘    └───┬───┘
-                                                  │
-                                    ┌─────────────┤
-                                    ▼             ▼
-                              ┌──────────┐  ┌───────────────┐
-                              │ Rework   │  │ Needs Your    │
-                              │ (auto    │  │ Help ⚠        │
-                              │  retry)  │  │ (escalated)   │
-                              └────┬─────┘  └───────────────┘
-                                   │
-                                   └──▶ back to Worker
+
+Here's what each stage does, and what you'll see in Linear:
+
+```mermaid
+flowchart LR
+    A["Triage<br/><i>(auto)</i>"] --> B["Dispatch<br/><i>(you assign)</i>"]
+    B --> C["Worker<br/><i>(auto)</i>"]
+    C --> D["Audit<br/><i>(auto)</i>"]
+    D --> E["Done ✔"]
+    D --> F["Rework<br/><i>(auto retry)</i>"]
+    D --> G["Needs Your<br/>Help ⚠<br/><i>(escalated)</i>"]
+    F --> C
 ```
 
 ### Stage 1: Triage (automatic)
@@ -136,7 +332,7 @@ The agent assesses complexity, picks an appropriate model, creates an isolated g
 
 **What you'll see in Linear:**
 
-> **Dispatched** as **senior** (anthropic/claude-opus-4-6)
+> **Dispatched** as **high** (anthropic/claude-opus-4-6)
 > > Complex multi-service refactor with migration concerns
 >
 > Worktree: `/home/claw/worktrees/ENG-100` (fresh)
@@ -153,9 +349,9 @@ The agent assesses complexity, picks an appropriate model, creates an isolated g
 
 | Tier | Model | When |
 |---|---|---|
-| Junior | claude-haiku-4-5 | Simple config changes, typos, one-file fixes |
-| Medior | claude-sonnet-4-6 | Standard features, multi-file changes |
-| Senior | claude-opus-4-6 | Complex refactors, architecture changes |
+| Small | claude-haiku-4-5 | Simple config changes, typos, one-file fixes |
+| Medium | claude-sonnet-4-6 | Standard features, multi-file changes |
+| High | claude-opus-4-6 | Complex refactors, architecture changes |
 
 ### Stage 3: Implementation (automatic)
 
@@ -291,10 +487,12 @@ If something went wrong, start with `log.jsonl` — it shows every phase, how lo
 
 You don't need to memorize magic commands. The bot uses an LLM-based intent classifier to understand what you want from any comment.
 
-```
-User comment → Intent Classifier (small model, ~2s) → Route to handler
-                         ↓ (on failure)
-                    Regex fallback → Route to handler
+```mermaid
+flowchart LR
+    A["User comment"] --> B["Intent Classifier<br/><i>(small model, ~2s)</i>"]
+    B --> C["Route to handler"]
+    B -. "on failure" .-> D["Regex fallback"]
+    D --> C
 ```
 
 **What the bot understands:**
@@ -753,7 +951,7 @@ rework:
 | `{{title}}` | Issue title |
 | `{{description}}` | Full issue body |
 | `{{worktreePath}}` | Path to the git worktree |
-| `{{tier}}` | Complexity tier (junior/medior/senior) |
+| `{{tier}}` | Complexity tier (small/medium/high) |
 | `{{attempt}}` | Current attempt number |
 | `{{gaps}}` | Audit gaps from previous attempt |
 | `{{projectName}}` | Project name (planner prompts) |
@@ -853,7 +1051,7 @@ If you don't tag the issue at all, the plugin uses your `codexBaseRepo` setting
 
 When the agent picks up a multi-repo issue, the dispatch comment tells you:
 
-> **Dispatched** as **senior** (anthropic/claude-opus-4-6)
+> **Dispatched** as **high** (anthropic/claude-opus-4-6)
 >
 > Worktrees:
 > - `api` → `/home/claw/worktrees/ENG-100/api`
@@ -1025,30 +1223,15 @@ Both must point to the same URL. `AgentSessionEvent` payloads carry workspace/te
 
 The handler dispatches by `type + action`:
 
-```
-Incoming POST /linear/webhook
-  │
-  ├─ type=AgentSessionEvent, action=created
-  │    └─ New agent session → dedup → scan message for @mentions →
-  │       route to mentioned agent (or default) → run agent
-  │
-  ├─ type=AgentSessionEvent, action=prompted
-  │    └─ Follow-up message → dedup → scan message for @mentions →
-  │       route to mentioned agent (one-time detour, or default) → resume agent
-  │
-  ├─ type=Comment, action=create
-  │    └─ Comment on issue → filter self-comments (viewerId) → dedup →
-  │       intent classify → route to handler (see Intent Classification below)
-  │
-  ├─ type=Issue, action=update
-  │    └─ Issue field changed → check assignment → if assigned to app user →
-  │       dispatch (triage or full implementation)
-  │
-  ├─ type=Issue, action=create
-  │    └─ New issue created → triage (estimate, labels, priority)
-  │
-  └─ type=AppUserNotification
-       └─ Immediately discarded (duplicates workspace webhook events)
+```mermaid
+flowchart TD
+    A["POST /linear/webhook"] --> B{"Event Type"}
+    B --> C["AgentSessionEvent.created<br/>→ dedup → scan @mentions → run agent"]
+    B --> D["AgentSessionEvent.prompted<br/>→ dedup → scan @mentions → resume agent"]
+    B --> E["Comment.create<br/>→ filter self → dedup → intent classify → route"]
+    B --> F["Issue.update<br/>→ check assignment → dispatch"]
+    B --> G["Issue.create<br/>→ triage (estimate, labels, priority)"]
+    B --> H["AppUserNotification<br/>→ discarded (duplicates workspace events)"]
 ```
 
 ### Intent Classification
@@ -1100,16 +1283,15 @@ Agent responses follow an **emitActivity-first** pattern:
 
 When intent classification returns `close_issue`:
 
-```
-close_issue intent
-  │
-  ├─ Fetch full issue details (getIssueDetails)
-  ├─ Find team's "completed" state (getTeamStates → type=completed)
-  ├─ Create agent session on issue (createSessionOnIssue)
-  ├─ Emit "preparing closure report" thought (emitActivity)
-  ├─ Run agent in read-only mode to generate closure report (runAgent)
-  ├─ Transition issue state to completed (updateIssue → stateId)
-  └─ Post closure report (emitActivity → createComment fallback)
+```mermaid
+flowchart TD
+    A["close_issue intent"] --> B["Fetch issue details"]
+    B --> C["Find team's completed state"]
+    C --> D["Create agent session on issue"]
+    D --> E["Emit 'preparing closure report' thought"]
+    E --> F["Run agent in read-only mode<br/><i>(generates closure report)</i>"]
+    F --> G["Transition issue → completed"]
+    G --> H["Post closure report<br/><i>(emitActivity → createComment fallback)</i>"]
 ```
 
 This is a **static action** — the intent triggers direct API calls orchestrated by the plugin, not by giving the agent write tools. The agent only generates the closure report text; all state transitions are handled by the plugin.
@@ -1118,37 +1300,43 @@ This is a **static action** — the intent triggers direct API calls orchestrate
 
 The full dispatch flow for implementing an issue:
 
-```
-Issue assigned to app user
-  │
-  ├─ 1. Assess complexity tier (runAgent → junior/medior/senior)
-  ├─ 2. Create isolated git worktree (createWorktree)
-  ├─ 3. Register dispatch in state file (registerDispatch)
-  ├─ 4. Write .claw/manifest.json with issue metadata
-  ├─ 5. Notify: "dispatched as {tier}"
-  │
-  ├─ 6. Worker phase (spawnWorker)
-  │    ├─ Build prompt from prompts.yaml (worker.system + worker.task)
-  │    ├─ If retry: append rework.addendum with prior audit gaps
-  │    ├─ Tool access: code_run YES, linear_issues NO
-  │    └─ Output captured as text → saved to .claw/worker-{attempt}.md
-  │
-  ├─ 7. Audit phase (triggerAudit)
-  │    ├─ Build prompt from prompts.yaml (audit.system + audit.task)
-  │    ├─ Tool access: code_run YES, linear_issues READ+WRITE
-  │    ├─ Auditor verifies acceptance criteria, runs tests, reviews diff
-  │    └─ Must return JSON verdict: {pass, criteria, gaps, testResults}
-  │
-  └─ 8. Verdict (processVerdict)
-       ├─ PASS → updateIssue(stateId=Done), post summary, notify ✅
-       ├─ FAIL + retries left → back to step 6 with audit gaps as context
-       └─ FAIL + no retries → escalate, notify 🚨, status="stuck"
+```mermaid
+flowchart TD
+    A["Issue assigned to app user"] --> B["1. Assess complexity tier<br/><i>junior / medior / senior</i>"]
+    B --> C["2. Create isolated git worktree"]
+    C --> D["3. Register dispatch in state file"]
+    D --> E["4. Write .claw/manifest.json"]
+    E --> F["5. Notify: dispatched as tier"]
+
+    F --> W["6. Worker phase<br/><i>code_run: YES, linear_issues: NO</i><br/>Build prompt → implement → save to .claw/"]
+    W -->|"plugin code — automatic"| AU["7. Audit phase<br/><i>code_run: YES, linear_issues: READ+WRITE</i><br/>Verify criteria → run tests → JSON verdict"]
+
+    AU --> V{"8. Verdict"}
+    V -->|PASS| DONE["Done ✔<br/>updateIssue → notify"]
+    V -->|"FAIL ≤ max"| RW["Rework<br/><i>attempt++, inject audit gaps</i>"]
+    RW --> W
+    V -->|"FAIL > max"| STUCK["Stuck 🚨<br/>escalate + notify"]
 ```
 
 **State persistence:** Dispatch state is written to `~/.openclaw/linear-dispatch-state.json` with active dispatches, completed history, session mappings, and processed event IDs.
 
 **Watchdog:** A configurable inactivity timer (`inactivitySec`, default 120s) monitors agent output. If no tool calls or text output for the configured period, the agent process is killed and retried once. If the retry also times out, the dispatch is escalated.
 
+### Dispatch State Machine
+
+All transitions use compare-and-swap (CAS) to prevent races. `dispatch-state.json` is the canonical source of truth.
+
+```mermaid
+stateDiagram-v2
+    [*] --> DISPATCHED
+    DISPATCHED --> WORKING
+    WORKING --> AUDITING
+    AUDITING --> DONE
+    AUDITING --> WORKING : FAIL (attempt++)
+    WORKING --> STUCK : watchdog kill 2x
+    AUDITING --> STUCK : attempt > max
+```
+
 ### `linear_issues` Tool → API Mapping
 
 The `linear_issues` registered tool translates agent requests into `LinearAgentApi` method calls:
@@ -1293,7 +1481,7 @@ npx tsx scripts/uat-linear.ts --test intent
 ```
 [dispatch] Created issue ENG-200: "UAT: simple config tweak"
 [dispatch] Assigned to agent — waiting for dispatch comment...
-[dispatch] ✔ Dispatch confirmed (12s) — assessed as junior
+[dispatch] ✔ Dispatch confirmed (12s) — assessed as small
 [dispatch] Waiting for audit result...
 [dispatch] ✔ Audit passed (94s) — issue marked done
 [dispatch] Total: 106s
@@ -1444,6 +1632,7 @@ journalctl --user -u openclaw-gateway -f         # Watch live logs
 | `code_run` uses wrong backend | Check `coding-tools.json` — explicit backend > per-agent > global default. Run `code-run doctor` to see routing. |
 | `code_run` fails at runtime | Run `openclaw openclaw-linear code-run doctor` — checks binary, API key, and live callability for each backend. |
 | Webhook events not arriving | Run `openclaw openclaw-linear webhooks setup` to auto-provision. Both webhooks must point to `/linear/webhook`. Check tunnel is running. |
+| Tunnel down / webhooks silently failing | `systemctl status cloudflared` (or `systemctl --user status cloudflared`). Restart with `systemctl restart cloudflared`. Test: `curl -s -X POST https://your-domain.com/linear/webhook -H 'Content-Type: application/json' -d '{"type":"test"}'` — should return `"ok"`. |
 | OAuth token expired | Auto-refreshes. If stuck, re-run `openclaw openclaw-linear auth` and restart. |
 | Audit always fails | Run `openclaw openclaw-linear prompts validate` to check prompt syntax. |
 | Multi-repo not detected | Markers must be `<!-- repos: name1, name2 -->`. Names must match `repos` config keys. |

package/index.ts

@@ -1,4 +1,6 @@
 import { execFileSync } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { registerLinearProvider } from "./src/api/auth.js";
 import { registerCli } from "./src/infra/cli.js";
@@ -8,7 +10,7 @@ import { handleOAuthCallback } from "./src/api/oauth-callback.js";
 import { LinearAgentApi, resolveLinearToken } from "./src/api/linear-api.js";
 import { createDispatchService } from "./src/pipeline/dispatch-service.js";
 import { registerDispatchMethods } from "./src/gateway/dispatch-methods.js";
-import { readDispatchState, lookupSessionMapping, getActiveDispatch } from "./src/pipeline/dispatch-state.js";
+import { readDispatchState, lookupSessionMapping, getActiveDispatch, transitionDispatch, type DispatchStatus } from "./src/pipeline/dispatch-state.js";
 import { triggerAudit, processVerdict, type HookContext } from "./src/pipeline/pipeline.js";
 import { createNotifierFromConfig, type NotifyFn } from "./src/infra/notify.js";
 import { readPlanningState, setPlanningCache } from "./src/pipeline/planning-state.js";
@@ -169,6 +171,35 @@ export default function register(api: OpenClawPluginApi) {
       }
     } catch (err) {
       api.logger.error(`agent_end hook error: ${err}`);
+      // Escalate: mark dispatch as stuck so it's visible
+      try {
+        const statePath = pluginConfig?.dispatchStatePath as string | undefined;
+        const state = await readDispatchState(statePath);
+        const sessionKey = ctx?.sessionKey ?? "";
+        const mapping = sessionKey ? lookupSessionMapping(state, sessionKey) : null;
+        if (mapping) {
+          const dispatch = getActiveDispatch(state, mapping.dispatchId);
+          if (dispatch && dispatch.status !== "done" && dispatch.status !== "stuck" && dispatch.status !== "failed") {
+            const stuckReason = `Hook error: ${err instanceof Error ? err.message : String(err)}`.slice(0, 500);
+            await transitionDispatch(
+              mapping.dispatchId,
+              dispatch.status as DispatchStatus,
+              "stuck",
+              { stuckReason },
+              statePath,
+            );
+            // Notify if possible
+            await notify("escalation", {
+              identifier: dispatch.issueIdentifier,
+              title: dispatch.issueTitle ?? "Unknown",
+              status: "stuck",
+              reason: `Dispatch failed in ${mapping.phase} phase: ${stuckReason}`,
+            }).catch(() => {}); // Don't fail on notification failure
+          }
+        }
+      } catch (escalateErr) {
+        api.logger.error(`agent_end escalation also failed: ${escalateErr}`);
+      }
     }
   });
 
@@ -222,10 +253,11 @@ export default function register(api: OpenClawPluginApi) {
 
   // Check CLI availability (Codex, Claude, Gemini)
   const cliChecks: Record<string, string> = {};
+  const defaultBinDir = join(process.env.HOME ?? homedir(), ".npm-global", "bin");
   const cliBins: [string, string, string][] = [
-    ["codex", "/home/claw/.npm-global/bin/codex", "npm install -g @openai/codex"],
-    ["claude", "/home/claw/.npm-global/bin/claude", "npm install -g @anthropic-ai/claude-code"],
-    ["gemini", "/home/claw/.npm-global/bin/gemini", "npm install -g @anthropic-ai/gemini-cli"],
+    ["codex", pluginConfig?.codexBin as string ?? join(defaultBinDir, "codex"), "npm install -g @openai/codex"],
+    ["claude", pluginConfig?.claudeBin as string ?? join(defaultBinDir, "claude"), "npm install -g @anthropic-ai/claude-code"],
+    ["gemini", pluginConfig?.geminiBin as string ?? join(defaultBinDir, "gemini"), "npm install -g @anthropic-ai/gemini-cli"],
   ];
   for (const [name, bin, installCmd] of cliBins) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calltelemetry/openclaw-linear",
-  "version": "0.8.8",
+  "version": "0.9.1",
   "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__/webhook-scenarios.test.ts

@@ -98,7 +98,7 @@ vi.mock("../pipeline/intent-classify.js", () => ({
 }));
 
 vi.mock("../pipeline/dispatch-state.js", () => ({
-  readDispatchState: vi.fn().mockResolvedValue({ dispatches: { active: {}, completed: {} }, sessionMap: {} }),
+  readDispatchState: vi.fn().mockResolvedValue({ version: 2, dispatches: { active: {}, completed: {} }, sessionMap: {}, processedEvents: [] }),
   getActiveDispatch: vi.fn().mockReturnValue(null),
   registerDispatch: vi.fn().mockResolvedValue(undefined),
   updateDispatchStatus: vi.fn().mockResolvedValue(undefined),

package/src/gateway/dispatch-methods.test.ts

@@ -46,7 +46,7 @@ function makeDispatch(overrides?: Record<string, any>) {
     issueIdentifier: "CT-100",
     issueId: "issue-id",
     status: "working",
-    tier: "senior",
+    tier: "high",
     attempt: 0,
     worktreePath: "/wt/ct-100",
     model: "opus",
@@ -129,13 +129,13 @@ describe("dispatch.list", () => {
     const { api, methods } = createApi();
     registerDispatchMethods(api);
 
-    const d1 = makeDispatch({ issueIdentifier: "CT-1", tier: "junior" });
-    const d2 = makeDispatch({ issueIdentifier: "CT-2", tier: "senior" });
+    const d1 = makeDispatch({ issueIdentifier: "CT-1", tier: "small" });
+    const d2 = makeDispatch({ issueIdentifier: "CT-2", tier: "high" });
     mockReadDispatchState.mockResolvedValue(makeState());
     mockListActiveDispatches.mockReturnValue([d1, d2]);
 
     const respond = vi.fn();
-    await methods["dispatch.list"]({ params: { tier: "senior" }, respond });
+    await methods["dispatch.list"]({ params: { tier: "high" }, respond });
 
     const result = respond.mock.calls[0][1];
     expect(result.active).toEqual([d2]);
@@ -167,7 +167,7 @@ describe("dispatch.get", () => {
     const { api, methods } = createApi();
     registerDispatchMethods(api);
 
-    const completed = { status: "done", tier: "junior" };
+    const completed = { status: "done", tier: "small" };
     mockReadDispatchState.mockResolvedValue(makeState({}, { "CT-99": completed }));
     mockGetActiveDispatch.mockReturnValue(undefined);
 
@@ -372,9 +372,9 @@ describe("dispatch.stats", () => {
     registerDispatchMethods(api);
 
     const active = [
-      makeDispatch({ status: "working", tier: "senior" }),
-      makeDispatch({ status: "working", tier: "junior" }),
-      makeDispatch({ status: "stuck", tier: "senior" }),
+      makeDispatch({ status: "working", tier: "high" }),
+      makeDispatch({ status: "working", tier: "small" }),
+      makeDispatch({ status: "stuck", tier: "high" }),
     ];
     mockReadDispatchState.mockResolvedValue(makeState({}, { "CT-99": {} }));
     mockListActiveDispatches.mockReturnValue(active);
@@ -387,7 +387,7 @@ describe("dispatch.stats", () => {
     expect(result.activeCount).toBe(3);
     expect(result.completedCount).toBe(1);
     expect(result.byStatus).toEqual({ working: 2, stuck: 1 });
-    expect(result.byTier).toEqual({ senior: 2, junior: 1 });
+    expect(result.byTier).toEqual({ high: 2, small: 1 });
   });
 
   it("returns zeros when no dispatches", async () => {