fix(upstream): retain capacity through child cleanup

[mohanagy]

Closes #205

Summary

• wait for real local stdio child close signals before recycling profile capacity after forced cleanup
• keep the established clean idle-handoff reservation behavior while blocking replacements after timed-out child cleanup
• preserve bounded shutdown and restore abort of a hanging Streamable HTTP DELETE

Root cause

The MCP SDK can return from its SIGKILL shutdown path before the child process emits close. Miftah could release capacity or start a replacement in that gap. The regression fix briefly returned early for remote transports, which skipped aborting a timed-out DELETE; this PR restores that existing remote cleanup contract.

Validation

• npm test (122 files passed, 1 skipped; 1557 tests passed, 27 skipped)
• npm run test:core
• npm run test:coverage (95.77% statements, 91.94% branches, 98.33% functions)
• npm run lint
• npm run typecheck
• npm run build
• npm run smoke:cli
• npm run check:pack
• npm run test:package

Independent local review completed; no remaining actionable lifecycle defect found.

Summary by CodeRabbit

• Bug Fixes
  • Improved upstream process shutdown and restart reliability when local transport cleanup is still in progress.
  • Prevented replacement processes from starting before previous processes have fully closed.
  • Ensured capacity is retained correctly during close, restart, and recovery scenarios.
  • Added bounded forced shutdown behavior to prevent cleanup from hanging indefinitely.
• Tests
  • Expanded coverage for stdio descendant cleanup, concurrent shutdowns, and automatic recovery edge cases.

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 44 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 9398d8aa-bcfa-4155-a735-861493767480

📥 Commits

Reviewing files that changed from the base of the PR and between 017485b and c6dcc7b.

📒 Files selected for processing (1)

• tests/upstream-manager.test.ts

📝 Walkthrough

Walkthrough

UpstreamProcessManager now coordinates transport closure, local process teardown, replacement startup, and profile capacity release. New retained-stdio fixtures and lifecycle tests cover shutdown timeouts, restart races, forced cleanup, and automatic recovery exhaustion.

Changes

Upstream teardown coordination

Layer / File(s)	Summary
Transport close tracking and gated startup src/upstream/upstream-process-manager.ts	Managed sessions and startup attempts track transport closure, and replacement starts wait for blocking teardown gates.
Teardown completion and capacity release src/upstream/upstream-process-manager.ts	Shutdown paths defer incomplete cleanup, use bounded forced closes, and release profile capacity after teardown completion.
Retained stdio lifecycle coverage tests/fixtures/retained-stdio-descendant.mjs, tests/upstream-manager.test.ts	Fixtures and tests cover deferred replacement, shutdown races, forced cleanup, and capacity retention during restart exhaustion.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant UpstreamProcessManager
  participant StdioClientTransport
  participant TransportCloseSignal
  participant CapacityLimiter
  UpstreamProcessManager->>StdioClientTransport: terminate transport
  StdioClientTransport->>TransportCloseSignal: resolve local close
  UpstreamProcessManager->>TransportCloseSignal: complete teardown gate
  UpstreamProcessManager->>CapacityLimiter: release profile capacity

Loading

Possibly related PRs

• mohanagy/miftah#51: Related upstream lifecycle, capacity, restart, and teardown controls.
• mohanagy/miftah#70: Related transport termination and session shutdown handling.

Poem

I’m a rabbit watching transports close,
While teardown gates hold back the rows.
Capacity waits, then hops along,
Replacement starts when cleanup’s gone.
Stdio descendants lose their stay—
And tests keep chaos far away!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: retaining upstream capacity until child cleanup completes.
Description check	✅ Passed	The description covers summary, root cause, and validation, but omits the template's Security impact section.
Linked Issues check	✅ Passed	The PR adds focused regression tests and fixes the cleanup race, matching #205's goal to stabilize full and coverage suites without weakening guarantees.
Out of Scope Changes check	✅ Passed	The added fixture, lifecycle fix, and tests all support the stated cleanup/capacity-reliability goals; no unrelated changes stand out.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/205-upstream-child-cleanup

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/upstream/upstream-process-manager.ts`:
- Around line 1131-1150: The pending teardown path in deferTeardown can retain
profile capacity indefinitely without surfacing its state. Add periodic
diagnostic warnings or equivalent health metadata for teardown gates that remain
unresolved, including the profile and pending-since time, while preserving the
existing completion and capacity-release behavior in completeTeardown and
releaseProfileCapacity.

In `@tests/upstream-manager.test.ts`:
- Around line 877-885: Update the test cleanup around the second successful
manager.get("work") call to re-read the replacement descendant PID from
descendantPidPath and assign it to descendantPid before entering cleanup,
ensuring the finally block terminates the replacement descendant as well as the
upstream process.
- Around line 797-840: Update the test’s StdioClientTransport tracking to use
its public pid and onclose APIs instead of reading the private _process handle.
In the mocked start implementation, record the first transport’s pid and use
onclose to set firstChildClosed, preserving the assertion that replacement
startup waits for shutdown.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 185a52aa-96dc-42ce-8b77-71d4f0c872b7

📥 Commits

Reviewing files that changed from the base of the PR and between 0c00846 and 017485b.

📒 Files selected for processing (3)

• src/upstream/upstream-process-manager.ts
• tests/fixtures/retained-stdio-descendant.mjs
• tests/upstream-manager.test.ts