fix: surface swallowed wiki and run failures

[devin-ai-integration]

Summary

Four places where an error disappeared instead of reaching the operator:

• topics.yaml parse errors vanished. load_topics_yaml returned () for a malformed or unreadable file, so every topic silently dropped out of the index while validate reported the wiki as fine. Reads stay lenient (existing contract), but the reader now carries the error:

  read_topics_yaml(almanac_path) -> TopicsYamlRead(topics=..., error=...)
  load_topics_yaml(almanac_path) -> read_topics_yaml(almanac_path).topics

  HealthService.validate turns a non-None error into a topics_file issue.
• Every index refresh failure was labelled page_routes. Route collisions now raise PageRouteCollision(ValidationFailed); anything else ensure_fresh raises (bad page paths, frontmatter rewrites) is categorised index_sources instead of being mislabelled.
• A run could be left non-terminal with no record of why. OperationRunner.fail wrapped both the error event and the runs.finish transition in suppress(Exception). The event write stays best-effort; the terminal transition moved to finish_failed_run, which raises ExecutionFailed naming the run, the original failure, and the bookkeeping error.
• Unreadable files hashed like missing ones. file_hash returned sha256(b"") on OSError, so an unreadable topics.yaml produced the same source signature as an absent one and refresh could report itself fresh. Unreadable files now hash distinctly.

Why

These are the cases in the audit where a failure changed observable product state (topics dropped from the index, a run stuck in running, an index reporting itself fresh) with nothing surfaced to the user. The other broad handlers reviewed — telemetry capture, transcript/frontmatter parsing, webbrowser.Error, psutil teardown — are deliberate and documented, and are left alone.

Verification

uv run ruff check .
uv run pytest          # 567 passed
uv run codealmanac validate   # validate: ok, 71 pages

New tests: test_validate_reports_unreadable_topics_file, test_operation_failure_surfaces_unrecorded_terminal_transition, test_unreadable_source_file_does_not_hash_like_a_missing_one. The existing test_malformed_topics_yaml_does_not_break_reads and test_operation_failure_records_terminal_state_when_event_write_fails still pass unchanged, which is the point: lenient reads and best-effort event logging are preserved.

Docs and wiki

• almanac/ wiki updated: architecture/wiki/health-and-validation, architecture/wiki/topics-dag, architecture/lifecycle/operation-runner.

Notes for reviewers

workflows/operations/failure.py is a new file only because workflows/operations/service.py is capped at 250 lines by test_page_writing_workflow_services_stay_small; the terminal-transition write is a coherent responsibility to own next to commit.py and harness.py. The error-event write intentionally stayed in service.py so the existing monkeypatch on operations.record keeps exercising that path.

index_sources is a new validation category string, visible in validate --json output for wikis that fail index refresh for non-collision reasons.

Link to Devin session: https://app.devin.ai/sessions/ce558f6ddad94f819d9095b56d3d296b
Requested by: @rohans0509

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring