@calltelemetry/openclaw-linear 0.4.1 → 0.5.0

package/src/pipeline.ts

@@ -1,499 +1,654 @@
+/**
+ * pipeline.ts — Dispatch pipeline v2: hook-driven with hard-enforced audit.
+ *
+ * v1 (runFullPipeline) ran plan→implement→audit in a single synchronous flow
+ * with the same agent self-certifying its own work.
+ *
+ * v2 splits into:
+ * - Worker phase: orchestrator spawns worker via plugin code, worker plans + implements
+ * - Audit phase: agent_end hook auto-triggers independent audit (runAgent)
+ * - Verdict phase: agent_end hook processes audit result → done/rework/stuck
+ *
+ * Prompts are loaded from prompts.yaml (sidecar file, customizable).
+ */
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 import type { LinearAgentApi, ActivityContent } from "./linear-api.js";
 import { runAgent } from "./agent.js";
 import { setActiveSession, clearActiveSession } from "./active-session.js";
-import type { Tier } from "./dispatch-state.js";
-import { runCodex } from "./codex-tool.js";
-import { runClaude } from "./claude-tool.js";
-import { runGemini } from "./gemini-tool.js";
-import { resolveCodingBackend, loadCodingConfig, type CodingBackend } from "./code-tool.js";
-import type { CliResult } from "./cli-shared.js";
-
-export interface PipelineContext {
-  api: OpenClawPluginApi;
-  linearApi: LinearAgentApi;
-  agentSessionId: string;
-  agentId: string;
-  issue: {
-    id: string;
-    identifier: string;
-    title: string;
-    description?: string | null;
-  };
-  promptContext?: unknown;
-  /** Populated by implementor stage if Codex creates a worktree */
-  worktreePath?: string | null;
-  /** Codex branch name, e.g. codex/UAT-123 */
-  codexBranch?: string | null;
-  /** Complexity tier selected by tier assessment */
-  tier?: Tier;
-  /** Tier model ID — for display/tracking only, NOT passed to coding CLI */
-  model?: string;
-}
+import {
+  type Tier,
+  type DispatchStatus,
+  type ActiveDispatch,
+  type DispatchState,
+  type SessionMapping,
+  transitionDispatch,
+  registerSessionMapping,
+  markEventProcessed,
+  completeDispatch,
+  TransitionError,
+  readDispatchState,
+  getActiveDispatch,
+} from "./dispatch-state.js";
+import { type NotifyFn } from "./notify.js";
 
 // ---------------------------------------------------------------------------
-// Helpers
+// Prompt loading
 // ---------------------------------------------------------------------------
 
-function emit(ctx: PipelineContext, content: ActivityContent): Promise<void> {
-  return ctx.linearApi.emitActivity(ctx.agentSessionId, content).catch((err) => {
-    ctx.api.logger.error(`[${ctx.issue.identifier}] emit failed: ${err}`);
-  });
+interface PromptTemplates {
+  worker: { system: string; task: string };
+  audit: { system: string; task: string };
+  rework: { addendum: string };
 }
 
-/** Resolve the agent's model string from config for logging/display. */
-function resolveAgentModel(api: OpenClawPluginApi, agentId: string): string {
+const DEFAULT_PROMPTS: PromptTemplates = {
+  worker: {
+    system: "You are implementing a Linear issue. Post an implementation summary as a Linear comment when done. DO NOT mark the issue as Done.",
+    task: "Implement issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}",
+  },
+  audit: {
+    system: "You are an independent auditor. The Linear issue body is the SOURCE OF TRUTH. Worker comments are secondary evidence.",
+    task: 'Audit issue {{identifier}}: {{title}}\n\nIssue body:\n{{description}}\n\nWorktree: {{worktreePath}}\n\nReturn JSON verdict: {"pass": true/false, "criteria": [...], "gaps": [...], "testResults": "..."}',
+  },
+  rework: {
+    addendum: "PREVIOUS AUDIT FAILED (attempt {{attempt}}). Gaps:\n{{gaps}}\n\nAddress these specific issues.",
+  },
+};
+
+let _cachedPrompts: PromptTemplates | null = null;
+
+export function loadPrompts(pluginConfig?: Record<string, unknown>): PromptTemplates {
+  if (_cachedPrompts) return _cachedPrompts;
+
   try {
-    const config = (api as any).runtime?.config?.getCachedConfig?.() ?? {};
-    const agents = config?.agents?.list as Array<Record<string, any>> | undefined;
-    const entry = agents?.find((a) => a.id === agentId);
-    const modelRef: string =
-      entry?.model?.primary ??
-      config?.agents?.defaults?.model?.primary ??
-      "unknown";
-    // Strip provider prefix for display: "openrouter/moonshotai/kimi-k2.5" → "kimi-k2.5"
-    const parts = modelRef.split("/");
-    return parts.length > 1 ? parts.slice(1).join("/") : modelRef;
+    // Try custom path first
+    const customPath = pluginConfig?.promptsPath as string | undefined;
+    let raw: string;
+
+    if (customPath) {
+      const resolved = customPath.startsWith("~")
+        ? customPath.replace("~", process.env.HOME ?? "")
+        : customPath;
+      raw = readFileSync(resolved, "utf-8");
+    } else {
+      // Load from plugin directory (sidecar file)
+      const pluginRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+      raw = readFileSync(join(pluginRoot, "prompts.yaml"), "utf-8");
+    }
+
+    const parsed = parseYaml(raw) as Partial<PromptTemplates>;
+    _cachedPrompts = {
+      worker: { ...DEFAULT_PROMPTS.worker, ...parsed.worker },
+      audit: { ...DEFAULT_PROMPTS.audit, ...parsed.audit },
+      rework: { ...DEFAULT_PROMPTS.rework, ...parsed.rework },
+    };
   } catch {
-    return "unknown";
+    _cachedPrompts = DEFAULT_PROMPTS;
   }
+
+  return _cachedPrompts;
 }
 
-function elapsed(startMs: number): string {
-  const sec = ((Date.now() - startMs) / 1000).toFixed(1);
-  return `${sec}s`;
+/** Clear prompt cache (for testing or after config change) */
+export function clearPromptCache(): void {
+  _cachedPrompts = null;
 }
 
-function toolContext(ctx: PipelineContext): string {
-  const lines = [
-    `\n## code_run Tool`,
-    `When calling \`code_run\`, pass these parameters:`,
-  ];
-  lines.push(`- \`prompt\`: describe what to implement (be specific — file paths, function names, expected behavior)`);
-  if (ctx.worktreePath) {
-    lines.push(`- \`workingDir\`: \`"${ctx.worktreePath}"\``);
+function renderTemplate(template: string, vars: Record<string, string>): string {
+  let result = template;
+  for (const [key, value] of Object.entries(vars)) {
+    result = result.replaceAll(`{{${key}}}`, value);
   }
-  // Don't suggest model override — each coding CLI uses its own configured model
-  lines.push(`Progress streams to Linear automatically. The worktree is an isolated git branch for this issue.`);
-  return lines.join("\n");
+  return result;
 }
 
-const TAG = (ctx: PipelineContext) => `Pipeline [${ctx.issue.identifier}]`;
-
 // ---------------------------------------------------------------------------
-// Stage 1: Planner
+// Task builders
 // ---------------------------------------------------------------------------
 
-export async function runPlannerStage(ctx: PipelineContext): Promise<string | null> {
-  const t0 = Date.now();
-  const agentModel = resolveAgentModel(ctx.api, ctx.agentId);
+export interface IssueContext {
+  id: string;
+  identifier: string;
+  title: string;
+  description?: string | null;
+}
 
-  ctx.api.logger.info(`${TAG(ctx)} stage 1/3: planner starting (agent=${ctx.agentId}, model=${agentModel})`);
-  await emit(ctx, {
-    type: "thought",
-    body: `[1/3 Plan] Analyzing ${ctx.issue.identifier} with ${ctx.agentId} (${agentModel})...`,
-  });
+/**
+ * Build the task prompt for a worker sub-agent (sessions_spawn).
+ * Includes rework addendum if attempt > 0.
+ */
+export function buildWorkerTask(
+  issue: IssueContext,
+  worktreePath: string,
+  opts?: { attempt?: number; gaps?: string[]; pluginConfig?: Record<string, unknown> },
+): { system: string; task: string } {
+  const prompts = loadPrompts(opts?.pluginConfig);
+  const vars: Record<string, string> = {
+    identifier: issue.identifier,
+    title: issue.title,
+    description: issue.description ?? "(no description)",
+    worktreePath,
+    tier: "",
+    attempt: String(opts?.attempt ?? 0),
+    gaps: opts?.gaps?.join("\n- ") ?? "",
+  };
+
+  let task = renderTemplate(prompts.worker.task, vars);
+  if ((opts?.attempt ?? 0) > 0 && opts?.gaps?.length) {
+    task += "\n\n" + renderTemplate(prompts.rework.addendum, vars);
+  }
+
+  return {
+    system: renderTemplate(prompts.worker.system, vars),
+    task,
+  };
+}
+
+/**
+ * Build the task prompt for an audit sub-agent (runAgent).
+ */
+export function buildAuditTask(
+  issue: IssueContext,
+  worktreePath: string,
+  pluginConfig?: Record<string, unknown>,
+): { system: string; task: string } {
+  const prompts = loadPrompts(pluginConfig);
+  const vars: Record<string, string> = {
+    identifier: issue.identifier,
+    title: issue.title,
+    description: issue.description ?? "(no description)",
+    worktreePath,
+    tier: "",
+    attempt: "0",
+    gaps: "",
+  };
+
+  return {
+    system: renderTemplate(prompts.audit.system, vars),
+    task: renderTemplate(prompts.audit.task, vars),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Verdict parsing
+// ---------------------------------------------------------------------------
 
-  const issueDetails = await ctx.linearApi.getIssueDetails(ctx.issue.id).catch(() => null);
+export interface AuditVerdict {
+  pass: boolean;
+  criteria: string[];
+  gaps: string[];
+  testResults: string;
+}
 
-  const description = issueDetails?.description ?? ctx.issue.description ?? "(no description)";
-  const comments = issueDetails?.comments?.nodes ?? [];
-  const commentSummary = comments
-    .slice(-5)
-    .map((c) => `${c.user?.name ?? "Unknown"}: ${c.body}`)
-    .join("\n");
+/**
+ * Parse the audit verdict JSON from the agent's output.
+ * Looks for the last JSON object in the output that matches the verdict shape.
+ */
+export function parseVerdict(output: string): AuditVerdict | null {
+  // Try to find JSON in the output (last occurrence)
+  const jsonMatches = output.match(/\{[^{}]*"pass"\s*:\s*(true|false)[^{}]*\}/g);
+  if (!jsonMatches?.length) return null;
+
+  for (const match of jsonMatches.reverse()) {
+    try {
+      const parsed = JSON.parse(match);
+      if (typeof parsed.pass === "boolean") {
+        return {
+          pass: parsed.pass,
+          criteria: Array.isArray(parsed.criteria) ? parsed.criteria : [],
+          gaps: Array.isArray(parsed.gaps) ? parsed.gaps : [],
+          testResults: typeof parsed.testResults === "string" ? parsed.testResults : "",
+        };
+      }
+    } catch { /* try next match */ }
+  }
 
-  const message = `You are a planner agent. Analyze this Linear issue and create an implementation plan.
+  return null;
+}
 
-## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+// ---------------------------------------------------------------------------
+// Hook handlers (called by agent_end hook in index.ts)
+// ---------------------------------------------------------------------------
 
-**Description:**
-${description}
+export interface HookContext {
+  api: OpenClawPluginApi;
+  linearApi: LinearAgentApi;
+  notify: NotifyFn;
+  pluginConfig?: Record<string, unknown>;
+  configPath?: string;
+}
 
-${commentSummary ? `**Recent comments:**\n${commentSummary}` : ""}
+/**
+ * Triggered by agent_end hook when a worker sub-agent completes.
+ * Transitions dispatch to "auditing" and spawns an independent audit agent.
+ *
+ * Idempotent: uses CAS transition + event dedup.
+ */
+export async function triggerAudit(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  event: { messages?: unknown[]; success: boolean; output?: string },
+  sessionKey: string,
+): Promise<void> {
+  const { api, linearApi, notify, pluginConfig, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
+
+  // Dedup check
+  const eventKey = `worker-end:${sessionKey}`;
+  const isNew = await markEventProcessed(eventKey, configPath);
+  if (!isNew) {
+    api.logger.info(`${TAG} duplicate worker agent_end, skipping`);
+    return;
+  }
 
-${ctx.promptContext ? `**Additional context:**\n${JSON.stringify(ctx.promptContext)}` : ""}
+  // CAS transition: working → auditing
+  try {
+    await transitionDispatch(
+      dispatch.issueIdentifier,
+      "working",
+      "auditing",
+      undefined,
+      configPath,
+    );
+  } catch (err) {
+    if (err instanceof TransitionError) {
+      api.logger.warn(`${TAG} CAS failed for audit trigger: ${err.message}`);
+      return;
+    }
+    throw err;
+  }
 
-## Instructions
-1. Analyze the issue thoroughly
-2. Break it into concrete implementation steps
-3. Identify files that need to change
-4. Note any risks or dependencies
-5. Output your plan in markdown format
+  api.logger.info(`${TAG} worker completed, triggering audit (attempt ${dispatch.attempt})`);
 
-IMPORTANT: Do NOT call code_run or any coding tools. Your job is ONLY to analyze and write a plan. The implementor stage will execute the plan using code_run after you're done.
+  // Fetch fresh issue details for audit context
+  const issueDetails = await linearApi.getIssueDetails(dispatch.issueId).catch(() => null);
+  const issue: IssueContext = {
+    id: dispatch.issueId,
+    identifier: dispatch.issueIdentifier,
+    title: issueDetails?.title ?? dispatch.issueIdentifier,
+    description: issueDetails?.description,
+  };
 
-Output ONLY the plan, nothing else.`;
+  // Build audit prompt from YAML templates
+  const auditPrompt = buildAuditTask(issue, dispatch.worktreePath, pluginConfig);
 
-  await emit(ctx, {
-    type: "action",
-    action: "Planning",
-    parameter: `${ctx.issue.identifier} — agent: ${ctx.agentId} (${agentModel})`,
+  // Set Linear label
+  await linearApi.emitActivity(dispatch.agentSessionId ?? "", {
+    type: "thought",
+    body: `Audit triggered for ${dispatch.issueIdentifier} (attempt ${dispatch.attempt})`,
+  }).catch(() => {});
+
+  await notify("auditing", {
+    identifier: dispatch.issueIdentifier,
+    title: issue.title,
+    status: "auditing",
+    attempt: dispatch.attempt,
   });
 
-  const sessionId = `linear-plan-${ctx.agentSessionId}`;
-  ctx.api.logger.info(`${TAG(ctx)} planner: spawning agent session=${sessionId}`);
+  // Spawn audit agent via runAgent (deterministic, plugin-level — NOT sessions_spawn)
+  const auditSessionId = `linear-audit-${dispatch.issueIdentifier}-${dispatch.attempt}`;
+
+  // Register session mapping so the agent_end hook can find this dispatch
+  await registerSessionMapping(auditSessionId, {
+    dispatchId: dispatch.issueIdentifier,
+    phase: "audit",
+    attempt: dispatch.attempt,
+  }, configPath);
+
+  // Update dispatch with audit session key
+  const state = await readDispatchState(configPath);
+  const activeDispatch = getActiveDispatch(state, dispatch.issueIdentifier);
+  if (activeDispatch) {
+    activeDispatch.auditSessionKey = auditSessionId;
+  }
+
+  api.logger.info(`${TAG} spawning audit agent session=${auditSessionId}`);
 
   const result = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId,
-    message,
+    api,
+    agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
+    sessionId: auditSessionId,
+    message: `${auditPrompt.system}\n\n${auditPrompt.task}`,
     timeoutMs: 5 * 60_000,
   });
 
-  if (!result.success) {
-    ctx.api.logger.error(`${TAG(ctx)} planner failed after ${elapsed(t0)}: ${result.output.slice(0, 300)}`);
-    await emit(ctx, {
-      type: "error",
-      body: `[1/3 Plan] Failed after ${elapsed(t0)}: ${result.output.slice(0, 400)}`,
-    });
-    return null;
+  // runAgent returns inline (embedded runner) — process verdict directly.
+  // The agent_end hook in index.ts serves as safety net for sessions_spawn.
+  api.logger.info(`${TAG} audit completed inline (${result.output.length} chars, success=${result.success})`);
+
+  await processVerdict(hookCtx, dispatch, {
+    success: result.success,
+    output: result.output,
+  }, auditSessionId);
+}
+
+/**
+ * Triggered by agent_end hook when an audit sub-agent completes.
+ * Parses the verdict and transitions dispatch accordingly.
+ *
+ * Idempotent: uses CAS transition + event dedup.
+ */
+export async function processVerdict(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  event: { messages?: unknown[]; success: boolean; output?: string },
+  sessionKey: string,
+): Promise<void> {
+  const { api, linearApi, notify, pluginConfig, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
+  const maxAttempts = (pluginConfig?.maxReworkAttempts as number) ?? 2;
+
+  // Dedup check
+  const eventKey = `audit-end:${sessionKey}`;
+  const isNew = await markEventProcessed(eventKey, configPath);
+  if (!isNew) {
+    api.logger.info(`${TAG} duplicate audit agent_end, skipping`);
+    return;
+  }
+
+  // Extract output from event messages or direct output
+  let auditOutput = event.output ?? "";
+  if (!auditOutput && Array.isArray(event.messages)) {
+    // Get the last assistant message
+    for (const msg of [...(event.messages as any[])].reverse()) {
+      if (msg?.role === "assistant" && typeof msg?.content === "string") {
+        auditOutput = msg.content;
+        break;
+      }
+      // Handle array content (tool use + text blocks)
+      if (msg?.role === "assistant" && Array.isArray(msg?.content)) {
+        for (const block of msg.content) {
+          if (block?.type === "text" && typeof block?.text === "string") {
+            auditOutput = block.text;
+          }
+        }
+        if (auditOutput) break;
+      }
+    }
   }
 
-  const plan = result.output;
-  ctx.api.logger.info(`${TAG(ctx)} planner completed in ${elapsed(t0)} (${plan.length} chars)`);
+  // Parse verdict
+  const verdict = parseVerdict(auditOutput);
+  if (!verdict) {
+    api.logger.warn(`${TAG} could not parse audit verdict from output (${auditOutput.length} chars)`);
+    // Treat unparseable verdict as failure
+    await handleAuditFail(hookCtx, dispatch, {
+      pass: false,
+      criteria: [],
+      gaps: ["Audit produced no parseable verdict"],
+      testResults: "",
+    });
+    return;
+  }
 
-  // Post plan as a Linear comment
-  await ctx.linearApi.createComment(
-    ctx.issue.id,
-    `## Implementation Plan\n\n${plan}\n\n---\n*Proceeding to implementation...*`,
+  api.logger.info(
+    `${TAG} audit verdict: ${verdict.pass ? "PASS" : "FAIL"} ` +
+    `(criteria: ${verdict.criteria.length}, gaps: ${verdict.gaps.length})`,
   );
 
-  await emit(ctx, {
-    type: "action",
-    action: "Plan complete",
-    parameter: `${ctx.issue.identifier} — ${elapsed(t0)}, moving to implementation`,
-  });
-
-  return plan;
+  if (verdict.pass) {
+    await handleAuditPass(hookCtx, dispatch, verdict);
+  } else {
+    await handleAuditFail(hookCtx, dispatch, verdict);
+  }
 }
 
 // ---------------------------------------------------------------------------
-// Stage 2: Implementor
+// Verdict handlers
 // ---------------------------------------------------------------------------
-//
-// Deterministic: pipeline CODE calls the coding CLI directly.
-// The agent model only evaluates results between runs.
-
-const BACKEND_RUNNERS: Record<
-  CodingBackend,
-  (api: OpenClawPluginApi, params: any, pluginConfig?: Record<string, unknown>) => Promise<CliResult>
-> = {
-  codex: runCodex,
-  claude: runClaude,
-  gemini: runGemini,
-};
 
-export async function runImplementorStage(
-  ctx: PipelineContext,
-  plan: string,
-): Promise<string | null> {
-  const t0 = Date.now();
-  const agentModel = resolveAgentModel(ctx.api, ctx.agentId);
-  const pluginConfig = (ctx.api as any).pluginConfig as Record<string, unknown> | undefined;
-
-  // Resolve coding backend from config (coding-tools.json)
-  const codingConfig = loadCodingConfig();
-  const backend = resolveCodingBackend(codingConfig);
-  const runner = BACKEND_RUNNERS[backend];
-  const backendName = backend.charAt(0).toUpperCase() + backend.slice(1);
-
-  ctx.api.logger.info(
-    `${TAG(ctx)} stage 2/3: implementor starting ` +
-    `(coding_cli=${backendName}, tier=${ctx.tier ?? "unknown"}, ` +
-    `worktree=${ctx.worktreePath ?? "default"}, ` +
-    `eval_agent=${ctx.agentId}, eval_model=${agentModel})`,
-  );
+async function handleAuditPass(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  verdict: AuditVerdict,
+): Promise<void> {
+  const { api, linearApi, notify, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
 
-  await emit(ctx, {
-    type: "thought",
-    body: `[2/3 Implement] Starting ${backendName} CLI → ${ctx.worktreePath ?? "default workspace"}`,
-  });
+  // CAS transition: auditing → done
+  try {
+    await transitionDispatch(dispatch.issueIdentifier, "auditing", "done", undefined, configPath);
+  } catch (err) {
+    if (err instanceof TransitionError) {
+      api.logger.warn(`${TAG} CAS failed for audit pass: ${err.message}`);
+      return;
+    }
+    throw err;
+  }
 
-  // Build the implementation prompt for the coding CLI
-  const codePrompt = [
-    `Implement the following plan for issue ${ctx.issue.identifier} — ${ctx.issue.title}.`,
-    ``,
-    `## Plan`,
-    plan,
-    ``,
-    `## Instructions`,
-    `- Follow the plan step by step`,
-    `- Create commits for each logical change`,
-    `- Run tests if the project has them`,
-    `- Stay within scope of the plan`,
-  ].join("\n");
-
-  await emit(ctx, {
-    type: "action",
-    action: `Running ${backendName}`,
-    parameter: `${ctx.tier ?? "unknown"} tier — worktree: ${ctx.worktreePath ?? "default"}`,
+  // Move to completed
+  await completeDispatch(dispatch.issueIdentifier, {
+    tier: dispatch.tier,
+    status: "done",
+    completedAt: new Date().toISOString(),
+    project: dispatch.project,
+  }, configPath);
+
+  // Post approval comment
+  const criteriaList = verdict.criteria.map((c) => `- ${c}`).join("\n");
+  await linearApi.createComment(
+    dispatch.issueId,
+    `## Audit Passed\n\n**Criteria verified:**\n${criteriaList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Attempt ${dispatch.attempt + 1} — audit passed.*`,
+  ).catch((err) => api.logger.error(`${TAG} failed to post audit pass comment: ${err}`));
+
+  api.logger.info(`${TAG} audit PASSED — dispatch completed (attempt ${dispatch.attempt})`);
+
+  await notify("audit_pass", {
+    identifier: dispatch.issueIdentifier,
+    title: dispatch.issueIdentifier,
+    status: "done",
+    attempt: dispatch.attempt,
+    verdict: { pass: true, gaps: [] },
   });
 
-  // Call the coding CLI directly — deterministic, not LLM choice.
-  // NOTE: Do NOT pass ctx.model here. The tier model (e.g. anthropic/claude-sonnet-4-6)
-  // is for tracking/display only. Each coding CLI uses its own configured model.
-  ctx.api.logger.info(`${TAG(ctx)} implementor: invoking ${backendName} CLI (no model override — CLI uses its own config)`);
-  const cliStart = Date.now();
-
-  const codeResult = await runner(ctx.api, {
-    prompt: codePrompt,
-    workingDir: ctx.worktreePath ?? undefined,
-    timeoutMs: 10 * 60_000,
-  }, pluginConfig);
-
-  const cliElapsed = elapsed(cliStart);
-
-  if (!codeResult.success) {
-    ctx.api.logger.warn(
-      `${TAG(ctx)} implementor: ${backendName} CLI failed after ${cliElapsed} — ` +
-      `error: ${codeResult.error ?? "unknown"}, output: ${codeResult.output.slice(0, 300)}`,
-    );
-    await emit(ctx, {
-      type: "error",
-      body: `[2/3 Implement] ${backendName} failed after ${cliElapsed}: ${(codeResult.error ?? codeResult.output).slice(0, 400)}`,
-    });
+  clearActiveSession(dispatch.issueId);
+}
 
-    // Ask the agent to evaluate the failure
-    ctx.api.logger.info(`${TAG(ctx)} implementor: spawning ${ctx.agentId} (${agentModel}) to evaluate failure`);
-    await emit(ctx, {
-      type: "action",
-      action: "Evaluating failure",
-      parameter: `${ctx.agentId} (${agentModel}) analyzing ${backendName} error`,
-    });
+async function handleAuditFail(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  verdict: AuditVerdict,
+): Promise<void> {
+  const { api, linearApi, notify, pluginConfig, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
+  const maxAttempts = (pluginConfig?.maxReworkAttempts as number) ?? 2;
+  const nextAttempt = dispatch.attempt + 1;
+
+  if (nextAttempt > maxAttempts) {
+    // Escalate — too many failures
+    try {
+      await transitionDispatch(
+        dispatch.issueIdentifier,
+        "auditing",
+        "stuck",
+        { stuckReason: `audit_failed_${nextAttempt}x` },
+        configPath,
+      );
+    } catch (err) {
+      if (err instanceof TransitionError) {
+        api.logger.warn(`${TAG} CAS failed for stuck transition: ${err.message}`);
+        return;
+      }
+      throw err;
+    }
 
-    const evalResult = await runAgent({
-      api: ctx.api,
-      agentId: ctx.agentId,
-      sessionId: `linear-impl-eval-${ctx.agentSessionId}`,
-      message: `${backendName} failed to implement the plan for ${ctx.issue.identifier}.\n\n## Plan\n${plan}\n\n## ${backendName} Output\n${codeResult.output.slice(0, 3000)}\n\n## Error\n${codeResult.error ?? "unknown"}\n\nAnalyze the failure. Summarize what went wrong and suggest next steps. Be concise.`,
-      timeoutMs: 2 * 60_000,
+    const gapsList = verdict.gaps.map((g) => `- ${g}`).join("\n");
+    await linearApi.createComment(
+      dispatch.issueId,
+      `## Audit Failed — Escalating\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Max rework attempts reached. Needs human review.*`,
+    ).catch((err) => api.logger.error(`${TAG} failed to post escalation comment: ${err}`));
+
+    api.logger.warn(`${TAG} audit FAILED ${nextAttempt}x — escalating to human`);
+
+    await notify("escalation", {
+      identifier: dispatch.issueIdentifier,
+      title: dispatch.issueIdentifier,
+      status: "stuck",
+      attempt: nextAttempt,
+      reason: `audit failed ${nextAttempt}x`,
+      verdict: { pass: false, gaps: verdict.gaps },
     });
 
-    const failureSummary = evalResult.success
-      ? evalResult.output
-      : `Implementation failed and evaluation also failed: ${codeResult.output.slice(0, 500)}`;
+    return;
+  }
 
-    await ctx.linearApi.createComment(
-      ctx.issue.id,
-      `## Implementation Failed\n\n**Backend:** ${backendName} (ran for ${cliElapsed})\n**Tier:** ${ctx.tier ?? "unknown"}\n\n${failureSummary}`,
+  // Rework — transition back to working with incremented attempt
+  try {
+    await transitionDispatch(
+      dispatch.issueIdentifier,
+      "auditing",
+      "working",
+      { attempt: nextAttempt },
+      configPath,
     );
-
-    return null;
+  } catch (err) {
+    if (err instanceof TransitionError) {
+      api.logger.warn(`${TAG} CAS failed for rework transition: ${err.message}`);
+      return;
+    }
+    throw err;
   }
 
-  ctx.api.logger.info(`${TAG(ctx)} implementor: ${backendName} CLI completed in ${cliElapsed} (${codeResult.output.length} chars output)`);
-
-  // Ask the agent to evaluate the result
-  const evalMessage = [
-    `${backendName} completed implementation for ${ctx.issue.identifier}. Evaluate the result.`,
-    ``,
-    `## Original Plan`,
-    plan,
-    ``,
-    `## ${backendName} Output`,
-    codeResult.output.slice(0, 5000),
-    ``,
-    `## Worktree`,
-    `Path: ${ctx.worktreePath ?? "default"}`,
-    `Branch: ${ctx.codexBranch ?? "unknown"}`,
-    ``,
-    `Summarize what was implemented, any issues found, and whether the plan was fully executed. Be concise.`,
-  ].join("\n");
-
-  ctx.api.logger.info(`${TAG(ctx)} implementor: spawning ${ctx.agentId} (${agentModel}) to evaluate results`);
-  await emit(ctx, {
-    type: "action",
-    action: "Evaluating results",
-    parameter: `${ctx.agentId} (${agentModel}) reviewing ${backendName} output`,
-  });
+  const gapsList = verdict.gaps.map((g) => `- ${g}`).join("\n");
+  await linearApi.createComment(
+    dispatch.issueId,
+    `## Audit Failed — Rework\n\n**Attempt ${nextAttempt} of ${maxAttempts + 1}**\n\n**Gaps:**\n${gapsList}\n\n**Tests:** ${verdict.testResults || "N/A"}\n\n---\n*Reworking: addressing gaps above.*`,
+  ).catch((err) => api.logger.error(`${TAG} failed to post rework comment: ${err}`));
 
-  const evalStart = Date.now();
-  const evalResult = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId: `linear-impl-eval-${ctx.agentSessionId}`,
-    message: evalMessage,
-    timeoutMs: 3 * 60_000,
-  });
-
-  const summary = evalResult.success
-    ? evalResult.output
-    : `Implementation completed but evaluation failed. ${backendName} output:\n${codeResult.output.slice(0, 2000)}`;
-
-  ctx.api.logger.info(
-    `${TAG(ctx)} implementor: evaluation ${evalResult.success ? "succeeded" : "failed"} in ${elapsed(evalStart)}, ` +
-    `total stage time: ${elapsed(t0)}`,
-  );
+  api.logger.info(`${TAG} audit FAILED — rework attempt ${nextAttempt}/${maxAttempts + 1}`);
 
-  await emit(ctx, {
-    type: "action",
-    action: "Implementation complete",
-    parameter: `${backendName} ${cliElapsed} + eval ${elapsed(evalStart)} = ${elapsed(t0)} total`,
+  await notify("audit_fail", {
+    identifier: dispatch.issueIdentifier,
+    title: dispatch.issueIdentifier,
+    status: "working",
+    attempt: nextAttempt,
+    verdict: { pass: false, gaps: verdict.gaps },
   });
 
-  return summary;
+  // The webhook handler or dispatch service should re-spawn a worker
+  // with the rework context. Log emitted for observability.
+  api.logger.info(
+    `${TAG} dispatch is back in "working" state (attempt ${nextAttempt}). ` +
+    `Orchestrator should re-spawn worker with gaps: ${verdict.gaps.join(", ")}`,
+  );
 }
 
 // ---------------------------------------------------------------------------
-// Stage 3: Auditor
+// Worker phase (called by handleDispatch in webhook.ts)
 // ---------------------------------------------------------------------------
 
-export async function runAuditorStage(
-  ctx: PipelineContext,
-  plan: string,
-  implResult: string,
+/**
+ * Spawn the worker agent for a dispatch.
+ * Transitions dispatched→working, builds task, runs agent, then triggers audit.
+ *
+ * This is the main entry point for the v2 pipeline — replaces runFullPipeline.
+ */
+export async function spawnWorker(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  opts?: { gaps?: string[] },
 ): Promise<void> {
-  const t0 = Date.now();
-  const agentModel = resolveAgentModel(ctx.api, ctx.agentId);
-
-  ctx.api.logger.info(
-    `${TAG(ctx)} stage 3/3: auditor starting (agent=${ctx.agentId}, model=${agentModel})`,
-  );
-  await emit(ctx, {
-    type: "thought",
-    body: `[3/3 Audit] Reviewing implementation with ${ctx.agentId} (${agentModel})...`,
-  });
-
-  const worktreeInfo = ctx.worktreePath
-    ? `\n## Worktree\nCode changes are at: \`${ctx.worktreePath}\` (branch: \`${ctx.codexBranch ?? "unknown"}\`)\n`
-    : "";
-
-  const message = `You are an auditor. Review this implementation against the original plan.
-
-## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+  const { api, linearApi, pluginConfig, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
+
+  // Transition dispatched → working (first run) — skip if already working (rework)
+  if (dispatch.status === "dispatched") {
+    try {
+      await transitionDispatch(
+        dispatch.issueIdentifier,
+        "dispatched",
+        "working",
+        undefined,
+        configPath,
+      );
+    } catch (err) {
+      if (err instanceof TransitionError) {
+        api.logger.warn(`${TAG} CAS failed for worker spawn: ${err.message}`);
+        return;
+      }
+      throw err;
+    }
+  }
 
-## Original Plan:
-${plan}
+  // Fetch fresh issue details
+  const issueDetails = await linearApi.getIssueDetails(dispatch.issueId).catch(() => null);
+  const issue: IssueContext = {
+    id: dispatch.issueId,
+    identifier: dispatch.issueIdentifier,
+    title: issueDetails?.title ?? dispatch.issueIdentifier,
+    description: issueDetails?.description,
+  };
 
-## Implementation Result:
-${implResult}
-${worktreeInfo}
-## Instructions
-1. Verify each plan step was completed
-2. Check for any missed items — use \`ask_agent\` / \`spawn_agent\` for specialized review if needed
-3. Note any concerns or improvements needed
-4. Provide a pass/fail verdict with reasoning
-5. Output a concise audit summary in markdown
-${toolContext(ctx)}
+  // Build worker prompt from YAML templates
+  const workerPrompt = buildWorkerTask(issue, dispatch.worktreePath, {
+    attempt: dispatch.attempt,
+    gaps: opts?.gaps,
+    pluginConfig,
+  });
 
-Output ONLY the audit summary.`;
+  const workerSessionId = `linear-worker-${dispatch.issueIdentifier}-${dispatch.attempt}`;
 
-  const sessionId = `linear-audit-${ctx.agentSessionId}`;
-  ctx.api.logger.info(`${TAG(ctx)} auditor: spawning agent session=${sessionId}`);
+  // Register session mapping for agent_end hook lookup
+  await registerSessionMapping(workerSessionId, {
+    dispatchId: dispatch.issueIdentifier,
+    phase: "worker",
+    attempt: dispatch.attempt,
+  }, configPath);
 
-  await emit(ctx, {
-    type: "action",
-    action: "Auditing",
-    parameter: `${ctx.issue.identifier} — agent: ${ctx.agentId} (${agentModel})`,
+  await hookCtx.notify("working", {
+    identifier: dispatch.issueIdentifier,
+    title: issue.title,
+    status: "working",
+    attempt: dispatch.attempt,
   });
 
+  api.logger.info(`${TAG} spawning worker agent session=${workerSessionId} (attempt ${dispatch.attempt})`);
+
   const result = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId,
-    message,
-    timeoutMs: 5 * 60_000,
+    api,
+    agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
+    sessionId: workerSessionId,
+    message: `${workerPrompt.system}\n\n${workerPrompt.task}`,
+    timeoutMs: (pluginConfig?.codexTimeoutMs as number) ?? 10 * 60_000,
   });
 
-  const auditSummary = result.success
-    ? result.output
-    : `Audit failed: ${result.output.slice(0, 500)}`;
+  // runAgent returns inline — trigger audit directly.
+  // Re-read dispatch state since it may have changed during worker run.
+  const freshState = await readDispatchState(configPath);
+  const freshDispatch = getActiveDispatch(freshState, dispatch.issueIdentifier);
+  if (!freshDispatch) {
+    api.logger.warn(`${TAG} dispatch disappeared during worker run — skipping audit`);
+    return;
+  }
 
-  ctx.api.logger.info(
-    `${TAG(ctx)} auditor: ${result.success ? "completed" : "failed"} in ${elapsed(t0)} (${auditSummary.length} chars)`,
-  );
+  api.logger.info(`${TAG} worker completed (success=${result.success}, ${result.output.length} chars) — triggering audit`);
 
-  await ctx.linearApi.createComment(
-    ctx.issue.id,
-    `## Audit Report\n\n${auditSummary}`,
-  );
-
-  await emit(ctx, {
-    type: "response",
-    body: `[3/3 Audit] ${result.success ? "Complete" : "Failed"} (${elapsed(t0)}). ` +
-      `All stages done for ${ctx.issue.identifier}. Plan, implementation, and audit posted as comments.`,
-  });
+  await triggerAudit(hookCtx, freshDispatch, {
+    success: result.success,
+    output: result.output,
+  }, workerSessionId);
 }
 
 // ---------------------------------------------------------------------------
-// Full Pipeline
+// Exports for backward compatibility (v1 pipeline)
 // ---------------------------------------------------------------------------
-//
-// Runs all three stages sequentially: plan → implement → audit.
-// Assignment is the trigger AND the approval — no pause between stages.
-// Each stage's result feeds into the next. If any stage fails, the
-// pipeline stops and reports the error.
-
-export async function runFullPipeline(ctx: PipelineContext): Promise<void> {
-  const t0 = Date.now();
-  const agentModel = resolveAgentModel(ctx.api, ctx.agentId);
-  const codingConfig = loadCodingConfig();
-  const codingBackend = resolveCodingBackend(codingConfig);
-
-  ctx.api.logger.info(
-    `${TAG(ctx)} === PIPELINE START === ` +
-    `agent=${ctx.agentId}, agent_model=${agentModel}, ` +
-    `coding_cli=${codingBackend}, tier=${ctx.tier ?? "unknown"}, ` +
-    `worktree=${ctx.worktreePath ?? "none"}, ` +
-    `branch=${ctx.codexBranch ?? "none"}, ` +
-    `session=${ctx.agentSessionId}`,
-  );
-
-  // Register active session so tools (code_run) can resolve it
-  setActiveSession({
-    agentSessionId: ctx.agentSessionId,
-    issueIdentifier: ctx.issue.identifier,
-    issueId: ctx.issue.id,
-    agentId: ctx.agentId,
-    startedAt: Date.now(),
-  });
 
-  await emit(ctx, {
-    type: "thought",
-    body: `Pipeline started for ${ctx.issue.identifier} — ` +
-      `agent: ${ctx.agentId} (${agentModel}), ` +
-      `coding: ${codingBackend}, ` +
-      `tier: ${ctx.tier ?? "unknown"}`,
-  });
-
-  try {
-    // Stage 1: Plan
-    const plan = await runPlannerStage(ctx);
-    if (!plan) {
-      ctx.api.logger.error(`${TAG(ctx)} planner produced no plan — aborting after ${elapsed(t0)}`);
-      await emit(ctx, {
-        type: "error",
-        body: `Pipeline aborted — planning stage failed after ${elapsed(t0)}. No plan produced.`,
-      });
-      return;
-    }
+// Re-export v1 types and functions that other files may still use
+export type { Tier } from "./dispatch-state.js";
 
-    // Stage 2: Implement
-    const implResult = await runImplementorStage(ctx, plan);
-    if (!implResult) {
-      ctx.api.logger.error(`${TAG(ctx)} implementor failed — aborting after ${elapsed(t0)}`);
-      await emit(ctx, {
-        type: "error",
-        body: `Pipeline aborted — implementation stage failed after ${elapsed(t0)}.`,
-      });
-      return;
-    }
-
-    // Stage 3: Audit
-    await runAuditorStage(ctx, plan, implResult);
-
-    ctx.api.logger.info(
-      `${TAG(ctx)} === PIPELINE COMPLETE === total time: ${elapsed(t0)}`,
-    );
-  } catch (err) {
-    ctx.api.logger.error(`${TAG(ctx)} === PIPELINE ERROR === after ${elapsed(t0)}: ${err}`);
-    await emit(ctx, {
-      type: "error",
-      body: `Pipeline crashed after ${elapsed(t0)}: ${String(err).slice(0, 400)}`,
-    });
-  } finally {
-    clearActiveSession(ctx.issue.id);
-  }
+export interface PipelineContext {
+  api: OpenClawPluginApi;
+  linearApi: LinearAgentApi;
+  agentSessionId: string;
+  agentId: string;
+  issue: IssueContext;
+  promptContext?: unknown;
+  worktreePath?: string | null;
+  codexBranch?: string | null;
+  tier?: Tier;
+  model?: string;
 }