fix: retry transient Windows bundle publication locks

[mvanhorn]

Windows source installation executes the newly built gentle-ai.exe to verify its version immediately before publishing its staging directory. Transient executable or scanner handles can make the following rename fail with EPERM; the installer currently attempts the rename once and removes staging in its finally block. The reporter and two other participants reproduce the missing package-local runtime, including on the current pinned runtime 3.1.0; two report success on the second rename attempt after a delay. The local clone confirms that publishBundle still makes single-attempt renames, while its existing backup/rollback protocol can preserve an earlier bundle.

Summary

Add a private rename retry function in scripts/gentle-ai-installer.mjs, used by the production publication path: on effective platform win32 (options.platform ?? process.platform), retry only EPERM, EBUSY, and EACCES for five total attempts with asynchronous waits of 200, 400, 800, and 1600 ms; propagate the last original error immediately for other codes or after exhaustion. Preserve options.rename as the underlying filesystem operation and route both forward renames and the rollback rename in publishBundle through this function, retaining the movedPrior transition only after a successful backup rename, existing directory/symlink checks, and backup preservation when rollback fails.

Test Plan

• Fresh Windows x64 and arm64 source installation: staging publication first fails with EPERM and then succeeds; assert two rename attempts, one source build, installed=true, binary bytes and canonical integrity manifest at the pinned version path, no staging leftovers, and successful verified reuse on the next install.
• Table-test EPERM, EBUSY, and EACCES retries; succeed on the fifth attempt to establish the inclusive budget and verify increasing delays without sleeping after success. Use mocked timers where supported, flushing async filesystem work between timer advances rather than asserting wall-clock timing.
• Replacement of an existing bundle: transient failure moving live to backup eventually succeeds; staging publication also tolerates a transient lock. Check the final bundle and removal of the backup after success.
• Permanent publication lock: five failed staging renames reject with the final original error and restore the prior bundle; transient rollback locks also receive their own bounded retries. Preserve the current rollback test's non-coded error behavior and old.txt sentinel.
• Exhausted backup move leaves the original live bundle untouched; exhausted rollback retains the backup and surfaces the existing rollback error with its cause. A subsequent install exercises backup restoration, including a transient restoration lock, before rebuilding or reusing a valid recovered bundle.
• Nonretryable errors such as ENOSPC and uncoded errors fail after one attempt. Darwin/Linux signed-release fixtures fail on EPERM after one attempt, proving retries depend on the requested platform rather than the test host.
• A fresh install with persistent failure rejects and cleans staging without pretending a runtime exists; no fallback to an unverified binary is introduced. Keep existing symlink rejection, integrity checks, concurrency locks, source-build failure, and signed-bundle compatibility regressions passing.
• Implementation validation: run node --experimental-strip-types --test tests/gentle-ai-installer.test.ts, then the repository's pnpm test and pnpm run typecheck with already provisioned dependencies. Existing fixtures support portable failure injection without live downloads or Windows hardware; a Windows Defender install is useful supplementary validation, not required for deterministic regression coverage.

Closes #946

Summary by CodeRabbit

• Bug Fixes
  • Improved Windows bundle installation reliability by retrying transient file-lock errors during publication.
  • Added recovery handling for interrupted updates, including restoring the previously installed bundle when replacement fails.
  • Prevented incomplete staging or backup files from being left behind after failed installations.
  • Installation now avoids unnecessary rebuilds when a valid existing bundle can be recovered.
  • Non-retryable errors continue to fail promptly, and publication behavior on other platforms remains unchanged.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: c5c43e5b-934f-4d25-8692-3df2cec4c656

📥 Commits

Reviewing files that changed from the base of the PR and between 29f52a2 and b9651c5.

📒 Files selected for processing (2)

• scripts/gentle-ai-installer.mjs
• tests/gentle-ai-installer.test.ts

Included review availability: Your plan provides up to 4 included reviews per hour; 2 remain after this review.

---

📝 Walkthrough

Walkthrough

The installer now retries selected Windows rename failures during bundle publication and recovery. Tests cover retry timing, successful publication, rollback, backup restoration, cleanup, non-retryable errors, and non-Windows behavior.

Changes

Bundle publication recovery

Layer / File(s)	Summary
Windows rename retry and recovery scripts/gentle-ai-installer.mjs	Windows retries EPERM, EBUSY, and EACCES renames with 200, 400, 800, and 1600 ms delays. The helper is used for backup moves, staging publication, rollback, and backup recovery. Other platforms and errors retain single-attempt behavior.
Publication and failure-path tests tests/gentle-ai-installer.test.ts	Tests validate successful retries, retry limits, timer delays, backup restoration, rollback outcomes, cleanup, manifest contents, reuse, non-retryable errors, and Darwin/Linux single-attempt failures.

Priority: ➖ Normal

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Medium

Suggested reviewers: alan-thegentleman

Merge Risk: ⚪ Minimal · up to b9651

The retry, rollback, and recovery changes have no remaining actionable merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: retrying transient Windows bundle publication locks.
Linked Issues check	✅ Passed	Issue #946 requires bounded Windows retries for transient EPERM, EBUSY, and EACCES during bundle publication. The PR summary states that the retry helper makes five total attempts with 200, 400,…
Out of Scope Changes check	✅ Passed	The reported source change is limited to retrying bundle rename operations. The added test helpers and tests exercise the retry, recovery, cleanup, validation, and reuse behavior required by issue #94…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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.}