fix(linear): start new work from a follow-up comment on a PR-less task (#614)

A follow-up `@bgagent <request>` comment on a completed Linear task that
opened no PR was silently dropped. handleStandaloneCommentTrigger is
iteration-only: on prNumber === null it checks for a clarify-hold and, if it
isn't one, returns with just an info log — the comment vanished.

But a task finishes PR-less in several real ways (no change needed,
failed-before-commit, or a question/investigation run), and a follow-up on
such an issue is almost always NEW work ("then just do X instead"), not
iteration. Add maybeStartStandaloneNewWork: when the repo + user are known
and the comment carries instruction text, dispatch a fresh coding/new-task-v1
against the same repo using the comment text as the description — reusing the
same 👀-ack + threaded reply + fanout terminal ownership as the iteration and
clarify-resume paths. Idempotency keyed newwork_<issue>_<comment>.

Edge cases: a bare `@bgagent` (no instruction) gets a threaded reply telling
the user what to do rather than a vague dispatch or silence; no repo / no
user_id falls through to the (now-narrowed) no-op log.

Tests: replace the obsolete 'NO PR → no task, no ack' case with the new-work
dispatch, bare-mention reply, no-repo, and no-user cases. Full cdk build green
(3118 tests).

Closes #614.

Author: isadeks

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

@@ -2415,7 +2415,17 @@ async function handleStandaloneCommentTrigger(args: {
     if (await maybeResumeClarifyHold({ issueId, task, workspaceId, commentId, replyTargetId, trigger, resolved, registryTableName })) {
       return;
     }
-    logger.info('A6 comment (standalone): ABCA task has no resolvable PR/repo — cannot iterate', {
+    // #614: a PR-less completed task (no-change-needed, failed-before-commit, or
+    // a question/investigation run) is NOT an iteration target — but a follow-up
+    // ``@bgagent <request>`` on it is almost always NEW work ("then just do X
+    // instead"). When the repo is known, dispatch a fresh new-task-v1 rather than
+    // dropping the comment silently (the old dead-end). Falls through to the
+    // no-op log below only when we genuinely can't act (no repo/user, or a bare
+    // mention with no instruction).
+    if (await maybeStartStandaloneNewWork({ issueId, task, workspaceId, commentId, replyTargetId, trigger, resolved, registryTableName })) {
+      return;
+    }
+    logger.info('A6 comment (standalone): PR-less task, no new-work dispatched (no repo/user or empty instruction)', {
       linear_issue_id: issueId, task_id: task.task_id, has_repo: Boolean(task.repo),
     });
     return;
@@ -2470,6 +2480,112 @@ async function handleStandaloneCommentTrigger(args: {
   }
 }
 
+/**
+ * #614: start NEW work from a follow-up comment on a PR-less completed task.
+ *
+ * The standalone path only knows how to *iterate* an existing PR. But a task
+ * can finish with no PR (no change needed, failed before committing, or a
+ * question/investigation run), and a follow-up ``@bgagent <request>`` on such an
+ * issue is almost always a fresh ask ("then just do X instead") — not iteration.
+ * Before #614 those comments hit a silent ``return`` and vanished. This dispatches
+ * a fresh ``coding/new-task-v1`` against the SAME repo, using the comment text as
+ * the task description, with the same 👀-ack + threaded reply + fanout terminal
+ * ownership as the iteration/clarify paths.
+ *
+ * Returns true when it handled the comment (a task was dispatched, OR a bare
+ * mention was answered with a "nothing to do" reply), false when it cannot act
+ * (no repo/user) so the caller falls through to its no-op log.
+ *
+ * Best-effort: a dispatch failure is logged and still returns true (we already
+ * ACKed) — the fanout terminal path reports the outcome.
+ */
+async function maybeStartStandaloneNewWork(args: {
+  issueId: string;
+  task: { task_id: string; repo?: string; user_id?: string };
+  workspaceId: string;
+  commentId: string;
+  replyTargetId: string;
+  trigger: CommentTrigger;
+  resolved: { accessToken: string; oauthSecretArn: string; workspaceSlug: string };
+  registryTableName: string;
+}): Promise<boolean> {
+  const { issueId, task, workspaceId, commentId, replyTargetId, trigger, resolved, registryTableName } = args;
+
+  // Can't act without a repo to work in or a user to attribute the task to —
+  // let the caller no-op-log. (These are the only genuinely unactionable cases.)
+  if (!task.repo || !task.user_id) return false;
+
+  const instruction = trigger.instruction.trim();
+  const feedbackCtx = { linearWorkspaceId: workspaceId, registryTableName };
+
+  // A bare ``@bgagent`` with no text has nothing to start. Unlike iteration
+  // (where an empty instruction means "address the latest review"), there is no
+  // PR to fall back on here — so acknowledge briefly rather than dispatch a
+  // vague task or stay silent. Handled (return true) so we don't no-op-log.
+  if (!instruction) {
+    await reactToComment(feedbackCtx, commentId, EMOJI_STARTED);
+    try {
+      await upsertThreadedReply(
+        feedbackCtx,
+        issueId,
+        replyTargetId,
+        'This task already finished and has no open PR to iterate on. Reply with what '
+          + "you'd like me to do (e.g. `@bgagent add a note to the README`) and I'll start it.",
+      );
+    } catch (err) {
+      logger.warn('A6 comment (standalone): bare-mention reply failed (non-fatal)', {
+        linear_issue_id: issueId, error: err instanceof Error ? err.message : String(err),
+      });
+    }
+    logger.info('A6 comment (standalone): bare mention on PR-less task — replied, no dispatch', {
+      linear_issue_id: issueId, task_id: task.task_id,
+    });
+    return true;
+  }
+
+  // ACK immediately (👀 reaction + threaded "On it"), same as the iteration and
+  // clarify-resume paths.
+  await reactToComment(feedbackCtx, commentId, EMOJI_STARTED);
+  const iterationReplyId = await postIterationAck(workspaceId, registryTableName, issueId, replyTargetId);
+
+  // Idempotency: key on (issue, comment) so a webhook redelivery of the SAME
+  // comment doesn't spawn a second task. Distinct prefix from iterate_/clarify_.
+  const idempotencyKey = `newwork_${issueId}_${commentId}`.replace(/[^A-Za-z0-9_-]/g, '').slice(0, MAX_IDEMPOTENCY_KEY_LENGTH);
+  const channelMetadata: Record<string, string> = {
+    // NO orchestration_id / orchestration_iteration — the reconciler skips this;
+    // the fanout dispatcher posts the ✅/❌ reply on terminal. Reply to the thread
+    // ROOT (replyTargetId), never to a reply.
+    trigger_comment_id: replyTargetId,
+    linear_issue_id: issueId,
+    linear_workspace_id: workspaceId,
+    linear_oauth_secret_arn: resolved.oauthSecretArn,
+    linear_workspace_slug: resolved.workspaceSlug,
+    ...(iterationReplyId && { iteration_reply_comment_id: iterationReplyId }),
+  };
+
+  try {
+    const result = await createTaskCore(
+      {
+        repo: task.repo,
+        workflow_ref: 'coding/new-task-v1',
+        task_description: instruction,
+      },
+      { userId: task.user_id, channelSource: 'linear', channelMetadata, idempotencyKey },
+      idempotencyKey,
+    );
+    logger.info('A6 comment (standalone): fresh new-task dispatched from follow-up on PR-less task', {
+      linear_issue_id: issueId, prior_task_id: task.task_id, status_code: result.statusCode,
+    });
+  } catch (err) {
+    logger.error('A6 comment (standalone): createTaskCore threw for new-work dispatch', {
+      linear_issue_id: issueId,
+      prior_task_id: task.task_id,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+  return true;
+}
+
 /**
  * PM-1 clarify-resume. A ``coding/new-task-v1`` run can HOLD to ask a
  * clarifying question (no PR, ``code_changed=false``, ``answer_text=<question>``;

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

@@ -56,6 +56,7 @@ const transitionIssueStateMock = jest.fn();
 const upsertStatusCommentMock = jest.fn();
 const reactToCommentMock = jest.fn();
 const replyToCommentMock = jest.fn();
+const upsertThreadedReplyMock = jest.fn();
 jest.mock('../../src/handlers/shared/linear-feedback', () => ({
   reportIssueFailure: (...args: unknown[]) => reportIssueFailureMock(...args),
   swapIssueReaction: (...args: unknown[]) => swapIssueReactionMock(...args),
@@ -64,6 +65,7 @@ jest.mock('../../src/handlers/shared/linear-feedback', () => ({
   upsertStatusComment: (...args: unknown[]) => upsertStatusCommentMock(...args),
   reactToComment: (...args: unknown[]) => reactToCommentMock(...args),
   replyToComment: (...args: unknown[]) => replyToCommentMock(...args),
+  upsertThreadedReply: (...args: unknown[]) => upsertThreadedReplyMock(...args),
   EMOJI_STARTED: 'eyes',
   EMOJI_SUCCESS: 'white_check_mark',
   EMOJI_FAILURE: 'x',
@@ -473,6 +475,7 @@ describe('linear-webhook-processor — #247 A6 comment trigger', () => {
     discoverOrchestrationMock.mockReset();
     reactToCommentMock.mockReset().mockResolvedValue(true);
     replyToCommentMock.mockReset().mockResolvedValue(true);
+    upsertThreadedReplyMock.mockReset().mockResolvedValue('reply-1');
   });
 
   test('@bgagent on a started sub-issue → pr-iteration task on its PR with cascade marker', async () => {
@@ -594,14 +597,51 @@ describe('linear-webhook-processor — #247 A6 comment trigger', () => {
       expect(createTaskCoreMock.mock.calls[0][0].pr_number).toBe(123);
     });
 
-    test('plain issue whose ABCA task opened NO PR → no task, no ack', async () => {
+    // #614: a follow-up on a PR-less completed task is NEW work, not a dead-end.
+    test('PR-less task + instruction → fresh new-task-v1 on the same repo, 👀 ack, NO orchestration markers', async () => {
       mockStandaloneOnly({ task_id: 'task-solo', user_id: 'u-solo', repo: 'o/r' }); // no pr
+      await handler(eventWith(comment())); // '@bgagent change the timeout to 30 min'
+
+      expect(createTaskCoreMock).toHaveBeenCalledTimes(1);
+      const [body, ctx] = createTaskCoreMock.mock.calls[0];
+      expect(body.workflow_ref).toBe('coding/new-task-v1');
+      expect(body.pr_number).toBeUndefined(); // NEW work, not an iteration
+      expect(body.repo).toBe('o/r');
+      expect(body.task_description).toBe('change the timeout to 30 min');
+      expect(ctx.userId).toBe('u-solo');
+      expect(ctx.channelMetadata.trigger_comment_id).toBe('comment-1');
+      expect(ctx.channelMetadata.linear_issue_id).toBe('sub-issue-1');
+      expect(ctx.channelMetadata.orchestration_id).toBeUndefined();
+      expect(ctx.channelMetadata.orchestration_iteration).toBeUndefined();
+      expect(ctx.idempotencyKey).toContain('newwork_');
+      // 👀 ack on the comment.
+      expect(reactToCommentMock).toHaveBeenCalledWith(expect.anything(), 'comment-1', 'eyes');
+    });
+
+    test('PR-less task + BARE @bgagent (no instruction) → no task, but a threaded reply (not silent)', async () => {
+      mockStandaloneOnly({ task_id: 'task-solo', user_id: 'u-solo', repo: 'o/r' }); // no pr
+      await handler(eventWith(comment({ data: { id: 'comment-1', body: '@bgagent', issueId: 'sub-issue-1' } })));
+
+      expect(createTaskCoreMock).not.toHaveBeenCalled(); // nothing to start
+      expect(reactToCommentMock).toHaveBeenCalledWith(expect.anything(), 'comment-1', 'eyes');
+      expect(upsertThreadedReplyMock).toHaveBeenCalledTimes(1); // told the user what to do
+    });
+
+    test('PR-less task with NO repo → genuinely unactionable → no task, no ack', async () => {
+      mockStandaloneOnly({ task_id: 'task-solo', user_id: 'u-solo' }); // no pr, no repo
+      await handler(eventWith(comment()));
+      expect(createTaskCoreMock).not.toHaveBeenCalled();
+      expect(reactToCommentMock).not.toHaveBeenCalled();
+    });
+
+    test('PR-less task missing user_id → cannot attribute → no task, no ack', async () => {
+      mockStandaloneOnly({ task_id: 'task-solo', repo: 'o/r' }); // no user_id, no pr
       await handler(eventWith(comment()));
       expect(createTaskCoreMock).not.toHaveBeenCalled();
       expect(reactToCommentMock).not.toHaveBeenCalled();
     });
 
-    test('plain issue task missing user_id → cannot attribute → no task', async () => {
+    test('plain issue task missing user_id (has PR) → cannot attribute → no task', async () => {
       mockStandaloneOnly({ task_id: 'task-solo', repo: 'o/r', pr_number: 5 }); // no user_id
       await handler(eventWith(comment()));
       expect(createTaskCoreMock).not.toHaveBeenCalled();