Investigating the "dead cap" turned up the opposite of what it looked like, plus a
worse problem next to it.
The Plan Review replan loop was NOT unbounded. U3 re-owned the cap-park in the
graph: requestPreMergeOptionalStepFix parks via parkPlanReviewReplanCapExhausted
at awaiting-approval with reason plan-review-replan-cap, on both an explicit
finite budget and the unbounded default. That capability has been live throughout.
What was actually dead:
1. PLAN_REVIEW_GATE_REPLAN_CAP = 8 — an unread constant belonging to the
out-of-graph triage gate (runPlanReviewBeforeExecution) that U10/R4 deleted. Its
companion column Task.planReviewReplanCount was persisted, serialized and reset
but never incremented or compared. A constant and a column that look like a live
safety ceiling while enforcing nothing are worse than no ceiling: they answer "is
this loop bounded?" with a confident yes. Deleted, ratcheted in
legacy-tombstones.test.ts, and the column documented as legacy/never-written with
the live owner named.
2. planReviewReplanCap — an operator-facing setting, declared, validated,
documented in settings-reference.md and editable in the Workflow Editor, that
NOTHING read. Lowering it changed nothing. The unbounded backstop was instead
hardcoded to PLAN_REVIEW_FEEDBACK_HISTORY_LIMIT — a bound on how much reviewer
PROSE is replayed into the next planning prompt, whose own comment says it is
"bounded independently of persistence and retry accounting". Two unrelated
concerns shared one number, so trimming prompt history would have silently
tightened a safety ceiling.
The backstop now resolves from the setting, defaulting to the new
DEFAULT_PLAN_REVIEW_REPLAN_CAP = 15 — the previously-effective value, so this is a
pure re-wiring rather than a silent behavior change. The existing 15-attempt
regression test passes unchanged, which is the evidence for that. 0 is honored as
park-on-first-REVISE. An explicit planReviewMaxRevisions / node maxRevisions
budget remains a stricter, earlier gate.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Three changes to the triage planning path.
1. Unclassified planning failures are bounded. specifyTask's catch-all branch —
the one reached by every error the classifiers above do not recognize — restored
the card's claimable status and wrote nothing else: no counter, no
nextRecoveryAt, no park. Triage rediscovery re-admitted the card on the very next
poll, and replaceActiveTaskWorkflowContinuation replaced the terminal work item
with a fresh one carrying no attempt count, so nothing recorded that the task had
already failed N times. It now consumes the same recoveryRetryCount/nextRecoveryAt
budget the transient branch uses (MAX_RECOVERY_RETRIES = 3, 60s/120s/300s jittered
backoff) and parks status:"failed" with a PLANNING_FAILED_EXHAUSTED: error once
spent — status:"failed" is what suppresses rediscovery. Classifying one error
string fixes one symptom; this budget is what makes the NEXT unrecognized error
fail safely instead of looping for a day.
2. The planning turn has a ceiling. Fusion set no timeout on it at all:
workflowStepTimeoutMs covers pre-merge workflow steps only, and the provider SDK's
300s APIConnectionTimeoutError caps time-to-first-byte and is cleared once headers
arrive, after which the stream is uncapped. configureHttpDispatcher, which would
install undici idle timeouts, is only called from pi's CLI entrypoints and never
in the in-process engine. Observed consequence: single attempts ran to 126 minutes,
with failed-attempt durations spread smoothly from 1 to 126 min and no clustering —
the signature of nothing enforcing a bound. New workflow-native planningTimeoutMs
(default 90 min) aborts the session; the failure consumes one bounded attempt.
The default is deliberately generous rather than tight. Successful planning work
items measured over 7 days ran p50 12.7 / p90 39.5 / p99 105.7 minutes, so a
tighter bound would abort legitimate plans and pay for the restart — the churn
this work exists to remove. It bounds hung turns, not slow ones.
3. [event:task:moved] executor tracing dropped from log to debug. It fires on
every dispatch, rebound, requeue, archive and self-healing move across every task,
which made it the loudest line in engine output and buried operator-actionable
events. No test pins the level; the information remains at debug.
Also fixes a test break shipped in 963dba6f80: the review blocking-severity
settings landed inside BUILTIN_REVIEW_REVISION_SETTINGS, whose contents
builtin-workflow-settings-triage.test.ts asserts exactly.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
"Request timed out." is the literal default message of the Anthropic and OpenAI
SDKs' APIConnectionTimeoutError, surfaced to Fusion by checkSessionError after
pi-coding-agent exhausts its in-session retries. It matched none of the
connection-scoped timeout patterns, which deliberately excluded "general
timeouts", so it fell through to specifyTask's generic failure branch — the one
that restores status: null and writes no counter, no nextRecoveryAt, and no park.
Triage rediscovery then re-admitted the card on the very next poll, forever.
Measured before this change: 48 "Specification failed: Request timed out." events
across 10 tasks in 30 hours with zero backoff between attempts. FN-8950 alone
burned 8 consecutive attempts over ~8 hours and never reached implementation.
Across 2 days, 91 failed planning attempts averaged 33 minutes each — ~50 hours of
wall-clock producing nothing, 24% of all planning time.
Classifying these as transient routes them into the bounded recovery policy
(MAX_RECOVERY_RETRIES = 3, 60s/120s/300s jittered backoff) already used by the
connection-level patterns, so a provider blip costs three spaced retries instead
of an unbounded loop.
The pattern is anchored to "request timed out" rather than a bare timeout match:
agent log prose and verification output legitimately contain "timed out"
("BuildKit timed out", "stuck-kill unwind timeout"), and a broad pattern would
reclassify real permanent failures as retryable — the mistake the connection-only
rule was written to avoid. Regression tests pin both directions.
This does not affect model fallback, which pi decides internally and Fusion only
observes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review remediation loops were the dominant cost of task wall-clock: over 14 days,
tasks with >=5 post-review fix rounds were 22% of tasks but consumed 78% of all
task active time, and 311 of 331 recorded findings were spec-internal-consistency
complaints that changed no delivered behavior.
Two causes compounded. Plan/Code Review remediation was unbounded by default, and
the review policy ordered a full re-derivation of the artifact after every edit
("distrust the edit ... fresh holistic pass"), so each round surfaced a fresh crop
of previously-acceptable observations as new blockers.
Make the already-persisted WorkflowReviewFinding.severity load-bearing instead of
decorative: a REVISE only blocks when it carries a finding at or above the review
kind's threshold (plan: P0+P1, code: P0). Non-blocking findings are still parsed,
persisted, and handed to the implementer as advisory notes in PROMPT.md. Fails
closed — a REVISE with no findings, or with any unclassified finding, still blocks,
so prose-only and custom reviewers keep full blocking power. The gate only ever
relaxes a verdict, never promotes one.
Reviewer prompts now request the structured findings schema (Plan Review emitted
none before), define severity by consequence as P0/P1/P2, omit nits entirely rather
than filing them as low-severity findings, and use an incremental re-review contract.
Remediation renders findings grouped by priority and sanctions an explicit decline
with rationale, so a disputed finding has a terminal state.
Also preserve the implementation session across a review bounce: sendTaskBackForFix
no longer nulls sessionFile when preserving resume state, and the executor's finally
no longer clears it on a review handoff. Remediation rounds continue the conversation
instead of re-reading the repo and re-deriving the change they just wrote. The resume
prompt now directs a PROMPT.md re-read, without which a resumed agent would never see
the new findings.
New per-workflow settings planReviewBlockingSeverity / codeReviewBlockingSeverity;
set either to "any" to restore the previous behavior.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Renewal runs every poll for every implementation-column task with declared
symbols, and a lost lock never recovers by renewing — renewSymbolLocks reports
the same lost set on each pass, so the warning and its store.logEntry companion
repeated forever: log-pane spam plus unbounded activityLog growth for a stuck
task. The two error paths had the same shape on any persistent failure.
Extract the executor's suppression into a shared createRepeatSuppressedLog and
use it in both: first occurrence per task/signature logs at full level, repeats
drop to debug(), a changed lost set or error message logs again, and a clean
renewal clears the memo. The logEntry write is gated on the same decision.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The unmet-dependency and ephemeral-disabled pre-dispatch gates re-run on every
dispatch attempt for a blocked task but only change state on the first, so every
later pass re-logged the same line at default level and drowned the log pane.
Route both through logDispatchBlockedOnce: first block per task/reason logs at
log(), identical repeats drop to debug() (FUSION_DEBUG=executor), a changed
reason logs again, and the marker clears when the gate passes.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
FN-8923 sat silent in Todo for 7+ hours with zero run-audit rows. Its plan node
held on principal routing, triage correctly recorded `needs-replan`, and then
dependency auto-unblock nulled that status when its blocker completed. From that
moment the card was invisible to both lanes: triage saw a fully-written spec with
no replan flag and skipped it, while the executor's `isUnplannedForExecution`
refused to dispatch because no capacity-boundary continuation existed. Not stuck
in a retry loop -- unowned.
- Dependency auto-unblock clears only the `queued` marker it owns, at all four
sites (scheduler.ts plus three in self-healing.ts). `status` is a shared
lifecycle channel and `needs-replan` is the only signal that re-admits a
hold-column card whose PROMPT.md is already a real spec.
- New self-healing sweep `reconcilePrincipalHeldPlanningContinuations` re-queues
planning for a card whose sole active continuation is a principal-routing hold.
A planning hold otherwise has no retry owner at all. Gated on the planning
lane, effective auto-merge, an owned (null) status, and the shared planning
lifecycle lock, so it cannot clobber a triage claim or launder a `failed` /
`stuck-killed` / `queued` card into a replan.
- Workflow node-instance-id materialization is idempotent across foreach, loop,
and optional-group containers. It re-wrapped its own output on every dispatch,
so FN-8869 grew a ~1.8 KB `run_id` of ~30 repeated segments on a hot indexed
column and every retry read as a distinct run.
- An unresolvable node instance or absent IR now fails closed instead of being
treated as an edited-away override -- the previous shape would have discarded a
real reviewer fence and handed a named review to the pool.
- Mirror the routing exports into the gate-safe core barrel; the reduced barrel
resolved them to `undefined`, a latent trap for any suite reaching the router.
Findings from a multi-reviewer pass; 9 of 11 confirmed by an independent
validator. Each fix carries a regression asserting the invariant across its
surfaces, not the single reported case -- the optional-group accretion test was
verified to fail without the fix.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Workflow principal routing conflated two different questions: whether an agent
CAN run a node, and whether it can run it RIGHT NOW. Both produced a hold, and a
named principal never falls through to the role pool — so an agent that could
never satisfy the node wedged the task permanently.
FN-8869, FN-8928, and FN-8845 were each explicitly assigned to a permanent
engineer-role agent (which the assignment policy allows). Their `step-execute`
nodes took that owner as `task-assignee` authority, found no `executor` tag, and
held closed. Each card re-dispatched and re-held every ~15 minutes for hours
while two idle `Workflow Executor` pool agents were never consulted. The only
thing still touching them was the owner's hourly heartbeat, which logged
"progressing, no blockers" and exited: heartbeat observation had replaced
execution.
- Structural incapability (wrong role, agent deleted, authority edited away) is
no longer authority for the node. Routing continues to the column binding and
then the role pool.
- A resumed continuation whose fence proves stale discards it and re-routes,
instead of re-asserting a dead principal on every dispatch.
- Availability is unchanged and still fail-closed: a role-capable principal that
is paused, disabled, or at session capacity holds, and is never silently
replaced by a pool member.
- An explicitly assigned engineer-role agent is now valid task-assignee
authority for an executor node, so the assigned agent executes its own task
continuously under graph dispatch. The role pool stays strict, since automatic
backlog pickup by engineers is a separate opt-in.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
- keep operator-routed external checkouts out of managed worktree
preflight, cleanup, and lost-work reconciliation paths
- mark injected custom graph worktree creation as native so workspace
mode accepts the managed backend
- add an extraction regression guard for the ownership fences
## Test plan
- `pnpm --filter @fusion/engine exec vitest run
src/executor/__tests__/external-checkout-extraction-guards.test.ts
--silent=passed-only --reporter=dot`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm check:changesets`
- targeted ESLint on the changed TypeScript files
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* External execution checkouts are no longer treated as Fusion-managed
worktrees.
* Prevented unnecessary Git checks, cleanup, and reconciliation during
retries, pauses, recovery, and stuck-task handling.
* Invalid external checkout configurations now fail safely with an
error.
* Graph-injected worktrees now use the native worktree backend for
consistent setup.
* **Tests**
* Added coverage verifying external checkouts remain excluded from
managed worktree operations.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- serialize pinned-path classification, orphan preservation, quarantine
reconciliation, and recreation under one reservation
- preserve cross-filesystem orphans atomically beside the configured
worktree root and retain the newest 10 generated entries per recovery
root
- exclude recovery containers from pool and self-healing scans, with
fail-closed symlink and active-session guards
- document recovery location and retention behavior
## Test plan
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/worktree-acquisition.test.ts
src/__tests__/worktree-paths.test.ts src/__tests__/worktree-pool.test.ts
src/__tests__/self-healing-tempdir-sweep.test.ts --silent=passed-only
--reporter=dot`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm --filter @fusion/engine build`
- `pnpm test:gate:static`
- `pnpm check:changesets --strict`
- `pnpm check:fnxc-future-dates`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Preserves orphaned pinned worktrees during recovery, including across
filesystems.
* Retains the 10 most recent recovery entries and safely skips active or
invalid entries.
* Keeps recovery data separate from normal worktree discovery, cleanup,
and capacity checks.
* Adds safeguards for path containment, active-session ownership, and
concurrent recovery.
* **Bug Fixes**
* Prevents pinned worktree data from being lost during recreation or
quarantine cleanup.
* Ensures recovery cleanup failures do not interrupt worktree
acquisition.
* **Documentation**
* Documented orphan recovery, retention, fallback behavior, and cleanup
safeguards.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
PR #3317 rewrote executor.ts from a pre-change base. A refactor rebased off a
stale base does not conflict — it deletes. An audit of every commit touching
executor.ts before the peel found two landed fixes silently removed:
- FN-8850 completion recommendations: the `fn_task_done` VALIDATOR survived the
peel but the engine-appended prompt section asking the executor to produce
recommendations did not. Nothing failed — recommendations were still accepted,
no test covered the prompt wiring, and capture simply stopped. Restored
verbatim in executor/system-prompt.ts, next to the validator it pairs with.
- The WorktreeBaseRefreshError guard (a06a4988d9): without it a pre-session
checkout refusal falls through to the generic terminal sink and parks the task
`failed`, which is the path that produced 99 parks and 47 operator alerts over
2026-08-01..09. Restored in executor/run-implementation.ts as a wait.
Everything else from that window verified intact: external checkout routing
(#3398/#3400/#3401), FN-8864/FN-8868 agent activity telemetry, FN-8863
remediation holds, FN-8841 CLOSE_NO_OP, FN-8870 approval mail, FN-8910 held-task
remediation — line-level diffs looked missing only because the peel rewrote
`this.` to `deps.`.
Adds executor-prompt-completion-recommendations.test.ts to pin the prompt
wiring, since the absence of coverage is what let it disappear silently.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
runtimeConfig.enabled answered two different questions. Every consumer in the
engine reads it as "run this agent's own durable heartbeat loop" — heartbeat
scheduling, error recovery, self-healing, in-process runtime — except the
workflow router, which also read it as "may own a workflow stage".
That conflation caused both failures:
- Built-in owners ship with the heartbeat off, which is CORRECT (they are
invoked by the workflow engine and must not run autonomous loops or auto-claim
work). That silently made every built-in role unroutable and deadlocked the
board.
- Enabling the heartbeat to restore routing then gave four agents autonomous
loops and auto-claiming nobody asked for.
Separate the flag:
- runtimeConfig.enabled governs the heartbeat runtime ONLY
- isWorkflowPrincipalEligible answers routability, and treats the four built-in
role owners as routable structurally — there is no fallback if a role cannot
route, so "unroutable" is not a state an operator can meaningfully select
- provision built-ins { enabled: false, autoClaimRelevantTasks: false }
- paused/errored still outranks the exemption, so it can never resurrect a
broken principal
Removes the earlier write-seam coercion that forced enabled:true — the invariant
is now structural rather than fought for on every write.
Also re-applies the principal-hold backoff ladder (15s -> 5m, checked before
graph entry) into executor/execute-workflow-graph.ts. PR #3317's executor peel
rewrote executor.ts from a pre-change base and dropped it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Symptom
A tunnel process that dies unexpectedly (crash, OOM, network hiccup, the
24h `maxLifetimeMs` supervision cutoff) leaves `TunnelProcessManager` in
a terminal `failed` state. `handleUnexpectedExit` records the error and
stops — the operator's remote-access tunnel silently goes dark until a
human notices and restarts it.
## Fix
The manager now remembers the desired tunnel (`provider` + `config`)
across the start/switch lifecycle and respawns it after an unexpected
exit with exponential backoff — 1s base doubling to a 30s cap, both
configurable via new `restartBaseDelayMs` / `restartMaxDelayMs` options,
and `autoRestart: false` to opt out. The attempt counter resets once the
tunnel reports ready.
Intentional shutdowns stay shut down: `stop()` and `switchProvider()`
clear the desired tunnel and cancel any pending restart timer.
Hardening that falls out of restart support:
- Exit/spawn-error/readiness-timeout handlers are guarded by
process-handle identity, so a stale `close` event from a superseded
child cannot clobber the state of the restarted tunnel.
- The readiness-timeout path now SIGTERMs the stalled child instead of
leaking it while marking the tunnel failed.
- A synchronous `superviseSpawn` throw now records a redacted
`start_failed` status instead of escaping unhandled.
## Verification
- New tests (fake timers, no real waits): restart after unexpected exit
for both cloudflare and tailscale providers; backoff progression and
delay cap across repeated pre-readiness failures; explicit `stop()`
cancels a pending restart.
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/tunnel-process-manager.test.ts` — 17/17 pass.
- `pnpm verify:fast` — 14 steps green (scoped typecheck/build + CLI
build + boot smoke).
- Changeset included (`patch`, category `fix`).
## Provenance
This is the tunnel half of a fork-side fix (FN-915) that has been
running in production since July; the merge-blocker-preservation half of
that same fix already landed upstream (present since v0.76.0-beta.0).
Ported onto current `main` — the original patch applied cleanly.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Tunnels now automatically restart after unexpected crashes.
* Restart attempts use increasing delays up to a configurable maximum.
* Automatic recovery is enabled by default and can be configured.
* **Bug Fixes**
* Prevented stale process events from triggering unwanted restarts.
* Explicit stops and provider changes now cancel pending restart
attempts.
* Failed or unready tunnel processes are terminated cleanly.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: v <v@v.speedport.ip>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
## Summary
- fail closed when a persisted external remediation route lacks a
concrete checkout path
- verify recovery, remediation, dependency-abort cleanup, and completion
validation use the live persisted task route
- use unique missing-checkout fixtures and exact observed-path
assertions
## Test plan
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/verify-worktree-invariants-missing.test.ts
src/__tests__/executor-triage-column-audit.test.ts --silent=passed-only
--reporter=dot`
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/executor-fast-mode-workflows.test.ts -t 'completed-task
recovery captures the live external checkout|pre-merge remediation'
--silent=passed-only --reporter=dot`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm exec eslint packages/engine/src/executor.ts
packages/engine/src/__tests__/verify-worktree-invariants-missing.test.ts
packages/engine/src/__tests__/executor-triage-column-audit.test.ts
packages/engine/src/__tests__/executor-fast-mode-workflows.test.ts`
- `pnpm check:fnxc-future-dates`
- `pnpm check:changesets --strict`
- `git diff --check`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved recovery for externally executed tasks by using the latest
routing information instead of outdated task data.
* External remediation now stops safely when a checkout location is
missing or invalid, preventing execution in an unintended location.
* Improved cleanup behavior to preserve operator-owned checkouts.
* Enhanced validation and error reporting for missing or invalid
checkout paths.
* **Tests**
* Expanded coverage for recovery, remediation safety, checkout
ownership, and worktree validation scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
The board stopped moving. Work items churned held -> running -> held at
~3.5/sec across every task, pinning a core and writing ~19k workflowWorkItem
audit rows/hour while nothing executed. Hold reason:
workflow-principal-role-pool-exhausted:executor.
provisionBuiltinWorkflowRoleAgents seeded the four permanent owners (triage,
executor, reviewer, merger) with runtimeConfig.enabled=false, while the
router's available() treats enabled===false as unavailable. The only permanent
principals for every built-in role were unroutable BY CONSTRUCTION — shipped
that way, so any instance without operator-created role agents deadlocks at its
first workflow node. Nothing self-recovers: a pool only changes by operator
action.
Routability of these four is an invariant, not a setting. Unlike an operator's
agent, disabling one does not opt an agent out — it removes the only thing that
can run that stage, and there is no fallback.
- seed built-ins enabled; converge existing rows on provisioning
- enforceBuiltinWorkflowRoleRoutability coerces enabled back at the durable
writeAgent seam, so no REST/UI/plugin/restore path can reintroduce the
deadlock. Other runtimeConfig keys are preserved; operator-owned agents keep
their off switch
- share the static routability predicate (isWorkflowPrincipalEligible) between
provisioning and the router so the two cannot drift apart again
Also fix the spin itself: a principal hold had no cooldown, so the scheduler
re-dispatched instantly and the run re-entered only to re-fence and re-park.
It now records a backoff ladder (15s -> 5m) checked before graph entry, and
logs once per distinct reason instead of every pass — the same self-recovering
shape as holdForSessionContention. The hold never increments `attempt`, so no
existing guard could ever fire.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
- recover task-ID-pinned worktrees when their directory remains but Git
metadata/registration is gone
- preserve the orphan directory under `.fusion/recovery/worktrees`
before recreating the worktree
- retain existing fail-closed behavior for active, foreign, repo-root,
or out-of-root paths
## Problem
A task-pinned worktree can lose `.git` metadata while leaving build
artifacts behind. Fusion classifies that path as incomplete or
unregistered, but then calls `git worktree remove --force`. Git cannot
remove a directory it no longer recognizes as a worktree, so acquisition
aborts and the scheduler can repeat the same recovery indefinitely.
The observed reproduction left `.build` and `.swiftpm` under the pinned
path after Git registration was gone.
## Fix
For an inactive path that is both:
1. inside the configured worktree root, and
2. classified as incomplete or unregistered,
hold the shared worktree-path reservation across classification,
preservation, and recreation. Recovery directories are created one
canonical, project-contained component at a time, then the orphan is
atomically moved into `.fusion/recovery/worktrees` and the pinned
worktree is recreated. Moving rather than deleting preserves any unknown
task artifacts for operator inspection. Other classifications continue
through the existing guarded Git-removal path.
## Verification
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/worktree-acquisition.test.ts --silent=passed-only
--reporter=dot` — 30 passed
- `pnpm --filter @fusion/engine typecheck`
- `pnpm --filter @fusion/engine build`
- `pnpm test:gate:static`
- `pnpm check:changesets`
- `git diff --check`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Bug Fixes**
- Improved recovery of task-pinned worktrees when incomplete or stale
directories occupy the expected location.
- Preserves eligible inactive or unregistered worktree contents in a
recovery area instead of deleting them.
- Prevents unsafe recovery through symbolic links and handles concurrent
recovery attempts reliably.
- Supports recovery when directories span different storage devices.
- Ensures interrupted or invalid worktree states can be recreated safely
without disrupting active sessions.
- **Documentation**
- Added a patch changeset documenting the improved worktree recovery
behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- keep persisted operator-routed external checkouts authoritative during
executor recovery, remediation, verification, and cleanup
- fail closed when a configured external route is invalid instead of
falling back to a Fusion-managed worktree
- prevent Fusion from cleaning up operator-owned external checkouts
- add dashboard and executor regression coverage for the routing
handoffs
## Test plan
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/verify-worktree-invariants-missing.test.ts`
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/external-execution-checkout.test.ts
src/__tests__/executor-triage-column-audit.test.ts`
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/executor-fast-mode-workflows.test.ts -t 'external
execution|authoritative executor route|completed-task recovery captures
the live external|pre-merge remediation reuses the live external'`
- `FUSION_DASHBOARD_DEEP=1 pnpm --filter @fusion/dashboard exec vitest
run src/__tests__/routes-tasks-near-duplicate.test.ts -t 'PATCH
external-checkout persists one clean Git checkout for execution and
review'`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm --filter @fusion/dashboard typecheck`
- `pnpm test:gate:static`
- `pnpm check:changesets --strict`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
- **Bug Fixes**
- Improved external checkout routing across execution, verification,
recovery, retries, and remediation.
- Operations now use the latest persisted checkout details, preventing
stale routing information from directing work to the wrong location.
- Invalid or missing checkout routes fail safely with clear verification
errors.
- External checkouts are protected from unintended managed worktree or
branch cleanup.
- **Documentation**
- Clarified external checkout routing and validation behavior.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
A stale base is an optimization miss, not an execution failure. FN-8693's
dispatch-time refresh refused dirty checkouts and own-commit rebase conflicts
with executionSafe:false, and the refusal threw out of acquireTaskWorktree into
execute()'s generic terminal sink — parking the task `failed` and paging the
operator. Run-audit for 2026-08-01..09: 99 of 136 execution failures were these
refusals (74 dirty-worktree, 25 stale-base-conflict), and the bounded
non-parking lane built for them fired 0 times because it only ever saw refusals
published as typed graph node values and no code node enables refreshStaleBase.
82 of the 99 landed within five minutes of "Task marked done by agent": they
were code-review-remediation re-entries into execute() on the task's own warm
worktree — exactly the checkout the refresh must leave alone. Dispatch-time
rebase has no conflict resolution, so on a busy main it could only ever fail;
the merge lane already rebases with AI arbitration before landing and
deliberately leaves refreshStaleBase off.
- refreshReusedWorktreeBase: dirty tree, own-commit conflict, unresolvable base
and compensated persistence failures now return skipped/executionSafe — keep
the local base and run. Only an unproven tree (failed compensation, so a
half-rebased checkout may be on disk) still refuses.
- Check whether a mutation is needed before consulting the working tree: a
worktree already on the current base was refused just for carrying WIP.
- executor: catch WorktreeBaseRefreshError first and route it into
holdForWorktreeBaseRefresh, one shared non-parking lane the graph path now
uses too, so the two entry points cannot drift.
- run-audit: worktree:base-refresh-skipped separates a declined refresh from a
genuine block.
reset-to-base — the actual FN-8693 requirement — is preserved and tested.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
## Summary
- apply Fusion's existing stale-base reconciliation to freshly
reacquired and pooled execution worktrees
- advance retained task branches to the current local integration commit
after dependencies land
- keep planning and Worktrunk behavior unchanged while preserving
dirty/conflict fail-closed handling
## Problem
A dependent task can be planned before its dependency lands. If the
dependency merges and its branch is deleted, a later execution retry may
recreate the dependent worktree from its already-existing task branch.
That branch can still point at the pre-dependency commit.
Fusion already refreshes reused execution worktrees, but fresh
acquisition returned without calling the same reconciliation primitive.
The dependent task therefore executed without the landed dependency
output even though Fusion marked the dependency complete.
## Fix
When `refreshStaleBase` is enabled, run `refreshReusedWorktreeBase`
after a native fresh or pooled worktree is acquired and before cleanup,
init, or session execution. Track the actual backend used by injected
and fallback creators so a native fallback still refreshes while
Worktrunk-managed paths remain excluded. The existing primitive:
- resolves the current local integration branch without requiring a
remote
- resets branches with no task-owned commits
- rebases branches with task-owned commits
- blocks dirty or conflicting worktrees
- persists the integration commit as `baseCommitSha`
If refresh blocks a pooled checkout, clear the task's durable binding
before releasing the checkout for reuse.
Planning callers do not enable `refreshStaleBase`, so planning worktrees
remain unchanged.
## Verification
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/worktree-base-refresh.test.ts
src/__tests__/worktree-acquisition.test.ts --silent=passed-only
--reporter=dot` — 34 passed
- `pnpm --filter @fusion/engine typecheck`
- `pnpm --filter @fusion/engine build`
- `pnpm test:gate:static`
- `pnpm check:changesets`
- `git diff --check`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved worktree acquisition by refreshing stale branches against the
current integration branch.
* Added refresh support for recreated, pooled, and native fallback
worktrees.
* Prevented task execution when refresh fails and safely released
affected pooled worktrees.
* Avoided unnecessary refreshes for newly created Worktrunk worktrees.
* **Tests**
* Added coverage for stale-base refresh behavior across supported
acquisition scenarios.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## Summary
- normalize Vitest mock-call tuples before selecting graph
implementation sessions
- restore six clean-main executor assertions that otherwise misclassify
a routed implementation call as missing
## Test plan
- `pnpm --filter @fusion/engine exec vitest run --reporter=dot
src/__tests__/executor-review-verdicts.test.ts
src/__tests__/executor-worktree-liveness.test.ts`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm test:gate:static`
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Tests**
* Updated workflow routing and worktree liveness tests to use normalized
agent configuration when validating implementation-session selection.
* Improved coverage for fresh worktrees, configured directories, and
routed implementation sessions.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: gsxdsm <gsxdsm@users.noreply.github.com>
## Summary
- add an explicit API route that persists one clean external Git
checkout for task execution and enforced review
- fence execution to the checkout's persisted branch and fail closed
when the route becomes invalid
- allow completion invariants to validate explicitly routed checkouts
outside the project worktree directory
## Test plan
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/external-execution-checkout.test.ts
src/__tests__/review-checkout.test.ts
src/__tests__/engine-no-blocking-shellout.test.ts --silent=passed-only
--reporter=dot`
- `pnpm --filter @fusion/engine exec vitest run
src/__tests__/executor-fast-mode-workflows.test.ts -t 'prepares a
persisted external execution checkout' --silent=passed-only
--reporter=dot`
- `FUSION_DASHBOARD_DEEP=1 pnpm --filter @fusion/dashboard exec vitest
run src/__tests__/routes-tasks-near-duplicate.test.ts -t 'PATCH
external-checkout' --project dashboard-api --silent=passed-only
--reporter=dot`
- `pnpm --filter @fusion/engine typecheck`
- `pnpm --filter @fusion/dashboard exec tsc --noEmit`
- `pnpm verify:fast`
- `pnpm test:gate` (605 non-PostgreSQL tests pass; local PostgreSQL
suites cannot authenticate because the configured client returns an
empty password)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **New Features**
* Added support for routing task execution and review through
operator-selected external Git checkouts.
* External checkouts are validated for valid Git repositories, attached
branches, clean status, and branch consistency.
* Tasks can clear previously configured external checkout routing.
* Valid routed checkouts are used directly without creating a separate
worktree.
* **Bug Fixes**
* Invalid, incomplete, dirty, or mismatched checkout configurations now
fail early with clear validation errors.
* Missing tasks return the appropriate not-found response.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: gsxdsm <gsxdsm@users.noreply.github.com>
## Summary
Resolves merge conflicts from #3392 against current `main`.
`main` already landed the core #3386 fix via FN-8909 (`includeArchived:
false` live-row enumeration + per-task isolation). This PR rebases the
remaining #3392 refinements on top of that:
- Best-effort, secret-free audit emission (per-task and no-action)
- Distinguish `no-eligible-orphan` vs `all-attempts-failed` /
`no-finalization` no-action outcomes
- Redacted `errorType=` warn logs so poisoned-row failures cannot abort
the sweep or leak error prose
Supersedes #3392 (fork head is not writable from this environment
despite `maintainer_can_modify`).
## Test plan
- [x] `pnpm --filter @fusion/engine exec vitest run
src/__tests__/self-healing.test.ts --project engine-default --run -t
"finalizeOrphanedPlanningSegments"` — 8 passed
- [ ] CI PR checks green
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Bug Fixes**
* Improved recovery of orphaned planning segments when individual
finalization attempts fail.
* Recovery now continues successfully even if audit recording encounters
an error.
* Added clearer recovery outcomes, distinguishing cases where no
segments qualify, all attempts fail, or only some segments are
finalized.
* Warning messages now provide structured error details without exposing
sensitive information.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
Co-authored-by: Codex <codex@openai.com>
