refactor(runtime): preserve transport error codes over IPC (#12667)

Errors thrown across Electron's `ipcMain.handle` lose their structured error code — only the message survives. So the renderer classified transport failures by matching substrings of English message text. That is how a queue-overload rejection escaped classification during a remote outage and surfaced as a raw error wall: the code was stripped in transit and its message fragment was not in the recoverable list.

This converts `RemoteRuntimeClientError` and `RuntimeRpcCallQueueOverloadError` rejections from `runtimeEnvironments:call` into the existing structured `{ok:false, error:{code,message}}` response, which the preload already passes through unchanged and `unwrapRuntimeRpcResult` already reconstructs with the code intact. Classification now treats a present code as authoritative and consults message fragments only when there is no code.

The fragment list is deliberately RETAINED as a backstop, not deleted: untyped main-handler rejections, subscription-start failures, and older code-less paths still rely on it.

Proven real rather than cosmetic: a test-only patch applied to unmodified main fails (4 failed / 66 passed) because the code does not survive the boundary today, and passes on this branch.

Independent review specifically chased the risk that a present-but-unrecognized code would now short-circuit to fatal where a message fragment previously rescued it — the shape that dead-ends a pane. It enumerated all 34 reachable code/message pairs and confirmed no pair flips recoverable to fatal, that the newly-serialized code set is closed and client-local, and that host-forwarded codes preserve recoverable classification by design. A differential harness over that corpus was verified non-vacuous by injecting the bad shape.

Nothing crosses the paired-runtime wire: desktop main -> IPC -> preload -> renderer only, reusing an existing response shape, no new fields or opcodes.

The connection-level offline state with a single reconnect affordance remains as STA-3456 follow-up work.
This commit is contained in:
Jinwoo Hong
2026-08-05 00:44:05 -07:00
committed by GitHub
parent c4d5a535f2
commit 15ef69a814
4 changed files with 127 additions and 15 deletions
@@ -1,6 +1,7 @@
import { describe, expect, it } from 'vitest'
import {
isRecoverableRemoteRuntimeConnectionError,
isRuntimeRpcQueueOverloadError,
toRemoteRuntimeClientErrorLike
} from './remote-runtime-client-error-classification'
@@ -29,6 +30,24 @@ describe('remote runtime client error classification', () => {
).toBe(false)
})
it('trusts a structured recovery code before legacy message fragments', () => {
expect(
isRecoverableRemoteRuntimeConnectionError({
code: 'unauthorized',
message: 'Remote Orca runtime closed the connection.'
})
).toBe(false)
})
it('trusts a structured queue code before legacy message fragments', () => {
expect(
isRuntimeRpcQueueOverloadError({
code: 'remote_runtime_unavailable',
message: 'Remote runtime call queue is full; retry after current calls finish.'
})
).toBe(false)
})
it.each([
'Could not connect to the remote Orca runtime.',
'Remote Orca runtime closed the connection.',