feat: Add threaded review comments + agent comment responses

Introduces GitHub-style threaded comments via parentCommentId self-reference.
Users and agents can reply within comment threads, and review agents receive
comment IDs so they can post targeted responses via comment-responses.json.

- Migration 0032: parentCommentId column + index on review_comments
- Repository: createReply() copies parent context, default author 'you' → 'user'
- tRPC: replyToReviewComment procedure, requestPhaseChanges passes threaded comments
- Orchestrator: formats [comment:ID] tags with full reply threads in task description
- Agent IO: readCommentResponses() reads .cw/output/comment-responses.json
- OutputHandler: processes agent comment responses (creates replies, resolves threads)
- Execute prompt: conditional <review_comments> block when task has [comment:] markers
- Frontend: CommentThread renders root+replies with agent-specific styling + reply form
- Sidebar/ReviewTab: root-only comment counts, reply mutation plumbing through DiffViewer chain

apps/server/agent/file-io.ts

@@ -397,6 +397,34 @@ export async function readDecisionFiles(agentWorkdir: string): Promise<ParsedDec
   });
 }
 
+export interface ParsedCommentResponse {
+  commentId: string;
+  body: string;
+  resolved?: boolean;
+}
+
+export async function readCommentResponses(agentWorkdir: string): Promise<ParsedCommentResponse[]> {
+  const filePath = join(agentWorkdir, '.cw', 'output', 'comment-responses.json');
+  try {
+    const raw = await readFile(filePath, 'utf-8');
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((entry: unknown) => {
+        if (typeof entry !== 'object' || entry === null) return false;
+        const e = entry as Record<string, unknown>;
+        return typeof e.commentId === 'string' && typeof e.body === 'string';
+      })
+      .map((entry: Record<string, unknown>) => ({
+        commentId: String(entry.commentId),
+        body: String(entry.body),
+        resolved: typeof entry.resolved === 'boolean' ? entry.resolved : undefined,
+      }));
+  } catch {
+    return [];
+  }
+}
+
 export async function readPageFiles(agentWorkdir: string): Promise<ParsedPageFile[]> {
   const dirPath = join(agentWorkdir, '.cw', 'output', 'pages');
   return readFrontmatterDir(dirPath, (data, body, filename) => {

apps/server/agent/manager.ts

@@ -27,6 +27,7 @@ import type { TaskRepository } from '../db/repositories/task-repository.js';
 import type { PageRepository } from '../db/repositories/page-repository.js';
 import type { LogChunkRepository } from '../db/repositories/log-chunk-repository.js';
 import type { ChatSessionRepository } from '../db/repositories/chat-session-repository.js';
+import type { ReviewCommentRepository } from '../db/repositories/review-comment-repository.js';
 import { generateUniqueAlias } from './alias.js';
 import type {
   EventBus,
@@ -84,11 +85,12 @@ export class MultiProviderAgentManager implements AgentManager {
     private debug: boolean = false,
     processManagerOverride?: ProcessManager,
     private chatSessionRepository?: ChatSessionRepository,
+    private reviewCommentRepository?: ReviewCommentRepository,
   ) {
     this.signalManager = new FileSystemSignalManager();
     this.processManager = processManagerOverride ?? new ProcessManager(workspaceRoot, projectRepository);
     this.credentialHandler = new CredentialHandler(workspaceRoot, accountRepository, credentialManager);
-    this.outputHandler = new OutputHandler(repository, eventBus, changeSetRepository, phaseRepository, taskRepository, pageRepository, this.signalManager, chatSessionRepository);
+    this.outputHandler = new OutputHandler(repository, eventBus, changeSetRepository, phaseRepository, taskRepository, pageRepository, this.signalManager, chatSessionRepository, reviewCommentRepository);
     this.cleanupManager = new CleanupManager(workspaceRoot, repository, projectRepository, eventBus, debug, this.signalManager);
     this.lifecycleController = createLifecycleController({
       repository,

apps/server/agent/output-handler.ts

@@ -15,6 +15,7 @@ import type { PhaseRepository } from '../db/repositories/phase-repository.js';
 import type { TaskRepository } from '../db/repositories/task-repository.js';
 import type { PageRepository } from '../db/repositories/page-repository.js';
 import type { ChatSessionRepository } from '../db/repositories/chat-session-repository.js';
+import type { ReviewCommentRepository } from '../db/repositories/review-comment-repository.js';
 import type {
   EventBus,
   AgentStoppedEvent,
@@ -37,6 +38,7 @@ import {
   readDecisionFiles,
   readPageFiles,
   readFrontmatterFile,
+  readCommentResponses,
 } from './file-io.js';
 import { getProvider } from './providers/registry.js';
 import { markdownToTiptapJson } from './markdown-to-tiptap.js';
@@ -92,6 +94,7 @@ export class OutputHandler {
     private pageRepository?: PageRepository,
     private signalManager?: SignalManager,
     private chatSessionRepository?: ChatSessionRepository,
+    private reviewCommentRepository?: ReviewCommentRepository,
   ) {}
 
   /**
@@ -851,6 +854,28 @@ export class OutputHandler {
       }
     }
 
+    // Process comment responses from agent (for review/execute tasks)
+    if (this.reviewCommentRepository) {
+      try {
+        const commentResponses = await readCommentResponses(agentWorkdir);
+        for (const resp of commentResponses) {
+          try {
+            await this.reviewCommentRepository.createReply(resp.commentId, resp.body, 'agent');
+            if (resp.resolved) {
+              await this.reviewCommentRepository.resolve(resp.commentId);
+            }
+          } catch (err) {
+            log.warn({ agentId, commentId: resp.commentId, err: err instanceof Error ? err.message : String(err) }, 'failed to process comment response');
+          }
+        }
+        if (commentResponses.length > 0) {
+          log.info({ agentId, count: commentResponses.length }, 'processed agent comment responses');
+        }
+      } catch (err) {
+        log.warn({ agentId, err: err instanceof Error ? err.message : String(err) }, 'failed to read comment responses');
+      }
+    }
+
     const resultPayload: AgentResult = {
       success: true,
       message: resultMessage,

apps/server/agent/prompts/execute.ts

@@ -14,13 +14,26 @@ import {
 } from './shared.js';
 
 export function buildExecutePrompt(taskDescription?: string): string {
+  const hasReviewComments = taskDescription?.includes('[comment:');
+  const reviewCommentsSection = hasReviewComments
+    ? `
+<review_comments>
+You are addressing review feedback. Each comment is tagged with [comment:ID].
+For EACH comment you address:
+1. Fix the issue in code, OR explain why no change is needed.
+2. Write \`.cw/output/comment-responses.json\`:
+   [{"commentId": "abc123", "body": "Fixed: added try-catch around token validation", "resolved": true}]
+Set resolved:true when you fixed it, false when you're explaining why you didn't.
+</review_comments>`
+    : '';
+
   const taskSection = taskDescription
     ? `
 <task>
 ${taskDescription}
 
 Read \`.cw/input/task.md\` for the full structured task with metadata, priority, and dependencies.
-</task>`
+</task>${reviewCommentsSection}`
     : '';
 
   return `<role>

apps/server/container.ts

@@ -183,6 +183,7 @@ export async function createContainer(options?: ContainerOptions): Promise<Conta
     options?.debug ?? false,
     undefined, // processManagerOverride
     repos.chatSessionRepository,
+    repos.reviewCommentRepository,
   );
   log.info('agent manager created');
 

apps/server/db/repositories/drizzle/review-comment.ts

@@ -23,7 +23,43 @@ export class DrizzleReviewCommentRepository implements ReviewCommentRepository {
       lineNumber: data.lineNumber,
       lineType: data.lineType,
       body: data.body,
-      author: data.author ?? 'you',
+      author: data.author ?? 'user',
+      parentCommentId: data.parentCommentId ?? null,
+      resolved: false,
+      createdAt: now,
+      updatedAt: now,
+    });
+    const rows = await this.db
+      .select()
+      .from(reviewComments)
+      .where(eq(reviewComments.id, id))
+      .limit(1);
+    return rows[0]!;
+  }
+
+  async createReply(parentCommentId: string, body: string, author?: string): Promise<ReviewComment> {
+    // Fetch parent comment to copy context fields
+    const parentRows = await this.db
+      .select()
+      .from(reviewComments)
+      .where(eq(reviewComments.id, parentCommentId))
+      .limit(1);
+    const parent = parentRows[0];
+    if (!parent) {
+      throw new Error(`Parent comment not found: ${parentCommentId}`);
+    }
+
+    const now = new Date();
+    const id = nanoid();
+    await this.db.insert(reviewComments).values({
+      id,
+      phaseId: parent.phaseId,
+      filePath: parent.filePath,
+      lineNumber: parent.lineNumber,
+      lineType: parent.lineType,
+      body,
+      author: author ?? 'user',
+      parentCommentId,
       resolved: false,
       createdAt: now,
       updatedAt: now,

apps/server/db/repositories/review-comment-repository.ts

@@ -13,10 +13,12 @@ export interface CreateReviewCommentData {
   lineType: 'added' | 'removed' | 'context';
   body: string;
   author?: string;
+  parentCommentId?: string;  // for replies
 }
 
 export interface ReviewCommentRepository {
   create(data: CreateReviewCommentData): Promise<ReviewComment>;
+  createReply(parentCommentId: string, body: string, author?: string): Promise<ReviewComment>;
   findByPhaseId(phaseId: string): Promise<ReviewComment[]>;
   resolve(id: string): Promise<ReviewComment | null>;
   unresolve(id: string): Promise<ReviewComment | null>;

apps/server/db/schema.ts

@@ -617,11 +617,13 @@ export const reviewComments = sqliteTable('review_comments', {
   lineType: text('line_type', { enum: ['added', 'removed', 'context'] }).notNull(),
   body: text('body').notNull(),
   author: text('author').notNull().default('you'),
+  parentCommentId: text('parent_comment_id').references((): ReturnType<typeof text> => reviewComments.id, { onDelete: 'cascade' }),
   resolved: integer('resolved', { mode: 'boolean' }).notNull().default(false),
   createdAt: integer('created_at', { mode: 'timestamp' }).notNull(),
   updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull(),
 }, (table) => [
   index('review_comments_phase_id_idx').on(table.phaseId),
+  index('review_comments_parent_id_idx').on(table.parentCommentId),
 ]);
 
 export type ReviewComment = InferSelectModel<typeof reviewComments>;

apps/server/drizzle/0032_add_comment_threading.sql

@@ -0,0 +1,2 @@
+ALTER TABLE review_comments ADD COLUMN parent_comment_id TEXT REFERENCES review_comments(id) ON DELETE CASCADE;
+CREATE INDEX review_comments_parent_id_idx ON review_comments(parent_comment_id);

apps/server/execution/orchestrator.ts

@@ -344,7 +344,14 @@ export class ExecutionOrchestrator {
    */
   async requestChangesOnPhase(
     phaseId: string,
-    unresolvedComments: Array<{ filePath: string; lineNumber: number; body: string }>,
+    unresolvedThreads: Array<{
+      id: string;
+      filePath: string;
+      lineNumber: number;
+      body: string;
+      author: string;
+      replies: Array<{ id: string; body: string; author: string }>;
+    }>,
     summary?: string,
   ): Promise<{ taskId: string }> {
     const phase = await this.phaseRepository.findById(phaseId);
@@ -365,16 +372,16 @@ export class ExecutionOrchestrator {
       return { taskId: activeReview.id };
     }
 
-    // Build revision task description from comments + summary
+    // Build revision task description from threaded comments + summary
     const lines: string[] = [];
     if (summary) {
       lines.push(`## Summary\n\n${summary}\n`);
     }
-    if (unresolvedComments.length > 0) {
+    if (unresolvedThreads.length > 0) {
       lines.push('## Review Comments\n');
       // Group comments by file
-      const byFile = new Map<string, typeof unresolvedComments>();
-      for (const c of unresolvedComments) {
+      const byFile = new Map<string, typeof unresolvedThreads>();
+      for (const c of unresolvedThreads) {
         const arr = byFile.get(c.filePath) ?? [];
         arr.push(c);
         byFile.set(c.filePath, arr);
@@ -382,9 +389,13 @@ export class ExecutionOrchestrator {
       for (const [filePath, fileComments] of byFile) {
         lines.push(`### ${filePath}\n`);
         for (const c of fileComments) {
-          lines.push(`- **Line ${c.lineNumber}**: ${c.body}`);
+          lines.push(`#### Line ${c.lineNumber} [comment:${c.id}]`);
+          lines.push(`**${c.author}**: ${c.body}`);
+          for (const r of c.replies) {
+            lines.push(`> **${r.author}**: ${r.body}`);
+          }
+          lines.push('');
         }
-        lines.push('');
       }
     }
 
@@ -414,12 +425,12 @@ export class ExecutionOrchestrator {
         phaseId,
         initiativeId: phase.initiativeId,
         taskId: task.id,
-        commentCount: unresolvedComments.length,
+        commentCount: unresolvedThreads.length,
       },
     };
     this.eventBus.emit(event);
 
-    log.info({ phaseId, taskId: task.id, commentCount: unresolvedComments.length }, 'changes requested on phase');
+    log.info({ phaseId, taskId: task.id, commentCount: unresolvedThreads.length }, 'changes requested on phase');
 
     // Kick off dispatch
     this.scheduleDispatch();

apps/server/trpc/routers/phase.ts

@@ -368,6 +368,17 @@ export function phaseProcedures(publicProcedure: ProcedureBuilder) {
         return comment;
       }),
 
+    replyToReviewComment: publicProcedure
+      .input(z.object({
+        parentCommentId: z.string().min(1),
+        body: z.string().trim().min(1),
+        author: z.string().optional(),
+      }))
+      .mutation(async ({ ctx, input }) => {
+        const repo = requireReviewCommentRepository(ctx);
+        return repo.createReply(input.parentCommentId, input.body, input.author);
+      }),
+
     requestPhaseChanges: publicProcedure
       .input(z.object({
         phaseId: z.string().min(1),
@@ -378,15 +389,33 @@ export function phaseProcedures(publicProcedure: ProcedureBuilder) {
         const reviewCommentRepo = requireReviewCommentRepository(ctx);
 
         const allComments = await reviewCommentRepo.findByPhaseId(input.phaseId);
-        const unresolved = allComments
-          .filter((c: { resolved: boolean }) => !c.resolved)
-          .map((c: { filePath: string; lineNumber: number; body: string }) => ({
+        // Build threaded structure: unresolved root comments with their replies
+        const rootComments = allComments.filter((c) => !c.parentCommentId);
+        const repliesByParent = new Map<string, typeof allComments>();
+        for (const c of allComments) {
+          if (c.parentCommentId) {
+            const arr = repliesByParent.get(c.parentCommentId) ?? [];
+            arr.push(c);
+            repliesByParent.set(c.parentCommentId, arr);
+          }
+        }
+
+        const unresolvedThreads = rootComments
+          .filter((c) => !c.resolved)
+          .map((c) => ({
+            id: c.id,
             filePath: c.filePath,
             lineNumber: c.lineNumber,
             body: c.body,
+            author: c.author,
+            replies: (repliesByParent.get(c.id) ?? []).map((r) => ({
+              id: r.id,
+              body: r.body,
+              author: r.author,
+            })),
           }));
 
-        if (unresolved.length === 0 && !input.summary) {
+        if (unresolvedThreads.length === 0 && !input.summary) {
           throw new TRPCError({
             code: 'BAD_REQUEST',
             message: 'Add comments or a summary before requesting changes',
@@ -395,7 +424,7 @@ export function phaseProcedures(publicProcedure: ProcedureBuilder) {
 
         const result = await orchestrator.requestChangesOnPhase(
           input.phaseId,
-          unresolved,
+          unresolvedThreads,
           input.summary,
         );
         return { success: true, taskId: result.taskId };