fix(server): subagent threads settle with their parent instead of sweeping on their own#19665

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Do not run the settle script when reading the parent fails.

If getThread fails to read or decode an existing parent, Effect.orElseSucceed treats that failure as a missing parent. Cleanup can then run the settle script in the parent's shared worktree. Recover only ProjectionStoreThreadNotFoundError; let read failures reach the existing cleanup error handler. As per coding guidelines: “Catch known tags with Effect.catchTags({ ... }), even for one tag.”

Source: Coding guidelines

✅ Addressed in commit a8ac79c

Addressed in a8ac79ca90. cleanUpSettledThread now recovers only ProjectionStoreThreadNotFoundError via Effect.catchTags, matching Orchestrator.ts:8531; a ProjectionStoreReadError on the parent reaches the existing "cleaning up a settled thread failed" handler and skips the script instead of running it. Marking thread resolved.

@mikeohuo The supplied code confirms the fix. Effect.catchTags recovers only ProjectionStoreThreadNotFoundError. Other parent-read failures reach the cleanup error handler and skip the settle script.

If you found this review helpful, would you consider giving us a shout-out on X?

Thank you for using CodeRabbit!

✅ Review thread resolved.

You are interacting with an AI system.

🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift

Recheck the parent before settling a selected child.

getSettlementCandidates filters subagents by the parent’s current state. thread.unsettle can make the parent active after selection while changing only the parent. The child’s snapshot can remain unchanged.

thread.auto-settle and thread.settle validate only the child. Their per-thread locks do not serialize a parent command with a child command. The child can therefore settle while its parent is active.

Make parent eligibility part of the same serialized or atomic mutation check.

Investigated. The selection-to-dispatch race is real, but its outcome is an idle hidden child parked under an active parent, which main already produces today for every subagent child settled by inactivity; this PR narrows that. Nothing reads the child's settled state: subagent result finalization keys on lineage (Orchestrator.ts:10144-10150, :10443-10448), needsRecovery("subagent-results") keys on lineage and run status (ProjectionStore.ts:576-600), and the next message into the child un-settles it (Orchestrator.ts:4666-4685). A parent re-read inside the thread.auto-settle handler would still run outside the parent's lock, so it only shortens the window; the snapshot guard is the same design top-level auto-settle uses. Happy to add the re-read if a maintainer wants the narrower window. Marking this thread resolved.

@mikeohuo Thanks for the clarification. The race is real, but it does not establish the functional failure claimed in my finding. Result finalization and recovery do not depend on the child’s settled state, and a new message un-settles the child.

I withdraw the required atomic parent-state check. A parent re-read alone would not eliminate the race.

✅ Review thread resolved.

You are interacting with an AI system.

🚀 Performance & Scalability | 🟡 Minor | ⚡ Quick win

Fetch only subagent candidates when automatic settlement is off.

When automatic settlement is disabled, the sweep still reads all eligible candidates and filters out non-subagent threads afterward. This occurs on periodic and other full-sweep paths. A non-empty result also triggers projectStore.listShells() and the provider-thread and pending-turn reads for every returned candidate.

Thread-specific provider and run events pass a threadId, so they do not perform an all-thread read. They still perform unnecessary candidate work for non-subagent threads.

Add a subagentsOnly option to getSettlementCandidates, apply it in the SQL and memory implementations, and enable it when automatic settlement is disabled.