fix(orchestration): bot must not trigger on its OWN comments — kill the self-reply loop (aws-samples#247 UX.20 root cause)

The 50-reply spam was NOT webhook redelivery (my first UX.20 theory) — it
was a genuine INFINITE SELF-TRIGGER LOOP: the parent-epic disambiguation
reply embeds a literal example '@bgagent ABCA-123: <what to change>'. That
reply is itself a Linear comment → fires a Comment webhook →
parseCommentTrigger's /@bgagent/ regex matched the mention INSIDE the
bot's own reply → posted another disambiguation reply (also containing
@bgagent) → … ~50 deep. Each iteration was a NEW comment with a NEW id, so
the per-comment ack-claim (UX.20 round 1) couldn't dedup it — it guarded
redelivery, not self-reference.

Root fix (the guard the Linear path never had — Slack already skips its
own bot_id messages to avoid exactly this): parseCommentTrigger now
returns NOT-triggered for any comment whose trimmed body starts with one
of the bot's own template markers (👋 ✅ ❌ ⚠️ 🔄 🤖 🖼️ 🔗) — exported
isBotAuthoredComment. The bot can never act on a comment it authored,
regardless of what example text the body contains. The pre-existing A6
trigger never looped only because the agent's progress comments happen
not to contain @bgagent; UX.18's reply was the first bot comment that did.

The UX.20-round-1 ack-claim (claimCommentAck) stays — it's still correct
defense against genuine webhook redelivery; this is the orthogonal,
primary fix for self-reference.

Tests: the EXACT spam body (👋 + embedded @bgagent example) → not
triggered; every template prefix → bot-authored; a real human @bgagent →
still triggers; leading-whitespace marker still caught. 41 green across
trigger+webhook suites.

Author: isadeks

cdk/src/handlers/shared/orchestration-comment-trigger.ts

@@ -59,6 +59,17 @@ export interface CommentTrigger {
  */
 export function parseCommentTrigger(body: string | undefined | null): CommentTrigger {
   if (!body) return { triggered: false, instruction: '' };
+  // SELF-COMMENT GUARD (#247 UX.20 — live-caught infinite loop): the bot's OWN
+  // rendered comments must NEVER trigger it, or it talks to itself forever.
+  // This bit me when the disambiguation reply embedded a literal "@bgagent
+  // ABCA-123: …" example — the reply re-matched the mention and spawned another
+  // reply, ~50 deep. The agent's progress comments are also bot-authored.
+  // Cheapest robust signal that needs no actor-identity config: a body that
+  // STARTS WITH one of our own template markers is ours, not a user
+  // instruction. (Linear strips a leading emoji to its own line sometimes, so
+  // we test the trimmed start.) Keep this list in sync with the rendered
+  // comment prefixes (panel, acks, disambiguation, agent progress).
+  if (isBotAuthoredComment(body)) return { triggered: false, instruction: '' };
   // Token-boundary match: @bgagent not immediately followed by a word char or
   // a '.' (so it won't fire on @bgagentbot or an @bgagent.io address).
   const re = /@bgagent(?![\w.])/gi;
@@ -67,6 +78,28 @@ export function parseCommentTrigger(body: string | undefined | null): CommentTri
   return { triggered: true, instruction };
 }
 
+/**
+ * Markers that begin a comment the BOT itself rendered (panel, acks,
+ * disambiguation reply, agent progress). A comment starting with any of these
+ * is never a human instruction — used to break self-trigger loops (#247 UX.20).
+ */
+const BOT_COMMENT_PREFIXES = [
+  '👋', // disambiguation "which sub-issue?" reply
+  '✅', // "✅ Updated — PR #…" ack / "✅ **ABCA orchestration complete**" panel
+  '❌', // failure reply
+  '⚠️', // "finished with failures" panel
+  '🔄', // in-progress panel
+  '🤖', // agent progress ("🤖 Starting…")
+  '🖼️', // preview screenshot comment
+  '🔗', // "PR opened" / combined-PR
+] as const;
+
+/** True when ``body`` is one of the bot's own rendered comments (loop guard). */
+export function isBotAuthoredComment(body: string): boolean {
+  const trimmed = body.trimStart();
+  return BOT_COMMENT_PREFIXES.some((p) => trimmed.startsWith(p));
+}
+
 /**
  * Build the task description handed to ``coding/pr-iteration-v1`` from the
  * comment instruction. When the reviewer left explicit text, that IS the

cdk/test/handlers/shared/orchestration-comment-trigger.test.ts

@@ -19,6 +19,7 @@
 
 import {
   buildIterationInstruction,
+  isBotAuthoredComment,
   parseCommentTrigger,
 } from '../../../src/handlers/shared/orchestration-comment-trigger';
 
@@ -70,6 +71,45 @@ describe('parseCommentTrigger', () => {
     expect(t.triggered).toBe(true);
     expect(t.instruction).toBe('do X and also Y');
   });
+
+  // #247 UX.20 — the self-trigger infinite loop. The bot's OWN comments must
+  // never re-trigger it, even when (esp. when) they contain a literal @bgagent.
+  describe('self-comment guard (#247 UX.20 loop prevention)', () => {
+    test('the disambiguation reply does NOT trigger, even though it embeds "@bgagent ABCA-123:"', () => {
+      // This EXACT body spammed ~50 replies live: it starts with 👋 and contains
+      // a literal @bgagent example, which the old regex re-matched → loop.
+      const body = '👋 I couldn\'t tell which sub-issue that\'s about.\n\nOtherwise, comment on the '
+        + 'specific sub-issue, or name it here — e.g. `@bgagent ABCA-123: <what to change>`. The sub-issues are:';
+      expect(parseCommentTrigger(body).triggered).toBe(false);
+      expect(isBotAuthoredComment(body)).toBe(true);
+    });
+
+    test('all bot template prefixes are recognized as bot-authored (never trigger)', () => {
+      for (const body of [
+        '👋 That could apply to more than one sub-issue…',
+        '✅ Updated — PR #193.',
+        '✅ **ABCA orchestration complete**',
+        '❌ I made the change, but the build/tests didn\'t pass.',
+        '⚠️ **ABCA orchestration finished with failures**',
+        '🔄 **ABCA orchestration** · 1/3 complete',
+        '🤖 Starting on this issue…',
+        '🖼️ **Preview screenshot**',
+        '🔗 PR opened: https://github.com/o/r/pull/9',
+      ]) {
+        expect(isBotAuthoredComment(body)).toBe(true);
+        expect(parseCommentTrigger(body).triggered).toBe(false);
+      }
+    });
+
+    test('a genuine human @bgagent comment is NOT misclassified as bot-authored', () => {
+      expect(isBotAuthoredComment('@bgagent for the footer change the tagline')).toBe(false);
+      expect(parseCommentTrigger('@bgagent for the footer change the tagline').triggered).toBe(true);
+    });
+
+    test('leading whitespace before a bot marker is still caught', () => {
+      expect(isBotAuthoredComment('  \n✅ Updated — PR #193.')).toBe(true);
+    });
+  });
 });
 
 describe('buildIterationInstruction', () => {