fix(converge): re-run records-harness after tools installs an agent

[mlorentedev]

#2013 D11 (owner, 2026-10-10). Found by the from-zero job (#2331, run 38107714925) on macos-latest: the second converge was not a no-op.

[CHANGE] records-harness  1 instruction file(s) deployed: .copilot/copilot-instructions.md

records-harness runs before tools on purpose (#2016, instructions-first), but it only deploys the instructions of agents already on PATH. In the first run, tools installs copilot after records-harness has skipped it. The same will happen to claude, pi and agy once they install through mise (P5c).

Change

• converge.Revisiter: a reconciler declares the step whose change re-runs it. Run applies it again right after an apply in which that step reported a change, as its own report entry (after tools: …).
• records-harness declares RevisitAfter() = "tools".
• Never revisited:
  • a converged machine, because tools reports no change;
  • a plan, because nothing it reports has been installed yet;
  • a reconciler that does not run on this OS.
• A revisit's failure stops the run and names the step, like any other step.

The owner declined two alternatives:

• moving records-harness after tools, which opens a window where an agent has no instructions;
• gating on the catalog, which would mean changing compile-harness.sh as well, since it also gates on PATH.

Evidence

macOS arm64:

• go build, go vet, GOOS=windows go vet, go test ./... all ok.
• golangci-lint: 0 issues.

New tests:

• TestRun_AChangeRerunsTheStepsThatRevisitIt
• TestRun_NoChangeOrAPlanRevisitsNothing, which includes a step another OS runs
• TestRun_AFailedRevisitStopsTheRun
• TestRegistry_RecordsHarnessRevisitsAfterTools

Mutations, each one caught:

• Dropping the revisit call or its error.
• Revisiting under a plan.
• Dropping the platform filter.
• Pointing records-harness at another step.

The end-to-end proof is X1's idempotence step on its next macOS run after this merges.

Knowledge

• Lesson: none: the rule is the Revisiter doc comment plus the D11 entry in specs/PLAT-001b-one-entrypoint/verification.md
• ADR: none: an ordering refinement inside ADR-041 decision 4, recorded as D11 on PLAT-001: [EPIC] OS-agnostic from-zero bootstrap — macOS bring-up as the forcing function #2013 and in the spec
• Runbook: none: no procedure changes

Evidence output (fc0fa74, macOS arm64)

$ go build ./... && go vet ./... && GOOS=windows go vet ./... && go test ./...
36 packages ok (internal/review has no test files)
$ go test ./internal/converge/ -run 'Revisit|Revisits' -v
--- PASS: TestRun_AChangeRerunsTheStepsThatRevisitIt (0.00s)
--- PASS: TestRun_NoChangeOrAPlanRevisitsNothing (0.00s)
--- PASS: TestRun_AFailedRevisitStopsTheRun (0.00s)
--- PASS: TestRegistry_RecordsHarnessRevisitsAfterTools (0.00s)
ok  	github.com/mlorentedev/dotfiles/cli/internal/converge	0.254s
$ golangci-lint run ./...
0 issues.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 8 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: mlorentedev/dotfiles/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 10ca2ca9-d470-449f-b3ac-c0f9c11af79f

---

📥 Commits

Reviewing files that changed from the base of the PR and between 27020ee and 5008864.

---

📒 Files selected for processing (4)

• cli/internal/converge/converge.go
• cli/internal/converge/converge_test.go
• cli/internal/converge/harness.go
• specs/PLAT-001b-one-entrypoint/verification.md

---

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis 🔶 2013 - Partially compliant Compliant requirements: Small, focused change touching shared converge path, within the ~300 LOC row budget. Ships the guard (tests: rerun, no-op/plan, failed revisit, registry wiring). Does not regress Windows: GOOS=windows go vet in evidence and the revisit platform check. Touches a specs/<id>/ folder (specs/PLAT-001b-one-entrypoint/verification.md). Non-compliant requirements: Cannot confirm the reference to "D11" from the ticket body, since the epic lists only D1–D8. Requires further human verification: Confirmation that the macOS Wave-1 gate is respected (setup not run on the Mac prematurely). Confirmation the Windows CI leg stays green for this change. 2016 - Partially compliant Compliant requirements: Makes a second converge a no-op instead of redeploying (contributes to the "0 changes on re-run" intent). A revisit failure is fatal and names the step, matching "fatal, not a warning". Non-compliant requirements: Does not implement the first-run bootstrap step (mirror/deploy/bind), which is PLAT-001 P9: instructions-first deploy so harness rules reach agents before setup #2016's core fix. Does not add the doctor FAIL check for an agent on PATH without its instruction file. records-harness stays linux/darwin only, so the Windows-equivalent acceptance is not addressed here. Requires further human verification: "Every present agent has its instruction file after step 1 alone" on macos/ubuntu runners (needs the X1 run). "Running the step twice reports 0 changes" verified on real runners. Doctor FAIL behaviour for a missing instruction file.

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 PR contains tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Harness compliance Definition of Done §5 (Evidence): the ## Evidence section asserts results rather than showing the command output produced in the session — "go build, go vet, GOOS=windows go vet, go test ./... all ok" and "golangci-lint: 0 issues". The rule requires that no completion claim stand without the command output that proves it, so the claim is currently unverifiable from the PR alone. This is REAL with respect to the harness rule (the section is fully shown, not part of the truncation); paste the actual run output.

---

⚙️ Agent run details

• Model: openai/deepseek-v4-flash
• Tokens: 20,283 in / 18,487 out / 38,770 total
• Time cost: 111.6s
• AI calls: 1

[mlorentedev]

Review triage

Reviewed by pr-agent (github-actions, on fc0fa74). No other reviewer output.

#	Finding	Disposition
1	Harness compliance: the Evidence section states results without the command output	Applied: the body now carries the run output (build, vet, Windows vet, the full test run, the four revisit tests by name, golangci-lint)