FN-7802: recover phantom-worktree tasks stuck merge-active with scopeOverride
Fixes phantom-worktree context bleed where the engine refused to start a
coding agent in a missing worktree for in-review/merge-active tasks even
when scopeOverride=1, stranding them past the normal recovery paths and
retry budget.
- Add isMergeActiveMissingWorktreeSessionStartFailure/isInReviewMissingWorktreeSessionStartFailure classifiers and MERGE_ACTIVE_MISSING_WORKTREE_STATUSES (merging/merging-pr/merging-fix) in restart-recovery-coordinator.ts, exported from @fusion/engine.
- Self-healing: reorder missing-worktree-review-failures sweep earlier, extend the in-review sweep to also match merge-active missing-worktree failures with a triple-proof-guarded, bounded (recoveryRetryCount) stale-metadata clear and fresh session-start retry budget reset.
- Self-healing: extend scopeOverride worktree-metadata reconciliation to safely clear phantom worktree/branch/session metadata for in-review tasks stuck in a merge-active sub-status, narrowly scoped to avoid clobbering genuinely live in-progress/mid-step tasks (FN-5256 guard preserved).
- CLI (task.ts), pi extension (extension.ts), and dashboard route (register-task-workflow-routes.ts) retry paths now bypass the merge-active status gate via a signature-only check, clearing worktree/branch/sessionFile and requeuing to todo while preserving progress.
- Add regression coverage across self-healing.test.ts, restart-recovery-coordinator.test.ts, extension.test.ts, task-retry.test.ts, and routes-tasks-ops.test.ts; update mockCoreEngine.ts test scaffolding.
- Update docs/architecture.md, docs/self-healing-backward-move-audit.md, docs/task-management.md, and AGENTS.md to describe the new merge-active missing-worktree recovery behavior.
- Add changeset (patch) for @runfusion/fusion.
Files changed:
.changeset/fn-7802-phantom-worktree-merge-active-recovery.md | 7 +
AGENTS.md | 1 +
docs/architecture.md | 4 +-
docs/self-healing-backward-move-audit.md | 5 +-
docs/task-management.md | 2 +-
packages/cli/src/__tests__/extension.test.ts | 64 +++++
packages/cli/src/__tests__/task-retry.test.ts | 49 ++++
packages/cli/src/commands/task.ts | 28 +-
packages/cli/src/extension.ts | 26 +-
packages/dashboard/src/__tests__/routes-tasks-ops.test.ts | 52 ++++
packages/dashboard/src/routes/register-task-workflow-routes.ts | 25 +-
packages/dashboard/src/test/mockCoreEngine.ts | 11 +
packages/engine/src/__tests__/restart-recovery-coordinator.test.ts | 20 ++
packages/engine/src/__tests__/self-healing.test.ts | 297 +++++++++++++++++++++
packages/engine/src/index.ts | 13 +
packages/engine/src/restart-recovery-coordinator.ts | 19 +-
packages/engine/src/self-healing.ts | 157 +++++++++--
17 files changed, 744 insertions(+), 36 deletions(-)
Fusion-Task-Id: FN-7802
Fusion-Task-Lineage: 5897105b-6b5c-49d5-a8e8-519902182861
Co-authored-by: Fusion (runfusion.ai) <noreply@runfusion.ai>
21fb8f6786