A

Debug A Failed Lifecycle Run

Use this guide when build, ingest, or garden leaves a failed run. Start with codealmanac jobs, then inspect jobs show <run-id> and jobs logs <run-id>. The durable run ledger keeps the record and normalized event stream after the original process exits [@repo-readme] [@run-store].

If the run is active, codealmanac jobs attach <run-id> follows the same event record until it becomes terminal. The readable log is the primary debugging surface; JSON output exposes the corresponding structured harness fields. Pressing Ctrl-C while attached only detaches the foreground command without mutating the run; cancel it explicitly with codealmanac jobs cancel <run-id> if the run should stop [@jobs-dispatch]. See Run states and events for the full attach, detach, and cancellation contract.

Identify The Boundary#

  • Readiness or authentication failures appear before provider execution and include Yoke's repair message when available [@yoke-adapter].
  • Provider failures and timeouts become a failed terminal harness event with structured failure details [@yoke-results].
  • Tool and helper-agent failures appear in the preceding normalized events.
  • Validation failures occur after a successful agent run when the resulting wiki source does not satisfy CodeAlmanac's product checks [@operation-runner].
  • Indexing failures usually indicate malformed source or route collisions.

The operation runner records harness output before validating success, so the event stream normally contains the provider evidence needed to distinguish a Yoke/provider failure from a wiki validation failure [@operation-runner] [@operation-harness]. Do not inspect deleted provider-specific adapter files or infer failure state from assistant prose when a structured error event exists.

After correcting wiki source, follow Verify A Wiki Change. After correcting credentials, installation, or provider configuration, run codealmanac doctor and queue a new lifecycle run.