@calltelemetry/openclaw-linear 0.9.2 → 0.9.4

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.4",
   "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__/smoke-linear-api.test.ts

@@ -10,13 +10,14 @@
  */
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { LinearAgentApi } from "../api/linear-api.js";
 
 // ── Setup ──────────────────────────────────────────────────────────
 
 const AUTH_PROFILES_PATH = join(
-  process.env.HOME ?? "/home/claw",
+  homedir(),
   ".openclaw",
   "auth-profiles.json",
 );

package/src/__test__/webhook-scenarios.test.ts

@@ -87,6 +87,9 @@ vi.mock("../pipeline/pipeline.js", () => ({
 vi.mock("../pipeline/active-session.js", () => ({
   setActiveSession: mockSetActiveSession,
   clearActiveSession: mockClearActiveSession,
+  getIssueAffinity: vi.fn().mockReturnValue(null),
+  _configureAffinityTtl: vi.fn(),
+  _resetAffinityForTesting: vi.fn(),
 }));
 
 vi.mock("../infra/observability.js", () => ({

package/src/agent/agent.ts

@@ -1,6 +1,8 @@
 import { randomUUID } from "node:crypto";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
 import { mkdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { LinearAgentApi, ActivityContent } from "../api/linear-api.js";
 import { InactivityWatchdog, resolveWatchdogConfig } from "./watchdog.js";
@@ -15,7 +17,7 @@ interface AgentDirs {
 }
 
 function resolveAgentDirs(agentId: string, config: Record<string, any>): AgentDirs {
-  const home = process.env.HOME ?? "/home/claw";
+  const home = homedir();
   const agentList = config?.agents?.list as Array<Record<string, any>> | undefined;
   const agentEntry = agentList?.find((a) => a.id === agentId);
 
@@ -33,13 +35,13 @@ function resolveAgentDirs(agentId: string, config: Record<string, any>): AgentDi
 }
 
 // Import extensionAPI for embedded agent runner (internal, not in public SDK)
-let _extensionAPI: typeof import("/home/claw/.npm-global/lib/node_modules/openclaw/dist/extensionAPI.js") | null = null;
+let _extensionAPI: any | null = null;
 async function getExtensionAPI() {
   if (!_extensionAPI) {
-    // Dynamic import to avoid blocking module load if unavailable
-    _extensionAPI = await import(
-      "/home/claw/.npm-global/lib/node_modules/openclaw/dist/extensionAPI.js"
-    );
+    // Resolve the openclaw package location dynamically, then import extensionAPI
+    const _require = createRequire(import.meta.url);
+    const openclawDir = dirname(_require.resolve("openclaw/package.json"));
+    _extensionAPI = await import(join(openclawDir, "dist", "extensionAPI.js"));
   }
   return _extensionAPI;
 }

package/src/agent/watchdog.ts

@@ -129,7 +129,7 @@ interface AgentProfileWatchdog {
   toolTimeoutSec?: number;
 }
 
-const PROFILES_PATH = join(process.env.HOME ?? "/home/claw", ".openclaw", "agent-profiles.json");
+const PROFILES_PATH = join(homedir(), ".openclaw", "agent-profiles.json");
 
 function loadProfileWatchdog(agentId: string): AgentProfileWatchdog | null {
   try {

package/src/api/linear-api.ts

@@ -1,11 +1,12 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 import { refreshLinearToken } from "./auth.js";
 import { withResilience } from "../infra/resilience.js";
 
 export const LINEAR_GRAPHQL_URL = "https://api.linear.app/graphql";
 export const AUTH_PROFILES_PATH = join(
-  process.env.HOME ?? "/home/claw",
+  homedir(),
   ".openclaw",
   "auth-profiles.json",
 );

package/src/api/oauth-callback.ts

@@ -2,10 +2,11 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import { writeFileSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { homedir } from "node:os";
 
 const LINEAR_OAUTH_TOKEN_URL = "https://api.linear.app/oauth/token";
 const AUTH_PROFILES_PATH = join(
-  process.env.HOME ?? "/home/claw",
+  homedir(),
   ".openclaw",
   "auth-profiles.json",
 );

package/src/infra/cli.ts

@@ -846,8 +846,8 @@ async function reposAction(
     console.log(`\n  No "repos" configured in plugin config.`);
     console.log(`  Add a repos map to openclaw.json → plugins.entries.openclaw-linear.config:`);
     console.log(`\n    "repos": {`);
-    console.log(`      "api": "/home/claw/repos/api",`);
-    console.log(`      "frontend": "/home/claw/repos/frontend"`);
+    console.log(`      "api": "~/repos/api",`);
+    console.log(`      "frontend": "~/repos/frontend"`);
     console.log(`    }\n`);
     return;
   }

package/src/infra/codex-worktree.ts

@@ -5,7 +5,7 @@ import path from "node:path";
 import { ensureGitignore } from "../pipeline/artifacts.js";
 import type { RepoConfig } from "./multi-repo.js";
 
-const DEFAULT_BASE_REPO = "/home/claw/ai-workspace";
+const DEFAULT_BASE_REPO = path.join(homedir(), "ai-workspace");
 const DEFAULT_WORKTREE_BASE_DIR = path.join(homedir(), ".openclaw", "worktrees");
 
 export interface WorktreeInfo {
@@ -22,7 +22,7 @@ export interface WorktreeStatus {
 }
 
 export interface WorktreeOptions {
-  /** Base git repo to create worktrees from. Default: /home/claw/ai-workspace */
+  /** Base git repo to create worktrees from. Default: ~/ai-workspace */
   baseRepo?: string;
   /** Directory under which worktrees are created. Default: ~/.openclaw/worktrees */
   baseDir?: string;

package/src/infra/config-paths.test.ts

@@ -33,6 +33,9 @@ vi.mock("../api/linear-api.js", () => ({
 vi.mock("../pipeline/active-session.js", () => ({
   setActiveSession: vi.fn(),
   clearActiveSession: vi.fn(),
+  getIssueAffinity: vi.fn().mockReturnValue(null),
+  _configureAffinityTtl: vi.fn(),
+  _resetAffinityForTesting: vi.fn(),
 }));
 
 vi.mock("../infra/observability.js", () => ({