@calltelemetry/openclaw-linear 0.9.2 → 0.9.3

package/README.md

@@ -20,22 +20,23 @@ Connect Linear to AI agents. Issues get triaged, implemented, and audited — au
 
 - [x] Cloudflare tunnel setup (webhook ingress, no inbound ports)
 - [x] Linear webhook sync (Comment + Issue events)
+- [x] Linear OAuth app webhook (AgentSessionEvent created/prompted)
 - [x] Linear API integration (issues, comments, labels, state transitions)
 - [x] Agent routing (`@mentions`, natural language intent classifier)
-- [ ] Linear OAuth app webhook (AgentSessionEvent created/prompted)
 - [x] Auto-triage (story points, labels, priority — read-only)
 - [x] Complexity-tier dispatch (small → Haiku, medium → Sonnet, high → Opus)
 - [x] Isolated git worktrees per dispatch
 - [x] Worker → Auditor pipeline (hard-enforced, not LLM-mediated)
-- [ ] Audit rework loop (gaps fed back, automatic retry)
-- [ ] Watchdog timeout + escalation
+- [x] Audit rework loop (gaps fed back, automatic retry)
+- [x] Watchdog timeout + escalation
 - [x] Webhook deduplication (60s sliding window across session/comment/assignment)
 - [ ] Multi-repo worktree support
 - [ ] Project planner (interview → user stories → sub-issues → DAG dispatch)
 - [ ] Cross-model plan review (Claude ↔ Codex ↔ Gemini)
-- [ ] Issue closure with summary report
+- [x] Issue closure with summary report
 - [ ] Sub-issue decomposition (orchestrator-level only)
 - [x] `spawn_agent` / `ask_agent` sub-agent tools
+- [x] CI + coverage badges (1000+ tests, Codecov integration)
 - [ ] **Worktree → PR merge** — `createPullRequest()` exists but is not wired into the pipeline. After audit pass, commits sit on a `codex/{identifier}` branch. You create the PR manually.
 - [ ] **Sub-agent worktree sharing** — Sub-agents spawned via `spawn_agent`/`ask_agent` do not inherit the parent worktree. They run in their own session without code access.
 - [ ] **Parallel worktree conflict resolution** — DAG dispatch runs up to 3 issues concurrently in separate worktrees, but there's no merge conflict detection across them.
@@ -548,11 +549,97 @@ flowchart LR
 >
 > **Summary:** The search API endpoint was implemented with pagination, input validation, and error handling. All 14 tests pass. The frontend search page renders results correctly.
 
-### Timeout recovery
+### Watchdog & timeout recovery
 
-If an agent produces no output for 2 minutes (configurable), the watchdog kills it and retries once. If the retry also times out, the issue is escalated.
+Every running agent has an inactivity watchdog. If the agent goes silent — no text, no tool calls, no thinking — the watchdog kills it.
 
-**Notification:** `⚡ ENG-100 timed out (no activity for 120s). Will retry.`
+```
+Agent runs ─────────── output ──→ timer resets (120s default)
+                       output ──→ timer resets
+                       ...
+                       silence ─→ 120s passes ─→ KILL
+                                                   │
+                                          ┌────────┴────────┐
+                                          ▼                 ▼
+                                    Retry (auto)     Already retried?
+                                          │                 │
+                                          ▼                 ▼
+                                    Agent runs again   STUCK → you're notified
+```
+
+**What resets the timer:** any agent output — partial text, tool call start/result, reasoning stream, or error.
+
+**What triggers a kill:** LLM hangs, API timeouts, CLI lockups, rate limiting — anything that causes the agent to stop producing output.
+
+**After a kill:**
+1. First timeout → automatic retry (new attempt, same worktree)
+2. Second timeout → dispatch transitions to `stuck`, Linear comment posted with remediation steps, you get a notification
+
+**The "Agent Timed Out" comment includes:**
+- `/dispatch retry ENG-100` command to try again
+- Suggestion to break the issue into smaller pieces
+- How to increase `inactivitySec` in agent profiles
+- Path to `.claw/log.jsonl` for debugging
+
+**Configure per agent** in `~/.openclaw/agent-profiles.json`:
+```json
+{ "agents": { "mal": { "watchdog": { "inactivitySec": 180 } } } }
+```
+
+### Audit rework loop
+
+When the auditor finds problems, it doesn't just fail — it tells the worker exactly what's wrong, and the worker tries again automatically.
+
+```
+Worker implements ──→ Auditor reviews
+                          │
+                     ┌────┴────┐
+                     ▼         ▼
+                   PASS      FAIL
+                     │         │
+                     ▼         ▼
+                   Done    Gaps extracted
+                              │
+                              ▼
+                     Worker gets gaps as context ──→ "PREVIOUS AUDIT FAILED:
+                              │                       - Missing input validation
+                              │                       - No test for empty query"
+                              ▼
+                     Rework attempt (same worktree)
+                              │
+                         ┌────┴────┐
+                         ▼         ▼
+                       PASS    FAIL again?
+                         │         │
+                         ▼         ▼
+                       Done    Retries left?
+                                   │
+                              ┌────┴────┐
+                              ▼         ▼
+                            Retry    STUCK → you're notified
+```
+
+**How gaps flow back:**
+1. Auditor returns a structured verdict: `{ pass: false, gaps: ["missing validation", "no empty query test"], criteria: [...] }`
+2. Pipeline extracts the `gaps` array
+3. Next worker prompt gets a "PREVIOUS AUDIT FAILED" addendum with the gap list
+4. Worker sees exactly what to fix — no guessing
+
+**What you control:**
+- `maxReworkAttempts` (default: `2`) — how many audit failures before escalation
+- After max attempts, issue goes to `stuck` with reason `audit_failed_Nx`
+- You get a Linear comment with what went wrong and a notification
+
+**What the worker sees on rework:**
+```
+PREVIOUS AUDIT FAILED — fix these gaps before proceeding:
+1. Missing input validation on the search endpoint
+2. No test for empty query string
+
+Your previous work is still in the worktree. Fix the issues above and run tests again.
+```
+
+**Artifacts per attempt:** Each rework cycle writes `worker-{N}.md` and `audit-{N}.json` to `.claw/`, so you can see what happened at every attempt.
 
 ### Project-level progress
 
@@ -1488,7 +1575,7 @@ This is separate from the main `doctor` because each live test spawns a real CLI
 
 ### Unit tests
 
-551 tests covering the full pipeline — triage, dispatch, audit, planning, intent classification, native issue tools, cross-model review, notifications, and infrastructure:
+1000+ tests covering the full pipeline — triage, dispatch, audit, planning, intent classification, native issue tools, cross-model review, notifications, watchdog, and infrastructure:
 
 ```bash
 cd ~/claw-extensions/linear

package/package.json

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

package/src/pipeline/e2e-dispatch.test.ts

@@ -581,4 +581,139 @@ describe("E2E dispatch pipeline", () => {
       expect(call[0]).toBe("telegram-chat-1");
     }
   });
+
+  // =========================================================================
+  // Test 9: Watchdog kill → stuck with artifact verification
+  // =========================================================================
+  it("watchdog kill writes correct artifacts (log.jsonl, manifest)", async () => {
+    const hookCtx = makeHookCtx();
+    const dispatch = makeDispatch(worktree);
+
+    await registerDispatch(dispatch.issueIdentifier, dispatch, hookCtx.configPath);
+
+    // Pre-create manifest (as webhook.ts handleDispatch would)
+    const { ensureClawDir, writeManifest } = await import("./artifacts.js");
+    ensureClawDir(worktree);
+    writeManifest(worktree, {
+      issueIdentifier: "ENG-100",
+      issueId: "issue-1",
+      tier: "small",
+      status: "dispatched",
+      attempts: 0,
+      dispatchedAt: new Date().toISOString(),
+    });
+
+    hookCtx.mockLinearApi.getIssueDetails.mockResolvedValue(
+      makeIssueDetails({ id: "issue-1", identifier: "ENG-100", title: "Fix auth" }),
+    );
+
+    runAgentMock.mockResolvedValue({
+      success: false,
+      output: "partial work before timeout",
+      watchdogKilled: true,
+    });
+
+    await spawnWorker(hookCtx, dispatch);
+
+    // State should be stuck
+    const state = await readDispatchState(hookCtx.configPath);
+    expect(state.dispatches.active["ENG-100"].status).toBe("stuck");
+    expect(state.dispatches.active["ENG-100"].stuckReason).toBe("watchdog_kill_2x");
+
+    // Artifacts should exist
+    const clawDir = join(worktree, ".claw");
+    expect(existsSync(join(clawDir, "manifest.json"))).toBe(true);
+    expect(existsSync(join(clawDir, "log.jsonl"))).toBe(true);
+
+    // Manifest should reflect stuck status
+    const manifest = JSON.parse(readFileSync(join(clawDir, "manifest.json"), "utf8"));
+    expect(manifest.status).toBe("stuck");
+    expect(manifest.attempts).toBe(1);
+
+    // Log should contain watchdog phase entry
+    const logContent = readFileSync(join(clawDir, "log.jsonl"), "utf8");
+    const logLines = logContent.trim().split("\n").map((l) => JSON.parse(l));
+    const wdEntry = logLines.find((e) => e.phase === "watchdog");
+    expect(wdEntry).toBeDefined();
+    expect(wdEntry.success).toBe(false);
+    expect(wdEntry.watchdog).toBeDefined();
+    expect(wdEntry.watchdog.reason).toBe("inactivity");
+    expect(wdEntry.watchdog.retried).toBe(true);
+    expect(wdEntry.watchdog.thresholdSec).toBeGreaterThan(0);
+    expect(wdEntry.outputPreview).toBe("partial work before timeout");
+
+    // Should NOT have audit artifacts (no audit on watchdog kill)
+    expect(existsSync(join(clawDir, "audit-0.json"))).toBe(false);
+  });
+
+  // =========================================================================
+  // Test 10: Watchdog kill comment includes remediation steps
+  // =========================================================================
+  it("watchdog kill comment includes remediation guidance", async () => {
+    const hookCtx = makeHookCtx();
+    const dispatch = makeDispatch(worktree);
+
+    await registerDispatch(dispatch.issueIdentifier, dispatch, hookCtx.configPath);
+
+    hookCtx.mockLinearApi.getIssueDetails.mockResolvedValue(
+      makeIssueDetails({ id: "issue-1", identifier: "ENG-100", title: "Fix auth" }),
+    );
+
+    runAgentMock.mockResolvedValue({
+      success: false,
+      output: "",
+      watchdogKilled: true,
+    });
+
+    await spawnWorker(hookCtx, dispatch);
+
+    // Comment should include all remediation steps
+    const commentCall = hookCtx.mockLinearApi.createComment.mock.calls[0];
+    expect(commentCall).toBeDefined();
+    const [issueId, comment] = commentCall;
+    expect(issueId).toBe("issue-1");
+    expect(comment).toContain("Agent Timed Out");
+    expect(comment).toContain("Try again");
+    expect(comment).toContain("/dispatch retry ENG-100");
+    expect(comment).toContain("Break it down");
+    expect(comment).toContain("Increase timeout");
+    expect(comment).toContain("inactivitySec");
+    expect(comment).toContain("log.jsonl");
+    expect(comment).toContain("Stuck — waiting for you");
+  });
+
+  // =========================================================================
+  // Test 11: Watchdog notification payload shape
+  // =========================================================================
+  it("watchdog kill sends notification with correct payload", async () => {
+    const hookCtx = makeHookCtx();
+    const dispatch = makeDispatch(worktree);
+
+    await registerDispatch(dispatch.issueIdentifier, dispatch, hookCtx.configPath);
+
+    hookCtx.mockLinearApi.getIssueDetails.mockResolvedValue(
+      makeIssueDetails({ id: "issue-1", identifier: "ENG-100", title: "Fix auth" }),
+    );
+
+    runAgentMock.mockResolvedValue({
+      success: false,
+      output: "",
+      watchdogKilled: true,
+    });
+
+    await spawnWorker(hookCtx, dispatch);
+
+    // Find the watchdog_kill notification
+    const wdNotify = hookCtx.notifyCalls.find(([k]) => k === "watchdog_kill");
+    expect(wdNotify).toBeDefined();
+    const [kind, payload] = wdNotify!;
+    expect(kind).toBe("watchdog_kill");
+    expect(payload).toMatchObject({
+      identifier: "ENG-100",
+      title: "Fix auth",
+      status: "stuck",
+      attempt: 0,
+    });
+    expect((payload as any).reason).toMatch(/no I\/O for \d+s/);
+  });
 });

package/src/pipeline/pipeline.test.ts

@@ -1538,4 +1538,83 @@ describe("spawnWorker (error branch coverage)", () => {
     );
     expect(clearActiveSession).toHaveBeenCalled();
   });
+
+  it("watchdog kill writes log entry with correct shape", async () => {
+    (runAgent as any).mockResolvedValue({
+      success: false,
+      output: "partial output before hang",
+      watchdogKilled: true,
+    });
+    const ctx = makeHookCtx();
+    const dispatch = makeDispatch({ status: "working" as any });
+
+    await spawnWorker(ctx, dispatch);
+
+    // appendLog should be called with watchdog phase
+    expect(appendLog).toHaveBeenCalledWith(
+      dispatch.worktreePath,
+      expect.objectContaining({
+        phase: "watchdog",
+        attempt: dispatch.attempt,
+        prompt: "(watchdog kill)",
+        success: false,
+        watchdog: expect.objectContaining({
+          reason: "inactivity",
+          retried: true,
+          thresholdSec: expect.any(Number),
+        }),
+      }),
+    );
+
+    // Verify output preview is included
+    const logCall = (appendLog as any).mock.calls.find(
+      (c: any[]) => c[1]?.phase === "watchdog",
+    );
+    expect(logCall).toBeDefined();
+    expect(logCall[1].outputPreview).toBe("partial output before hang");
+    expect(logCall[1].durationMs).toBeGreaterThanOrEqual(0);
+  });
+
+  it("watchdog kill updates manifest to stuck", async () => {
+    (runAgent as any).mockResolvedValue({
+      success: false,
+      output: "",
+      watchdogKilled: true,
+    });
+    const ctx = makeHookCtx();
+    const dispatch = makeDispatch({ status: "working" as any });
+
+    await spawnWorker(ctx, dispatch);
+
+    expect(updateManifest).toHaveBeenCalledWith(
+      dispatch.worktreePath,
+      { status: "stuck", attempts: dispatch.attempt + 1 },
+    );
+  });
+
+  it("watchdog kill does not trigger audit", async () => {
+    (runAgent as any).mockResolvedValue({
+      success: false,
+      output: "",
+      watchdogKilled: true,
+    });
+    const ctx = makeHookCtx();
+    const dispatch = makeDispatch({ status: "working" as any });
+
+    await spawnWorker(ctx, dispatch);
+
+    // runAgent should only be called ONCE (for the worker)
+    // NOT a second time (no audit spawned)
+    expect(runAgent).toHaveBeenCalledTimes(1);
+
+    // No audit artifacts should be saved
+    expect(saveAuditVerdict).not.toHaveBeenCalled();
+
+    // Transition should be to stuck, never to auditing
+    expect(transitionDispatch).toHaveBeenCalledWith(
+      "ENG-100", "working", "stuck",
+      expect.objectContaining({ stuckReason: "watchdog_kill_2x" }),
+      expect.any(String),
+    );
+  });
 });