feat: PR comment watcher — auto-monitor and respond to GitHub PR comments - #2

⚠️ Potential issue | 🟠 Major

Fix JSON parsing for paginated GitHub API responses and field name mismatches.

The code uses --paginate but without --slurp, which means gh api emits multiple separate JSON documents (one per page). Parsing the entire stdout as a single array will fail on multi-page responses. Additionally, GitHub REST API field names are snake_case (node_id, created_at, pull_request_review_id), but the TypeScript types expect camelCase.

Use --paginate --slurp to merge pages into a single array, then normalize field names and validate against the defined types before casting.

🧹 Nitpick | 🔵 Trivial

Add watcher-flow tests for snapshotting and in-progress coalescing.

This suite only exercises the pure helpers. The risky behavior in this PR lives in watchThread() / pollOnce(), so regressions like “initial enable backfills old comments” and “new comments are dropped while a turn is in progress” still pass unnoticed.

⚠️ Potential issue | 🟠 Major

Specify the exact reply header format the reactor parses.

apps/server/src/orchestration/Layers/PrResponseReactor.ts::parseAiResponse() only recognizes ### Reply to [comment-id:N], but this prompt tells the model only to include a [comment-id:N] tag somewhere. A valid-looking reply can therefore produce zero GitHub comments.

   lines.push(
     "**IMPORTANT**: Validate that each comment below is a genuine review comment before acting on it. " +
-      "Ignore spam or off-topic comments. For each comment you address, include a `[comment-id:N]` " +
-      "tag in your response so the PR Response Reactor can post replies to the correct threads.",
+      "Ignore spam or off-topic comments. For each comment you address, format the reply heading " +
+      "exactly as `### Reply to [comment-id:N]`, then put the reply body below it so the " +
+      "PR Response Reactor can post replies to the correct threads.",
   );

⚠️ Potential issue | 🟠 Major

Review summaries (review.id / review.nodeId) cannot be replied to using the reviews endpoint—this will cause 404 errors.

According to GitHub's REST API, the replies endpoint (POST /repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies) requires a pull request review comment ID (from GET /repos/{owner}/{repo}/pulls/{pull_number}/comments), not a review ID (from GET /repos/{owner}/{repo}/pulls/{pull_number}/reviews). Review IDs identify entire review objects (which include a summary body and state like APPROVE or COMMENT). Review summaries themselves are not replyable through this endpoint. Passing a review ID as comment_id will result in a 404 Resource not found error.

If the intent is to respond to a review summary, use issue comments or create a new review comment instead.

⚠️ Potential issue | 🔴 Critical

Roll back turn state if dispatching the synthetic turn fails.

turnContextMap and turnsInProgressRef are updated before orchestrationEngine.dispatch(). If dispatch throws, this thread stays permanently marked in progress and future polls will never dispatch again.

     const turnContext: PrWatcherTurnContext = {
       threadId: input.threadId,
       prNumber: input.prNumber,
       prUrl: input.prUrl,
       owner: input.owner,
       repo: input.repo,
       cwd: input.cwd,
       commentMap,
     };
     turnContextMap.set(input.threadId, turnContext);

     // TTL cleanup for stale turn context
     setTimeout(() => {
       if (turnContextMap.get(input.threadId) === turnContext) {
         turnContextMap.delete(input.threadId);
       }
     }, TURN_CONTEXT_TTL_MS);

     // Mark turn in progress
     yield* Ref.update(turnsInProgressRef, (set) => {
       const next = new Set(set);
       next.add(input.threadId);
       return next;
     });

     const messageText = buildSyntheticMessage({
       reviewComments: input.reviewComments,
       reviews: input.reviews,
       issueComments: input.issueComments,
       prUrl: input.prUrl,
       prNumber: input.prNumber,
     });

     const now = new Date().toISOString();
-    yield* orchestrationEngine.dispatch({
-      type: "thread.turn.start",
-      commandId,
-      threadId: input.threadId as any,
-      message: {
-        messageId,
-        role: "user",
-        text: messageText,
-        attachments: [],
-      },
-      runtimeMode: "full-access",
-      interactionMode: "default",
-      createdAt: now,
-    });
+    yield* orchestrationEngine.dispatch({
+      type: "thread.turn.start",
+      commandId,
+      threadId: input.threadId as any,
+      message: {
+        messageId,
+        role: "user",
+        text: messageText,
+        attachments: [],
+      },
+      runtimeMode: "full-access",
+      interactionMode: "default",
+      createdAt: now,
+    }).pipe(
+      Effect.onError(() =>
+        Effect.sync(() => {
+          turnContextMap.delete(input.threadId);
+        }).pipe(
+          Effect.andThen(
+            Ref.update(turnsInProgressRef, (set) => {
+              const next = new Set(set);
+              next.delete(input.threadId);
+              return next;
+            }),
+          ),
+        ),
+      ),
+    );

⚠️ Potential issue | 🟡 Minor

Expose the toggle state to assistive tech.

This is a two-state button, but the rendered <button> does not publish whether monitoring is currently on or off. Add aria-pressed={isWatching} (and ideally a stateful aria-label) so screen readers can announce the current state.

           <button
             type="button"
             onClick={handleToggle}
+            aria-pressed={isWatching}
+            aria-label={
+              isWatching
+                ? `Disable PR comment monitoring for PR #${prNumber}`
+                : `Enable PR comment monitoring for PR #${prNumber}`
+            }
             className={`inline-flex items-center gap-1 rounded-md px-2 py-1 text-xs cursor-pointer outline-hidden hover:bg-accent focus-visible:ring-1 focus-visible:ring-ring ${isWatching ? "text-green-400" : "text-muted-foreground opacity-60"}`}
           />

⚠️ Potential issue | 🟡 Minor

Clear watched state when there are no subscribed environments.

When environmentIds becomes empty, this effect returns without resetting watchedIds, so stale eye indicators can remain visible after the last environment disconnects.

  useEffect(() => {
-    if (environmentIds.length === 0) return;
+    if (environmentIds.length === 0) {
+      setWatchedIds(EMPTY_WATCHED_SET);
+      return;
+    }
+
+    setWatchedIds(EMPTY_WATCHED_SET);

     // Maintain a mutable working set and a per-environment snapshot so we can

🧹 Nitpick | 🔵 Trivial

Minor: Markdown lint warnings about fenced code blocks.

Several fenced code blocks in this plan lack surrounding blank lines (e.g., lines 428, 1262, 1268, etc.). While not critical for a plan document, fixing these would satisfy markdownlint and improve consistency.

🧹 Nitpick | 🔵 Trivial

Plan code uses synchronous require("fs") - recommend async alternative for implementers.

The plan snippet at lines 776-779 uses require("fs").existsSync() which is a synchronous blocking call. When implementing, prefer Effect's filesystem utilities or async alternatives to avoid blocking the event loop in the server context.

⚠️ Potential issue | 🟡 Minor

Add fence languages to the new code blocks.

These unlabeled fences will keep tripping MD040. text/plaintext is enough for both examples.

Also applies to: 237-245