Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / server-lifecycle-and-policy

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_required means the operation needs an opened target.
  • provider_missing means the required integration is not configured.
  • provider_unavailable means an integration failed or is not ready.
  • target_unsupported means the active target does not support the operation.
  • unsupported_host means the host cannot run the operation.
  • client_capability_missing means 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_session status 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 doctor deadline 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

TriggerConsequenceGuard
Configured initial target cannot openThe 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 failsOnly dependent tools are unavailable; peer tools remain usable.Read binary_session.tool_availability and follow its remediation.
Client cancels a target switchThe 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 overwriteSnapshot 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 failsclose_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 shutdownShutdown reports failure, and only the failed cleanup owner is retried.Retry server shutdown after the resource becomes removable.
Shutdown events arrive togetherCleanup 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 catalogDoctor reports unhealthy even if a process was spawned.Use the failed checks and retained stderr diagnostics to fix startup.
Doctor client or child cleanup failsThe doctor reports unhealthy with a separate cleanup failure.Treat the cleanup check as a runtime failure, not as a harmless close warning.

Key files

FileWhy to read it
src/main.tsShows the top-level startup order, transport handoff, and process-level failure boundary.
src/…/startup.tsDefines target-free startup and the fail-before-transport rule for an initial target.
src/…/transport.tsShows optional provider tolerance, MCP transport creation, and shutdown cleanup.
src/…/shutdown.tsShows shared shutdown attempts, cleanup ownership, retries, and event unregistration.
src/…/processShutdown.tsDefines the process and stdin events that request shutdown.
src/mcpStartupPolicy.tsDefines startup, diagnostic, and provider-derived tool time budgets.
src/…/sessionAvailabilityPolicy.tsDefines configured availability, target-free defaults, and host restriction merging.
src/…/CapabilityInventory.tsExplains how host, target, provider, and client facts become tool availability decisions.
src/…/registerSessionStatusTool.tsShows how parallel live readiness probes, session status, and server identity form binary_session.
src/…/sessionLifecycle.tsShows the public close operation's joined resource cleanup and retry behavior.
src/…/registerSessionTools.tsShows how lifecycle and status tools are bound with session-owned process resources.
src/…/BinarySession.tsShows the ordering rules for open, switch, snapshot close, cleanup retry, and status.
src/serverIdentity.tsDefines server alignment states and restart guidance.
src/mcpDoctor.tsDefines production startup checks, diagnostic output, and bounded cleanup.
src/…/shutdownRegistration.test.tsIllustrates the contract for joined shutdown events, retry behavior, and handler removal.