Restructured AGENTS.md from a 588-line catch-all into a lean reference of essential rules by offloading deep guidance into five new/expanded doc files: agents.md, architecture.md, dashboard-guide.md, settings-reference.md, and testing.md. Also restored a missing FN-5345 lifecycle invariant in self-h
Fusion-Task-Id: FN-5339
Fusion-Task-Lineage: e1a2dc4f-ae50-46f4-acd3-8f2c3673feb4
Merges the Layer 2.5 scope-auto-widen feature (FN-5226) into the merger: a new evaluator module that automatically widens a task's declared file scope based on git attribution prior to the existing scope partition gate, wired into `merger.ts` with full audit taxonomy, persisted task metadata, and re
Fusion-Task-Id: FN-5226
Test coverage hardening for FN-5440: adds stronger interaction tests across three steps covering the cwd-integration-fallback-removed path and the merge-reuse-task-worktree early fast-path, including expanded fallback audit tripwires and hardened metadata literal guards. No production code changes.
Fusion-Task-Id: FN-5440
Removes the broad-scope detection feature end-to-end: the TaskCard chip and TaskDetailModal advisory banner are gone from the dashboard, the triage heuristic that flagged tasks as broad-scope has been deleted from the engine along with its associated run-audit events, and documentation references ha
Fusion-Task-Id: FN-5405
FN-5351 adds structured telemetry for merge audit events and integration worktree state, including typed ref-advance tracking, terminal handoff fallback audit, and integration state probes with corresponding reliability backstop tests and documentation updates.
Fusion-Task-Id: FN-5351
Implements ref-only integration branch advancement via `git update-ref` instead of checkout+commit, including a new `merger-ref-update-advance.ts` helper, a reduced and clarified `merger.ts`, comprehensive unit and real-git regression coverage, and audit event wiring.
Fusion-Task-Id: FN-5350
Removes the `cwd-main` integration fallback mode (FN-5348), eliminating the legacy shortcut path where the merger would operate directly on the project root instead of a dedicated worktree. Steps normalize the `reuse-task-worktree` integration mode as the sole path, wire stricter mode invariants in
Fusion-Task-Id: FN-5348
Added executor logic to skip retries when a review is pending for a task, introducing a `pendingReviewBlockHelper` in the task-done path and updating the retry-gate to consult it; two new reliability-interaction test suites cover the feature behavior and composition with existing retry/backstop laye
Fusion-Task-Id: FN-5436
Close the last fire-and-forget gap from the previous fixes: the task:moved
(away from in-progress) and task:deleted listeners no longer call the
synchronous fire-and-forget `abortInFlightTaskWork`. Instead they track an
awaited disposal promise per task in `pendingTaskDisposals`. The task:moved
(to in-progress) dispatch path awaits any in-flight disposal for the same
task before calling `execute()`, so a fast bounce (in-progress → todo →
in-progress) no longer races the conflict-cleanup path against a still-live
shell.
`awaitAbortInFlightTaskWork` now claims each session surface (activeSessions,
activeStepExecutors, activeWorkflowStepSessions, activeSubagentSessions)
synchronously before awaiting any async abort. This lets concurrent disposal
calls for the same task dedupe naturally — the second call finds the maps
empty and no-ops, preserving the existing single-abort/single-dispose
contract that the soft-delete and user-cancel tests assert.
Adds a regression test in executor-user-cancel covering the re-dispatch
ordering: an immediate task:moved-to-in-progress that follows a still-running
task:moved-away must wait for abort to complete before execute() runs.
The legacy `abortInFlightTaskWork` is removed (no callers).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Three independent reliability fixes that all surfaced as the same bug:
live tasks losing their worktrees mid-execution and emitting
`wrong_toplevel` errors.
Fix A — executor stale-self-owned classifier:
`reconcileSelfOwnedActiveSessionForRemoval` now takes a process-active
probe (`executingTaskLock.has`) and a minimum-idle window (default 5s)
in addition to the existing in-memory `activeWorktrees` binding probe.
Recently-registered or still-running entries are refused with
`process-active-refuses` / `too-recent-refuses`, with audit-grade
log lines. Both the pre-remove path
(`reconcileSelfOwnedBeforeRemove`), the post-throw retry in
`removeOwnWorktreeWithReconcile`, and the defensive reconcile in
`removeWorktree` route through the same hardened gates.
Fix B — pause synchronously reaps the agent session:
New `awaitAbortInFlightTaskWork` mirrors the existing fire-and-forget
abort but awaits each `session.abort()` /
`stepExecutor.terminateAllSessions()` /
`workflowSession.abort()`. `parkTaskAfterWorkflowStepPause` calls it
before `moveTask("todo")`, and the `task:updated` user-pause handler
routes through it, so a fast re-dispatch can no longer race a still-
live shell.
Fix C — self-healing realpath + active-task skip:
`reconcileTaskWorktreeMetadata` now realpath-normalizes both sides of
the registry comparison (handling macOS `/private/var/...`) and
refuses to clear `worktree`/`branch` on in-progress or in-review
tasks. The skip emits a new
`task:auto-recover-worktree-metadata-skipped-active` audit event;
executor-level recovery paths remain in charge of active tasks.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Raised room transcript defaults (`messagesBefore` and `daysBefore`) in the core settings schema and updated project-level setting defaults, with corresponding documentation refresh in the settings reference. Added full test coverage for room compaction defaults, pinned room default settings in Setti
Fusion-Task-Id: FN-5374
The merge adds a post-completion defensive backstop that probes and removes stale same-task `activeSessionRegistry` entries on `done`/`archived` transitions, completing FN-5346 with a shared reconcile helper, a defensive ownership probe wired into paused cleanup, audit event alignment, and regressio
Fusion-Task-Id: FN-5346
Removes the speculative orphan requeue mutation path from self-healing, replacing it with an observation-only sweep that no longer attempts to re-enqueue orphaned tasks — a conservative regression that eliminates noisy false-positive recovery attempts. The change includes rewritten unit coverage, a
Fusion-Task-Id: FN-5337
Follow-up to c64884c24 addressing three review findings, including one
real interaction bug caught by a new test.
MEDIUM
- Re-indented and rewrote 'if (directReuseEligible) try { ... } catch'
as 'if (directReuseEligible) { try { ... } catch { ... } }' with the
whole body at one consistent indent level. No behavior change \u2014 fixes
the mismatched indentation from c64884c24 where the body sat one level
deeper than its containing block.
LOW
- Two new backstop tests in merge-reuse-task-worktree.test.ts:
* 'preserves worktrees with uncommitted tracked changes' \u2014 asserts the
fast-path leaves a tracked-dirty worktree alone (result.worktreeRemoved
is false, dir still exists). Without this, a future refactor could
silently re-enable destructive cleanup.
* 'cleans up worktrees with only untracked noise' \u2014 asserts untracked
junk (.DS_Store, editor swap files) does NOT block cleanup. Also caught
a real interaction bug: 'git worktree remove' without --force refuses
on untracked files, so the LOW finding's intent (drop noise, preserve
tracked dirt) needs --force on the removal call. Restored --force with
a comment explaining why it's safe (the tracked-only dirty check above
already refused if there was real work to preserve).
- Switched 'git status' check from '--untracked-files=normal' to
'--untracked-files=no'. Tracked modifications and staged changes still
block cleanup; untracked junk is correctly ignored. Dirty-skip warn log
now includes the first 5 dirty paths for operator diagnosability.
Tests
- Full @fusion/engine suite: 448 files / 5883 tests / 9 skipped, all green
- pnpm lint green, pnpm build green
Follow-up to 1983dac6e addressing nine findings from a code review of the
FN-5345/FN-5377 engine fixes. Includes a real bug fix (commit-message bypass
of the amend detection), two reliability invariant restorations (FN-4811 +
FN-4954 in the new D3 reuse-fallback path), a resource-leak cleanup, plus
test/audit/taxonomy polish.
HIGH
- D3 reuse-fallback now respects FN-4811 active-session safety: matches whose
path is currently owned by a different task in activeSessionRegistry are
skipped, never silently rebound. Skipped owners are recorded in audit
metadata for forensics.
- D3 reuse-fallback now respects FN-4954 pool-lease bookkeeping: when
recycleWorktrees=true AND a worktree pool is attached, the direct-reuse
shortcut is bypassed and the existing acquireTaskWorktree path is used so
WorktreePool.acquire/.release stays consistent. Without this guard the
new path could trip PoolDoubleLeaseError.
- prepare-commit-msg amend detection tokenizes the parent command line and
stops at the first message-supplying flag (-m/-F/--message/--file/=variants)
so a commit message containing the substring '--amend' cannot bypass the
guard. New regression test in prepare-commit-msg-empty-guard.real-git.test.ts.
MEDIUM
- Early empty-own-diff fast-path extracted into tryEarlyEmptyOwnDiffFinalize()
helper. Removes the exception-as-control-flow sentinel ('skip-early-fast-path:
not-reuse-mode') in favor of a plain if (eligible) { try { ... } catch {} }
block.
- Fast-path best-effort cleans up the stranded fusion/<id> worktree and branch
before completeTask(), so empty-own-diff residuals do not accumulate in
.worktrees/ or the branch namespace. FN-4811 guard ensures we never remove
a foreign-owned worktree.
- Two new audit subtypes in run-audit.ts replace the prior overloading of
merge:reuse-fallback-new-worktree:
- merge:reuse-fallback-pruned-stale-registration
- merge:reuse-fallback-reused-existing-registration
merge:reuse-fallback-new-worktree is now reserved for actual new-worktree
creation. Local emitReuseHandoffAuditEvent type union updated to match.
- New direct classifier test in merger-finalize-unproven.real-git.test.ts
('classifies proven-no-op for empty-own-diff branches') covers the new
branch in classifyOwnedLandedEvidence that self-healing and post-handoff
paths also depend on.
LOW
- Alpine/busybox ps fallback: prepare-commit-msg hook reads /proc/$PPID/cmdline
if 'ps -o args=' returns empty (busybox ps often lacks '-o args=' support).
- New backstop test variant 'FN-5345: empty-own-diff fast-path fires even
when branch is registered to two worktrees' reproduces the actual FN-5345
production wedge geometry where fusion/<id> was double-registered to two
worktrees.
Tests
- Full @fusion/engine suite: 448 files / 5881 tests / 9 skipped, all green
- pnpm lint green, pnpm build green
Three engine-level fixes for the in-review wedge class identified via FN-5345
(verification-only task with empty handoff commit + drifted worktree mapping
escalating to 'merge-deadlock-detected: verified content not on main' after
FN-4999 completion-handoff-limbo recovery exhausts).
D1 — prepare-commit-msg empty-commit guard
Fusion task worktrees install a prepare-commit-msg hook that refuses
'git commit --allow-empty' and other zero-staged-diff commits. Amend
(detected via $2==commit source arg or '--amend' in 'ps -o args= -p $PPID')
and merge/squash/cherry-pick/revert/rebase ceremonies are allowed.
D5 — early empty-own-diff fast-path in aiMergeTask
In reuse-task-worktree integration mode, BEFORE any reuse-handoff acquisition,
detect branches with own_commit_count >= 1 but zero net diff vs merge-base
(git diff --quiet <mergeBase>..<branch>) and finalize as no-op with
mergeDetails.noOpMerge=true + task:auto-recover-finalize-already-on-main
audit (reason: empty-own-diff-early-fast-path). cwd-main integration mode
is unchanged. classifyOwnedLandedEvidence also detects empty-own-diff so
self-healing and post-handoff finalize paths benefit too.
D3 — reuse-fallback consults existing branch registration
Before creating a fresh worktree in merger's reacquireReuseIntegrationWorktree,
consult 'git worktree list --porcelain' for existing registrations of
fusion/<id>. Reuse extant usable registrations directly. Prune stale
registrations first. Eliminates FN-5083-class double-registration where
'git worktree add -f' on an already-registered branch produced two worktrees
both claiming the branch and wedged the next handoff gate.
Tests
- New real-git backstop: prepare-commit-msg-empty-guard.real-git.test.ts
- New reliability interaction backstop in merge-reuse-task-worktree.test.ts
('FN-5345: empty-own-diff branch auto-finalizes via early fast-path')
- commit-msg-trailer.real-git.test.ts updated to use real commits (it was
relying on --allow-empty, which the new guard now refuses)
- Full @fusion/engine suite: 448 files / 5879 tests / 9 skipped, all green
- pnpm lint green, pnpm build green
Removes the branch-recovery CLI surface, orphan-rescue engine primitives, and their associated tests (over 1,500 lines deleted), while restoring a minimal prune-only orphan branch sweep with proper git audit mutation types. Documentation across `cli-reference.md`, `task-management.md`, and `AGENTS.m
Fusion-Task-Id: FN-5329
The merge introduces an engine-activation timestamp as the staleness floor for task age calculations, replacing arbitrary wall-clock thresholds with a runtime-relative anchor. Step 1 adds settings defaults, Steps 2–4 wire the floor helper through project engine, in-process runtime, and task store hy
Fusion-Task-Id: FN-5223
The merge delivers several meaningful features and fixes: a **priority-aware overlap deferral fix** (FN-5325) in the scheduler that aligns the queued-overlap helper with the priority-sortable type, preventing inversion; a **merge integration worktree feature** (FN-5279) with settings UI, reusable wo
Fusion-Task-Id: FN-5325
Adds an explicit duplicate-marker guard (FN-5220) spanning core helper, dashboard API endpoint, triage short-circuit, and self-healing sweep to detect and handle duplicate task creation attempts; includes comprehensive test coverage across unit, API, and integration layers plus documentation.
Fusion-Task-Id: FN-5220
In reuse-task-worktree mode the merger detaches HEAD in the task worktree so
the squash commit lands on detached HEAD; nothing previously advanced the
project root's local integration branch, so changes never appeared on main.
Step 5c now applies the squash to projectRootDir via git merge --ff-only,
falling back to a regular merge with AI conflict resolution if main has
diverged. pushAfterMerge (when enabled) now runs from projectRootDir where
the branch was just advanced, so parsePushRemoteTarget can resolve a branch
instead of failing on the worktree's detached HEAD.
Also tightens acquireReuseHandoff: the executor-lease check above the
queue-lease acquisition was non-atomic, letting a local executor grab the
task between checks. Re-check after acquisition and release the queue
lease with a precise diagnostic instead of proceeding into a generic
failure later.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Before: when reuse-task-worktree was configured but task worktree was missing/unusable,
merger fell back to cwd-main, losing the task worktree isolation benefit.
After: merger creates a fresh worktree for the task branch inline (using the standard
git worktree add pattern with identity guard installation) and retries the reuse handoff.
Only falls back to cwd-main if fresh acquisition also fails.
Three new audit events track the recovery path:
- merge:reuse-worktree-fresh-acquire — fresh acquisition started
- merge:reuse-worktree-fresh-acquired — fresh worktree created and bound to task
- merge:reuse-fallback-cwd-main — only when fresh acquisition itself fails (last resort)
Behavior:
- Missing/unusable task worktree → fresh worktree created, merge continues from it
- Fresh acquisition fails → cwd-main fallback (last resort, fully audited)
- Genuine liveness conflict (usable worktree but lease refused) → re-thrown, not masked
Regression test covers the missing-worktree case: verifies fresh acquisition + handoff
succeeds without any cwd-main fallback event.
After merge:reuse-handoff-refused with no usable task worktree:
- Acquire a fresh worktree and restore the fusion/<task-id> branch
from baseCommitSha before continuing merge
- Hard-fail only if fresh acquisition itself fails (not cwd-main fallback)
- Emit merge:reuse-worktree-fresh-acquire / merge:reuse-worktree-fresh-acquired
audit events around the acquisition lifecycle
Replaces the incorrect cwd-main fallback (499784581) with correct
reacquire path. Updates regression test in merge-reuse-task-worktree.test.ts
to assert fresh-acquire audit trail instead of cwd-main fallback.
Refs: FN-5353
Implements the `mergeIntegrationWorktree` setting (FN-5279) that allows tasks to reuse their own worktree as the integration root instead of spawning a separate one. Steps 1–2 added the settings schema, types, and SettingsModal surface with documentation; Step 3 wired an integration-root resolver th
Fusion-Task-Id: FN-5279
- Add a merger guard that verifies source fusion/FN branch attribution when rebase capture reports zero own commits
- Fail finalize with explicit no-op attribution mismatch handling instead of marking mergeConfirmed on ambiguous no-op ranges
- Type and emit dedicated audit events for mismatch and source-ref-unavailable skip diagnostics
- Expand branch attribution, merger, and reliability interaction tests to cover the full no-op guard matrix
Fusion-Task-Id: FN-5304
Implements canonical worktrunk binary naming and manifest handling (FN-5320), adding a worktrunk installer that canonicalizes the executable name and manifest data, with documentation updates for architecture and settings, plus test alignments across routes, audit, and worktree acquisition fixtures.
Fusion-Task-Id: FN-5320
Adds pre-commit identity guard handling for branch case normalization (FN-5271), updating the worktree hooks implementation and adding a real-git integration test alongside a changeset for `@runfusion/fusion`.
Fusion-Task-Id: FN-5271
The merge adds a new self-healing recovery path for tasks stuck in `in-progress` limbo (no pending step updates but not marked done), hardening `resetTask` and `recoverInProgressLimboTasks` with proper worker binding cleanup, audit event coverage, and integration tests validating the invariant acros
Fusion-Task-Id: FN-5219
Adds a reconcile script to recover leaked soft-deleted tasks, threads delete audit context through all callers, and records soft-delete audit events with archive column tracking across core/engine/cli/dashboard, with reliability backstop tests covering caller alignment.
Fusion-Task-Id: FN-5175
Implements in-flight abort for soft-deleted tasks across all three execution lanes: executor, merger, and triage now check for `deletedAt` before proceeding and emit `task:soft-delete-in-flight-abort` audits rather than continuing work on a deleted task. The 829-line addition is dominated by integra
Fusion-Task-Id: FN-5264
Fusion-Task-Lineage: 4ee8e63b-abf0-43e2-9130-39a05434d8f9
The merge introduces an atomic review handoff seam in the core store (`packages/core/src/store.ts`) and migrates executor and self-healing transitions to use it, replacing the previous multi-step mutable-state handoff with a single transactional operation. Extensive reliability backstops and regress
Fusion-Task-Id: FN-5241
Implements deterministic followup deduplication for the project engine, routing eval and PR followups through a new `verification-followup-dedup` helper that excludes the parent task to prevent self-referential loops, with tests covering eval-followups, merge-error-recovery, PR comments, and the new
Fusion-Task-Id: FN-5232
Completes FN-5153 by delivering the soft-delete verification gate with a new end-to-end test suite covering the full soft-delete lifecycle and a documentation matrix summarizing the gate behavior. Updates the dashboard test file and adds a brief entry to AGENTS.md to surface the new feature.
Fusion-Task-Id: FN-5153
