feat: Linear status sync during loop execution

src/cli.ts

@@ -120,6 +120,10 @@ program
   .option('--figma-target <path>', 'Target directory for content mode')
   .option('--figma-preview', 'Show content changes without applying (content mode)')
   .option('--figma-mapping <file>', 'Custom content mapping file (content mode)')
+  .option(
+    '--linear-sync <issue>',
+    'Sync loop status to a Linear issue (e.g., ENG-42). Moves to In Progress/Done/In Review.'
+  )
   .option(
     '--model-selector',
     'Interactive model picker with live OpenRouter pricing and context info'

src/commands/run.ts

@@ -310,6 +310,8 @@ export interface RunCommandOptions {
   designImage?: string;
   // Visual comparison
   visualCheck?: boolean;
+  // Linear status sync
+  linearSync?: string;
   // Swarm mode
   swarm?: boolean;
   strategy?: 'race' | 'consensus' | 'pipeline';
@@ -1491,6 +1493,7 @@ Focus on one task at a time. After completing a task, update IMPLEMENTATION_PLAN
     designImagePath,
     visualValidation,
     figmaScreenshotPaths,
+    linearSync: options.linearSync,
     ampMode: options.ampMode,
     review: options.review,
     headless,

src/index.ts

@@ -44,6 +44,8 @@ export type {
 export { CostTracker, resolveModelPricing } from './loop/cost-tracker.js';
 export type { IterationUpdate, LoopOptions, LoopResult } from './loop/executor.js';
 export { runLoop } from './loop/executor.js';
+export type { LinearSyncConfig, LinearSyncEvent } from './loop/linear-sync.js';
+export { createLinearSync } from './loop/linear-sync.js';
 export { appendProjectMemory, readProjectMemory } from './loop/memory.js';
 export type { ReviewFinding, ReviewResult, ReviewSeverity } from './loop/reviewer.js';
 export { runReview } from './loop/reviewer.js';

src/loop/__tests__/linear-sync.test.ts

@@ -0,0 +1,95 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createLinearSync } from '../linear-sync.js';
+
+const updateTask = vi.fn().mockResolvedValue({
+  id: 'uuid-123',
+  identifier: 'ENG-42',
+  title: 'Test issue',
+  url: 'https://linear.app/team/ENG-42',
+  status: 'In Progress',
+  source: 'linear',
+});
+const addComment = vi.fn().mockResolvedValue(undefined);
+
+// Mock the LinearIntegration class
+vi.mock('../../integrations/linear/source.js', () => ({
+  LinearIntegration: class MockLinearIntegration {
+    updateTask = updateTask;
+    addComment = addComment;
+  },
+}));
+
+describe('createLinearSync', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Reset default resolved value
+    updateTask.mockResolvedValue({
+      id: 'uuid-123',
+      identifier: 'ENG-42',
+      title: 'Test issue',
+      url: 'https://linear.app/team/ENG-42',
+      status: 'In Progress',
+      source: 'linear',
+    });
+  });
+
+  it('should move issue to In Progress on creation', async () => {
+    const handler = await createLinearSync({ issueId: 'ENG-42', headless: true });
+
+    expect(handler).not.toBeNull();
+    expect(updateTask).toHaveBeenCalledWith('ENG-42', { status: 'In Progress' });
+  });
+
+  it('should return null if updateTask fails (no auth)', async () => {
+    updateTask.mockRejectedValueOnce(new Error('No API key'));
+
+    const handler = await createLinearSync({ issueId: 'ENG-42', headless: true });
+    expect(handler).toBeNull();
+  });
+
+  it('should move issue to Done on complete event', async () => {
+    const handler = await createLinearSync({ issueId: 'ENG-42', headless: true });
+
+    await handler!({
+      type: 'complete',
+      summary: 'Implemented feature X',
+      commits: 3,
+      iterations: 5,
+      cost: '$0.42',
+    });
+
+    expect(updateTask).toHaveBeenCalledWith('ENG-42', { status: 'Done' });
+    expect(addComment).toHaveBeenCalledWith(
+      'ENG-42',
+      expect.stringContaining('Loop completed successfully')
+    );
+    expect(addComment).toHaveBeenCalledWith('ENG-42', expect.stringContaining('Commits: 3'));
+    expect(addComment).toHaveBeenCalledWith('ENG-42', expect.stringContaining('$0.42'));
+  });
+
+  it('should move issue to In Review on failed event', async () => {
+    const handler = await createLinearSync({ issueId: 'ENG-42', headless: true });
+
+    await handler!({
+      type: 'failed',
+      error: 'circuit_breaker',
+      iterations: 3,
+    });
+
+    expect(updateTask).toHaveBeenCalledWith('ENG-42', { status: 'In Review' });
+    expect(addComment).toHaveBeenCalledWith('ENG-42', expect.stringContaining('Loop stopped'));
+    expect(addComment).toHaveBeenCalledWith('ENG-42', expect.stringContaining('circuit_breaker'));
+  });
+
+  it('should not throw on event handler errors', async () => {
+    const handler = await createLinearSync({ issueId: 'ENG-42', headless: true });
+
+    // Make the next updateTask call fail
+    updateTask.mockRejectedValueOnce(new Error('Network error'));
+
+    // Should not throw
+    await expect(
+      handler!({ type: 'complete', summary: 'done', commits: 1, iterations: 1 })
+    ).resolves.not.toThrow();
+  });
+});

src/loop/executor.ts

@@ -35,6 +35,7 @@
   type PlanBudget,
 } from './cost-tracker.js';
 import { estimateLoop, formatEstimateDetailed } from './estimator.js';
+import { createLinearSync } from './linear-sync.js';
 import { appendProjectMemory, formatMemoryPrompt, readProjectMemory } from './memory.js';
 import { checkFileBasedCompletion, createProgressTracker, type ProgressEntry } from './progress.js';
 import { RateLimiter } from './rate-limiter.js';
@@ -269,6 +270,8 @@
   headless?: boolean;
   onIterationComplete?: (update: IterationUpdate) => void;
   env?: Record<string, string>;
+  /** Linear issue ID to sync status to (e.g., "ENG-42"). Requires LINEAR_API_KEY. */
+  linearSync?: string;
   /** Amp agent mode: smart, rush, deep */
   ampMode?: import('./agents.js').AmpMode;
   /** Run LLM-powered diff review after validation passes (before commit) */
@@ -556,6 +559,11 @@
       })
     : null;
 
+  // Initialize Linear status sync (non-blocking — skipped if no API key or issue not found)
+  const linearSyncHandler = options.linearSync
+    ? await createLinearSync({ issueId: options.linearSync, headless })
+    : null;
+
   // Detect validation commands if validation is enabled
   // In batch-auto mode, skip test commands — only run build/lint to avoid loops on pre-existing test failures
   // Note: fixCommand also sets auto=true but always sets fixMode, so we use that to distinguish
@@ -1169,6 +1177,17 @@
 
       finalIteration = i;
       exitReason = 'blocked';
+
+      // Sync blocked status to Linear
+      if (linearSyncHandler) {
+        const reason = isRateLimit
+          ? 'Rate limit reached'
+          : isPermission
+            ? 'Permission denied'
+            : 'Task blocked';
+        await linearSyncHandler({ type: 'failed', error: reason, iterations: i });
+      }
+
       return {
         success: false,
         iterations: i,
@@ -1774,17 +1793,42 @@
     log(chalk.dim(costTracker.formatStats()));
   }
 
+  // Sync final status to Linear
+  if (linearSyncHandler) {
+    const isSuccess = exitReason === 'completed' || exitReason === 'file_signal';
+    const costLabel = costTracker
+      ? formatCost(costTracker.getStats().totalCost.totalCost)
+      : undefined;
+    if (isSuccess) {
+      await linearSyncHandler({
+        type: 'complete',
+        summary: lastAgentOutput?.slice(-200) || '',
+        commits: commits.length,
+        iterations: finalIteration,
+        cost: costLabel,
+      });
+    } else {
+      await linearSyncHandler({
+        type: 'failed',
+        error: exitReason || 'unknown',
+        iterations: finalIteration,
+      });
+    }
+  }
+
   // Save a run summary to project memory for future runs
-  const isSuccess = exitReason === 'completed' || exitReason === 'file_signal';
-  const memorySummary = [
-    `Task: ${options.taskTitle || options.task.slice(0, 100)}`,
-    `Result: ${isSuccess ? 'success' : exitReason}`,
-    `Iterations: ${finalIteration}, Commits: ${commits.length}`,
-  ];
-  if (costTracker) {
-    memorySummary.push(`Cost: ${formatCost(costTracker.getStats().totalCost.totalCost)}`);
+  {
+    const isSuccess = exitReason === 'completed' || exitReason === 'file_signal';
+    const memorySummary = [
+      `Task: ${options.taskTitle || options.task.slice(0, 100)}`,
+      `Result: ${isSuccess ? 'success' : exitReason}`,
+      `Iterations: ${finalIteration}, Commits: ${commits.length}`,
+    ];
+    if (costTracker) {
+      memorySummary.push(`Cost: ${formatCost(costTracker.getStats().totalCost.totalCost)}`);
+    }
+    appendProjectMemory(options.cwd, memorySummary.join('\n'), dotDir);
   }
-  appendProjectMemory(options.cwd, memorySummary.join('\n'), dotDir);
 
   return {
     success: exitReason === 'completed' || exitReason === 'file_signal',

src/loop/linear-sync.ts

@@ -0,0 +1,92 @@
+/**
+ * Linear Status Sync
+ *
+ * Syncs loop execution status to a Linear issue in real-time.
+ * Updates issue state at key transitions: start → In Progress, complete → Done, failed → In Review.
+ */
+
+import chalk from 'chalk';
+import { LinearIntegration } from '../integrations/linear/source.js';
+
+export type LinearSyncConfig = {
+  /** Linear issue identifier (e.g., "ENG-42") or UUID */
+  issueId: string;
+  /** Suppress console output */
+  headless?: boolean;
+};
+
+export type LinearSyncEvent =
+  | { type: 'start' }
+  | { type: 'iteration'; iteration: number; totalIterations: number; success: boolean }
+  | { type: 'complete'; summary: string; commits: number; iterations: number; cost?: string }
+  | { type: 'failed'; error: string; iterations: number };
+
+/**
+ * Creates a Linear sync handler that updates issue status at key loop transitions.
+ *
+ * Returns null if auth is missing or the issue can't be found (non-blocking).
+ */
+export async function createLinearSync(
+  config: LinearSyncConfig
+): Promise<((event: LinearSyncEvent) => Promise<void>) | null> {
+  const linear = new LinearIntegration();
+  const log = config.headless ? (..._args: unknown[]) => {} : console.log.bind(console);
+
+  // Verify auth + issue exist by moving to "In Progress" (non-blocking on failure)
+  try {
+    await linear.updateTask(config.issueId, { status: 'In Progress' });
+    log(chalk.dim(`  Linear sync: ${config.issueId} → In Progress`));
+  } catch (err) {
+    log(
+      chalk.yellow(`  Linear sync: could not update ${config.issueId} — ${(err as Error).message}`)
+    );
+    return null;
+  }
+
+  return async (event: LinearSyncEvent) => {
+    try {
+      switch (event.type) {
+        case 'start':
+          // Already moved to "In Progress" during init
+          break;
+
+        case 'iteration':
+          // No status change per iteration
+          break;
+
+        case 'complete': {
+          const lines = ['**Loop completed successfully**', ''];
+          lines.push(`- Iterations: ${event.iterations}`);
+          if (event.commits > 0) lines.push(`- Commits: ${event.commits}`);
+          if (event.cost) lines.push(`- Cost: ${event.cost}`);
+          if (event.summary) {
+            lines.push('', `**Summary:** ${event.summary.slice(0, 500)}`);
+          }
+
+          await linear.updateTask(config.issueId, { status: 'Done' });
+          await linear.addComment(config.issueId, lines.join('\n'));
+          log(chalk.dim(`  Linear sync: ${config.issueId} → Done`));
+          break;
+        }
+
+        case 'failed': {
+          const lines = ['**Loop stopped**', ''];
+          lines.push(`- Iterations: ${event.iterations}`);
+          if (event.error) {
+            lines.push(`- Reason: ${event.error.slice(0, 300)}`);
+          }
+
+          await linear.updateTask(config.issueId, { status: 'In Review' });
+          await linear.addComment(config.issueId, lines.join('\n'));
+          log(chalk.dim(`  Linear sync: ${config.issueId} → In Review`));
+          break;
+        }
+      }
+    } catch (err) {
+      // Non-blocking — log and continue
+      if (process.env.RALPH_DEBUG) {
+        console.error(`[DEBUG] Linear sync error: ${(err as Error).message}`);
+      }
+    }
+  };
+}