fix(worktrees): recover downgraded V2 registry wrappers

[gannonh]

Summary

• recover the exact completed-upgrade shape produced when an older process rewrites valid V2 worktree records beneath a V1 wrapper
• preserve the original backup lineage and completion timestamp across atomic and interrupted recovery
• keep missing evidence, mixed versions, malformed records, and concurrent changes fail-closed
• document the recovery contract and include it in pending release notes

Related to #40. The pre-existing nonparticipating-writer replacement race is tracked separately in #52.

Test Plan

• cd packages/server-core && bun test src/git/__tests__/worktree-registry.test.ts src/git/__tests__/managed-worktree-service.test.ts src/git/__tests__/reconcile.test.ts
• cd packages/server-core && bun run typecheck
• git diff --check origin/main

All 54 targeted tests pass.

Summary by CodeRabbit

• Bug Fixes
  • Improved recovery of saved worktree data after interrupted upgrades.
  • Preserved upgrade progress and completion timestamps during recovery.
  • Added stronger validation to detect mismatched, malformed, ambiguous, or corrupted records.
  • Prevented accidental overwrites when previously upgraded data is encountered.
• Tests
  • Added coverage for upgrade recovery, failure-safe handling, data integrity checks, and interrupted operations.

Greptile Summary

This change restores the V2 registry wrapper when an older Kata process retains valid V2 records but writes a V1 wrapper. It preserves lifecycle state, the original V1 backup, and upgrade completion time while rejecting mixed, malformed, missing-evidence, and mismatched-evidence states without rewriting the source registry.

Merge safety: safe to merge.

Confidence Score: 5/5

No blocking failure remains; the registry recovery and fail-closed paths behave as intended.

No accepted blocking findings remain.

T-Rex Logs

What T-Rex did

• Ran a filesystem-level Bun harness against the production WorktreeRegistry after rewriting a valid upgraded registry to a V1 wrapper while retaining a V2 record with a changed missing state.
• Observed successful V2-wrapper restoration while preserving the record state, original backup, and completion lineage, with mixed records, missing or mismatched evidence, and an injected interruption all failed closed or recovered correctly on retry.
• Executed the focused registry test suite and confirmed 20 tests passed with zero failures.
• Compared legacy V1 wrapper pre-capture to capture state, confirming the V1 wrapper contained a V2 record and a legitimate missing state change, then verified recovery conditions post-capture.
• Validated that after capture all recovery and fail-closed assertions passed as expected.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "docs(release): link registry recovery pr..." | Re-trigger Greptile}

[coderabbitai]

Important

Review skipped

Review was skipped due to path filters

⛔ Files ignored due to path filters (1)

• apps/electron/resources/release-notes/next.md is excluded by !**/*.md

CodeRabbit blocks several paths by default. You can override this behavior by explicitly including those paths in the path filters. For example, including **/dist/** will override the default block on the dist directory, by removing the pattern from both the lists.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: cf6c2cb3-0dff-4385-93b3-fa907097e8cf

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The worktree registry now handles V1-wrapped V2 records during recovery. It validates record schemas, checks source and backup hashes, preserves migration evidence and completion timestamps, and rejects ambiguous or malformed states without modifying invalid source data.

Changes

Worktree registry recovery

Layer / File(s)	Summary
Versioned record parsing packages/server-core/src/git/worktree-registry.ts	V1 parsing preserves V2 fields and applies V2 validation when V2 markers exist.
Upgrade lineage recovery packages/server-core/src/git/worktree-registry.ts	Recovery validates source and backup hashes, preserves valid V2 records and completion timestamps, and rejects unsupported or inconsistent migration states.
Recovery validation tests packages/server-core/src/git/__tests__/worktree-registry.test.ts	Tests cover successful recovery, interrupted rewrites, hash mismatches, missing evidence, ambiguous wrappers, and malformed V2 records.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• gannonh/kata-agents#44: Introduces the Worktree V2 registry migration and recovery behavior extended by this change.
• gannonh/kata-agents#46: Adds related Worktree V2 lifecycle and schema support in the same registry implementation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes recovery of V2 records from downgraded worktree registry wrappers.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/recover-downgraded-worktree-registry

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4bc5a718d4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/server-core/src/git/worktree-registry.ts`:
- Around line 847-853: Update the generic RPC error handler at the registry
boundary to detect WorktreeRegistryError and translate each registry error code
through its corresponding i18n.t() key before sending the response. Cover
REGISTRY_CONFLICT, including both referenced conflict paths, and every other
registry error code without exposing WorktreeRegistryError.message directly. Add
all required translation keys to each of the seven locale files in alphabetical
order.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 88cb77f8-7699-4972-82d0-0f8d3f56761a

📥 Commits

Reviewing files that changed from the base of the PR and between 5fee437 and 4bc5a71.

⛔ Files ignored due to path filters (4)

• apps/electron/resources/release-notes/next.md is excluded by !**/*.md
• docs/adrs/2026-07-29-server-owned-managed-worktrees.md is excluded by !**/*.md
• docs/adrs/log.md is excluded by !**/*.md
• docs/log.md is excluded by !**/*.md

📒 Files selected for processing (2)

• packages/server-core/src/git/__tests__/worktree-registry.test.ts
• packages/server-core/src/git/worktree-registry.ts