Propagate failure reason from run_failed event to CanonicalRunStatus

[williamthorsen]

Context

After #130, the complete_run MCP tool emits run_failed events with an optional reason field when a run fails. The RunFailedEvent type and Zod schema in run-core already support this field. However, foldEvents in packages/run-core/src/event-folder.ts handles run_failed events but discards the reason field — CanonicalRunStatus has no corresponding property.

Problem

Downstream consumers (Factory visualization, status adapter) cannot access the failure reason because it is lost during event folding. If a run fails with a reason like "quality gates failed", that context is preserved in the JSONL event log but not surfaced through the canonical run status API.

Considerations

• CanonicalRunStatus is the single source of truth for run state, defined in packages/run-core/src/types/canonical.ts. Factory re-exports it from packages/factory/src/shared/types/canonical.ts.
• The status adapter (packages/factory/src/server/adapters/status-adapter.ts) is a re-export from @codeassembly/run-core/parsers and needs no changes.
• The project uses exactOptionalPropertyTypes, so the field should be reason: string | undefined (always present, nullable) rather than reason?: string (possibly absent), matching the pattern of completedAt.
• The Factory event-folder test file mirrors the run-core test file; both must be updated.

Proposed solution

1. Add reason: string | undefined to CanonicalRunStatus in packages/run-core/src/types/canonical.ts
2. Update foldEvents in packages/run-core/src/event-folder.ts to initialize reason: undefined and extract reason from run_failed events
3. Display the failure reason in the Factory StatusBar (packages/factory/src/client/components/StatusBar.tsx) when present
4. Add/update tests in both run-core and factory packages

Acceptance criteria

Must have

• CanonicalRunStatus includes a reason: string | undefined field
• foldEvents extracts reason from run_failed events and includes it in the returned status
• foldEvents initializes reason to undefined for new runs and non-failure completions
• Existing tests continue to pass
• New tests verify reason propagation (with and without reason)

Should have

• Factory StatusBar displays the failure reason when available
• StatusBar tests cover both present and absent reason

Nice to have

• Factory visualization shows failure reason on hover or in a tooltip

[williamthorsen]

Implementation plan

Plan: Propagate failure reason from run_failed event to CanonicalRunStatus

Date: 2026-03-03 12:00 UTC
Scope: Surface the reason field from run_failed events through the canonical run status API and into the Factory status bar.

Problem

The complete_run MCP tool emits run_failed events with an optional reason field (e.g., "quality gates failed"). The RunFailedEvent type and Zod schema already support this field. However, foldEvents discards the reason during event folding because CanonicalRunStatus has no corresponding property. Downstream consumers (Factory visualization, status adapter) cannot access the failure context.

Approach

This is a straightforward data-flow threading change:

1. Add the field to the domain type
2. Populate it during event folding
3. Display it in the UI

The RunFailedEvent type and Zod validation already include reason — no changes needed at the event-level schema or MCP tool layer. The status adapter (packages/factory/src/server/adapters/status-adapter.ts) is a re-export from @codeassembly/run-core/parsers and needs no changes.

Steps

1. Add reason to CanonicalRunStatus

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

Add reason: string | undefined to the CanonicalRunStatus interface, positioned after status:

export interface CanonicalRunStatus {
  // ... existing fields ...
  status: RunStatus;
  reason: string | undefined;  // ← new
  // ... remaining fields ...
}

This is the single source of truth — Factory re-exports it via packages/factory/src/shared/types/canonical.ts.

2. Update foldEvents to extract reason from run_failed

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

In the initial state construction (line 68), add reason: undefined.

In the run_failed case of applyEvent (lines 106–109), add state.reason = event.reason:

case 'run_failed':
  state.status = event.status;
  state.completedAt = event.t;
  state.reason = event.reason;
  break;

3. Update event-folder tests (run-core)

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

• Extend the existing 'sets status and completedAt on run_failed' test to also assert result.reason === 'coder crashed'
• Add a new test: 'sets reason to undefined on run_failed without reason' — verifying that run_failed events without a reason field produce reason: undefined
• Extend the 'returns initial state with no events' test to verify result.reason is undefined

4. Update event-folder tests (factory)

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

Mirror the same test updates from step 3, since this test file exercises the Factory's re-exported foldEvents.

5. Display failure reason in StatusBar

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

Add a conditional <span> after the status display that shows the failure reason when reason is defined:

<span className="status-item">
  <strong>Status:</strong> {status.status}
</span>
{status.reason !== undefined && (
  <span className="status-item">
    <strong>Reason:</strong> {status.reason}
  </span>
)}

6. Update StatusBar tests

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

• Add test: 'displays failure reason when status is failed and reason is present'
• Add test: 'does not display reason when reason is undefined'
• Update createMockStatus to include reason: undefined in the default mock

7. Verify

Run pnpm run check from root to confirm typecheck, lint, format, and all tests pass across both packages.

Risks

• Low: The CanonicalRunStatus type is used widely in Factory mappers and React components. Adding a required-but-nullable field is backwards-compatible — existing spread patterns and destructuring will continue to work. The TypeScript compiler (tsgo strict mode with exactOptionalPropertyTypes) will surface any issues at typecheck time.
• Low: The Factory event-folder test file (packages/factory/src/shared/__tests__/event-folder.test.ts) is a near-duplicate of the run-core test. Both must be updated in sync.

Dependencies

None — all prerequisite work (run_failed event type, Zod schema, MCP tool) was completed in #130.

Files to modify

File	Change
packages/run-core/src/types/canonical.ts	Add reason field to CanonicalRunStatus
packages/run-core/src/event-folder.ts	Extract reason from run_failed; initialize to undefined
packages/run-core/src/__tests__/event-folder.test.ts	Add/extend tests for reason propagation
packages/factory/src/shared/__tests__/event-folder.test.ts	Mirror run-core test changes
packages/factory/src/client/components/StatusBar.tsx	Display failure reason conditionally
packages/factory/src/client/components/__tests__/StatusBar.test.tsx	Add tests for reason display