fix(orchestration): thread the trigger comment's issue id so a parent-routed iteration's ✅/❌ reply lands (aws-samples#247 UX.19)

Live-caught on ABCA-304 immediately after UX.18 shipped: a comment left
on the PARENT epic was routed to the footer sub-issue and an iteration
spawned (👀 ack + 'routed to sub-issue … pr_number 193'), but the
iteration then FAILED (transient GITHUB_UNREACHABLE) and NO ❌ reply
appeared — the human saw 👀 then silence.

Root cause: replyToIterationComment posted the ✅/❌ reply with
issueId = changedSubIssueId (the sub-issue, ABCA-305), but the trigger
comment lives on the PARENT epic (ABCA-304). Linear's commentCreate
rejects a threaded reply whose parentId belongs to a different issue, so
the reply silently failed. (The cascade-skip on FAILED was correct; the
reply, which runs BEFORE the success gate, was the casualty.)

Fix: thread trigger_comment_issue_id (the issue the human actually
commented on) through channel_metadata —
 - iterateOrchestrationChild adds it (defaults to the sub-issue id; the
 parent-epic path passes snapshot.meta.parent_linear_issue_id).
 - parseTerminalTaskRecord reads it into TerminalTaskEvent.
 - replyToIterationComment uses it as commentCreate's issueId, falling
 back to changedSubIssueId for pre-UX.19 tasks.
Direct sub-issue comments are unaffected (issue id == sub-issue). The
standalone fanout reply path already replies on linear_issue_id = the
comment's own issue, so no change needed there.

Tests: reconciler 'PARENT-routed iteration replies on the PARENT issue
not the sub-issue'; webhook wiring asserts trigger_comment_issue_id =
the parent. 78 green across reconciler+webhook+matcher suites.

Author: isadeks

cdk/src/handlers/linear-webhook-processor.ts

@@ -759,6 +759,9 @@ async function handleParentEpicCommentTrigger(args: {
   await iterateOrchestrationChild({
     orchestrationId, snapshot, child: childRow,
     workspaceId, commentId, replyTargetId, trigger, resolved, registryTableName,
+    // #247 UX.19: the trigger comment lives on the PARENT epic, not the
+    // sub-issue — the reconciler must reply with the parent issue id.
+    triggerCommentIssueId: snapshot.meta.parent_linear_issue_id,
     // Already acked on the parent comment above.
     skipAck: true,
     prNumber,
@@ -783,6 +786,13 @@ async function iterateOrchestrationChild(args: {
   workspaceId: string;
   commentId: string;
   replyTargetId: string;
+  /**
+   * The Linear ISSUE the trigger comment lives on — the sub-issue for a direct
+   * comment, the PARENT epic for a UX.18 parent-routed comment. The reconciler
+   * replies ✅/❌ using THIS as commentCreate's issueId (#247 UX.19). Defaults to
+   * the sub-issue id.
+   */
+  triggerCommentIssueId?: string;
   trigger: CommentTrigger;
   resolved: { oauthSecretArn: string; workspaceSlug: string };
   registryTableName: string;
@@ -794,6 +804,7 @@ async function iterateOrchestrationChild(args: {
     trigger, resolved, registryTableName,
   } = args;
   const subIssueId = child.sub_issue_id;
+  const triggerCommentIssueId = args.triggerCommentIssueId ?? subIssueId;
 
   const prNumber = args.prNumber ?? (child.child_task_id ? await resolveChildPrNumber(child.child_task_id) : null);
   if (prNumber === null || prNumber === undefined) {
@@ -827,6 +838,10 @@ async function iterateOrchestrationChild(args: {
     // #247 UX.3: the reconciler replies ✅/❌ to the thread ROOT when the
     // iteration lands (threaded ack — closes the conversation the human opened).
     trigger_comment_id: replyTargetId,
+    // #247 UX.19: the issue that comment lives on, so the reconciler's reply
+    // uses the right commentCreate issueId (parent epic for a routed comment;
+    // the sub-issue for a direct comment).
+    trigger_comment_issue_id: triggerCommentIssueId,
     linear_workspace_id: workspaceId,
     linear_oauth_secret_arn: resolved.oauthSecretArn,
     linear_workspace_slug: resolved.workspaceSlug,

cdk/src/handlers/orchestration-reconciler.ts

@@ -122,6 +122,15 @@ interface TerminalTaskEvent {
    * comment to reply to).
    */
   readonly triggerCommentId?: string;
+  /**
+   * #247 UX.19: the Linear ISSUE the trigger comment lives on. Usually the
+   * iterated sub-issue, but for a comment left on the PARENT epic (routed to a
+   * sub-issue via UX.18) it's the PARENT issue id. The threaded ✅/❌ reply must
+   * use THIS as commentCreate's issueId — Linear rejects a reply whose parentId
+   * belongs to a different issue. Absent on older tasks → reply falls back to
+   * the sub-issue id (the prior behavior).
+   */
+  readonly triggerCommentIssueId?: string;
 }
 
 /**
@@ -171,6 +180,9 @@ export function parseTerminalTaskRecord(record: DynamoDBRecord): TerminalTaskEve
   const cascadeSubIssueId = isCascadeSource ? cm?.orchestration_sub_issue_id?.S : undefined;
   // #247 UX.3: the human comment that triggered this iteration, if any.
   const triggerCommentId = isIteration ? cm?.trigger_comment_id?.S : undefined;
+  // #247 UX.19: the issue that comment lives on (parent epic for a UX.18
+  // parent-routed comment; the sub-issue for a direct comment).
+  const triggerCommentIssueId = isIteration ? cm?.trigger_comment_issue_id?.S : undefined;
 
   return {
     taskId,
@@ -181,6 +193,7 @@ export function parseTerminalTaskRecord(record: DynamoDBRecord): TerminalTaskEve
     ...(cascadeSubIssueId !== undefined && { cascadeSubIssueId }),
     ...(cascadeSubIssueId !== undefined && { cascadeIsIteration: isIteration }),
     ...(triggerCommentId !== undefined && { triggerCommentId }),
+    ...(triggerCommentIssueId !== undefined && { triggerCommentIssueId }),
   };
 }
 
@@ -662,10 +675,13 @@ async function replyToIterationComment(
       ...(evt.errorMessage !== undefined && { errorMessage: evt.errorMessage }),
       taskId: evt.taskId,
     });
-  // The triggering comment lives on the sub-issue (changedSubIssueId is its
-  // Linear issue id) — Linear requires issueId on commentCreate even for a
-  // threaded reply.
-  await replyToComment(ctx, changedSubIssueId, commentId, body);
+  // The reply's issueId MUST be the issue the trigger comment lives on —
+  // Linear rejects a threaded reply whose parentId belongs to a different
+  // issue. For a comment left on the PARENT epic (UX.18 routing) that's the
+  // parent issue, NOT changedSubIssueId. Fall back to the sub-issue id for
+  // tasks created before UX.19 (no triggerCommentIssueId persisted).
+  const replyIssueId = evt.triggerCommentIssueId ?? changedSubIssueId;
+  await replyToComment(ctx, replyIssueId, commentId, body);
 }
 
 /** Build the ✅ ack reply, linking the (re-pushed) PR when resolvable. */

cdk/test/handlers/linear-webhook-processor-orchestration.test.ts

@@ -538,6 +538,10 @@ describe('linear-webhook-processor — #247 A6 comment trigger', () => {
       expect(ctx.channelMetadata.orchestration_sub_issue_id).toBe('sub-footer');
       expect(ctx.channelMetadata.orchestration_iteration).toBe('true');
       expect(ctx.channelMetadata.linear_issue_id).toBe('sub-footer');
+      // #247 UX.19: the trigger comment lives on the PARENT epic, so the reply
+      // must target the parent issue (not the sub-issue) — else Linear rejects it.
+      expect(ctx.channelMetadata.trigger_comment_issue_id).toBe('PARENT-EPIC');
+      expect(ctx.channelMetadata.trigger_comment_id).toBe('pc-1');
       // No disambiguation reply — we acted.
       expect(replyToCommentMock).not.toHaveBeenCalled();
     });

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

@@ -74,6 +74,8 @@ function taskRecord(fields: {
   orchestration_iteration?: boolean;
   // #247 UX.3: the human comment that triggered an iteration.
   trigger_comment_id?: string;
+  // #247 UX.19: the issue that trigger comment lives on (parent epic when routed).
+  trigger_comment_issue_id?: string;
   // #247 UX.5: raw agent error_message (drives the failure-reply detail).
   error_message?: string;
 }): DynamoDBRecord {
@@ -96,6 +98,7 @@ function taskRecord(fields: {
   }
   if (fields.orchestration_iteration) cm.orchestration_iteration = { S: 'true' };
   if (fields.trigger_comment_id) cm.trigger_comment_id = { S: fields.trigger_comment_id };
+  if (fields.trigger_comment_issue_id) cm.trigger_comment_issue_id = { S: fields.trigger_comment_issue_id };
   if (Object.keys(cm).length > 0) img.channel_metadata = { M: cm };
   return {
     eventName: fields.eventName ?? 'MODIFY',
@@ -694,6 +697,29 @@ describe('orchestration-reconciler handler — A6 iteration ack reply (#247 UX.3
     expect(body).toMatch(/^✅ Updated — PR #\d+\./);
   });
 
+  test('#247 UX.19: a PARENT-routed iteration replies on the PARENT issue, not the sub-issue', async () => {
+    // The human commented on the parent epic (UX.18 routed it to sub-issue A).
+    // The ✅/❌ reply must use the PARENT issue id as commentCreate's issueId —
+    // else Linear rejects the reply (parentId belongs to a different issue) and
+    // the human sees 👀 then silence (live-caught on ABCA-304).
+    mockCascade([
+      { sub_issue_id: 'A', child_status: 'succeeded', child_task_id: 'task-A', child_branch_name: 'branch-A', linear_identifier: 'ENG-1' },
+    ]);
+    await handler({
+      Records: [taskRecord({
+        task_id: 'iter-task-1', status: 'COMPLETED', orchestration_id: 'orch_1',
+        orchestration_sub_issue_id: 'A', orchestration_iteration: true,
+        trigger_comment_id: 'parent-cmt-1',
+        trigger_comment_issue_id: 'PARENT', // comment lives on the parent epic
+      })],
+    } as never);
+
+    expect(replyToCommentMock).toHaveBeenCalledTimes(1);
+    const [, issueId, parentCommentId] = replyToCommentMock.mock.calls[0];
+    expect(issueId).toBe('PARENT'); // NOT 'A' — the reply targets the parent comment's issue
+    expect(parentCommentId).toBe('parent-cmt-1');
+  });
+
   test('FAILED iteration (agent crash) → ❌ reply with classified reason + CloudWatch task id (UX.5)', async () => {
     mockCascade([
       { sub_issue_id: 'A', child_status: 'succeeded', child_task_id: 'task-A', child_branch_name: 'branch-A', linear_identifier: 'ENG-1' },