Jinwoo-H
d4890a78bc
The OutputSpan gate is right for `terminal.subscribe` and wrong for
`terminal.multiplex`. Keying spans off a declared `outputSpan` capability treats
"peer did not declare it" as "peer cannot decode opcode 15", which is false on
multiplex: opcode 15 shipped in v1.4.147 (c0f0810dd9, 2026-07-19) and every
capability a peer could declare to prove it is younger — `ackOutput` by 9 days,
`ackOutputSourceRanges` by 10. So the gate read the entire installed base as
incapable and downgraded it.
The downgrade cannot be made safe there. A plain Output frame carries only
`(data, seq)`, so a seq-tracking peer reconstructs a run as `seq - data.length`,
which a transformed run (`rawLength !== data.length`) contradicts by definition.
Three failures reproduced through the real dispatcher against the shipped desktop
capability set:
- a zero-byte absorbed-query frame fails `TerminalSourceRangeLedger.canAccept`
(`encodedBytes > 0`), parks in `ackPendingOutput`, and head-blocks the flush
loop on the same head forever — all later output is lost;
- every transformed emission reads as a dropped-frame gap in `detectOutputGap`
and triggers `requestResyncSnapshot`;
- a >48 KiB transformed run takes the `shouldDelayFinalSeq` arm, which omits
`sourceRanges`, flipping the ledger's mapping mode and detaching the stream.
Multiplex now always frames transformed runs as OutputSpan; the vestigial
`outputSpan` capability is removed from the multiplex schema, stream state, and
the renderer's subscribe frame. Subscribe keeps the gate: mobile ignores Output
`seq` outright, which is what makes the downgrade lossless there — that property,
not the capability flag, is the licence, so the chunker option is now
`transformedRuns: 'span' | 'downgrade-to-text'` and the unsound call site cannot
be written by accident.
Coverage for the fallback arm was absent — every fixture was a 14-character
string, so the multi-chunk downgrade never ran and deleting a yield (48 KiB of
silently dropped output) passed everything. Adds over-cap, zero-byte and
per-frame-seq contracts plus a 600-case fuzz, transformed and multi-chunk
transformed steps to the cross-version journey (which pins current code against
the real v1.4.173 release client), and repairs the JS benchmark that the required
options argument broke.
Refs STA-3482
7.7 KiB
Remote wire compatibility
Orca's remote-server feature pairs a desktop client to a remote Orca runtime, and users update the two independently. Mixed versions are the normal state, not an edge case. This page is the contract for changing anything a paired client and host exchange: the runtime RPC envelope, the terminal binary stream, and the content either side publishes over them.
src/shared/protocol-version.ts says when to bump RUNTIME_PROTOCOL_VERSION. This
page covers the changes that do not bump it and are therefore easy to get wrong.
Rule 1 — a new optional JSON field on an existing frame is safe
Every JSON payload is parsed with a decoder that ignores unknown keys (zod .strip()
on RPC params, JSON.parse on stream frames). An older peer that has never heard of
the field simply does not read it.
Safe:
// host adds a field; older clients ignore it
encodeTerminalStreamJson({ kind, cols, rows, hiddenOutputReason })
The field is safe only for as long as every reader treats it as optional. The moment a newer client requires it, that client is broken against every host that predates the field — which is the same defect as removing a field, just discovered later. If new behavior depends on the field being present, that is Rule 2: negotiate it, or make the reader fall back.
Rule 2 — a new stream opcode is NOT safe; negotiate it
decodeTerminalStreamFrame returns null for an opcode it does not know, and
runtime-rpc.ts drops that frame without an error:
const frame = decodeTerminalStreamFrame(bytes)
if (!frame) {
return // silently dropped — the sender never learns
}
So a new opcode sent to an older peer does not fail loudly. It vanishes, and the feature behind it appears to hang. Input sent under a new opcode is swallowed.
A new opcode must be announced in the subscribe handshake and sent only after the
peer confirms it. The existing pattern is SetOutputPaused (opcode 16):
- the client advertises support in the
Subscribeframe'scapabilities; - the host echoes
capabilities: { outputPause: 1 }on thesubscribedevent; - the client sends opcode 16 only after that echo (
stream.supportsOutputPause); - the host only acts on opcode 16 when it negotiated it (
stream.supportsOutputPause).
OutputSpan (opcode 15) is the worked example, and it is worth reading closely because
the obvious fix was wrong on half the paths.
It shipped ungated in v1.4.147 (2026-07-19) on both the legacy terminal.subscribe
stream and the multiplex stream, so transformed emissions (SSH relay, startup ingress,
daemon keep-tail salvage) reached mobile as an opcode its vendored table does not
contain — dropped with no error, no banner, no retry. On terminal.subscribe it is now
gated on capabilities.outputSpan, and a sender that has not been told the peer can
decode a span downgrades to plain Output rather than sending nothing.
On terminal.multiplex it is deliberately not gated. Two reasons, and both
generalise:
A capability cannot retroactively prove incapability. The gate keys off the peer
declaring outputSpan, a flag no shipped build sends. Opcode 15 predates every
capability a multiplex peer could declare — ackOutput by 9 days, ackOutputSourceRanges
by 10 — so "did not declare it" is indistinguishable between a build from before the
opcode and the entire installed base from after it. Since mixed versions are the normal
state, a gate added after an opcode ships reads the whole fleet as incapable.
A fallback is only a fallback if it is lossless for that peer. A plain Output
frame carries (data, seq) and nothing else, so the receiver can only reconstruct a run
as seq - data.length. A transformed run has rawLength !== data.length by definition.
Downgrading it to Output therefore cannot be made correct for a peer that tracks
seq, and the desktop multiplex client does: it head-blocks the ack queue on a
zero-byte frame, reads a false dropped-frame gap on every transformed emission, and
detaches the stream when a >48 KiB run flips the source-range ledger's mapping mode.
The downgrade works on terminal.subscribe for exactly one reason — mobile ignores
Output seq entirely — and that fact, not the capability flag, is what licenses it.
So: for an opcode carrying user-visible data, "don't send it" is still data loss, and a gate needs a fallback that preserves the payload. But check what the fallback frame can actually express for the peer you are aiming it at before you reach for one, and prefer gating at the point where the new opcode was genuinely new rather than adding a gate to a path where it has already shipped.
Mobile vendors its own opcode table
mobile/ is a separate pnpm workspace, so
mobile/src/transport/terminal-stream-protocol.ts has historically held a hand-copied
enum knowing only 1-6 and 12. Adding an opcode to the shared file did not add it to
mobile, and nothing failed — not typecheck, not lint, not the cross-version harness,
which pairs desktop builds only. The two tables drifted silently by construction.
terminal-subscribe-output-span-capability.test.ts now parses mobile's real source and
forces an explicit per-opcode decision, so a new opcode is neither "mobile decodes it"
nor "gated" until someone says which. Until mobile shares the table outright, treat
every mobile-reachable opcode above 12 as unsupported unless the stream negotiated it.
Reuse an existing opcode with a new optional payload field (Rule 1) whenever that expresses the change; reach for a new opcode only when framing genuinely differs.
Opcode numbers are permanent. See the Ack = 13 and ClaimViewport = 14 comments
in src/shared/terminal-stream-protocol.ts for why a shipped number cannot be
reused even if the feature behind it is removed.
Rule 3 — changing what the host publishes breaks old clients with no wire change
The frame shape can be untouched and the skew still real, because clients react to frame content. PR #12641 is the worked example: the host stopped synthesizing a finished agent status, and clients running older code saw different content in an identical frame.
Treat these as wire changes even though nothing in the codec moves:
- a field the host stops populating (an old client reading it now sees
undefined); - a value whose meaning, units, or nullability changes;
- content the host stops synthesizing, trims, or starts deriving from a new source;
- a frame the host stops sending, or starts sending, on an existing path.
If old clients cannot interpret the new projection correctly, gate it behind a runtime capability the same way Rule 2 gates an opcode.
Enforcement
tests/e2e/cross-version-wire/cross-version-terminal-wire.unit.test.ts runs the real
host RPC methods and the real renderer multiplexer from two builds against each
other — current working tree against the newest release tag, in both skew
directions — over one scripted terminal journey (subscribe, input, hide/reveal
snapshot, drop, reconnect).
Run it with:
pnpm exec vitest run --config config/vitest.config.ts tests/e2e/cross-version-wire/cross-version-terminal-wire.unit.test.ts
It fails when a frame is refused by the receiving build's decoder (Rule 2), when the observed frame sequence changes (Rule 3), or when published snapshot content or negotiated capabilities differ from the contract. Adding an optional field keeps it green (Rule 1); making a client depend on that field turns the new-client/old-host pairing red.
The harness covers the terminal stream only. It does not cover the session-tab sync channel, agent-session publications, file or Git RPCs, mobile/E2EE framing, or the relay transport. A change on those paths still needs its own reasoning against the three rules above.