Prompt64 Wire Protocol v2 #

Each frame has a four-byte header: message type, flags, and a little-endian 16-bit payload length. Bridge payloads are limited to 768 bytes; the C64 accepts 92. Text is display-safe ASCII, with bytes 80-FF reserved as literal C64 screen-code tokens (byte & 7F). The bridge uses those tokens for the opt-in PETSCII graphic palette.

Protocol v2 is strict. The first frame must be Hello with PROMPT64/2. HelloOk returns major 2, minor 0, then a 16-bit little-endian capability mask. Capability bit 6 advertises the heartbeat watchdog, and bit 7 advertises durable approval acknowledgements. Any older or malformed greeting receives PROMPT64/2 REQUIRED.

Messages #

Every asynchronous current-turn frame (11, 12, 13, 15, 16, 18, 19, and 1B) begins with a wrapping 16-bit sequence. A frame is newer when the unsigned wrapping distance from the applied sequence is between 1 and 32767. Control, history, dashboard, action, and diff frames are not sequenced. Heartbeat frames are also unsequenced and are never retained for replay.

Leases and replay #

After HelloOk, a new client requests LeaseGet. The bridge permits one attached C64 per 128-bit token and at most eight detached leases. Unexpected disconnects keep provider state, activity, the current turn, attachments, and pending approvals for 120 seconds. Active work continues.

The bridge retains at most 64 KiB of encoded current-turn asynchronous frames. Crossing the limit cancels the provider and emits TurnFailed. A reconnect supplies the token and last applied sequence; after ReconnectState, the bridge sends only newer retained frames and terminates replay with ReconnectDone. Duplicate attachments and expired/released tokens fail. SessionRelease cancels remaining work, closes bridge-owned provider state, invalidates the token, and is used for explicit F5/RUN-STOP navigation. During an active turn, the C64 sends a heartbeat after two seconds without inbound traffic. If no acknowledgement arrives within another two seconds, it enters the same lease reconnect and replay path as a detected socket error. TCP reopen attempts are spaced five seconds apart so the Ultimate network target and Wi-Fi interface have time to recover without a connection storm. An approval decision is complete only after the C64 receives a sequenced ApprovalAck. If the socket fails first, reconnect replay either supplies the retained acknowledgement or proves the decision was not received, in which case the C64 resends it.

Settings, sessions, and history #

The existing control range is:

• 20/21/22: SettingsGet, SettingsSet, SettingsState. Reasoning is 0 Off, 1 Summary, or 2 Detailed. Both visible modes carry only provider-generated reasoning summaries. Value 3 is Developer; it requests Codex's developer reasoning level and carries raw provider reasoning text.
• 23/24: WorkspaceSet/WorkspaceState. Paths must resolve beneath the bridge workspace root.
• 25/26/27: SessionListGet, SessionEntry, SessionListDone.
• 28/29: SessionSelect/SessionState. $FF selects a new provider session.
• 2A/2B: AccessSet/AccessState. Access is 0 Read Only, 1 Ask Me to Approve, or 2 Auto Review.
• 2C/2D: HistoryGet/HistoryDone. HistoryText speaker is 0 user or 1 assistant; flag 1 starts an entry and flag 0 continues it.

Approval kind is 0 command/network or 1 file/filesystem. Decisions are 0 accept once, 1 accept for session, 2 decline, and 3 cancel.

Dashboard data #

Tab bytes are 0 STATUS, 1 ACTIVITY, 2 CHANGES, and 3 ACTIONS. ACTIONS requests fail while a turn is active. Dashboard, cancellation, and approval decisions may be sent during a turn and share one serialized bridge writer queue.

STATUS includes provider, workspace, access, reasoning, turn state, Git branch, and change totals. ACTIVITY lifecycle is 0 started, 1 completed, or 2 failed. CHANGES row indexes remain stable until a new CHANGES snapshot. Diff kind is 0 context, 1 addition, 2 deletion, or 3 metadata.

Git inspection uses direct subprocess arguments (never a shell or external diff), a three-second timeout, a 256 KiB combined-output ceiling, and unified one-context hunks.