5.6 KiB
id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design
| id | title | status | wave | depends_on | plan | requirements | acceptance_criteria | system_design | |||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 01-git-diagnostics | Explain Git refresh failures | done | 1 | plan.md |
|
|
|
Task 01: Explain Git refresh failures
Summary
Add diagnostic evidence without changing refresh admission or fallback. Use fixed categories and explanations instead of raw Git output.
In scope
- Add
refresh_diagnostics.gowith a diagnostic-only classifier and fixed summaries. - Integrate both fetch and pull failure paths, including configured fallback failures.
- Record operation, local checkout path, branch, existing reason, diagnostic code, fixed detail, and optional exit code. Do not read or emit remote URLs.
- Preserve error identities, progress payloads, return values, and ref selection.
- Correct the misleading raw-output comment on
syncFailureCause.
Out of scope
Other work orders, terminal behavior, UI, schema, retry policy, and live-instance changes.
Acceptance
- Known failures have useful fixed explanations. Unknown output remains unknown.
- Logs, errors, and progress contain no injected secret or raw command output.
- Required refresh, local fallback, missing-ref fallback, and cancellation retain their decisions.
Regression evidence
In new refresh_diagnostics_test.go, add TestRefreshDiagnosticClassification,
TestBaseRefreshDiagnosticEmission, and TestRefreshDiagnosticsPreservePolicy.
The emission test must fail first because current logs lack the new fields.
Use the fake command pattern from manager_test.go and the observer pattern
from manager_state_test.go. Exercise fetch and pull through the manager,
not only the classifier. Include SSH public-key and host-key errors, DNS,
connection/TLS errors, missing refs, non-fast-forward errors, inaccessible
repositories, locks, unknown text, timeout, and cancellation.
Inject tokens, credential URLs, headers, control characters, and long output. Assert their absence from all emitted fields, returned errors, and progress. Use actual local refs to cover required failure and successful local fallback. Assert no ref mutation or extra Git invocation. Keep the existing missing-ref policy tests authoritative for eligibility.
Verification
Run the regression first and record its expected failure. After implementation, run these commands from the repository root:
(cd apps/backend && go test ./internal/worktree -count=1)
(cd apps/backend && go test -race ./internal/worktree -run 'Test(RefreshDiagnostic|BaseRefreshDiagnostic|RefreshDiagnosticsPreservePolicy)' -count=1)
git diff --check
Files likely touched
apps/backend/internal/worktree/manager_git.goapps/backend/internal/worktree/refresh_diagnostics.go (new)apps/backend/internal/worktree/refresh_diagnostics_test.go (new)
Dependencies
None. Execute in the plan order by default.
Risks
Git text is not a stable API. Keep diagnostic classification separate from policy.
Parallelism
sequential
Inputs
- Requirement
- System design
- Plan evidence and exclusions
- Backend AGENTS.md and TDD backend test guidance.
Results
Implemented credential-safe diagnostic classification and emission for base branch fetch and pull failures. The diagnostic fields preserve the existing refresh reason and policy decisions, while fixed explanations and optional exit codes keep raw Git output out of logs, returned errors, and progress.
The new regression suite covers authentication, SSH key and host failures, DNS, connection, TLS, missing refs, non-fast-forward updates, repository access, lock contention, unknown output, timeout, cancellation, fetch and pull emission, and required-refresh policy preservation. The first emission test failed before the production change because no diagnostic log existed.
Verification passed:
go test ./internal/worktree -count=1
go test -race ./internal/worktree -run 'Test(RefreshDiagnostic|BaseRefreshDiagnostic|RefreshDiagnosticsPreservePolicy)' -count=1
git diff --check
Review remediation
The classifier now recognizes Git's pull fast-forward refusal, uses local branch wording for that outcome, and leaves tag-clobber output unknown. Fetch and pull fixtures cover the real failure forms. Builds and tests were not rerun for this review remediation, so the verification above describes the pre-remediation implementation state at that time.
PR fixup verification
The focused worktree regression passed after the review fixes:
go test ./internal/worktree -run 'Test(RefreshDiagnostic|BaseRefreshDiagnostic|RefreshDiagnosticsPreservePolicy)' -count=1
golangci-lint run ./... --new-from-rev='195530e5766abf7f44f08e2d5ad436b22c28d748' --timeout=5m
The later CI remediation also passed go build ./... and the full
internal/worktree, internal/agent/runtime/lifecycle, and
internal/gateway/websocket package suites, including race-enabled runs for
the two packages affected by CI. Base-relative lint reports zero issues with
the ten-minute analyzer budget. A complete local go test ./... -count=1
run remains nonzero on environment-sensitive process-tree, home-config, and
launcher tests, plus one lifecycle package failure under aggregate scheduling;
the lifecycle package passed when rerun alone.