mstro-app 0.4.33 → 0.4.35

package/server/services/plan/agents/review-criteria.md

@@ -0,0 +1,53 @@
+---
+name: review-criteria
+description: "Help write effective custom review criteria for PM board issue reviews. Use when configuring what the AI reviewer should check for on completed work."
+user-invocable: false
+disable-model-invocation: true
+---
+
+You are helping the user write effective review criteria for their PM board. Review criteria tell the AI reviewer what to check when evaluating completed work.
+
+## What Are Review Criteria?
+
+Review criteria are custom instructions that the AI reviewer follows when checking completed issues. They supplement the issue's acceptance criteria with board-level quality standards.
+
+## How to Write Good Criteria
+
+Good criteria are:
+- **Specific**: "Verify all API endpoints return proper error codes (4xx/5xx)" not "Check for errors"
+- **Observable**: Things the reviewer can verify by reading code/output
+- **Relevant**: Match the type of work on the board (code, writing, research, design)
+
+## Examples by Task Type
+
+### Code Tasks
+- Verify all new functions have TypeScript types (no `any`)
+- Ensure error handling exists for all async operations
+- Check that no hardcoded credentials or secrets are present
+- Verify tests exist for new functionality
+- Ensure all endpoints have input validation
+
+### Writing/Content Tasks
+- Verify the document follows the company style guide
+- Check that all claims have citations or evidence
+- Ensure the tone matches the target audience
+- Verify all sections from the outline are addressed
+
+### Design Tasks
+- Verify designs match the Figma source files
+- Check responsive behavior is documented for mobile/tablet/desktop
+- Ensure accessibility requirements (contrast ratios, ARIA labels) are noted
+
+### Research Tasks
+- Verify at least 3 sources are cited for each major finding
+- Check that methodology is documented
+- Ensure conclusions follow logically from the evidence
+
+## Your Task
+
+Help the user craft review criteria for their board. Ask them:
+1. What type of work does this board contain? (code, writing, research, design, mixed)
+2. What quality standards matter most?
+3. Are there specific patterns or anti-patterns to watch for?
+
+Then generate 3-7 clear, actionable review criteria they can paste into their board's review criteria field.

package/server/services/plan/agents/review-custom.md

@@ -1,7 +1,10 @@
 ---
 name: review-custom
-description: Reviews work using board-defined custom criteria alongside acceptance criteria — works for code, content, research, planning, and any other task type
+description: "Reviews work using board-defined custom criteria alongside acceptance criteria — works for code, content, research, planning, and any other task type. Use when a PM board has custom review criteria configured."
+user-invocable: false
 type: review
+allowed-tools: Read, Grep, Glob, Bash
+context: fork
 variables: [issue_id, issue_title, context_section, acceptance_criteria, review_criteria, read_instruction]
 checks: [criteria_met, review_criteria]
 ---

package/server/services/plan/agents/review-quality.md

@@ -1,7 +1,10 @@
 ---
 name: review-quality
-description: Reviews non-code output (writing, research, plans, designs, analysis) for completeness, accuracy, and quality against acceptance criteria
+description: "Reviews non-code output (writing, research, plans, designs, analysis) for completeness, accuracy, and quality against acceptance criteria. Use when reviewing completed PM board issues that produce documents or deliverables."
+user-invocable: false
 type: review
+allowed-tools: Read, Grep, Glob, Bash
+context: fork
 variables: [issue_id, issue_title, output_path, issue_spec_path, acceptance_criteria]
 checks: [criteria_met, output_quality, completeness]
 ---

package/server/services/plan/agents/verify-review.md

@@ -0,0 +1,56 @@
+---
+name: verify-review
+description: "Independent verification pass for code review findings — skeptically re-checks each finding against actual code to catch hallucinations and false positives. Use after an AI code review to validate findings."
+user-invocable: false
+allowed-tools: Read, Grep, Glob, Bash
+context: fork
+---
+
+You are an independent code review VERIFIER. A separate reviewer produced the findings below. Your job is to VERIFY each finding against the actual code. You are a skeptic — do NOT trust the original reviewer's claims.
+
+IMPORTANT: Your current working directory is "{{dirPath}}". Only read files within this directory.
+
+## Findings to Verify
+
+{{findingsJson}}
+
+## Verification Process
+
+For EACH finding:
+
+1. **Read the cited file and line** using the Read tool. Read at least 20 lines around the cited line for context.
+2. **Check the specific claim** in the description. Does the code actually do what the finding claims?
+3. **Search for counter-evidence**:
+   - If the finding claims something is missing (no validation, no cleanup, no guard): search for it with Grep
+   - If the finding claims an API is used: verify the actual API call at that line
+   - If the finding claims a value is leaked/exposed: check if it's filtered/deleted elsewhere in the same function
+4. **Verdict**: Mark as "confirmed" or "rejected" with a brief explanation
+
+## Rules
+
+- You MUST actually Read each cited file. Do not rely on memory or assumptions.
+- Use Grep to search for patterns the finding claims exist (or don't exist).
+- A finding is "rejected" if:
+  - The code does NOT match what the description claims
+  - There IS a guard/fix that the finding claims is missing
+  - The line number doesn't contain the relevant code
+  - The finding is about a different version of the code than what exists now
+- A finding is "confirmed" if you can independently verify the issue exists in the current code.
+- Be thorough but efficient — focus verification effort on high/critical severity findings.
+
+## Output
+
+Output EXACTLY one JSON code block. No other text after the JSON block.
+
+```json
+{
+  "verifications": [
+    {
+      "id": 1,
+      "verdict": "confirmed|rejected",
+      "confidence": 0.95,
+      "note": "Brief explanation of what you found when checking the code"
+    }
+  ]
+}
+```

package/server/services/plan/composer.ts

@@ -129,6 +129,7 @@ export async function handlePlanPrompt(
   userPrompt: string,
   workingDir: string,
   boardId?: string,
+  executionDir?: string,
 ): Promise<void> {
   const pmDir = resolvePmDir(workingDir) ?? defaultPmDir(workingDir);
   const projectContent = readFileOrEmpty(join(pmDir, 'project.md'));
@@ -246,7 +247,7 @@ User request: ${userPrompt}`;
     });
 
     const runner = new HeadlessRunner({
-      workingDir,
+      workingDir: executionDir || workingDir,
       directPrompt: enrichedPrompt,
       stallWarningMs: 300_000,   // 5 min — compose usually finishes quickly
       stallKillMs: 900_000,      // 15 min

package/server/services/plan/executor.ts

@@ -73,6 +73,8 @@ export class PlanExecutor extends EventEmitter {
   private _scopeSetByCall = false;
   /** Extra environment variables forwarded to HeadlessRunner child processes (e.g. API keys) */
   private extraEnv?: Record<string, string>;
+  /** Optional worktree directory for running AI agents. PM data is always read from workingDir. */
+  private executionDir: string | null = null;
   private metrics: ExecutionMetrics = {
     issuesCompleted: 0,
     issuesAttempted: 0,
@@ -98,8 +100,9 @@ export class PlanExecutor extends EventEmitter {
   }
 
   /** Start execution, optionally scoped to a specific board. */
-  async startBoard(boardId: string): Promise<void> {
+  async startBoard(boardId: string, executionDir?: string): Promise<void> {
     this.boardId = boardId;
+    this.executionDir = executionDir ?? null;
     this._scopeSetByCall = true;
     return this.start();
   }
@@ -113,6 +116,7 @@ export class PlanExecutor extends EventEmitter {
     if (!this._scopeSetByCall) {
       this.epicScope = null;
       this.boardId = null;
+      this.executionDir = null;
     }
     this._scopeSetByCall = false;
     this.status = 'starting';
@@ -247,10 +251,11 @@ export class PlanExecutor extends EventEmitter {
     waveLabel: string,
     abortSignal?: AbortSignal,
   ): Promise<void> {
+    const effectiveDir = this.executionDir || this.workingDir;
     const outputPath = resolveOutputPath(issue, this.workingDir, this.boardDir);
     const prompt = buildIssuePrompt({
       issue,
-      workingDir: this.workingDir,
+      workingDir: effectiveDir,
       pmDir,
       boardDir: this.boardDir,
       existingDocs,
@@ -259,7 +264,7 @@ export class PlanExecutor extends EventEmitter {
 
     const boardLogDir = this.boardDir ? join(this.boardDir, 'logs') : undefined;
     const result = await runWithFileLogger(`pm-issue-${issue.id}`, () => runIssueWithRetry({
-      workingDir: this.workingDir,
+      workingDir: effectiveDir,
       prompt,
       stallWarningMs: ISSUE_STALL_WARNING_MS,
       stallKillMs: ISSUE_STALL_KILL_MS,

package/server/services/plan/parser-core.ts

@@ -402,12 +402,26 @@ export function parseBoard(content: string, filePath: string): Board {
   };
 }
 
+function parseWorktreeEntry(v: unknown): { path: string; branch: string } | null {
+  if (!v || typeof v !== 'object' || !('path' in v) || !('branch' in v)) return null;
+  const e = v as { path: unknown; branch: unknown };
+  return typeof e.path === 'string' && typeof e.branch === 'string' ? { path: e.path, branch: e.branch } : null;
+}
+
 export function parseWorkspace(content: string): Workspace {
   try {
     const parsed = JSON.parse(content) as Record<string, unknown>;
+    const boardWorktrees: Record<string, { path: string; branch: string }> = {};
+    if (parsed.boardWorktrees && typeof parsed.boardWorktrees === 'object') {
+      for (const [k, v] of Object.entries(parsed.boardWorktrees as Record<string, unknown>)) {
+        const entry = parseWorktreeEntry(v);
+        if (entry) boardWorktrees[k] = entry;
+      }
+    }
     return {
       activeBoardId: typeof parsed.activeBoardId === 'string' ? parsed.activeBoardId : null,
       boardOrder: Array.isArray(parsed.boardOrder) ? parsed.boardOrder.map(String) : [],
+      ...(Object.keys(boardWorktrees).length > 0 ? { boardWorktrees } : {}),
     };
   } catch {
     return { activeBoardId: null, boardOrder: [] };

package/server/services/plan/types.ts

@@ -138,9 +138,15 @@ export interface BoardExecutionSummary {
 // Workspace (workspace.json)
 // ============================================================================
 
+export interface BoardWorktreeEntry {
+  path: string;
+  branch: string;
+}
+
 export interface Workspace {
   activeBoardId: string | null;
   boardOrder: string[];
+  boardWorktrees?: Record<string, BoardWorktreeEntry>;
 }
 
 // ============================================================================

package/server/services/websocket/git-head-watcher.ts

@@ -0,0 +1,120 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { existsSync, type FSWatcher, watch } from 'node:fs';
+import { join } from 'node:path';
+import { executeGitCommand } from './git-utils.js';
+import type { HandlerContext } from './handler-context.js';
+
+/**
+ * Watches .git/HEAD and .git/worktrees/ for branch changes and
+ * broadcasts updates to all connected web clients.
+ */
+export class GitHeadWatcher {
+  private headWatcher: FSWatcher | null = null;
+  private worktreeWatcher: FSWatcher | null = null;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastKnownBranch = '';
+  private lastKnownWorktreeBranches = new Map<string, string>();
+  private started = false;
+
+  constructor(
+    private readonly workingDir: string,
+    private readonly ctx: HandlerContext,
+  ) {}
+
+  start(): void {
+    if (this.started) return;
+
+    const gitDir = join(this.workingDir, '.git');
+    if (!existsSync(gitDir)) return;
+
+    this.initLastKnownBranches();
+
+    try {
+      this.headWatcher = watch(join(gitDir, 'HEAD'), () => this.debounce());
+    } catch { /* not a git repo or permission issue */ }
+
+    this.startWorktreeWatcher();
+    this.started = true;
+  }
+
+  startWorktreeWatcher(): void {
+    if (this.worktreeWatcher) return;
+    try {
+      const worktreesDir = join(this.workingDir, '.git', 'worktrees');
+      if (!existsSync(worktreesDir)) return;
+      this.worktreeWatcher = watch(worktreesDir, { recursive: true }, (_event, filename) => {
+        if (filename?.endsWith('HEAD')) this.debounce();
+      });
+    } catch { /* recursive watch not supported or dir missing */ }
+  }
+
+  stop(): void {
+    if (this.headWatcher) { this.headWatcher.close(); this.headWatcher = null; }
+    if (this.worktreeWatcher) { this.worktreeWatcher.close(); this.worktreeWatcher = null; }
+    if (this.debounceTimer) { clearTimeout(this.debounceTimer); this.debounceTimer = null; }
+    this.started = false;
+  }
+
+  private async initLastKnownBranches(): Promise<void> {
+    try {
+      const result = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], this.workingDir);
+      if (result.exitCode === 0) this.lastKnownBranch = result.stdout.trim();
+    } catch { /* ignore */ }
+
+    for (const [tabId, wtPath] of this.ctx.gitDirectories) {
+      if (wtPath === this.workingDir) continue;
+      try {
+        const result = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], wtPath);
+        if (result.exitCode === 0) this.lastKnownWorktreeBranches.set(tabId, result.stdout.trim());
+      } catch { /* ignore */ }
+    }
+  }
+
+  private debounce(): void {
+    if (this.debounceTimer) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => { this.handleChange(); }, 300);
+  }
+
+  private async handleChange(): Promise<void> {
+    try {
+      await this.checkMainBranch();
+      await this.checkWorktreeBranches();
+    } catch { /* ignore errors from concurrent git operations */ }
+  }
+
+  private async checkMainBranch(): Promise<void> {
+    const result = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], this.workingDir);
+    if (result.exitCode !== 0) return;
+    const branch = result.stdout.trim();
+    if (!branch || branch === this.lastKnownBranch) return;
+    this.lastKnownBranch = branch;
+    this.ctx.broadcastToAll({
+      type: 'gitBranchChanged',
+      data: { directory: this.workingDir, branch },
+    });
+  }
+
+  private async checkWorktreeBranches(): Promise<void> {
+    for (const [tabId, wtPath] of this.ctx.gitDirectories) {
+      if (wtPath === this.workingDir) continue;
+      try {
+        const result = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], wtPath);
+        if (result.exitCode !== 0) continue;
+        const branch = result.stdout.trim();
+        if (!branch) continue;
+        const lastBranch = this.lastKnownWorktreeBranches.get(tabId);
+        if (branch === lastBranch) continue;
+        this.lastKnownWorktreeBranches.set(tabId, branch);
+        this.ctx.gitBranches.set(tabId, branch);
+        const registry = this.ctx.getRegistry(this.workingDir);
+        registry.updateTabWorktree(tabId, wtPath, branch);
+        this.ctx.broadcastToAll({
+          type: 'gitBranchChanged',
+          data: { directory: wtPath, branch },
+        });
+      } catch { /* ignore */ }
+    }
+  }
+}

package/server/services/websocket/git-worktree-handlers.ts

@@ -1,11 +1,35 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
 // Licensed under the MIT License. See LICENSE file for details.
 
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { resolvePmDir } from '../plan/parser.js';
+import type { Workspace } from '../plan/types.js';
 import { executeGitCommand, handleGitStatus, spawnWithOutput } from './git-handlers.js';
 import type { HandlerContext } from './handler-context.js';
 import type { WebSocketMessage, WorktreeInfo, WSContext } from './types.js';
 
+function persistBoardWorktree(workingDir: string, boardId: string, worktreePath: string | null, branch: string | null): void {
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+  const wsPath = join(pmDir, 'workspace.json');
+  if (!existsSync(wsPath)) return;
+  try {
+    const workspace: Workspace = JSON.parse(readFileSync(wsPath, 'utf-8'));
+    if (!workspace.boardWorktrees) workspace.boardWorktrees = {};
+    if (worktreePath && branch) {
+      workspace.boardWorktrees[boardId] = { path: worktreePath, branch };
+    } else {
+      delete workspace.boardWorktrees[boardId];
+    }
+    writeFileSync(wsPath, JSON.stringify(workspace, null, 2), 'utf-8');
+  } catch { /* non-fatal */ }
+}
+
+function isBoardId(id: string): boolean {
+  return id.startsWith('BOARD-');
+}
+
 export async function handleGitWorktreeMessage(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, gitDir: string, workingDir: string): Promise<void> {
   const handlers: Record<string, () => Promise<void>> = {
     gitWorktreeList: () => handleGitWorktreeList(ctx, ws, tabId, gitDir),
@@ -116,6 +140,9 @@ async function handleGitWorktreeCreateAndAssign(ctx: HandlerContext, ws: WSConte
     ctx.gitBranches.set(tabId, branchName);
     const registry = ctx.getRegistry(workingDir);
     registry.updateTabWorktree(tabId, wtPath, branchName);
+    if (isBoardId(tabId)) {
+      persistBoardWorktree(workingDir, tabId, wtPath, branchName);
+    }
 
     ctx.send(ws, {
       type: 'gitWorktreeCreatedAndAssigned',
@@ -129,6 +156,17 @@ async function handleGitWorktreeCreateAndAssign(ctx: HandlerContext, ws: WSConte
   }
 }
 
+function cleanupWorktreeReferences(ctx: HandlerContext, workingDir: string, wtPath: string): void {
+  const resolvedWtPath = join(wtPath);
+  for (const [tid, dir] of ctx.gitDirectories) {
+    if (dir === resolvedWtPath || dir === wtPath) {
+      ctx.gitDirectories.delete(tid);
+      ctx.gitBranches.delete(tid);
+      if (isBoardId(tid)) persistBoardWorktree(workingDir, tid, null, null);
+    }
+  }
+}
+
 async function handleGitWorktreeRemove(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string): Promise<void> {
   try {
     const { path: wtPath, force, deleteBranch } = msg.data || {};
@@ -155,15 +193,7 @@ async function handleGitWorktreeRemove(ctx: HandlerContext, ws: WSContext, msg:
     }
 
     await executeGitCommand(['worktree', 'prune'], workingDir);
-
-    // Clean up gitDirectories entries for any tabs referencing the removed worktree
-    const resolvedWtPath = join(wtPath); // normalize
-    for (const [tid, dir] of ctx.gitDirectories) {
-      if (dir === resolvedWtPath || dir === wtPath) {
-        ctx.gitDirectories.delete(tid);
-        ctx.gitBranches.delete(tid);
-      }
-    }
+    cleanupWorktreeReferences(ctx, workingDir, wtPath);
 
     ctx.send(ws, { type: 'gitWorktreeRemoved', tabId, data: { path: wtPath } });
   } catch (error: unknown) {
@@ -180,6 +210,9 @@ async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg:
       ctx.gitDirectories.delete(resolvedTabId);
       ctx.gitBranches.delete(resolvedTabId);
       registry.updateTabWorktree(resolvedTabId, null, null);
+      if (isBoardId(resolvedTabId)) {
+        persistBoardWorktree(workingDir, resolvedTabId, null, null);
+      }
       ctx.send(ws, { type: 'tabWorktreeSwitched', tabId: resolvedTabId, data: { tabId: resolvedTabId, worktreePath: workingDir, branch: '' } });
       handleGitStatus(ctx, ws, resolvedTabId, workingDir);
       return;
@@ -191,6 +224,9 @@ async function handleTabWorktreeSwitch(ctx: HandlerContext, ws: WSContext, msg:
     const branch = branchResult.stdout.trim();
     ctx.gitBranches.set(resolvedTabId, branch);
     registry.updateTabWorktree(resolvedTabId, worktreePath, branch);
+    if (isBoardId(resolvedTabId)) {
+      persistBoardWorktree(workingDir, resolvedTabId, worktreePath, branch);
+    }
 
     ctx.send(ws, { type: 'tabWorktreeSwitched', tabId: resolvedTabId, data: { tabId: resolvedTabId, worktreePath, branch } });
     handleGitStatus(ctx, ws, resolvedTabId, worktreePath);
@@ -361,26 +397,44 @@ async function cleanupAfterMerge(
   strategy: string,
   deleteWorktree: boolean,
   deleteBranch: boolean,
-): Promise<void> {
+): Promise<{ warnings: string[]; removedWorktreePath: string | null }> {
+  const warnings: string[] = [];
+  let removedWorktreePath: string | null = null;
+
   if (deleteWorktree) {
     const wtList = await executeGitCommand(['worktree', 'list', '--porcelain'], mainPath);
     const worktreePath = findWorktreePathForBranch(wtList.stdout, sourceBranch);
     if (worktreePath && worktreePath !== mainPath) {
-      await executeGitCommand(['worktree', 'remove', worktreePath], mainPath);
+      const removeResult = await executeGitCommand(['worktree', 'remove', worktreePath], mainPath);
+      if (removeResult.exitCode !== 0) {
+        const forceResult = await executeGitCommand(['worktree', 'remove', '--force', worktreePath], mainPath);
+        if (forceResult.exitCode !== 0) {
+          warnings.push(`Failed to remove worktree: ${forceResult.stderr || 'unknown error'}`);
+        } else {
+          removedWorktreePath = worktreePath;
+        }
+      } else {
+        removedWorktreePath = worktreePath;
+      }
     }
   }
   if (deleteBranch) {
     const deleteFlag = strategy === 'squash' ? '-D' : '-d';
-    await executeGitCommand(['branch', deleteFlag, sourceBranch], mainPath);
+    const branchResult = await executeGitCommand(['branch', deleteFlag, sourceBranch], mainPath);
+    if (branchResult.exitCode !== 0) {
+      warnings.push(`Failed to delete branch: ${branchResult.stderr || 'unknown error'}`);
+    }
   }
   await executeGitCommand(['worktree', 'prune'], mainPath);
+  return { warnings, removedWorktreePath };
 }
 
 function findWorktreePathForBranch(porcelainOutput: string, branchName: string): string | null {
   let currentWtPath = '';
+  const fullRef = `refs/heads/${branchName}`;
   for (const line of porcelainOutput.split('\n')) {
     if (line.startsWith('worktree ')) currentWtPath = line.slice(9).trim();
-    if (line.startsWith('branch ') && line.includes(branchName)) return currentWtPath;
+    if (line.startsWith('branch ') && line.slice(7).trim() === fullRef) return currentWtPath;
   }
   return null;
 }
@@ -401,6 +455,8 @@ async function handleGitWorktreeMerge(ctx: HandlerContext, ws: WSContext, msg: W
       return;
     }
 
+    const headBefore = await executeGitCommand(['rev-parse', 'HEAD'], mainPath);
+
     const mergeResult = await executeMergeStrategy(strategy, sourceBranch, commitMessage, mainPath);
     if (mergeResult.exitCode !== 0) {
       const conflictFiles = await detectMergeConflicts(mainPath);
@@ -411,10 +467,24 @@ async function handleGitWorktreeMerge(ctx: HandlerContext, ws: WSContext, msg: W
       return;
     }
 
+    const headAfter = await executeGitCommand(['rev-parse', 'HEAD'], mainPath);
+    if (headBefore.stdout.trim() === headAfter.stdout.trim()) {
+      ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: false, error: `Already up to date — "${sourceBranch}" has no new commits to merge into "${targetBranch}"` } });
+      return;
+    }
+
     const commitHashResult = await executeGitCommand(['rev-parse', '--short', 'HEAD'], mainPath);
-    await cleanupAfterMerge(mainPath, sourceBranch, strategy, !!deleteWorktree, !!deleteBranch);
+    const { warnings, removedWorktreePath } = await cleanupAfterMerge(mainPath, sourceBranch, strategy, !!deleteWorktree, !!deleteBranch);
 
-    ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data: { success: true, mergeCommit: commitHashResult.stdout.trim() } });
+    if (removedWorktreePath) {
+      cleanupWorktreeReferences(ctx, workingDir, removedWorktreePath);
+    }
+
+    const data: Record<string, unknown> = { success: true, mergeCommit: commitHashResult.stdout.trim() };
+    if (warnings.length > 0) {
+      data.warnings = warnings;
+    }
+    ctx.send(ws, { type: 'gitWorktreeMergeResult', tabId, data });
   } catch (error: unknown) {
     ctx.send(ws, { type: 'gitError', tabId, data: { error: error instanceof Error ? error.message : String(error) } });
   }

package/server/services/websocket/handler-context.ts

@@ -5,6 +5,7 @@ import type { ChildProcess } from 'node:child_process';
 import type { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
 import type { AutocompleteService } from './autocomplete.js';
 import type { FileUploadHandler } from './file-upload-handler.js';
+import type { GitHeadWatcher } from './git-head-watcher.js';
 import type { SessionRegistry } from './session-registry.js';
 import type { WebSocketResponse, WSContext } from './types.js';
 
@@ -33,6 +34,7 @@ export interface HandlerContext {
   autocompleteService: AutocompleteService;
   usageReporter: UsageReporter | null;
   fileUploadHandler: FileUploadHandler | null;
+  gitHeadWatcher: GitHeadWatcher | null;
 
   // Registry access
   getRegistry(workingDir: string): SessionRegistry;

package/server/services/websocket/handler.ts

@@ -19,6 +19,7 @@ import { handleDeployMessage } from './deploy-handlers.js';
 import { handleFileExplorerMessage, handleFileMessage } from './file-explorer-handlers.js';
 import { FileUploadHandler } from './file-upload-handler.js';
 import { handleGitMessage } from './git-handlers.js';
+import { GitHeadWatcher } from './git-head-watcher.js';
 import type { HandlerContext, UsageReporter } from './handler-context.js';
 import { handlePlanMessage } from './plan-handlers.js';
 import { handleQualityMessage } from './quality-handlers.js';
@@ -46,6 +47,7 @@ export class WebSocketImproviseHandler implements HandlerContext {
   terminalListenerCleanups: Map<string, () => void> = new Map();
   terminalSubscribers: Map<string, Set<WSContext>> = new Map();
   fileUploadHandler: FileUploadHandler | null = null;
+  gitHeadWatcher: GitHeadWatcher | null = null;
 
   constructor() {
     this.frecencyPath = join(homedir(), '.mstro', 'autocomplete-frecency.json');
@@ -103,9 +105,14 @@ export class WebSocketImproviseHandler implements HandlerContext {
     }
   }
 
-  handleConnection(ws: WSContext, _workingDir: string): void {
+  handleConnection(ws: WSContext, workingDir: string): void {
     this.connections.set(ws, new Map());
     this.allConnections.add(ws);
+
+    if (!this.gitHeadWatcher && workingDir) {
+      this.gitHeadWatcher = new GitHeadWatcher(workingDir, this);
+      this.gitHeadWatcher.start();
+    }
   }
 
   async handleMessage(
@@ -147,7 +154,7 @@ export class WebSocketImproviseHandler implements HandlerContext {
     // Quality
     qualityDetectTools: 'quality', qualityScan: 'quality', qualityInstallTools: 'quality', qualityCodeReview: 'quality', qualityFixIssues: 'quality', qualityLoadState: 'quality', qualitySaveDirectories: 'quality',
     // Plan + boards + sprints
-    planInit: 'plan', planGetState: 'plan', planListIssues: 'plan', planGetIssue: 'plan', planGetSprint: 'plan', planGetMilestone: 'plan', planCreateIssue: 'plan', planUpdateIssue: 'plan', planDeleteIssue: 'plan', planScaffold: 'plan', planPrompt: 'plan', planExecute: 'plan', planExecuteEpic: 'plan', planPause: 'plan', planStop: 'plan', planResume: 'plan', planCreateBoard: 'plan', planUpdateBoard: 'plan', planArchiveBoard: 'plan', planGetBoard: 'plan', planGetBoardState: 'plan', planReorderBoards: 'plan', planSetActiveBoard: 'plan', planGetBoardArtifacts: 'plan', planCreateSprint: 'plan', planActivateSprint: 'plan', planCompleteSprint: 'plan', planGetSprintArtifacts: 'plan',
+    planInit: 'plan', planGetState: 'plan', planListIssues: 'plan', planGetIssue: 'plan', planGetSprint: 'plan', planGetMilestone: 'plan', planCreateIssue: 'plan', planUpdateIssue: 'plan', planDeleteIssue: 'plan', planScaffold: 'plan', planPrompt: 'plan', planExecute: 'plan', planExecuteEpic: 'plan', planPause: 'plan', planStop: 'plan', planResume: 'plan', planCreateBoard: 'plan', planUpdateBoard: 'plan', planArchiveBoard: 'plan', planGetBoard: 'plan', planGetBoardState: 'plan', planReorderBoards: 'plan', planSetActiveBoard: 'plan', planGetBoardArtifacts: 'plan', planCreateSprint: 'plan', planActivateSprint: 'plan', planCompleteSprint: 'plan', planGetSprintArtifacts: 'plan', chatToBoard: 'plan',
     // File upload
     fileUploadStart: 'fileUpload', fileUploadChunk: 'fileUpload', fileUploadComplete: 'fileUpload', fileUploadCancel: 'fileUpload',
     // Deploy management + HTTP relay
@@ -243,10 +250,16 @@ export class WebSocketImproviseHandler implements HandlerContext {
     this.allConnections.delete(ws);
     cleanupTerminalSubscribers(this, ws);
 
-    // Clean up file upload handler when no connections remain
-    if (this.allConnections.size === 0 && this.fileUploadHandler) {
-      this.fileUploadHandler.destroy();
-      this.fileUploadHandler = null;
+    // Clean up resources when no connections remain
+    if (this.allConnections.size === 0) {
+      if (this.fileUploadHandler) {
+        this.fileUploadHandler.destroy();
+        this.fileUploadHandler = null;
+      }
+      if (this.gitHeadWatcher) {
+        this.gitHeadWatcher.stop();
+        this.gitHeadWatcher = null;
+      }
     }
   }