@calltelemetry/openclaw-linear 0.4.0 → 0.5.0

package/src/pipeline.ts

@@ -1,270 +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";
-
-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;
+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";
+
+// ---------------------------------------------------------------------------
+// Prompt loading
+// ---------------------------------------------------------------------------
+
+interface PromptTemplates {
+  worker: { system: string; task: string };
+  audit: { system: string; task: string };
+  rework: { addendum: string };
 }
 
-function emit(ctx: PipelineContext, content: ActivityContent): Promise<void> {
-  return ctx.linearApi.emitActivity(ctx.agentSessionId, content).catch((err) => {
-    ctx.api.logger.error(`Failed to emit activity: ${err}`);
-  });
+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 {
+    // 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 {
+    _cachedPrompts = DEFAULT_PROMPTS;
+  }
+
+  return _cachedPrompts;
 }
 
-function toolContext(ctx: PipelineContext): string {
-  return [
-    `\n## Tool Context`,
-    `When calling \`code_run\`, you MUST pass these parameters:`,
-    `- \`agentSessionId\`: \`"${ctx.agentSessionId}"\``,
-    `- \`issueIdentifier\`: \`"${ctx.issue.identifier}"\``,
-    `This enables real-time progress streaming to Linear and isolated worktree creation.`,
-  ].join("\n");
+/** Clear prompt cache (for testing or after config change) */
+export function clearPromptCache(): void {
+  _cachedPrompts = null;
 }
 
-// ── Stage 1: Planner ───────────────────────────────────────────────
+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);
+  }
+  return result;
+}
 
-export async function runPlannerStage(ctx: PipelineContext): Promise<string | null> {
-  await emit(ctx, { type: "thought", body: `Analyzing issue ${ctx.issue.identifier}...` });
+// ---------------------------------------------------------------------------
+// Task builders
+// ---------------------------------------------------------------------------
 
-  const issueDetails = await ctx.linearApi.getIssueDetails(ctx.issue.id).catch(() => null);
+export interface IssueContext {
+  id: string;
+  identifier: string;
+  title: string;
+  description?: string | null;
+}
 
-  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");
+/**
+ * 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- ") ?? "",
+  };
 
-  const message = `You are a planner agent. Analyze this Linear issue and create an implementation plan.
+  let task = renderTemplate(prompts.worker.task, vars);
+  if ((opts?.attempt ?? 0) > 0 && opts?.gaps?.length) {
+    task += "\n\n" + renderTemplate(prompts.rework.addendum, vars);
+  }
 
-## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+  return {
+    system: renderTemplate(prompts.worker.system, vars),
+    task,
+  };
+}
 
-**Description:**
-${description}
+/**
+ * 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: "",
+  };
 
-${commentSummary ? `**Recent comments:**\n${commentSummary}` : ""}
+  return {
+    system: renderTemplate(prompts.audit.system, vars),
+    task: renderTemplate(prompts.audit.task, vars),
+  };
+}
 
-${ctx.promptContext ? `**Additional context:**\n${JSON.stringify(ctx.promptContext)}` : ""}
+// ---------------------------------------------------------------------------
+// Verdict parsing
+// ---------------------------------------------------------------------------
 
-## 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
+export interface AuditVerdict {
+  pass: boolean;
+  criteria: string[];
+  gaps: string[];
+  testResults: string;
+}
 
-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.
+/**
+ * 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 */ }
+  }
 
-Output ONLY the plan, nothing else.`;
+  return null;
+}
 
-  await emit(ctx, { type: "action", action: "Planning", parameter: ctx.issue.identifier });
+// ---------------------------------------------------------------------------
+// Hook handlers (called by agent_end hook in index.ts)
+// ---------------------------------------------------------------------------
 
-  const result = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId: `linear-plan-${ctx.agentSessionId}`,
-    message,
-    timeoutMs: 5 * 60_000,
+export interface HookContext {
+  api: OpenClawPluginApi;
+  linearApi: LinearAgentApi;
+  notify: NotifyFn;
+  pluginConfig?: Record<string, unknown>;
+  configPath?: string;
+}
 
-  });
+/**
+ * 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;
+  }
 
-  if (!result.success) {
-    await emit(ctx, { type: "error", body: `Planning failed: ${result.output.slice(0, 500)}` });
-    return null;
+  // 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;
   }
 
-  const plan = result.output;
+  api.logger.info(`${TAG} worker completed, triggering audit (attempt ${dispatch.attempt})`);
 
-  // Post plan as a Linear comment
-  await ctx.linearApi.createComment(
-    ctx.issue.id,
-    `## Implementation Plan\n\n${plan}\n\n---\n*Reply to this comment to approve the plan and begin implementation.*`,
-  );
+  // 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,
+  };
+
+  // Build audit prompt from YAML templates
+  const auditPrompt = buildAuditTask(issue, dispatch.worktreePath, pluginConfig);
+
+  // Set Linear label
+  await linearApi.emitActivity(dispatch.agentSessionId ?? "", {
+    type: "thought",
+    body: `Audit triggered for ${dispatch.issueIdentifier} (attempt ${dispatch.attempt})`,
+  }).catch(() => {});
 
-  await emit(ctx, {
-    type: "elicitation",
-    body: "I've posted an implementation plan as a comment. Please review and reply to approve.",
+  await notify("auditing", {
+    identifier: dispatch.issueIdentifier,
+    title: issue.title,
+    status: "auditing",
+    attempt: dispatch.attempt,
   });
 
-  return plan;
-}
+  // 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;
+  }
 
-// ── Stage 2: Implementor ──────────────────────────────────────────
+  api.logger.info(`${TAG} spawning audit agent session=${auditSessionId}`);
 
-export async function runImplementorStage(
-  ctx: PipelineContext,
-  plan: string,
-): Promise<string | null> {
-  await emit(ctx, { type: "thought", body: "Plan approved. Starting implementation..." });
+  const result = await runAgent({
+    api,
+    agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
+    sessionId: auditSessionId,
+    message: `${auditPrompt.system}\n\n${auditPrompt.task}`,
+    timeoutMs: 5 * 60_000,
+  });
 
-  const message = `You are an implementor agent. Execute this plan for issue ${ctx.issue.identifier}.
+  // 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})`);
 
-## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+  await processVerdict(hookCtx, dispatch, {
+    success: result.success,
+    output: result.output,
+  }, auditSessionId);
+}
 
-## Approved Plan:
-${plan}
+/**
+ * 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;
+  }
 
-## Instructions
-1. Follow the plan step by step
-2. Use \`code_run\` to write code, create files, run tests, and refactor — it works in an isolated git worktree
-3. Use \`spawn_agent\` / \`ask_agent\` to delegate to other crew agents if needed
-4. Create commits for each logical change
-5. If the plan involves creating a PR, do so
-6. Report what you did, any files changed, and the worktree/branch path
-${toolContext(ctx)}
+  // 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;
+      }
+    }
+  }
 
-Be thorough but stay within scope of the plan.`;
+  // 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;
+  }
 
-  await emit(ctx, { type: "action", action: "Calling coding provider", parameter: "Codex" });
+  api.logger.info(
+    `${TAG} audit verdict: ${verdict.pass ? "PASS" : "FAIL"} ` +
+    `(criteria: ${verdict.criteria.length}, gaps: ${verdict.gaps.length})`,
+  );
 
-  const result = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId: `linear-impl-${ctx.agentSessionId}`,
-    message,
-    timeoutMs: 10 * 60_000,
+  if (verdict.pass) {
+    await handleAuditPass(hookCtx, dispatch, verdict);
+  } else {
+    await handleAuditFail(hookCtx, dispatch, verdict);
+  }
+}
 
-  });
+// ---------------------------------------------------------------------------
+// Verdict handlers
+// ---------------------------------------------------------------------------
+
+async function handleAuditPass(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  verdict: AuditVerdict,
+): Promise<void> {
+  const { api, linearApi, notify, configPath } = hookCtx;
+  const TAG = `[${dispatch.issueIdentifier}]`;
 
-  if (!result.success) {
-    await emit(ctx, { type: "error", body: `Implementation failed: ${result.output.slice(0, 500)}` });
-    return null;
+  // 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;
   }
 
-  // Try to extract worktree info from agent output (Codex results include it)
-  const worktreeMatch = result.output.match(/worktreePath["\s:]+([/\w.-]+)/);
-  const branchMatch = result.output.match(/branch["\s:]+([/\w.-]+)/);
-  if (worktreeMatch) ctx.worktreePath = worktreeMatch[1];
-  if (branchMatch) ctx.codexBranch = branchMatch[1];
+  // 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: [] },
+  });
 
-  await emit(ctx, { type: "action", action: "Implementation complete", parameter: ctx.issue.identifier });
-  return result.output;
+  clearActiveSession(dispatch.issueId);
 }
 
-// ── Stage 3: Auditor ──────────────────────────────────────────────
-
-export async function runAuditorStage(
-  ctx: PipelineContext,
-  plan: string,
-  implResult: string,
+async function handleAuditFail(
+  hookCtx: HookContext,
+  dispatch: ActiveDispatch,
+  verdict: AuditVerdict,
 ): Promise<void> {
-  await emit(ctx, { type: "thought", body: "Auditing implementation against the plan..." });
-
-  const worktreeInfo = ctx.worktreePath
-    ? `\n## Worktree\nCode changes are at: \`${ctx.worktreePath}\` (branch: \`${ctx.codexBranch ?? "unknown"}\`)\n`
-    : "";
+  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 message = `You are an auditor. Review this implementation against the original plan.
+    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}`));
 
-## Issue: ${ctx.issue.identifier} — ${ctx.issue.title}
+    api.logger.warn(`${TAG} audit FAILED ${nextAttempt}x — escalating to human`);
 
-## Original Plan:
-${plan}
+    await notify("escalation", {
+      identifier: dispatch.issueIdentifier,
+      title: dispatch.issueIdentifier,
+      status: "stuck",
+      attempt: nextAttempt,
+      reason: `audit failed ${nextAttempt}x`,
+      verdict: { pass: false, gaps: verdict.gaps },
+    });
 
-## 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)}
+    return;
+  }
 
-Output ONLY the audit summary.`;
+  // Rework — transition back to working with incremented attempt
+  try {
+    await transitionDispatch(
+      dispatch.issueIdentifier,
+      "auditing",
+      "working",
+      { attempt: nextAttempt },
+      configPath,
+    );
+  } catch (err) {
+    if (err instanceof TransitionError) {
+      api.logger.warn(`${TAG} CAS failed for rework transition: ${err.message}`);
+      return;
+    }
+    throw err;
+  }
 
-  await emit(ctx, { type: "action", action: "Auditing", parameter: ctx.issue.identifier });
+  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 result = await runAgent({
-    api: ctx.api,
-    agentId: ctx.agentId,
-    sessionId: `linear-audit-${ctx.agentSessionId}`,
-    message,
-    timeoutMs: 5 * 60_000,
+  api.logger.info(`${TAG} audit FAILED — rework attempt ${nextAttempt}/${maxAttempts + 1}`);
 
+  await notify("audit_fail", {
+    identifier: dispatch.issueIdentifier,
+    title: dispatch.issueIdentifier,
+    status: "working",
+    attempt: nextAttempt,
+    verdict: { pass: false, gaps: verdict.gaps },
   });
 
-  const auditSummary = result.success ? result.output : `Audit failed: ${result.output.slice(0, 500)}`;
-
-  await ctx.linearApi.createComment(
-    ctx.issue.id,
-    `## Audit Report\n\n${auditSummary}`,
+  // 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(", ")}`,
   );
+}
 
-  await emit(ctx, {
-    type: "response",
-    body: `Completed work on ${ctx.issue.identifier}. Plan, implementation, and audit posted as comments.`,
+// ---------------------------------------------------------------------------
+// Worker phase (called by handleDispatch in webhook.ts)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 { 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;
+    }
+  }
+
+  // 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,
+  };
+
+  // Build worker prompt from YAML templates
+  const workerPrompt = buildWorkerTask(issue, dispatch.worktreePath, {
+    attempt: dispatch.attempt,
+    gaps: opts?.gaps,
+    pluginConfig,
   });
-}
 
-// ── Full Pipeline ─────────────────────────────────────────────────
+  const workerSessionId = `linear-worker-${dispatch.issueIdentifier}-${dispatch.attempt}`;
+
+  // Register session mapping for agent_end hook lookup
+  await registerSessionMapping(workerSessionId, {
+    dispatchId: dispatch.issueIdentifier,
+    phase: "worker",
+    attempt: dispatch.attempt,
+  }, configPath);
 
-export async function runFullPipeline(ctx: PipelineContext): Promise<void> {
-  // 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 hookCtx.notify("working", {
+    identifier: dispatch.issueIdentifier,
+    title: issue.title,
+    status: "working",
+    attempt: dispatch.attempt,
   });
 
-  try {
-    // Stage 1: Plan
-    const plan = await runPlannerStage(ctx);
-    if (!plan) {
-      clearActiveSession(ctx.issue.id);
-      return;
-    }
+  api.logger.info(`${TAG} spawning worker agent session=${workerSessionId} (attempt ${dispatch.attempt})`);
 
-    // Pipeline pauses here — user must reply to approve.
-    // The "prompted" / "created" webhook will call resumePipeline().
-    // Active session stays registered until resume completes.
-  } catch (err) {
-    clearActiveSession(ctx.issue.id);
-    ctx.api.logger.error(`Pipeline error: ${err}`);
-    await emit(ctx, { type: "error", body: `Pipeline failed: ${String(err).slice(0, 500)}` });
+  const result = await runAgent({
+    api,
+    agentId: (pluginConfig?.defaultAgentId as string) ?? "default",
+    sessionId: workerSessionId,
+    message: `${workerPrompt.system}\n\n${workerPrompt.task}`,
+    timeoutMs: (pluginConfig?.codexTimeoutMs as number) ?? 10 * 60_000,
+  });
+
+  // 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;
   }
+
+  api.logger.info(`${TAG} worker completed (success=${result.success}, ${result.output.length} chars) — triggering audit`);
+
+  await triggerAudit(hookCtx, freshDispatch, {
+    success: result.success,
+    output: result.output,
+  }, workerSessionId);
 }
 
-export async function resumePipeline(ctx: PipelineContext, plan: string): Promise<void> {
-  // Register (or update) active session for tool resolution
-  setActiveSession({
-    agentSessionId: ctx.agentSessionId,
-    issueIdentifier: ctx.issue.identifier,
-    issueId: ctx.issue.id,
-    agentId: ctx.agentId,
-    startedAt: Date.now(),
-  });
+// ---------------------------------------------------------------------------
+// Exports for backward compatibility (v1 pipeline)
+// ---------------------------------------------------------------------------
 
-  try {
-    // Stage 2: Implement
-    const implResult = await runImplementorStage(ctx, plan);
-    if (!implResult) return;
+// Re-export v1 types and functions that other files may still use
+export type { Tier } from "./dispatch-state.js";
 
-    // Stage 3: Audit
-    await runAuditorStage(ctx, plan, implResult);
-  } catch (err) {
-    ctx.api.logger.error(`Pipeline error: ${err}`);
-    await emit(ctx, { type: "error", body: `Pipeline failed: ${String(err).slice(0, 500)}` });
-  } 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;
 }