feat(linear): re-home first-run courtesy comments to the Lambda tier (ADR-016 P4.5)

isadeks · isadeks · commit 743e30e2b2de · 2026-07-22T15:05:26.000+01:00
With the Linear MCP removed, the agent no longer posts its own 'Starting' and 'PR opened' comments. Re-home both to the platform so first-run Linear tasks keep their headline signal: - webhook processor: post '🤖 Starting on this issue…' at task-admission (single-task first-run path only — orchestration/decompose/iteration returned earlier; their panel/reply already narrate start). Best-effort, never gates the run. Lands before the container even cold-starts. - fanout dispatcher: add pr_created to the Linear channel filter and post a '🔗 Opened PR #N: <url>' comment on the pr_created milestone for first-run tasks (iterations still mature their threaded reply). Post-once via a new linear_pr_comment_event_id marker. The terminal ✅/⚠️/❌ comment already carries the authoritative PR link (ABCA-584), so this is early feedback, not the source of truth. Both comments use the 🤖/🔗 bot-prefixes already in the self-trigger guard, so they never re-trigger ABCA. Reactions + state transitions remain agent-side deterministic (linear_reactions.py). Tests updated: Linear now subscribes to pr_created; new dispatcher tests for the PR-opened comment (post, no-url skip, post-once, iteration-matures-reply).
diff --git a/cdk/src/handlers/fanout-task-events.ts b/cdk/src/handlers/fanout-task-events.ts
@@ -167,20 +167,23 @@ export const CHANNEL_DEFAULTS: Record<NotificationChannel, ReadonlySet<string>>
     ...TERMINAL_EVENT_TYPES,
     'pr_created',
   ]),
-  // Linear posts a single deterministic final-status comment on
-  // terminal events. The agent's three-comment prompt contract (start /
-  // PR-opened / completion) covers in-flight progress; this dispatcher
-  // only fires once the task reaches a terminal state, with cost /
-  // turns / duration / pr_url metrics the requester wouldn't otherwise
-  // see. Crucially, this fires even when the agent crashes (e.g.
-  // error_max_turns, OOM) before reaching its own step-3 completion
-  // comment — the GH issue #239 motivating example.
+  // Linear posts deterministic status comments on the platform tier
+  // (ADR-016: Linear is fully deterministic — the agent has no Linear MCP
+  // and posts nothing itself). Two events:
+  //   * ``pr_created`` — the first-run "🔗 PR opened" courtesy comment (or,
+  //     for a comment-iteration, matures the threaded reply to "🔄 Working").
+  //     This replaces the agent's old step-2 MCP save_comment.
+  //   * terminal — the final ✅/⚠️/❌ status with cost / turns / duration /
+  //     pr_url metrics. Fires even when the agent crashes (error_max_turns,
+  //     OOM) before any PR — the GH issue #239 motivating example.
   //
-  // Linear's `save_comment` doesn't support edit, so this is post-once
-  // (no live updates a la GitHub edit-in-place). Approvals / milestones
-  // are excluded for the same reason — N comments rather than 1.
+  // Linear's `save_comment` doesn't support edit, so each is post-once (no
+  // live updates a la GitHub edit-in-place), idempotent across partial-batch
+  // retries via per-event markers. The start "🤖 Starting" comment is posted
+  // even earlier, at task-admission in the webhook processor (ADR-016 P4.5).
   linear: new Set<string>([
     ...TERMINAL_EVENT_TYPES,
+    'pr_created',
   ]),
   // Jira posts a single deterministic final-status comment on terminal
   // events — the Jira analogue of the Linear default above (issue #573).
@@ -639,6 +642,24 @@ async function saveLinearCommentState(taskId: string, eventId: string): Promise<
   });
 }
 
+/**
+ * Persist the post-once marker after a successful first-run Linear "PR opened"
+ * courtesy comment (ADR-016 P4.5). The pr_created analogue of
+ * ``saveLinearCommentState`` — a distinct attribute so the PR-opened and
+ * terminal comments are independently idempotent.
+ */
+async function saveLinearPrCommentState(taskId: string, eventId: string): Promise<void> {
+  await saveDispatchMarker({
+    taskId,
+    updateExpression: 'SET linear_pr_comment_event_id = :eid',
+    conditionExpression: 'attribute_exists(task_id) AND attribute_not_exists(linear_pr_comment_event_id)',
+    values: { ':eid': eventId },
+    channel: 'linear',
+    errorId: 'FANOUT_LINEAR_PR_PERSIST_FAILED',
+    logContext: { event_id: eventId },
+  });
+}
+
 /**
  * Persist the post-once marker after a successful Jira final-status comment
  * (see ``dispatchToJira``). The Jira analogue of ``saveLinearCommentState`` —
@@ -925,6 +946,16 @@ async function dispatchToEmail(event: FanOutEvent): Promise<void> {
   });
 }
 
+/**
+ * Render the first-run "PR opened" courtesy comment (ADR-016 P4.5). Kept short
+ * — the 🔗 prefix is in the self-trigger guard's bot-comment markers so it never
+ * re-triggers ABCA, and the terminal comment carries the authoritative outcome.
+ */
+export function renderLinearPrOpenedComment(prUrl: string, prNumber: number | null): string {
+  const ref = prNumber != null ? `PR #${prNumber}` : 'a pull request';
+  return `🔗 Opened ${ref}: ${prUrl}`;
+}
+
 /**
  * Render the Linear final-status comment body. Inputs are already
  * coerced to native types by the caller; this function only formats.
@@ -1128,9 +1159,13 @@ async function dispatchToLinear(event: FanOutEvent): Promise<void> {
   const triggerCommentId = task.channel_metadata?.trigger_comment_id;
   const isIteration = Boolean(triggerCommentId);
 
-  // pr_created milestone on an iteration → mature the reply to "🔄 Working".
-  // (Non-iteration tasks ignore pr_created here — the agent's own headline
-  // "🤖 PR opened" comment covers the first task; the terminal comment follows.)
+  // pr_created milestone:
+  //   * iteration → mature the threaded reply to "🔄 Working".
+  //   * first-run (non-iteration) → post the "🔗 PR opened" courtesy comment.
+  //     This replaces the agent's old step-2 `mcp__linear-server__save_comment`
+  //     (ADR-016 P4.5): the agent has no Linear MCP, so the platform posts it.
+  //     Post-once via `linear_pr_comment_event_id` so a pr_created redelivery
+  //     (or a sibling channel's infra-rejection re-run) doesn't duplicate it.
   if (event.event_type === 'agent_milestone') {
     if (isIteration && iterationReplyId && triggerCommentId) {
       await upsertThreadedReply(
@@ -1143,8 +1178,33 @@ async function dispatchToLinear(event: FanOutEvent): Promise<void> {
         }),
         iterationReplyId,
       );
+      return;
+    }
+    // First-run PR-opened comment. Skip if we've already posted it, or if
+    // there's no PR URL yet (nothing to link).
+    if (task.linear_pr_comment_event_id || !task.pr_url) return;
+    const prBody = renderLinearPrOpenedComment(task.pr_url, task.pr_number ?? null);
+    const prResult = await postIssueComment(
+      { linearWorkspaceId: workspaceId, registryTableName },
+      issueId,
+      prBody,
+    );
+    if (prResult.ok) {
+      logger.info('[fanout/linear] PR-opened comment dispatched', {
+        event: 'fanout.linear.pr_comment_dispatched',
+        task_id: task.task_id,
+        issue_id: issueId,
+      });
+      await saveLinearPrCommentState(task.task_id, event.event_id);
+    } else {
+      logger.warn('[fanout/linear] PR-opened comment post failed', {
+        event: 'fanout.linear.pr_comment_failed',
+        error_id: 'FANOUT_LINEAR_PR_COMMENT_FAILED',
+        task_id: task.task_id,
+        issue_id: issueId,
+      });
     }
-    return; // milestones never post the top-level status comment
+    return; // milestones never post the terminal status comment
   }
 
   // Idempotency across partial-batch retries: Linear has no comment
diff --git a/cdk/src/handlers/linear-webhook-processor.ts b/cdk/src/handlers/linear-webhook-processor.ts
@@ -31,6 +31,7 @@ import { cleanupPreScreenedAttachments, downloadScreenAndStoreLinearAttachments,
 import {
   deleteComment,
   fetchRecentComments,
+  postIssueComment,
   reactToComment,
   replyToComment,
   reportIssueFailure,
@@ -169,6 +170,14 @@ const MAX_IDEMPOTENCY_KEY_LENGTH = 128;
  */
 const ACK_CLAIM_TTL_SECONDS = 86_400;
 
+/**
+ * First-run "starting" courtesy comment (ADR-016 P4.5). The 🤖 prefix matches
+ * the bot-comment markers the self-trigger guard skips (isBotAuthoredComment),
+ * so this never re-triggers ABCA. Kept short — the terminal fan-out comment
+ * carries the outcome + cost + PR link.
+ */
+const LINEAR_START_COMMENT = '🤖 Starting on this issue — I\'ll open a PR and report back here when it\'s ready.';
+
 /**
  * Post a Linear comment + ❌ reaction without ever propagating an error.
  *
@@ -1031,6 +1040,30 @@ export async function handler(event: ProcessorEvent): Promise<void> {
     request_id: requestId,
   });
 
+  // ADR-016 P4.5: post the first-run "🤖 Starting" courtesy comment from the
+  // Lambda tier. This used to be the agent's own `mcp__linear-server__save_comment`
+  // call — with the Linear MCP removed (Linear is fully deterministic), the
+  // platform owns the comment. Only the single-task first-run path posts it:
+  // orchestration/decompose seeds and comment-iterations returned earlier (their
+  // panel / maturing reply already narrate start). Best-effort — never gates the
+  // run that already started. The 👀 reaction + In Progress transition still
+  // happen agent-side (linear_reactions.react_task_started); this is the human-
+  // readable companion, posted at admission so it lands before the container
+  // cold-starts. The terminal ✅/⚠️/❌ + PR link is posted by the fan-out plane.
+  if (WORKSPACE_REGISTRY_TABLE) {
+    try {
+      await postIssueComment(
+        { linearWorkspaceId: workspaceId, registryTableName: WORKSPACE_REGISTRY_TABLE },
+        issue.id,
+        LINEAR_START_COMMENT,
+      );
+    } catch (err) {
+      logger.warn('Failed to post Linear start comment (non-fatal)', {
+        issue_id: issue.id, error: err instanceof Error ? err.message : String(err),
+      });
+    }
+  }
+
   // Multi-part hint (customer-caught): a PLAIN ``bgagent`` label on an issue
   // that looks like several separate parts still runs as ONE task — but the
   // reviewer never saw a plan. Post a one-time, non-blocking nudge that
diff --git a/cdk/src/handlers/shared/types.ts b/cdk/src/handlers/shared/types.ts
@@ -218,6 +218,14 @@ export interface TaskRecord {
    * record). Absent until the first successful post.
    */
   readonly linear_final_comment_event_id?: string;
+  /**
+   * Event ID of the ``pr_created`` milestone whose Linear "PR opened"
+   * courtesy comment was successfully posted (fan-out plane, ADR-016 P4.5).
+   * Makes the first-run PR-opened comment post-once across partial-batch
+   * Lambda retries — the analogue of ``linear_final_comment_event_id`` for
+   * the mid-run PR notification. Absent until the first successful post.
+   */
+  readonly linear_pr_comment_event_id?: string;
   /**
    * Event ID of the terminal event whose Jira final-status comment was
    * successfully posted (fan-out plane). Jira has no comment edit API,
diff --git a/cdk/test/handlers/fanout-task-events.test.ts b/cdk/test/handlers/fanout-task-events.test.ts
@@ -198,6 +198,19 @@ function mkEvent(type: string, taskId = 't-1'): DynamoDBRecord {
   });
 }
 
+/** An ``agent_milestone`` event carrying ``metadata.milestone`` — the real
+ *  shape the agent emits for pr_created (progress_writer.write_agent_milestone),
+ *  which ``effectiveEventType`` unwraps for routing. */
+function mkMilestone(milestone: string, taskId = 't-1'): DynamoDBRecord {
+  return mkRecord('INSERT', {
+    task_id: { S: taskId },
+    event_id: { S: `01ABC${milestone}` },
+    event_type: { S: 'agent_milestone' },
+    timestamp: { S: '2026-04-22T04:00:00Z' },
+    metadata: { M: { milestone: { S: milestone } } },
+  });
+}
+
 describe('fanout-task-events: parseStreamRecord', () => {
   test('parses a well-formed INSERT into FanOutEvent', () => {
     const rec = mkEvent('task_completed', 't-parse-1');
@@ -350,9 +363,10 @@ describe('fanout-task-events: per-channel filter contract (design §6.2)', () =>
     ]);
   });
 
-  test('Linear subscribes to terminal events only (post-once final-status comment)', () => {
+  test('Linear subscribes to pr_created + terminal events (ADR-016 P4.5 courtesy comment + post-once final-status)', () => {
     const f = CHANNEL_DEFAULTS.linear;
     expect([...f].sort()).toEqual([
+      'pr_created',
       'task_cancelled',
       'task_completed',
       'task_failed',
@@ -496,9 +510,9 @@ describe('fanout-task-events: routeEvent (per-channel dispatch)', () => {
     expect(outcome.dispatched).toEqual(['slack']);
   });
 
-  test('pr_created routes to GitHub only (not Slack — task_completed already carries View PR)', async () => {
+  test('pr_created routes to GitHub + Linear (ADR-016 P4.5 courtesy comment), not Slack', async () => {
     const outcome = await routeEvent(mk('pr_created'));
-    expect(outcome.dispatched).toEqual(['github']);
+    expect([...outcome.dispatched].sort()).toEqual(['github', 'linear']);
     expect(outcome.dispatched).not.toContain('slack');
   });
 
@@ -1541,6 +1555,58 @@ describe('fanout-task-events: Linear dispatcher (issue #239)', () => {
     expect(mockPostIssueComment).not.toHaveBeenCalled();
   });
 
+  // ─── ADR-016 P4.5: first-run "PR opened" courtesy comment on pr_created ─────
+
+  test('pr_created posts a "🔗 Opened PR" comment for a first-run task', async () => {
+    mockGet({ ...TASK_RECORD_LINEAR, pr_number: 13 });
+
+    const event: DynamoDBStreamEvent = { Records: [mkMilestone('pr_created', 't-lin')] };
+    await handler(event);
+
+    expect(mockPostIssueComment).toHaveBeenCalledTimes(1);
+    const [, issueId, body] = mockPostIssueComment.mock.calls[0];
+    expect(issueId).toBe('issue-uuid-42');
+    expect(body).toContain('🔗');
+    expect(body).toContain('PR #13');
+    expect(body).toContain('https://github.com/owner/repo/pull/13');
+  });
+
+  test('pr_created without a PR url yet posts nothing (nothing to link)', async () => {
+    mockGet({ ...TASK_RECORD_LINEAR, pr_url: undefined });
+
+    const event: DynamoDBStreamEvent = { Records: [mkMilestone('pr_created', 't-lin')] };
+    await handler(event);
+
+    expect(mockPostIssueComment).not.toHaveBeenCalled();
+  });
+
+  test('pr_created is post-once — already-posted marker skips the comment', async () => {
+    mockGet({ ...TASK_RECORD_LINEAR, pr_number: 13, linear_pr_comment_event_id: 'prior-event' });
+
+    const event: DynamoDBStreamEvent = { Records: [mkMilestone('pr_created', 't-lin')] };
+    await handler(event);
+
+    expect(mockPostIssueComment).not.toHaveBeenCalled();
+  });
+
+  test('pr_created on an iteration matures the threaded reply instead of posting a top-level comment', async () => {
+    mockGet({
+      ...TASK_RECORD_LINEAR,
+      pr_number: 13,
+      channel_metadata: {
+        ...TASK_RECORD_LINEAR.channel_metadata,
+        trigger_comment_id: 'trigger-c1',
+        iteration_reply_comment_id: 'reply-c1',
+      },
+    });
+
+    const event: DynamoDBStreamEvent = { Records: [mkMilestone('pr_created', 't-lin')] };
+    await handler(event);
+
+    expect(mockUpsertThreadedReply).toHaveBeenCalledTimes(1);
+    expect(mockPostIssueComment).not.toHaveBeenCalled();
+  });
+
   test('Linear-origin task missing channel_metadata.linear_issue_id — skip with warning', async () => {
     // Defensive: a properly-admitted Linear task should always have
     // these fields, but if it doesn't we'd rather log + skip than
@@ -2496,9 +2562,12 @@ describe('fanout-task-events: agent_milestone routing (effective event type)', (
     expect(shouldFanOut(colliding)).toBe(false);
   });
 
-  test('routeEvent dispatches agent_milestone(pr_created) to GitHub only (Slack opted out to avoid duplicate View PR)', async () => {
+  test('routeEvent dispatches agent_milestone(pr_created) to GitHub + Linear (ADR-016 P4.5), not Slack', async () => {
+    // Slack stays opted out (task_completed carries View PR); Linear joined
+    // for the first-run "🔗 PR opened" courtesy comment.
     const outcome = await routeEvent(makeMilestone('pr_created'));
-    expect(outcome.dispatched).toEqual(['github']);
+    expect([...outcome.dispatched].sort()).toEqual(['github', 'linear']);
+    expect(outcome.dispatched).not.toContain('slack');
   });
 
   test('routeEvent drops agent_milestone(agent_turn-like) that no channel subscribes to', async () => {
