fix(backend): cache stopping/error frames for late joiners

[gmaclennan]

Summary

SimpleRpcServer already replays started / ready to clients connecting after the broadcast — that's what makes the Android RN module's read-only second connection to control.sock converge correctly when a fresh JS bundle loads against an already-running FGS. But stopping and error frames were explicitly not replayed, with the rationale that the imminent socket close lets the peer infer the terminal state. That inference is lossy in two ways:

• Late-join during graceful shutdown. Backend broadcasts {started}, {ready}, then {stopping}. A client connecting in the gap between the broadcast and Promise.all([close…]) gets the readiness replay, derives STARTED, then sees the socket close. The disconnect-reason rule in ComapeoCoreModule.kt hits the STARTING/STARTED → ERROR branch and reports node-runtime-unexpected — a graceful stop, mis-labelled as a crash.
• Late-join after error. Backend broadcasts {error, phase, message} then process.exit(1) after a 100 ms flush. A client that completes its connect inside that window sees only the close, not the frame, and lands in ERROR with synthetic errorPhase: "node-runtime-unexpected" / errorMessage: "Backend disconnected unexpectedly" — the original phase and message are gone.

This PR caches the latest terminal frame in SimpleRpcServer and replays it after the readiness frames on connect. One object reference of state, both gaps closed: late joiner during stop sees {stopping} → STOPPING → STOPPED on close; late joiner after error sees the real {error, phase, message} → ERROR with correct details.

broadcastError() is removed; both stopping and error are now sent through the existing broadcast() helper, which dispatches the cache decision on message.type. The parameter is typed as TerminalFrame | ({type: string} & JsonObject) — strict shapes for the known terminal types are visible to callers, but the union accepts arbitrary frames so a future non-terminal broadcast doesn't have to widen the cache type. The runtime if (type === "stopping" || "error") check is the load-bearing gate, not the type system, so the cache stays correct even if the JSDoc guarantee is bypassed.

Why this over a getState RPC

A getState RPC was considered as an alternative for the late-join case. Rejected because:

• iOS reads service state in-process — no IPC needed, RPC would be unused there.
• Backend Node only knows its own readiness phase + last error; the full ComapeoState is derived from inputs (NodeRuntimeState, stopRequested) that live FGS-side. Backend RPC can't return the derived state directly.
• Adds request/response correlation to a control socket that's currently broadcast-only.
• Would force state.getState() async-on-first-call.

Replay extension solves the actual gaps without any of those costs.

Files

• backend/lib/simple-rpc.js — add #terminalFrame cache; replay after readiness; consolidate terminal-frame emission into broadcast() with type-driven caching; remove the now-redundant broadcastError().
• backend/index.js — handleFatal now sends {type:"error", …} through broadcast(); same for the stopping frame in the shutdown handler.
• docs/ARCHITECTURE.md — §3.1 replay semantics rewritten; §5.5 and the timeout table updated to match the new API.

Test plan

No tests exist in the repo for this code path (backend/lib/ has no test files; root package.json test script is the expo-module suite for native bridges). Verified by:

• node --check on both modified backend files
• tsc --noEmit -p backend/tsconfig.json clean
• Manual: trigger graceful shutdown on Android, restart RN bundle mid-shutdown, observe STOPPED (not ERROR)
• Manual: trigger backend error, restart RN bundle within ~100 ms, observe original error phase/message preserved

The two manual repro scenarios are narrow timing windows; happy-path late-join (RN restart against a healthy ready backend) is unchanged and still covered by the existing started/ready replay.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the backend control-socket server so late-connecting clients can observe the most recent terminal lifecycle frame (stopping/error) in addition to the existing readiness replay (started/ready). This aligns Android’s “late joiner” behavior during shutdown/error windows with what an early-connected client sees, preserving correct STOPPING/ERROR attribution.

Changes:

• Cache the latest terminal control frame in SimpleRpcServer and replay it to newly connected clients after readiness frames.
• Remove the dedicated broadcastError() API and route error broadcasts through broadcast({type:"error", ...}).
• Update architecture documentation describing replay semantics for terminal frames.

Reviewed changes

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

File	Description
docs/ARCHITECTURE.md	Updates control-socket replay semantics to include caching/replay of terminal frames.
backend/lib/simple-rpc.js	Adds #terminalFrame caching and replays terminal frame to late-connecting clients; consolidates terminal broadcasting into broadcast().
backend/index.js	Updates fatal error path to emit {type:"error"} via broadcast() instead of broadcastError().

Comments suppressed due to low confidence (1)

backend/index.js:174

• This call site was updated to use controlIpcServer.broadcast({type:"error", ...}), but there are still comments earlier in this file describing broadcastError being used by handleFatal. Update those comments to avoid pointing readers at a non-existent method.

    controlIpcServer.broadcast({
      type: "error",
      phase,
      message: err.message,
      stack: err.stack,
    });

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.