docs: finalize rvbox v1 design and implementation plan

protos/rvbox/v1/agent.proto

@@ -2,35 +2,34 @@ syntax = "proto3";
 
 package rvbox.v1;
 
-option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";
-
 import "google/protobuf/timestamp.proto";
 import "rvbox/v1/common.proto";
 
+option go_package = "github.com/rvbox/rvbox/gen/go/rvbox/v1;rvboxv1";
+
 // One AgentEnvelope is carried in one binary WebSocket message.
 message AgentEnvelope {
   // Empty only for ClientHello. All other envelopes are fenced to a session.
   string session_id = 1;
   uint64 session_generation = 2;
-  string message_id = 3;
 
   oneof payload {
-    ClientHello client_hello = 10;
-    ServerWelcome server_welcome = 11;
-    CommandDispatch command_dispatch = 12;
-    CommandAccepted command_accepted = 13;
-    CommandEvent command_event = 14;
-    EventAck event_ack = 15;
-    StdinWrite stdin_write = 16;
-    CloseStdin close_stdin = 17;
-    SignalCommand signal_command = 18;
-    ScriptChunk script_chunk = 19;
-    ScriptCommit script_commit = 20;
-    ClientCapacity client_capacity = 21;
-    ReconcileRequest reconcile_request = 22;
-    ReconcileSnapshot reconcile_snapshot = 23;
-    AgentError error = 24;
-    ClientOutputTruncated client_output_truncated = 25;
+    ClientHello client_hello = 3;
+    ServerWelcome server_welcome = 4;
+    CommandDispatch command_dispatch = 5;
+    CommandAccepted command_accepted = 6;
+    CommandEvent command_event = 7;
+    EventAck event_ack = 8;
+    StdinWrite stdin_write = 9;
+    CloseStdin close_stdin = 10;
+    SignalCommand signal_command = 11;
+    ScriptChunk script_chunk = 12;
+    ScriptCommit script_commit = 13;
+    ClientCapacity client_capacity = 14;
+    ReconcileRequest reconcile_request = 15;
+    ReconcileSnapshot reconcile_snapshot = 16;
+    AgentError error = 17;
+    ReconcileResult reconcile_result = 18;
   }
 }
 
@@ -43,7 +42,8 @@ message ClientHello {
   string architecture = 5;
   string daemon_cwd = 6;
   repeated ShellType supported_shells = 7;
-  string reconnect_uuid = 8;
+  // Generated once and persisted in the client state directory.
+  string client_instance_id = 8;
   uint32 max_running_commands = 9;
   uint32 max_queued_commands = 10;
   google.protobuf.Timestamp sent_at = 11;
@@ -61,6 +61,7 @@ message CommandDispatch {
   uint64 target_session_generation = 3;
   google.protobuf.Timestamp issue_time = 4;
   ExecutionSpec spec = 5;
+  google.protobuf.Timestamp queue_expiry_time = 6;
 }
 
 message CommandAccepted {
@@ -122,23 +123,30 @@ message ReconcileTarget {
   string issue_uuid = 1;
   uint64 last_server_event_seq = 2;
   uint64 command_revision = 3;
+  bytes immutable_request_sha256 = 4;
 }
 
-// Sent only for requests in ReconcileRequest; server-confirmed terminal history
-// is intentionally not requested.
 message ReconcileSnapshot {
-  string issue_uuid = 1;
-  bool known_to_client = 2;
-  CommandLifecycle lifecycle = 3;
-  uint64 last_client_event_seq = 4;
-  uint64 command_revision = 5;
+  // The complete set still retained by the client, including non-terminal and
+  // terminal-but-unacknowledged commands.
+  repeated ReconcileCommandState retained_commands = 1;
 }
 
-// Sent before retained replay data when an offline client had to rotate
-// unacknowledged output to remain within its hard spool limits.
-message ClientOutputTruncated {
+message ReconcileCommandState {
   string issue_uuid = 1;
-  OutputTruncation truncation = 2;
+  CommandLifecycle lifecycle = 2;
+  uint64 last_client_event_seq = 3;
+  uint64 command_revision = 4;
+  // True only for a matching UUID/request hash in the compact tombstone ledger.
+  bool tombstoned = 5;
+  bytes immutable_request_sha256 = 6;
+}
+
+// Sent after the server durably compares a complete snapshot and before it
+// dispatches new work on the session. Repetition is idempotent.
+message ReconcileResult {
+  repeated string terminate_local_issue_uuids = 1;
+  repeated string discard_local_terminal_issue_uuids = 2;
 }
 
 message AgentError {