Gracefully handle invalid log files in orchestrated-run directories

[williamthorsen]

Problem

The Factory server's ProjectScanner encounters invalid run-index.json files during directory scans. When parsing fails, the server logs console.error with full stack traces that look like server crashes. In reality, these are data quality issues: old files, interrupted runs, or incompatible formats.

Example log output:

Error parsing run data for codeassembly/CODY-115/20260302-122846Z-orchestrated: Error: Invalid run-index.json at /Users/william/.ai/projects/codeassembly/tickets/CODY-115/20260302-122846Z-orchestrated/run-index.json
    at parseRunIndexFromRaw (file:///...run-data-parser.js:104:11)
    ...

Root cause

The parseRunData function in run-core throws plain Error objects with minimal context. The scanner's catch block in scanTicket treats all non-ENOENT errors the same way: console.error + skip the run. There are three distinct failure categories that should be handled differently:

1. Corrupt JSON — run-index.json exists but contains invalid JSON syntax
2. Invalid schema — valid JSON but doesn't match v2 or v3 schema (Zod validation details are discarded)
3. Missing companion — v3 header exists but run-log.jsonl is missing

Proposed solution

1. Introduce a structured RunDataParseError class in run-core with category, filePath, and optional zodIssues fields
2. Refactor the parser to throw RunDataParseError instead of plain Error (preserving existing error messages for backward compatibility)
3. Update the scanner to catch RunDataParseError specifically and log console.warn with an informative message and fix suggestion instead of console.error with a stack trace

Acceptance criteria

Must have

• Parse errors produce a console.warn (not console.error) with a clear, single-line message
• The warning includes the run path and what went wrong
• Invalid runs are still skipped (no crash, no partial data)
• Truly unexpected errors (permissions, I/O failures) remain as console.error

Should have

• The warning includes a suggestion for how to fix the problem
• Schema validation errors include Zod issue details (available on the error object)

Nice to have

• Auto-fixable errors are fixed automatically

Out of scope

• User sees errors in the UI

[williamthorsen]

Implementation plan

Context

The Factory server's ProjectScanner encounters invalid run-index.json files during directory scans and logs console.error with full stack traces. These look like server crashes but are really just data quality issues (old files, interrupted runs, incompatible formats). Invalid runs silently disappear from the index — no error indication, just a noisy log.

The fix introduces a structured error class in run-core so the scanner can distinguish known parse failures from unexpected errors, then downgrades known failures to informative warnings with fix guidance.

Step 1: Create RunDataParseError class in run-core

File: packages/run-core/src/run-data-parse-error.ts (new)

Create a custom error class with structured metadata:

export type RunDataParseErrorCategory = 'corrupt_json' | 'invalid_schema' | 'missing_companion';

export class RunDataParseError extends Error {
  readonly category: RunDataParseErrorCategory;
  readonly filePath: string;
  readonly zodIssues: ZodIssue[] | undefined;

  constructor(message: string, category: RunDataParseErrorCategory, filePath: string, zodIssues?: ZodIssue[]) {
    super(message);
    this.name = 'RunDataParseError';
    // ... assign fields
  }
}

Key design decisions:

• message is the first parameter — preserves the same error message text as the current plain Error throws, so existing test assertions (rejects.toThrow('Invalid run-index.json')) continue to pass with zero changes.
• suggestion is NOT on the error class — that's a consumer concern. The scanner maps category → suggestion. This keeps run-core neutral as a shared library.
• Exported from the run-core root (packages/run-core/src/index.ts) since it's a pure class with no Node.js deps.

Step 2: Refactor parser to throw RunDataParseError

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

Replace the 5 plain Error throws:

Current throw	Category	Change
throw new Error('Failed to parse JSON at ...: ...') (run-index.json)	corrupt_json	→ throw new RunDataParseError(sameMessage, 'corrupt_json', indexPath)
throw new Error('Invalid run-index.json at ...')	invalid_schema	→ throw new RunDataParseError(sameMessage, 'invalid_schema', filePath, zodIssues)
throw new Error('v3 ... but run-log.jsonl is missing')	missing_companion	→ throw new RunDataParseError(sameMessage, 'missing_companion', indexPath)
throw new Error('Failed to parse JSON at ...: ...') (status.json)	corrupt_json	→ throw new RunDataParseError(sameMessage, 'corrupt_json', filePath)
throw new Error('Invalid status.json at ...')	invalid_schema	→ throw new RunDataParseError(sameMessage, 'invalid_schema', filePath, zodIssues)

Also inline the safeParse calls at the throw site to capture Zod issues:

• Remove isValidRunIndex() helper — inline v2RunIndexSchema.safeParse(raw) in parseRunIndexFromRaw
• Remove isValidStatusObject() helper — inline v1StatusSchema.safeParse(raw) in parseStatusFile

Step 3: Update scanTicket error handling in project-scanner

File: packages/factory/src/server/services/project-scanner.ts

Replace the catch block in scanTicket:

import { RunDataParseError } from '@codeassembly/run-core';

const PARSE_ERROR_SUGGESTIONS: Record<RunDataParseErrorCategory, string> = {
  corrupt_json: 'Check for syntax errors or delete and regenerate the file',
  invalid_schema: 'The file may be from an incompatible version; delete the run directory to clear it',
  missing_companion: 'The run may have been interrupted; delete the run directory to clear it',
};

// In catch block:
if (error instanceof RunDataParseError) {
  const suggestion = PARSE_ERROR_SUGGESTIONS[error.category];
  console.warn(`[project-scanner] Skipping ${slug}/${ticketId}/${runId}: ${error.message} — ${suggestion}`);
  continue;
}
// Non-parse errors keep console.error (these are truly unexpected)
console.error(`Error parsing run data for ${slug}/${ticketId}/${runId}:`, error);

Step 4: Tests

New file: packages/run-core/src/__tests__/run-data-parse-error.test.ts

• Verify construction, instanceof Error, field values, name property

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

• Add instanceof RunDataParseError assertions alongside existing rejects.toThrow(string) assertions
• Verify category and filePath fields on thrown errors
• Verify zodIssues is populated for schema validation failures

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

• Update "skips runs with invalid status.json" test: throw RunDataParseError instead of plain Error
• Assert console.warn is called with the expected format (not console.error)
• Add a second test case: non-RunDataParseError errors still go to console.error

Files to modify

File	Change type
packages/run-core/src/run-data-parse-error.ts	New
packages/run-core/src/index.ts	Add export
packages/run-core/src/parsers/run-data-parser.ts	Refactor throws
packages/factory/src/server/services/project-scanner.ts	Update catch block
packages/run-core/src/__tests__/run-data-parse-error.test.ts	New
packages/run-core/src/parsers/__tests__/run-data-parser.test.ts	Extend assertions
packages/factory/src/server/services/__tests__/project-scanner.test.ts	Update mock + assertions

Not implementing

• Auto-fix: None of the three error categories can be meaningfully auto-fixed (corrupt JSON can't be regenerated, schema mismatches need the source agent, missing companions are genuinely lost).
• UI error display: Explicitly out of scope per the issue.

Verification

1. pnpm run ws test in both packages/run-core and packages/factory — all existing tests pass
2. pnpm run typecheck — no new type errors
3. Manual test: place a corrupt run-index.json in a run directory, start the Factory server, confirm console.warn message appears (not console.error with stack trace)

[williamthorsen]

Insight: Assertion functions as a Zod integration pattern

When inlining Zod safeParse to capture zodIssues on the RunDataParseError, the coder chose TypeScript assertion functions (asserts raw is T) over as casts or z.infer types. This is a clean solution for strict-mode projects where exactOptionalPropertyTypes causes z.infer<> types to diverge from hand-written interfaces — the assertion function narrows the type without lying about it.

function assertValidRunIndex(raw: unknown, filePath: string): asserts raw is V2RunIndex {
  const result = v2RunIndexSchema.safeParse(raw);
  if (!result.success) {
    throw new RunDataParseError('Invalid run-index.json at ' + filePath, 'invalid_schema', filePath, result.error.issues);
  }
}

This pattern replaces the previous isValidRunIndex() boolean predicates, merging the check-and-throw into one step while preserving type narrowing downstream.