#148: Propagate failure reason from run_failed event to CanonicalRunStatus

packages/factory/src/__test-helpers__/fixtures.ts

@@ -23,6 +23,7 @@ export function createMockRunStatus(overrides: Partial<CanonicalRunStatus> = {})
     startedAt: '2026-01-01T00:00:00Z',
     completedAt: undefined,
     status: 'in_progress',
+    reason: undefined,
     externalPlan: false,
     mergeBaseSha: undefined,
     diffBase: undefined,

packages/factory/src/client/components/StatusBar.tsx

@@ -31,6 +31,11 @@ export function StatusBar({ status, demoSlot }: StatusBarProps): React.JSX.Eleme
       <span className="status-item">
         <strong>Status:</strong> {status.status}
       </span>
+      {status.reason !== undefined && (
+        <span className="status-item">
+          <strong>Reason:</strong> {status.reason}
+        </span>
+      )}
       {duration !== null && (
         <span className="status-item">
           <strong>Duration:</strong> {duration}s

packages/factory/src/client/components/__tests__/StatusBar.test.tsx

@@ -19,6 +19,7 @@ function createMockStatus(overrides: Partial<CanonicalRunStatus> = {}): Canonica
     startedAt: '2026-01-01T00:00:00Z',
     completedAt: undefined,
     status: 'completed',
+    reason: undefined,
     externalPlan: false,
     mergeBaseSha: undefined,
     diffBase: undefined,
@@ -107,4 +108,26 @@ describe('StatusBar', () => {
 
     expect(screen.getByText('0s')).toBeInTheDocument();
   });
+
+  it('displays failure reason when status is failed and reason is present', () => {
+    const status = createMockStatus({
+      status: 'failed',
+      reason: 'quality gates failed',
+    });
+
+    render(<StatusBar status={status} />);
+
+    expect(screen.getByText('quality gates failed')).toBeInTheDocument();
+  });
+
+  it('does not display reason when reason is undefined', () => {
+    const status = createMockStatus({
+      status: 'failed',
+      reason: undefined,
+    });
+
+    const { container } = render(<StatusBar status={status} />);
+
+    expect(container.textContent).not.toContain('Reason:');
+  });
 });

packages/factory/src/server/services/__tests__/project-scanner.test.ts

@@ -44,6 +44,7 @@ function createMockStatus(overrides: Partial<CanonicalRunStatus> = {}): Canonica
     startedAt: '2026-01-01T00:00:00Z',
     completedAt: undefined,
     status: 'completed',
+    reason: undefined,
     externalPlan: false,
     mergeBaseSha: undefined,
     diffBase: undefined,

packages/factory/src/shared/__tests__/event-folder.test.ts

@@ -33,6 +33,7 @@ describe('foldEvents', () => {
     expect(result.phaseDecisions).toEqual({});
     expect(result.artifacts).toEqual([]);
     expect(result.completedAt).toBeUndefined();
+    expect(result.reason).toBeUndefined();
   });
 
   it('accumulates phase_decision events', () => {
@@ -236,6 +237,16 @@ describe('foldEvents', () => {
 
     expect(result.status).toBe('failed');
     expect(result.completedAt).toBe('2026-01-01T01:00:00Z');
+    expect(result.reason).toBe('coder crashed');
+  });
+
+  it('sets reason to undefined on run_failed without reason', () => {
+    const header = createHeader();
+    const events: RunEvent[] = [{ t: '2026-01-01T01:00:00Z', event: 'run_failed', status: 'failed' }];
+
+    const result = foldEvents(header, events);
+
+    expect(result.reason).toBeUndefined();
   });
 
   it('fold-to-cursor produces partial state from event prefix', () => {

packages/run-core/src/__tests__/event-folder.test.ts

@@ -33,6 +33,7 @@ describe('foldEvents', () => {
     expect(result.phaseDecisions).toEqual({});
     expect(result.artifacts).toEqual([]);
     expect(result.completedAt).toBeUndefined();
+    expect(result.reason).toBeUndefined();
   });
 
   it('accumulates phase_decision events', () => {
@@ -260,6 +261,16 @@ describe('foldEvents', () => {
 
     expect(result.status).toBe('failed');
     expect(result.completedAt).toBe('2026-01-01T01:00:00Z');
+    expect(result.reason).toBe('coder crashed');
+  });
+
+  it('sets reason to undefined on run_failed without reason', () => {
+    const header = createHeader();
+    const events: RunEvent[] = [{ t: '2026-01-01T01:00:00Z', event: 'run_failed', status: 'failed' }];
+
+    const result = foldEvents(header, events);
+
+    expect(result.reason).toBeUndefined();
   });
 
   it('fold-to-cursor produces partial state from event prefix', () => {

packages/run-core/src/event-folder.ts

@@ -66,6 +66,7 @@ export function foldEvents(header: RunHeader, events: ReadonlyArray<RunEvent>):
     startedAt: header.startedAt,
     completedAt: undefined,
     status: 'in_progress',
+    reason: undefined,
     externalPlan: header.externalPlan,
     mergeBaseSha: header.mergeBaseSha,
     diffBase: header.diffBase,
@@ -106,6 +107,7 @@ function applyEvent(state: CanonicalRunStatus, event: RunEvent): void {
     case 'run_failed':
       state.status = event.status;
       state.completedAt = event.t;
+      state.reason = event.reason;
       break;
 
     case 'phase_decision':

packages/run-core/src/parsers/__tests__/run-data-parser.test.ts

@@ -214,6 +214,7 @@ describe('parseStatusFile', () => {
 
       expect(result.mode).toBeUndefined();
       expect(result.model).toBeUndefined();
+      expect(result.reason).toBeUndefined();
       expect(result.artifacts).toBeUndefined();
     });
   });
@@ -613,6 +614,7 @@ describe('parseRunData', () => {
       expect(result.completedAt).toBe('2026-02-26T15:30:00Z');
       expect(result.mode).toBe('orchestrated');
       expect(result.model).toBe('claude-opus-4-6');
+      expect(result.reason).toBeUndefined();
     });
 
     it('flattens nested context and config to top-level fields', async () => {
@@ -962,6 +964,29 @@ describe('parseRunData', () => {
       expect(result.model).toBe('claude-opus-4-6');
     });
 
+    it('propagates reason from run_failed event in JSONL', async () => {
+      const logContent = jsonlLines(
+        { t: '2026-01-01T00:00:00Z', event: 'run_started' },
+        { t: '2026-01-01T00:01:00Z', event: 'phase_started', phase: 'implementation' },
+        {
+          t: '2026-01-01T00:02:00Z',
+          event: 'run_failed',
+          status: 'failed',
+          reason: 'quality gates failed',
+        },
+      );
+
+      mockFileContents({
+        '/runs/test-run/run-index.json': JSON.stringify(minimalV3Header()),
+        '/runs/test-run/run-log.jsonl': logContent,
+      });
+
+      const result = await parseRunData('/runs/test-run');
+
+      expect(result.status).toBe('failed');
+      expect(result.reason).toBe('quality gates failed');
+    });
+
     it('throws descriptive error when v3 header is present but run-log.jsonl is ENOENT', async () => {
       mockFileContents({
         '/runs/test-run/run-index.json': JSON.stringify(minimalV3Header()),

packages/run-core/src/parsers/run-data-parser.ts

@@ -137,6 +137,7 @@ function normalizeV1(raw: V1StatusObject): CanonicalRunStatus {
   return {
     ...rest,
     completedAt: completedAt ?? undefined,
+    reason: undefined,
     mode: undefined,
     model: undefined,
     phaseDecisions: phaseDecision,
@@ -198,6 +199,7 @@ function normalizeV2(raw: V2RunIndex): CanonicalRunStatus {
     startedAt: context.startedAt,
     completedAt: context.completedAt ?? undefined,
     status: context.status,
+    reason: undefined,
     externalPlan: config.externalPlan,
     mergeBaseSha: config.mergeBaseSha,
     diffBase: config.diffBase,

packages/run-core/src/types/canonical.ts

@@ -25,6 +25,7 @@ export interface CanonicalRunStatus {
   startedAt: string;
   completedAt: string | undefined;
   status: RunStatus;
+  reason: string | undefined;
   externalPlan: boolean | undefined;
   mergeBaseSha: string | undefined;
   diffBase: string | undefined;