From 3c5e702af37ef42573482d44c04386e9e63fac0c Mon Sep 17 00:00:00 2001
From: Casey Brooks <casey.brooks@agyn.io>
Date: Fri, 24 Apr 2026 19:56:57 +0000
Subject: [PATCH 1/2] feat(runners): add workload failure fields

---
 proto/agynio/api/runners/v1/runners.proto | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/proto/agynio/api/runners/v1/runners.proto b/proto/agynio/api/runners/v1/runners.proto
index 9f1c8ea..3dce6bf 100644
--- a/proto/agynio/api/runners/v1/runners.proto
+++ b/proto/agynio/api/runners/v1/runners.proto
@@ -162,6 +162,15 @@ enum WorkloadStatus {
   WORKLOAD_STATUS_FAILED = 5;
 }
 
+enum WorkloadFailureReason {
+  WORKLOAD_FAILURE_REASON_UNSPECIFIED = 0;
+  WORKLOAD_FAILURE_REASON_START_FAILED = 1;
+  WORKLOAD_FAILURE_REASON_IMAGE_PULL_FAILED = 2;
+  WORKLOAD_FAILURE_REASON_CONFIG_INVALID = 3;
+  WORKLOAD_FAILURE_REASON_CRASHLOOP = 4;
+  WORKLOAD_FAILURE_REASON_RUNTIME_LOST = 5;
+}
+
 enum ContainerRole {
   CONTAINER_ROLE_UNSPECIFIED = 0;
   CONTAINER_ROLE_MAIN = 1;
@@ -207,6 +216,8 @@ message Workload {
   optional google.protobuf.Timestamp removed_at = 12;
   int32 allocated_cpu_millicores = 13;
   int64 allocated_ram_bytes = 14;
+  optional WorkloadFailureReason failure_reason = 15;
+  optional string failure_message = 16;
 }
 
 message CreateWorkloadRequest {
@@ -233,6 +244,8 @@ message UpdateWorkloadRequest {
   optional string instance_id = 4;
   optional google.protobuf.Timestamp removed_at = 5;
   optional google.protobuf.Timestamp last_metering_sampled_at = 6;
+  optional WorkloadFailureReason failure_reason = 7;
+  optional string failure_message = 8;
 }
 
 message UpdateWorkloadResponse {
@@ -273,9 +286,12 @@ message ListWorkloadsByThreadRequest {
   string thread_id = 1;
   int32 page_size = 2;
   string page_token = 3;
+  optional string agent_id = 4;
+  repeated WorkloadStatus status_in = 5;
 }
 
 message ListWorkloadsByThreadResponse {
+  // Ordered by created_at DESC.
   repeated Workload workloads = 1;
   string next_page_token = 2;
 }

From 2600e49b7bbe870628a66d9bd0e755e79d7acf37 Mon Sep 17 00:00:00 2001
From: Casey Brooks <casey.brooks@agyn.io>
Date: Fri, 24 Apr 2026 20:36:05 +0000
Subject: [PATCH 2/2] docs(runners): clarify failure fields

---
 proto/agynio/api/runners/v1/runners.proto | 14 ++++++++++++--
 1 file changed, 12 insertions(+), 2 deletions(-)

diff --git a/proto/agynio/api/runners/v1/runners.proto b/proto/agynio/api/runners/v1/runners.proto
index 3dce6bf..bacf9e1 100644
--- a/proto/agynio/api/runners/v1/runners.proto
+++ b/proto/agynio/api/runners/v1/runners.proto
@@ -216,7 +216,12 @@ message Workload {
   optional google.protobuf.Timestamp removed_at = 12;
   int32 allocated_cpu_millicores = 13;
   int64 allocated_ram_bytes = 14;
+  // Machine-readable reason for failures when status is WORKLOAD_STATUS_FAILED.
+  // When status is not FAILED, this value may be unset or stale.
   optional WorkloadFailureReason failure_reason = 15;
+  // Human-readable failure detail for failed workloads; not intended for
+  // programmatic parsing. When status is not FAILED, this value may be unset
+  // or stale.
   optional string failure_message = 16;
 }
 
@@ -244,7 +249,9 @@ message UpdateWorkloadRequest {
   optional string instance_id = 4;
   optional google.protobuf.Timestamp removed_at = 5;
   optional google.protobuf.Timestamp last_metering_sampled_at = 6;
+  // Use this RPC to set or update failure details.
   optional WorkloadFailureReason failure_reason = 7;
+  // Human-readable failure detail; not intended for programmatic parsing.
   optional string failure_message = 8;
 }
 
@@ -252,6 +259,8 @@ message UpdateWorkloadResponse {
   Workload workload = 1;
 }
 
+// Updates status and containers only. Use UpdateWorkload to set failure
+// details such as failure_reason and failure_message.
 message UpdateWorkloadStatusRequest {
   string id = 1;
   WorkloadStatus status = 2;
@@ -287,11 +296,12 @@ message ListWorkloadsByThreadRequest {
   int32 page_size = 2;
   string page_token = 3;
   optional string agent_id = 4;
-  repeated WorkloadStatus status_in = 5;
+  // Optional status filter. An empty list returns workloads for all statuses.
+  repeated WorkloadStatus statuses = 5;
 }
 
 message ListWorkloadsByThreadResponse {
-  // Ordered by created_at DESC.
+  // Ordered by created_at DESC, id DESC for stable pagination.
   repeated Workload workloads = 1;
   string next_page_token = 2;
 }