Repository navigation
[Onboarding] Make first-build failures diagnosable and fixable #529
Description
Context
During Step 7 ("First Build"), an activation-time Homebrew failure was presented as a generic build failure even though Nix evaluation/build had already succeeded.
The screen:
- makes the build log cumbersome to copy or share
- always shows the same three hardcoded suggestions ("Typo...", "Stale flake inputs", "Uncommitted changes"), even when none match
- says "Your Mac was not changed" while this repro reports
"system_untouched": false - offers Retry, but no targeted recovery action
The concrete repro was a Homebrew formula-to-cask migration failure for goplaces, not any of the three suggested causes.
The regular rebuild flow already has error classification, evidence-based notices, safety copy, and Fix with AI. This ticket brings those capabilities into onboarding and adds reliable full-log copying. It is the focused onboarding implementation slice of ENG-200.
Objective
Make a failed first build immediately shareable, accurately explained, and recoverable without requiring the user to interpret raw Nix/Homebrew output.
Acceptance Criteria
Copy the complete failed-run log
- The Build log header has a one-click Copy log action.
- Copy log copies the complete log for the displayed failed run, including after a retry; it never silently copies a truncated, empty, or newer run's log.
- The UI preserves formatting and confirms success or reports a copy failure.
Show accurate failure guidance
- The UI distinguishes a Nix build failure from a later activation failure such as Homebrew reconciliation.
- The hardcoded suggestions are removed. Guidance uses the best available error details and only shows cause-specific advice when supported by evidence.
- "No changes were made" appears only when the system is known to be untouched. Partial or unknown states use accurate copy without false reassurance.
- An unclassified failure still shows the best available stage and error, Copy log, Retry, and any eligible recovery action without unrelated suggestions.
Offer the right recovery action
- Retry remains available.
- Fix with AI appears when AI is configured and the failure is eligible, using the existing recovery flow and context from the displayed failed run.
- AI fixes go through the normal Review → Apply flow and never silently change or activate the system. Ineligible failures show their appropriate targeted guidance instead.
Coverage
- Tests cover a log longer than 500 lines and retry isolation, plus representative build, activation, safety-state, AI-eligibility, and unclassified failures.
Technical Notes
- The UI buffer is capped at 500 lines and rebuild status currently drops
log_file; complete copying must use the exact on-disk log for the displayed failed run, not the mtime-based tail used by Fix with AI. - Reuse the existing error helpers, evidence-based log notices, and Fix with AI flow rather than creating a second taxonomy or recovery path.
Dependencies
- Parent: ENG-200
- Related: ENG-201, ENG-202, Add "Fix" button to Review step to trigger agent build-check-and-fix loop #416
- Hard blockers: None; the needed foundations already exist on
main(use-fix-with-ai,lib/errors.ts, evidence-based log notices).
Activity
linear-code commentedon Jul 14, 2026
ENG-595
builtbyhuy commentedon Sep 12, 2026
I checked the onboarding code at
94d38b40c257147ec72efe819c25c87832d2e9b6:BuildStepstill displays “Your Mac was not changed” for every failure and maps over the staticFIXESlist. The regular rebuild panel already usesgetRebuildSystemSafetyMessage(systemUntouched, context), so that behavior can be shared rather than reimplemented.I would take this on as a paid contribution, starting with accurate failure guidance and run-specific log copying, then connecting the existing eligible recovery action. My acceptance checks would include a partial activation, unknown safety state, a log over 500 lines, a retry with a different log, and clipboard failure. I would keep Nix activation mocked during development; this source review has not run a live system change.
Is #529 available to external contributors as a paid task, and what budget and payout terms apply? I work from Vietnam through written briefs and PR review, using Codex with explicit test evidence. I would agree the scope and fee before implementation.
zephyrZhengAI commentedon Sep 12, 2026
I reproduced two of the onboarding failures against
94d38b40c257147ec72efe819c25c87832d2e9b6with the realBuildStepcomponent and stubbed native operations: whensystemUntouchedis false, it still says “Your Mac was not changed”; the backend's Homebrew error is not rendered. Both regression tests fail on unchanged source. I also traced the log gap:record_enddropslog_file, and the UI retains only 500 lines.Is #529 available as a US$100 paid contribution covering its full acceptance criteria? I propose preserving the completed run's log identity for full-log copying and AI context, reusing the existing classified guidance/notice helpers, and connecting eligible AI recovery to the existing Review → Apply flow. Tests would cover long logs, retry isolation, copy failure, partial/unknown system state, and recovery eligibility.
Development and testing are AI-assisted with GPT-6 Astra in Codex. The checks so far are component-level; no real Nix activation was performed. I see the earlier inquiry and have not assumed assignment or a funded reward. Please confirm availability, acceptance/payment terms, and the supported payout method before I open an upstream PR.
LegendaryGhostX commentedon Sep 12, 2026
Is #529 still available for a paid contribution? I propose $150 for its acceptance criteria, with AI-assisted implementation and regression tests. Please confirm availability and payment terms before work begins.
artpumpkin commentedon Sep 13, 2026
Implemented #529 in #689, including regression tests and follow-up fixes for the automated review findings. Is this contribution eligible for a funded bounty or contributor payment? If so, please confirm the amount, acceptance criteria for payment, and claim process. No reward has been assumed.