feat(task-lifecycle): task status transition guard and startup delegation reconciliation

[edelauna]

Related GitHub Issue

Closes: #366 (part of #357 — Epic 2: Task Lifecycle Fixes)

Description

Implements Story 2.3: a status transition guard and startup reconciliation loop to prevent and recover from HistoryItem status corruption.

Transition guard (assertValidTransition)

Adds an assertValidTransition(from, to) function that enforces the valid state machine:

• active → delegated | completed
• delegated → active
• completed → [] (terminal)

Called at all five updateTaskHistory sites in ClineProvider that change status (removeClineFromStack, cancelTask, delegateParentAndOpenChild, reopenParentFromDelegation ×2). Throws on invalid transitions so corrupt writes are surfaced immediately rather than silently persisted.

Startup reconciliation (reconcileDelegationState)

Called from TaskHistoryStore.initialize() after reconcile(). Repairs three crash-induced inconsistencies:

• Parent delegated with no awaitingChildId → active
• Parent delegated, child not found (orphaned) → active
• Parent delegated, child already completed (interrupted handoff) → active, copying the child's completionResultSummary

Implementation details:

• Runs inside withLock via a new upsertCore private helper (avoids re-entrant deadlock)
• Convergence loop (do { } while (repairsInThisPass > 0)) so chained delegations (A→B→C) are resolved in one startup
• O(1) child lookup via pre-built Map
• All three repair paths clear both awaitingChildId and delegatedToId

Test Procedure

pnpm --filter zoo-code test core/task-persistence/__tests__/TaskHistoryStore.reconciliation.spec.ts
pnpm --filter zoo-code test __tests__/history-resume-delegation.spec.ts
pnpm --filter zoo-code test core/task-persistence/__tests__/TaskHistoryStore

All 64 tests across the four affected suites pass. New TaskHistoryStore.reconciliation.spec.ts adds 18 tests covering the transition guard (valid/invalid transitions including self-loops) and all reconciliation scenarios (orphaned delegation, interrupted handoff, fallback summary, active-child left alone, multiple parents, chained delegation, idempotency, logging).

Pre-Submission Checklist

• Issue Linked: This PR is linked to an approved GitHub Issue (see "Related GitHub Issue" above).
• Scope: My changes are focused on the linked issue (one major feature/fix per PR).
• Self-Review: I have performed a thorough self-review of my code.
• Testing: New and/or updated tests have been added to cover my changes (if applicable).
• Documentation Impact: No documentation updates required — internal persistence layer change with no user-visible behaviour change in the happy path.
• Contribution Guidelines: I have read and agree to the Contributor Guidelines.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f7977196-6246-4c7c-88c8-29fdd5e83769

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue/366

---

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!