fix(witan): stop dropping in-flight requests 2s into a shutdown

[blarghmatey]

What are the relevant tickets?

N/A — no GitHub issue. The missing half of the shutdown safety asserted in
ol-infrastructure#5448;
that PR's comment has been corrected in
#5449.

Description (What does it do?)

• witan serve now passes uvicorn_config={"timeout_graceful_shutdown": …},
  defaulting to 120s, settable via --shutdown-grace-seconds /
  WITAN_MCP_SHUTDOWN_GRACE_SECONDS.
• Releases witan-council 0.15.0.

FastMCP hardcodes a 2-second graceful shutdown. From run_http_async
(fastmcp 4.0.0b2):

config_kwargs: dict[str, Any] = {
    "timeout_graceful_shutdown": 2,
    ...
}

So on SIGTERM uvicorn stops accepting connections, gives in-flight requests two
seconds, and drops the rest. A witan write has been measured at 27.1s under
16 concurrent writers, so every one in flight was severed by a deploy, an
eviction or a node drain — and a severed write is precisely the indeterminate
outcome a caller cannot safely retry, which is the failure class this deployment
has spent weeks removing elsewhere.

★ Why the deployment could not fix this alone

ol-infrastructure sets terminationGracePeriodSeconds: 150 so the kubelet is
willing to wait. uvicorn declined to use it. The pod-side setting bought
time that nothing spent, while looking like the entire fix — the comment there
asserted, in as many words, that "uvicorn shuts down gracefully on SIGTERM: it
stops accepting connections and waits for in-flight requests rather than
dropping them." That was wrong as configured. Both halves are required, and the
half that looks sufficient is the one that isn't.

Found while investigating FastMCP's concurrency knobs, not from a failure
report — so the window it closes has been open the whole time the 150s grace
period has been in place.

How can this be tested?

just test-witan-council   # 820 passed

Three new tests cover the override, its tunability, and that stdio passes no
uvicorn config at all.

The committed tests use the existing _FakeMCP double, so they prove the
kwarg is forwarded and nothing more. If FastMCP rejected or ignored it, witan
would either fail to start or silently keep the 2s default — neither of which a
fake can catch. So that was verified separately against the real library, with
uvicorn.Config instrumented to capture its kwargs:

timeout_graceful_shutdown reaching uvicorn.Config: 120.0
VERDICT: override lands

Additional Context

Why 120s. It matches the request budget the deployment enforces at APISIX
(WITAN_REQUEST_TIMEOUT), on the principle that shutdown should be willing to
wait as long as a request was allowed to take. Anything past that budget is
being cut off upstream anyway. The deployment's 150s termination grace sits
above it, so the kubelet remains the outer bound.

Local runs are unaffected. stdio never reaches this code path, and a local
HTTP run has nothing in flight worth waiting for — so the default is safe
everywhere rather than only in the cluster.

Rebased onto #240, which merged first and took witan-council 0.14.0. This
is now 0.15.0. The CHANGELOG conflict was resolved by keeping #240's 0.14.0
section intact and adding 0.15.0 above it — verified the SessionLife floor-bump
entry and the witan-core>=0.21 pin both survived. Full suite re-run after the
rebase: 820 passed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JYb9sMjetD9Nxjf24Aw3m5

[Copilot]

Pull request overview

Adds a configurable Uvicorn graceful-shutdown timeout to prevent interrupted in-flight Witan requests.

Changes:

• Defaults HTTP shutdown grace to 120 seconds.
• Adds forwarding and stdio-isolation tests.
• Prepares release metadata, which now requires rebasing to 0.15.0.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
uv.lock	Updates the workspace package version.
mcp/servers/witan/witan/cli/__init__.py	Configures graceful HTTP shutdown.
mcp/servers/witan/tests/test_cli.py	Tests timeout forwarding and stdio behavior.
mcp/servers/witan/pyproject.toml	Updates package release metadata.
mcp/servers/witan/CHANGELOG.md	Documents the shutdown fix.

Suppressed comments (1)

mcp/servers/witan/pyproject.toml:99

• This bumpversion value now collides with the 0.14.0 release merged in PR #240. Rebase and advance it to 0.15.0 together with the project version, changelog, and lockfile so future bumps start from the actual latest release.

current_version = "0.14.0"

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.