Server lifecycle and availability policy
The MCP server starts as a target-free analysis service or with one configured initial target. It keeps the session usable when optional capabilities are not ready, reports the current readiness of each tool, and gives clients explicit operations to open, inspect, save, and close a target. See MCP server for the wider server composition and MCP tool registration for the tool surface.
Startup policy
Startup separates server readiness from target readiness. The MCP transport can become available without an active target, while a configured target must open successfully before the transport starts.
Target-free startup
The server accepts a target-free start when no initial target is configured. This mode exposes session lifecycle and status tools immediately, so a client can inspect readiness and choose a target later through open_binary (src/…/startup.ts• L6-15, src/…/createServer.ts• L253-283).
References: src/…/startup.ts• L6-15 src/…/createServer.ts• L253-283
Initial target startup
When configuration names an initial target, startup opens it before the MCP transport is offered to the client. If the open fails, the server reports the projected error, closes the session, and exits instead of exposing a partly ready service (src/…/startup.ts• L14-32).
References: src/…/startup.ts• L14-32 src/main.ts• L51-70
Optional provider startup
Optional provider failures do not block the rest of the server. The transport records the failed provider and keeps its peer capabilities available; the status inventory later reports the affected tools as unavailable with a repair path (src/…/transport.ts• L38-57, src/…/sessionAvailabilityPolicy.ts• L29-76).
References: src/…/transport.ts• L38-57 src/…/sessionAvailabilityPolicy.ts• L29-76
Transport readiness
The production transport uses bounded startup phases so a client does not wait without limit. The policy gives clients a 30-second startup expectation and gives the diagnostic command a 30-second deadline. It also budgets initialization, tool listing, and the first catalog request, and retains up to 64 KiB of diagnostic standard error (src/mcpStartupPolicy.ts• L3-19).
Client tool deadlines must also cover the selected provider or upstream request budget. The recommended value adds 120 seconds of operation headroom, and the client-facing whole-second value rounds that result up (src/mcpStartupPolicy.ts• L21-61).
References: src/mcpStartupPolicy.ts• L3-19 src/mcpStartupPolicy.ts• L21-61
Session availability policy
Session availability is a live decision about whether each operation can run in the current host, target, provider, and client context. The server combines session status with configured feature flags and provider probes, then returns a stable per-tool inventory rather than treating the whole server as simply ready or not ready.
Availability inputs
The policy considers four sources of readiness. A target can be absent or unsupported. A provider can be missing or unavailable. The host can lack a required platform feature. The MCP client can lack a required negotiated feature (src/…/CapabilityInventory.ts• L88-101, src/…/CapabilityInventory.ts• L170-233).
The policy can use configured availability values, but observed host limits remain authoritative. Without a configured policy, optional feature flags come from runtime defaults and process capture is enabled only off Windows. Observed provider-load failures and host restrictions are merged into the returned policy, so a configured allowance cannot override an observed host restriction (src/…/sessionAvailabilityPolicy.ts• L21-80).
The resulting reason tells the client which class of condition it must fix:
target_requiredmeans the operation needs an opened target.provider_missingmeans the required integration is not configured.provider_unavailablemeans an integration failed or is not ready.target_unsupportedmeans the active target does not support the operation.unsupported_hostmeans the host cannot run the operation.client_capability_missingmeans the negotiated MCP client features are not sufficient.
Each unavailable entry can also include remediation. An available entry has reason: "available" and no remediation (src/…/toolOutputSchemaPrimitives.ts• L368-391).
References: src/…/CapabilityInventory.ts• L88-101 src/…/CapabilityInventory.ts• L170-233 src/…/sessionAvailabilityPolicy.ts• L21-80 src/…/toolOutputSchemaPrimitives.ts• L368-391
Capability inventory
binary_session publishes the inventory for all registered operations. The wire form groups tools with the same decision, but each group still carries availability, reason, remediation, client requirements, effects, and safety annotations (src/…/CapabilityInventory.ts• L249-260, src/…/toolOutputSchemaPrimitives.ts• L403-429). Clients should use this inventory to choose a supported operation instead of guessing from tool names.
References: src/…/CapabilityInventory.ts• L249-260 src/…/toolOutputSchemaPrimitives.ts• L403-429
Runtime readiness probes
When binary_session runs, it starts the available provider readiness probes in parallel. It waits for all probe results before it takes the session status snapshot, so target and provider information describe one completed status request. An AnalysisError, including a cancelled probe or status request, becomes the tool's projected error; other failures continue through the server error path (src/…/registerSessionStatusTool.ts• L52-103).
References: src/…/registerSessionStatusTool.ts• L52-103
Availability recovery
A cancelled target switch does not permanently disable the old session. The session retires or restores its provider binding, clears stale runtime availability, and rebuilds the inventory from the restored state. A later status request can therefore show the original target and its recovered tools (src/…/BinarySession.ts• L297-309, src/…/BinarySession.ts• L550-574).
References: src/…/BinarySession.ts• L297-309 src/…/BinarySession.ts• L550-574
Session status
binary_session is the read-only readiness and identity view for the long-lived MCP session. It reports the active target, provider and analysis state, runtime health, capability inventory, negotiated client features, and server identity without starting analysis (src/…/sessionToolContracts.ts• L80-84, src/…/registerSessionStatusTool.ts• L76-127).
Status scope
The status result joins session state with the live availability inventory. Its server identity includes the running package and catalog versions, start time, command path, negotiated protocol, connected client, and catalog digests. A caller can supply expected package, catalog, or absolute server-path values to detect that it connected to an outdated or different registration (src/…/sessionStatusContract.ts• L6-22, src/serverIdentity.ts• L30-112).
References: src/…/sessionStatusContract.ts• L6-22 src/serverIdentity.ts• L30-112 src/…/toolOutputSchemaPrimitives.ts• L464-529
Identity alignment
Identity comparison is explicit. Matching supplied expectations produces aligned; a mismatch produces mcp_server_restart_required; missing expectations produce unknown rather than an unsupported claim. The response includes a remediation message when the client must restart or provide more comparison data (src/serverIdentity.ts• L41-112).
References: src/serverIdentity.ts• L41-112
Target lifecycle
The lifecycle tools control the active analysis target while preserving ordering between provider work and target transitions. An open can create the first binding or switch from one target to another. A close retires the active provider and clears runtime state after earlier admitted work has drained (src/…/BinarySessionPort.ts• L36-88). The session registration binds lifecycle and status operations through the shared service-tool table, while keeping them outside analysis admission (src/…/registerSessionTools.ts• L20-33, src/…/registerSessionTools.ts• L52-91).
Target opening
open_binary validates the target and optional analysis selection, then opens or switches the session. A switch waits for earlier calls, retires the old provider, and can restore the previous binding if the new open is cancelled or fails. The failure remains visible even when restoration also fails (src/…/sessionToolContracts.ts• L68-78, src/…/BinarySession.ts• L210-229, src/…/BinarySession.ts• L252-309).
References: src/…/sessionToolContracts.ts• L68-78 src/…/BinarySession.ts• L210-229 src/…/BinarySession.ts• L252-309
Target closing
close_binary drains earlier provider requests before it closes the active target. It also closes process-capture resources as part of the same operation. Session close and process-resource cleanup run as joined work, so a failure from either is returned; a cleanup failure remains available for a later close retry. Later provider requests wait for the lifecycle transition, which prevents a new operation from overtaking a close (src/…/sessionToolContracts.ts• L76-78, src/…/sessionLifecycle.ts• L43-107, src/…/sessionLifecycle.ts• L110-153).
References: src/…/sessionToolContracts.ts• L76-78 src/…/sessionLifecycle.ts• L43-107 src/…/sessionLifecycle.ts• L110-153
Snapshot close
A close can first write an immutable analysis snapshot to an absolute caller path. The snapshot write and close share one lifecycle lock. If the write fails, the target stays open so cached analysis is not lost; an existing file is protected unless the caller sets overwrite: true (src/…/BinarySession.ts• L445-469, src/…/sessionLifecycleInputs.ts• L79-83). If process-capture cleanup also fails, the result preserves both the close failure and the cleanup retry state. Mutable observations can instead be preserved through the evidence bundle flow described in Session evidence and results.
References: src/…/BinarySession.ts• L445-469 src/…/sessionLifecycleInputs.ts• L79-83 src/…/sessionToolContracts.ts• L76-78 src/…/sessionLifecycle.ts• L51-107
Cleanup recovery
Close returns cleanup errors without discarding the pending cleanup state. A later close retries retained cleanup. The close tool retains failed process-capture cleanup and binds it to close_binary; when session close and process cleanup both fail, it combines the errors while preserving retry metadata (src/…/sessionLifecycle.ts• L43-107).
Server shutdown requests from SIGINT, SIGTERM, stdin end, and stdin close share one cleanup attempt, so concurrent requests do not duplicate work. A failed cleanup owner is retried while successful owners are not, and the event handlers are removed only after all owners close successfully (src/…/BinarySession.ts• L473-547, src/…/shutdown.ts• L29-75, src/…/processShutdown.ts• L23-37, src/…/shutdownRegistration.test.ts• L18-110).
Server shutdown also attempts transport, server, provider, and optional-resource cleanup together. It reports cleanup failure and keeps the failed owner available for a later retry (src/…/transport.ts• L60-80, src/…/transport.ts• L164-182, src/…/shutdownRegistration.test.ts• L113-178).
References: src/…/sessionLifecycle.ts• L43-107 src/…/BinarySession.ts• L473-547 src/…/shutdown.ts• L29-75 src/…/processShutdown.ts• L23-37 src/…/transport.ts• L60-80 src/…/transport.ts• L164-182 src/…/shutdownRegistration.test.ts• L18-178
Runtime diagnostics
The runtime provides two diagnostic paths. Normal MCP errors expose a safe projected error. The dedicated rea mcp doctor command starts the real stdio adapter and checks that the server initializes, lists the expected tools and prompts, answers binary_session, and reports the expected identity (src/mcpDoctor.ts• L81-167, src/mcpDoctor.ts• L195-281).
Doctor checks
The doctor marks the adapter healthy only when all checks pass. It retains exact missing, unexpected, and duplicate inventory names, so a startup that connects but exposes the wrong catalog is still unhealthy (src/mcpDoctor.ts• L217-281, src/mcpDoctor.ts• L326-358). Help is handled before a diagnostic session starts, while invalid options return a validation failure (src/mcpDoctor.ts• L287-323, src/mcpDoctor.ts• L404-448).
References: src/mcpDoctor.ts• L217-281 src/mcpDoctor.ts• L287-323 src/mcpDoctor.ts• L326-358 src/mcpDoctor.ts• L404-448
Failure diagnostics
A failed child startup returns a failed transport check and captured stderr. The doctor keeps a bounded stderr prefix while counting the full stream, marks truncation, and kills a child that misses the absolute deadline. Unexpected server-entrypoint failures use a generic startup message so internal causes do not reach the caller (src/mcpDoctor.ts• L81-167, src/mcpDoctor.ts• L510-535, src/main.ts• L94-110).
The doctor closes both the client and the retained child transport. A cleanup failure changes the result to unhealthy and adds a separate cleanup check, even when the startup checks passed (src/mcpDoctor.ts• L131-167).
References: src/mcpDoctor.ts• L81-167 src/mcpDoctor.ts• L510-535 src/main.ts• L94-110
Shutdown diagnostics
Transport loss and startup failure are written to the server log and standard error as high-level events. Cleanup failures are reported separately, which distinguishes a connection problem from a resource that still needs cleanup (src/…/transport.ts• L111-162).
References: src/…/transport.ts• L111-162
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the availability policy flags aligned with the provider probes and the tool requirements in
CapabilityInventory. - Keep observed host restrictions authoritative over configured availability values, including the default process-capture rule.
- Keep
binary_sessionstatus inputs, identity comparison fields, and output schema aligned so stale-server checks remain meaningful. - Preserve the ordering contract between admitted analysis calls, target transitions, snapshot writes, and close cleanup.
- Keep close-session and process-capture cleanup result joining aligned with cleanup retry metadata and projected error output.
- Keep lifecycle and status registration aligned with the shared service-tool table so both remain outside analysis admission.
- Keep startup phase budgets, provider-derived tool deadlines, and the
rea mcp doctordeadline consistent with their callers. - Keep optional-provider failure reporting separate from transport failure reporting so one missing adapter does not hide peer capabilities.
- Keep all shutdown event sources attached to the same retry-aware cleanup owner, and unregister them only after successful cleanup.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Configured initial target cannot open | The transport does not start and the process exits after session cleanup. | Check the projected startup error and retry with a valid target. |
| Optional provider load fails | Only dependent tools are unavailable; peer tools remain usable. | Read binary_session.tool_availability and follow its remediation. |
| Client cancels a target switch | The request fails, but the prior target may be restored before the next admitted request. | Read binary_session again before issuing target-dependent work. |
| Snapshot path is not absolute or the file exists without overwrite | Snapshot close is rejected and the active session remains open. | Use an absolute path and set overwrite: true only when replacement is intended. |
| Session close or process-capture cleanup fails | close_binary reports the failure and retains the failed cleanup for a later retry. | Retry close after the resource becomes removable. |
| Provider or resource cleanup fails during shutdown | Shutdown reports failure, and only the failed cleanup owner is retried. | Retry server shutdown after the resource becomes removable. |
| Shutdown events arrive together | Cleanup is joined into one attempt instead of running once per event. | Let the shared shutdown operation finish before issuing another request. |
| Doctor child misses its deadline or emits the wrong catalog | Doctor reports unhealthy even if a process was spawned. | Use the failed checks and retained stderr diagnostics to fix startup. |
| Doctor client or child cleanup fails | The doctor reports unhealthy with a separate cleanup failure. | Treat the cleanup check as a runtime failure, not as a harmless close warning. |
Key files
| File | Why to read it |
|---|---|
| src/main.ts | Shows the top-level startup order, transport handoff, and process-level failure boundary. |
| src/…/startup.ts | Defines target-free startup and the fail-before-transport rule for an initial target. |
| src/…/transport.ts | Shows optional provider tolerance, MCP transport creation, and shutdown cleanup. |
| src/…/shutdown.ts | Shows shared shutdown attempts, cleanup ownership, retries, and event unregistration. |
| src/…/processShutdown.ts | Defines the process and stdin events that request shutdown. |
| src/mcpStartupPolicy.ts | Defines startup, diagnostic, and provider-derived tool time budgets. |
| src/…/sessionAvailabilityPolicy.ts | Defines configured availability, target-free defaults, and host restriction merging. |
| src/…/CapabilityInventory.ts | Explains how host, target, provider, and client facts become tool availability decisions. |
| src/…/registerSessionStatusTool.ts | Shows how parallel live readiness probes, session status, and server identity form binary_session. |
| src/…/sessionLifecycle.ts | Shows the public close operation's joined resource cleanup and retry behavior. |
| src/…/registerSessionTools.ts | Shows how lifecycle and status tools are bound with session-owned process resources. |
| src/…/BinarySession.ts | Shows the ordering rules for open, switch, snapshot close, cleanup retry, and status. |
| src/serverIdentity.ts | Defines server alignment states and restart guidance. |
| src/mcpDoctor.ts | Defines production startup checks, diagnostic output, and bounded cleanup. |
| src/…/shutdownRegistration.test.ts | Illustrates the contract for joined shutdown events, retry behavior, and handler removal. |