feat(orchestration): platform settles the comment + sub-issue on iteration done — 👀→✅/❌ + In Review (aws-samples#247 UX.21)

User-caught, three symptoms one cause: after a comment-iteration finishes,
(1) the trigger comment stayed on 👀 forever (never ✅), (2) the sub-issue
state flapped In Progress/In Review, and (3) the panel showed ✅ (correct,
reads child_status) while the sub-issue said In Progress — three views
disagreeing. Root cause: the reconciler posted the threaded ✅/❌ reply but
never settled the comment REACTION or the sub-issue STATE; state was
delegated to the AGENT via a prompt instruction (non-deterministic, raced,
got stuck).

Fix: the platform now owns settlement (as it already does for the parent
epic's reaction/state). In replyToIterationComment, after the reply:
 - swap the TRIGGER comment 👀 → ✅ (success) / ❌ (failure) so the comment
 reads done at a glance, not just the threaded reply.
 - on success, advance the SUB-ISSUE to In Review (PR updated & open,
 awaiting human merge — same convention the epic uses; user's choice).
 On failure, leave the state (never demote). The reaction/state target
 the actual trigger comment + the iterated sub-issue, so a parent-routed
 comment settles the parent's comment + the footer sub-issue correctly.
Gated once-only by the existing ack_replied_at claim; both helpers are
idempotent (re-converge to one marker / skip if already in target state).

New helper swapCommentReaction (mirrors swapIssueReaction but on a COMMENT
— queries comment(id){reactions}, deletes stale bgagent markers, adds the
target; never touches a human reaction). Tests: helper (swap/idempotent/
human-safe/no-token) + reconciler success→✅+In Review, failure→❌+no
transition. 80 green across linear-feedback + reconciler suites.

Author: isadeks

cdk/src/handlers/orchestration-reconciler.ts

@@ -47,7 +47,7 @@ import {
 import type { DynamoDBRecord, DynamoDBStreamEvent } from 'aws-lambda';
 import { createTaskCore } from './shared/create-task-core';
 import { renderFailureReply } from './shared/failure-reply';
-import { postIssueComment, replyToComment } from './shared/linear-feedback';
+import { EMOJI_FAILURE, EMOJI_SUCCESS, postIssueComment, replyToComment, swapCommentReaction, transitionIssueState } from './shared/linear-feedback';
 import { logger } from './shared/logger';
 import { isIntegrationNode } from './shared/orchestration-integration-node';
 import { ORCH_LOG } from './shared/orchestration-log-events';
@@ -682,6 +682,21 @@ async function replyToIterationComment(
   // tasks created before UX.19 (no triggerCommentIssueId persisted).
   const replyIssueId = evt.triggerCommentIssueId ?? changedSubIssueId;
   await replyToComment(ctx, replyIssueId, commentId, body);
+
+  // #247 UX.21: settle the comment + sub-issue so all three views agree (panel
+  // row, sub-issue state, comment reaction) — the platform owns this, not the
+  // agent (whose prompt-driven state-setting flapped In Progress/In Review).
+  //   - swap the TRIGGER comment's 👀 → ✅ (success) / ❌ (failure), so the
+  //     comment itself reads done at a glance, not just the threaded reply.
+  //   - on success, advance the SUB-ISSUE to In Review (its PR is updated &
+  //     open, awaiting human merge — same convention the epic uses). On
+  //     failure, leave the state (the ❌ + reply convey it). Never demote.
+  // Best-effort + idempotent (the ack_replied_at claim above already gates this
+  // to once per iteration; swapCommentReaction/transition re-converge anyway).
+  await swapCommentReaction(ctx, commentId, succeeded ? EMOJI_SUCCESS : EMOJI_FAILURE);
+  if (succeeded) {
+    await transitionIssueState(ctx, changedSubIssueId, 'started', ['In Review']);
+  }
 }
 
 /** Build the ✅ ack reply, linking the (re-pushed) PR when resolvable. */

cdk/src/handlers/shared/linear-feedback.ts

@@ -126,6 +126,13 @@ query IssueReactions($issueId: String!) {
 }
 `.trim();
 
+/** Read a COMMENT's reactions (id + emoji) — to swap the comment's bgagent marker (#247 UX.21). */
+const COMMENT_REACTIONS_QUERY = `
+query CommentReactions($commentId: String!) {
+  comment(id: $commentId) { reactions { id emoji } }
+}
+`.trim();
+
 /**
  * The bgagent status-marker emojis we manage on the PARENT epic. Mirrors
  * ``_BGAGENT_EMOJIS`` in ``agent/src/linear_reactions.py``. Only these are
@@ -434,6 +441,41 @@ export async function swapIssueReaction(
   return (await graphqlRequest(token, REACTION_CREATE_MUTATION, { issueId, emoji })).ok;
 }
 
+/**
+ * Swap the bgagent status marker on a COMMENT (👀 → ✅/❌), so the trigger
+ * comment shows ONE marker reflecting the outcome — mirrors
+ * {@link swapIssueReaction} but on a comment (#247 UX.21). The 👀 lands at
+ * receipt ({@link reactToComment}); when the iteration settles we swap it for
+ * ✅ (success) / ❌ (failure) so the comment itself reads done at a glance, not
+ * just the threaded reply. Queries the comment's reactions, deletes every
+ * bgagent marker except the target, adds the target if absent. Only bgagent
+ * emojis (👀/✅/❌) are removed — a human's reaction is never touched.
+ * Idempotent (a reconciler redelivery re-converges to the same single marker).
+ * Best-effort; returns true if the target marker is present afterwards.
+ */
+export async function swapCommentReaction(
+  ctx: LinearFeedbackContext,
+  commentId: string,
+  emoji: string,
+): Promise<boolean> {
+  const token = await resolveToken(ctx);
+  if (!token) return false;
+
+  const data = await graphqlData(token, COMMENT_REACTIONS_QUERY, { commentId });
+  const reactions = ((data?.comment as { reactions?: Array<{ id: string; emoji: string }> } | undefined)?.reactions) ?? [];
+
+  let targetPresent = false;
+  for (const r of reactions) {
+    if (r.emoji === emoji) { targetPresent = true; continue; }
+    if (BGAGENT_EMOJIS.has(r.emoji)) {
+      await graphqlRequest(token, REACTION_DELETE_MUTATION, { id: r.id });
+    }
+  }
+
+  if (targetPresent) return true;
+  return (await graphqlRequest(token, REACTION_CREATE_ON_COMMENT_MUTATION, { commentId, emoji })).ok;
+}
+
 /**
  * Convenience: post a feedback comment **and** drop a ❌ reaction in one call.
  * Both calls run in parallel; both are best-effort. Returns void — callers

cdk/test/handlers/orchestration-reconciler.test.ts

@@ -37,12 +37,14 @@ jest.mock('../../src/handlers/shared/create-task-core', () => ({
 const postIssueCommentMock = jest.fn();
 const upsertStatusCommentMock = jest.fn();
 const swapIssueReactionMock = jest.fn();
+const swapCommentReactionMock = jest.fn();
 const transitionIssueStateMock = jest.fn();
 const replyToCommentMock = jest.fn();
 jest.mock('../../src/handlers/shared/linear-feedback', () => ({
   postIssueComment: (...args: unknown[]) => postIssueCommentMock(...args),
   upsertStatusComment: (...args: unknown[]) => upsertStatusCommentMock(...args),
   swapIssueReaction: (...args: unknown[]) => swapIssueReactionMock(...args),
+  swapCommentReaction: (...args: unknown[]) => swapCommentReactionMock(...args),
   transitionIssueState: (...args: unknown[]) => transitionIssueStateMock(...args),
   replyToComment: (...args: unknown[]) => replyToCommentMock(...args),
   EMOJI_SUCCESS: 'white_check_mark',
@@ -665,6 +667,7 @@ describe('orchestration-reconciler handler — A6 iteration ack reply (#247 UX.3
     postIssueCommentMock.mockReset().mockResolvedValue(true);
     upsertStatusCommentMock.mockReset().mockResolvedValue('panel-cmt-1');
     swapIssueReactionMock.mockReset().mockResolvedValue(true);
+    swapCommentReactionMock.mockReset().mockResolvedValue(true);
     transitionIssueStateMock.mockReset().mockResolvedValue(true);
     replyToCommentMock.mockReset().mockResolvedValue('reply-1');
   });
@@ -695,6 +698,10 @@ describe('orchestration-reconciler handler — A6 iteration ack reply (#247 UX.3
     expect(issueId).toBe('A'); // the sub-issue the comment lives on
     expect(parentCommentId).toBe('human-cmt-1');
     expect(body).toMatch(/^✅ Updated — PR #\d+\./);
+    // #247 UX.21: the trigger comment's 👀 swaps to ✅, and the sub-issue
+    // advances to In Review (platform-owned settle, not agent-flapped).
+    expect(swapCommentReactionMock).toHaveBeenCalledWith(expect.anything(), 'human-cmt-1', 'white_check_mark');
+    expect(transitionIssueStateMock).toHaveBeenCalledWith(expect.anything(), 'A', 'started', ['In Review']);
   });
 
   test('#247 UX.19: a PARENT-routed iteration replies on the PARENT issue, not the sub-issue', async () => {
@@ -734,6 +741,10 @@ describe('orchestration-reconciler handler — A6 iteration ack reply (#247 UX.3
     expect(body).toMatch(/reply with guidance/i);
     // A failed iteration still does not cascade onto dependents.
     expect(createTaskCoreMock).not.toHaveBeenCalled();
+    // #247 UX.21: the trigger comment's 👀 swaps to ❌, but the sub-issue state
+    // is LEFT in place on failure (the ❌ + reply convey it; never demote).
+    expect(swapCommentReactionMock).toHaveBeenCalledWith(expect.anything(), 'human-cmt-1', 'x');
+    expect(transitionIssueStateMock).not.toHaveBeenCalled();
   });
 
   test('COMPLETED-but-build-failed iteration → ❌ build/test reply pointing at PR checks (UX.5)', async () => {

cdk/test/handlers/shared/linear-feedback.test.ts

@@ -33,6 +33,7 @@ import {
   reactToComment,
   replyToComment,
   reportIssueFailure,
+  swapCommentReaction,
   swapIssueReaction,
   transitionIssueState,
   upsertStatusComment,
@@ -339,6 +340,60 @@ describe('linear-feedback', () => {
     });
   });
 
+  describe('swapCommentReaction (#247 UX.21 — settle the trigger comment 👀→✅/❌)', () => {
+    const commentReactionsResp = (rs: Array<{ id: string; emoji: string }>) =>
+      jsonResponse({ data: { comment: { reactions: rs } } });
+
+    test('👀 on the comment → deletes it and adds ✅ (on the COMMENT, not the issue)', async () => {
+      fetchMock
+        .mockResolvedValueOnce(commentReactionsResp([{ id: 'r-eyes', emoji: 'eyes' }]))
+        .mockResolvedValueOnce(jsonResponse({ data: { reactionDelete: { success: true } } }))
+        .mockResolvedValueOnce(jsonResponse({ data: { reactionCreate: { success: true } } }));
+      const ok = await swapCommentReaction(CTX, 'comment-77', 'white_check_mark');
+      expect(ok).toBe(true);
+      // query targets the COMMENT
+      expect(JSON.parse(fetchMock.mock.calls[0][1].body).variables).toEqual({ commentId: 'comment-77' });
+      // delete the stale 👀
+      expect(JSON.parse(fetchMock.mock.calls[1][1].body).variables).toEqual({ id: 'r-eyes' });
+      // create the ✅ via reactionCreate(commentId)
+      const createVars = JSON.parse(fetchMock.mock.calls[2][1].body).variables;
+      expect(createVars).toEqual({ commentId: 'comment-77', emoji: 'white_check_mark' });
+    });
+
+    test('target already present → no re-create (idempotent under redelivery)', async () => {
+      fetchMock
+        .mockResolvedValueOnce(commentReactionsResp([
+          { id: 'r-eyes', emoji: 'eyes' },
+          { id: 'r-check', emoji: 'white_check_mark' },
+        ]))
+        .mockResolvedValueOnce(jsonResponse({ data: { reactionDelete: { success: true } } }));
+      const ok = await swapCommentReaction(CTX, 'comment-77', 'white_check_mark');
+      expect(ok).toBe(true);
+      expect(fetchMock).toHaveBeenCalledTimes(2); // query + delete 👀; ✅ already present
+    });
+
+    test('never deletes a human reaction on the comment', async () => {
+      fetchMock
+        .mockResolvedValueOnce(commentReactionsResp([
+          { id: 'r-eyes', emoji: 'eyes' },
+          { id: 'r-heart', emoji: 'heart' }, // human — must survive
+        ]))
+        .mockResolvedValueOnce(jsonResponse({ data: { reactionDelete: { success: true } } }))
+        .mockResolvedValueOnce(jsonResponse({ data: { reactionCreate: { success: true } } }));
+      await swapCommentReaction(CTX, 'comment-77', 'x');
+      const deletedIds = fetchMock.mock.calls
+        .filter((c) => JSON.parse(c[1].body).query.includes('reactionDelete'))
+        .map((c) => JSON.parse(c[1].body).variables.id);
+      expect(deletedIds).toEqual(['r-eyes']); // never r-heart
+    });
+
+    test('no token → false, no fetch', async () => {
+      resolveLinearOauthTokenMock.mockResolvedValueOnce(null);
+      expect(await swapCommentReaction(CTX, 'comment-77', 'eyes')).toBe(false);
+      expect(fetchMock).not.toHaveBeenCalled();
+    });
+  });
+
   describe('upsertStatusComment (#3 live status block)', () => {
     test('no existing id → creates a comment and returns the new id', async () => {
       fetchMock.mockResolvedValueOnce(