From 7d475f85bfdecb268ca007b0896b3852d00da9d8 Mon Sep 17 00:00:00 2001
From: Dotta <bippadotta@protonmail.com>
Date: Tue, 28 Apr 2026 15:58:54 -0500
Subject: [PATCH] Add recovery_needed and next-action surface to
 IssueBlockerAttention

Phase 5 of the liveness plan needs the blocker read model to distinguish
a "productive run stopped without continuation" leaf from generic
attention or stalled-review chains. Extend the shared type so server and
UI share one vocabulary for the new surface (state, reasons, owner,
hint).

Co-Authored-By: Paperclip <noreply@paperclip.ing>
---
 packages/shared/src/index.ts       |  3 +++
 packages/shared/src/types/index.ts |  3 +++
 packages/shared/src/types/issue.ts | 28 +++++++++++++++++++++++++++-
 3 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index 72d8ca73ab4..bbfeb23de3e 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -333,6 +333,9 @@ export type {
   IssueBlockerAttention,
   IssueBlockerAttentionReason,
   IssueBlockerAttentionState,
+  IssueBlockerNextActionHint,
+  IssueBlockerNextActionOwner,
+  IssueBlockerNextActionOwnerType,
   IssueProductivityReview,
   IssueProductivityReviewTrigger,
   IssueReferenceSource,
diff --git a/packages/shared/src/types/index.ts b/packages/shared/src/types/index.ts
index a574f8541e8..d0265d31d12 100644
--- a/packages/shared/src/types/index.ts
+++ b/packages/shared/src/types/index.ts
@@ -136,6 +136,9 @@ export type {
   IssueBlockerAttention,
   IssueBlockerAttentionReason,
   IssueBlockerAttentionState,
+  IssueBlockerNextActionHint,
+  IssueBlockerNextActionOwner,
+  IssueBlockerNextActionOwnerType,
   IssueProductivityReview,
   IssueProductivityReviewTrigger,
   IssueReferenceSource,
diff --git a/packages/shared/src/types/issue.ts b/packages/shared/src/types/issue.ts
index 8ee1821d6f7..1199ab098b4 100644
--- a/packages/shared/src/types/issue.ts
+++ b/packages/shared/src/types/issue.ts
@@ -119,13 +119,37 @@ export interface IssueRelationIssueSummary {
   terminalBlockers?: IssueRelationIssueSummary[];
 }
 
-export type IssueBlockerAttentionState = "none" | "covered" | "stalled" | "needs_attention";
+export type IssueBlockerAttentionState =
+  | "none"
+  | "covered"
+  | "stalled"
+  | "needs_attention"
+  | "recovery_needed";
 
 export type IssueBlockerAttentionReason =
   | "active_child"
   | "active_dependency"
   | "stalled_review"
   | "attention_required"
+  | "explicit_waiting"
+  | "productive_run_stopped"
+  | "continuation_exhausted"
+  | "continuation_suppressed"
+  | null;
+
+export type IssueBlockerNextActionOwnerType = "agent" | "user" | "none";
+
+export interface IssueBlockerNextActionOwner {
+  type: IssueBlockerNextActionOwnerType;
+  agentId?: string | null;
+  userId?: string | null;
+}
+
+export type IssueBlockerNextActionHint =
+  | "wake_to_continue"
+  | "needs_human_review"
+  | "create_recovery_issue"
+  | "reassign"
   | null;
 
 export interface IssueBlockerAttention {
@@ -137,6 +161,8 @@ export interface IssueBlockerAttention {
   attentionBlockerCount: number;
   sampleBlockerIdentifier: string | null;
   sampleStalledBlockerIdentifier: string | null;
+  nextActionOwner: IssueBlockerNextActionOwner | null;
+  nextActionHint: IssueBlockerNextActionHint;
 }
 
 export type IssueProductivityReviewTrigger =