mstro-app 0.5.1 → 0.5.5

package/server/services/settings.ts

@@ -15,10 +15,75 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import type { EngineId } from '../engines/types.js'
 
 const MSTRO_DIR = join(homedir(), '.mstro')
 const SETTINGS_FILE = join(MSTRO_DIR, 'settings.json')
 
+/**
+ * Configuration for the Layer-2 Bouncer classifier (the AI model that runs
+ * for every ambiguous tool call). The model MUST be flagged
+ * `bouncerEligible` in the engine's model catalogue — frontier models
+ * (Opus, GPT-4o, …) are deliberately disallowed because they slow the
+ * classifier path and degrade the whole security layer.
+ */
+export interface BouncerClassifierConfig {
+  engine: EngineId
+  /** Engine-specific model id, e.g. 'haiku', 'sonnet', 'openai/gpt-5-mini'. */
+  model: string
+}
+
+/**
+ * Canonical list of bouncer-eligible models per engine. Mirrors
+ * `web/src/components/views/SettingsView/constants.ts` — keep the two in
+ * sync. Only cheap/fast models appear here; if you need to add a model,
+ * check p50 latency < ~1s and JSON-mode capability first.
+ */
+export const BOUNCER_ELIGIBLE_MODELS: Record<EngineId, readonly string[]> = {
+  'claude-code': ['haiku', 'sonnet'],
+  opencode: [
+    'openai/gpt-5-mini',
+    'openai/gpt-5-nano',
+    'google/gemini-2.5-flash',
+    'ollama/llama3.1:8b',
+  ],
+}
+
+/** Default classifier — Claude Haiku. Matches the pre-feature-flag behavior. */
+export const DEFAULT_BOUNCER_CLASSIFIER: BouncerClassifierConfig = {
+  engine: 'claude-code',
+  model: 'haiku',
+}
+
+/**
+ * Validate a `BouncerClassifierConfig`. Rejects with a thrown `Error` when
+ * the model is not flagged `bouncerEligible` under the requested engine —
+ * e.g. attempting to use Opus as a classifier, or a frontier OpenCode
+ * model. The WebSocket settings handler uses this to reject crafted
+ * payloads from the web client.
+ */
+export function validateBouncerClassifier(config: unknown): BouncerClassifierConfig {
+  if (config === null || typeof config !== 'object') {
+    throw new Error('bouncerClassifier must be an object with { engine, model }')
+  }
+  const { engine, model } = config as { engine?: unknown; model?: unknown }
+  if (engine !== 'claude-code' && engine !== 'opencode') {
+    throw new Error(`bouncerClassifier.engine must be 'claude-code' or 'opencode' (got ${String(engine)})`)
+  }
+  if (typeof model !== 'string' || model.length === 0) {
+    throw new Error('bouncerClassifier.model must be a non-empty string')
+  }
+  const eligible = BOUNCER_ELIGIBLE_MODELS[engine]
+  if (!eligible.includes(model)) {
+    throw new Error(
+      `Model '${model}' is not bouncer-eligible for engine '${engine}'. ` +
+        `Eligible models: ${eligible.join(', ')}. ` +
+        `Frontier models (Opus, GPT-4o, etc.) are deliberately excluded to keep the classifier fast.`,
+    )
+  }
+  return { engine, model }
+}
+
 export interface MstroSettings {
   /**
    * Claude model to use for main execution.
@@ -37,11 +102,26 @@ export interface MstroSettings {
   effortLevel: string
   /** Per-repo preferred PR base branch, keyed by normalized remote URL */
   prBaseBranches?: Record<string, string>
+  /**
+   * Feature flag gating all OpenCode code paths (engine factory, classifier
+   * factory, and UI). When `false`, the system behaves byte-identically to
+   * pre-OpenCode main: no `opencode serve` subprocess, no classifier picker,
+   * no EngineSection/EnginePicker in the web UI. Resolution order in
+   * `isEngineSwapEnabled()`: env var → stored setting → NODE_ENV default.
+   */
+  engineSwap?: boolean
+  /**
+   * Which engine + model backs the Layer-2 Bouncer classifier. Defaults to
+   * `{ engine: 'claude-code', model: 'haiku' }`. Only models flagged
+   * `bouncerEligible` are accepted — see {@link validateBouncerClassifier}.
+   */
+  bouncerClassifier?: BouncerClassifierConfig
 }
 
 const DEFAULT_SETTINGS: MstroSettings = {
   model: 'opus',
-  effortLevel: 'auto'
+  effortLevel: 'auto',
+  bouncerClassifier: { ...DEFAULT_BOUNCER_CLASSIFIER },
 }
 
 /**
@@ -54,7 +134,11 @@ function ensureMstroDir(): void {
 }
 
 /**
- * Get current settings, merged with defaults for any missing fields
+ * Get current settings, merged with defaults for any missing fields. A
+ * persisted `bouncerClassifier` that is no longer bouncer-eligible (e.g. a
+ * catalogue change removed the model) is dropped in favor of the default
+ * and a warning is logged — the Bouncer must never silently run a
+ * non-eligible model just because someone edited settings.json by hand.
  */
 export function getSettings(): MstroSettings {
   if (!existsSync(SETTINGS_FILE)) {
@@ -64,10 +148,22 @@ export function getSettings(): MstroSettings {
   try {
     const content = readFileSync(SETTINGS_FILE, 'utf-8')
     const stored = JSON.parse(content)
-    return {
+    const merged: MstroSettings = {
       ...DEFAULT_SETTINGS,
       ...stored,
     }
+    if (stored && typeof stored === 'object' && 'bouncerClassifier' in stored) {
+      try {
+        merged.bouncerClassifier = validateBouncerClassifier(stored.bouncerClassifier)
+      } catch (err) {
+        console.warn(
+          '[settings] Stored bouncerClassifier is not bouncer-eligible, falling back to default:',
+          err instanceof Error ? err.message : String(err),
+        )
+        merged.bouncerClassifier = { ...DEFAULT_BOUNCER_CLASSIFIER }
+      }
+    }
+    return merged
   } catch (err) {
     console.warn('Failed to read settings file, using defaults:', err)
     return { ...DEFAULT_SETTINGS }
@@ -75,9 +171,18 @@ export function getSettings(): MstroSettings {
 }
 
 /**
- * Save full settings to disk
+ * Save full settings to disk. Rejects if `bouncerClassifier` is present but
+ * its model is not flagged `bouncerEligible` — this is the save-time half
+ * of the guard; `getSettings` enforces the read-time half. Together they
+ * ensure the Bouncer is never configured with a frontier model (Opus,
+ * GPT-4o, …) regardless of whether the mutation came from the web UI or a
+ * direct edit of settings.json.
  */
 export function saveSettings(settings: MstroSettings): void {
+  if (settings.bouncerClassifier !== undefined) {
+    // Throws on non-eligible model — callers must surface the error.
+    validateBouncerClassifier(settings.bouncerClassifier)
+  }
   ensureMstroDir()
   writeFileSync(SETTINGS_FILE, JSON.stringify(settings, null, 2), {
     mode: 0o600
@@ -116,6 +221,58 @@ export function setEffortLevel(effortLevel: string): void {
   saveSettings(settings)
 }
 
+/**
+ * Get the current Bouncer classifier configuration. Returns the default
+ * `{ engine: 'claude-code', model: 'haiku' }` when nothing is persisted.
+ */
+export function getBouncerClassifier(): BouncerClassifierConfig {
+  const settings = getSettings()
+  if (settings.bouncerClassifier) {
+    try {
+      return validateBouncerClassifier(settings.bouncerClassifier)
+    } catch {
+      // Stored config is no longer eligible (e.g. model removed from the
+      // catalogue). Fall back to the safe default rather than crashing.
+      return { ...DEFAULT_BOUNCER_CLASSIFIER }
+    }
+  }
+  return { ...DEFAULT_BOUNCER_CLASSIFIER }
+}
+
+/**
+ * Persist a new Bouncer classifier config. Throws if the model is not
+ * flagged `bouncerEligible` under the requested engine — callers should
+ * surface the error to the UI so the user sees a clear rejection reason.
+ */
+export function setBouncerClassifier(config: unknown): BouncerClassifierConfig {
+  const validated = validateBouncerClassifier(config)
+  const settings = getSettings()
+  settings.bouncerClassifier = validated
+  saveSettings(settings)
+  return validated
+}
+
+/**
+ * Resolve the engineSwap feature flag. Precedence:
+ *   1. `MSTRO_ENABLE_ENGINE_SWAP` env var ('true'|'1' → on, 'false'|'0' → off).
+ *   2. `engineSwap` field in `~/.mstro/settings.json`.
+ *   3. NODE_ENV default — off in production, on otherwise (dev/staging/test).
+ *
+ * Callers who need a single boolean should use this helper rather than
+ * reading the field directly, so the precedence stays in one place.
+ */
+export function isEngineSwapEnabled(): boolean {
+  const envFlag = process.env.MSTRO_ENABLE_ENGINE_SWAP
+  if (envFlag !== undefined) {
+    const normalized = envFlag.trim().toLowerCase()
+    if (normalized === 'true' || normalized === '1') return true
+    if (normalized === 'false' || normalized === '0') return false
+  }
+  const stored = getSettings().engineSwap
+  if (typeof stored === 'boolean') return stored
+  return process.env.NODE_ENV !== 'production'
+}
+
 /** Normalize a remote URL into a stable key (e.g. "github.com/owner/repo") */
 function normalizeRemoteUrl(remoteUrl: string): string {
   return remoteUrl

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

@@ -63,38 +63,52 @@ async function redirectToWorktreeIfBranchCheckedOut(
 
 export async function handleGitCheckout(ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string, rootWorkingDir: string): Promise<void> {
   try {
-    const { branch, create, startPoint } = msg.data || {};
+    const { branch, create, startPoint, worktreePath } = msg.data || {};
     if (!branch) {
       ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Branch name is required' } });
       return;
     }
 
+    // `worktreePath` lets the caller target a specific working directory
+    // (typically the main repo) regardless of which tab is active. Used by
+    // the "Base branch" dropdown so checkout always lands on main, not on
+    // whichever worktree the user happened to be inspecting.
+    const targetDir = typeof worktreePath === 'string' && worktreePath.length > 0
+      ? worktreePath
+      : workingDir;
+
     // Skip the worktree redirect for `create` — a name collision there is a real user error.
-    if (!create && await redirectToWorktreeIfBranchCheckedOut(ctx, ws, tabId, branch, workingDir, rootWorkingDir)) {
+    if (!create && await redirectToWorktreeIfBranchCheckedOut(ctx, ws, tabId, branch, targetDir, rootWorkingDir)) {
       return;
     }
 
-    const statusResult = await executeGitCommand(['status', '--porcelain'], workingDir);
+    const statusResult = await executeGitCommand(['status', '--porcelain'], targetDir);
     if (statusResult.stdout.trim()) {
       ctx.send(ws, { type: 'gitError', tabId, data: { error: 'Commit or stash changes before switching branches' } });
       return;
     }
 
-    const prevResult = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], workingDir);
+    const prevResult = await executeGitCommand(['rev-parse', '--abbrev-ref', 'HEAD'], targetDir);
     const previous = prevResult.stdout.trim();
 
     const args = create
       ? ['checkout', '-b', branch, ...(startPoint ? [startPoint] : [])]
       : ['checkout', branch];
 
-    const result = await executeGitCommand(args, workingDir);
+    const result = await executeGitCommand(args, targetDir);
     if (result.exitCode !== 0) {
       ctx.send(ws, { type: 'gitError', tabId, data: { error: result.stderr || 'Failed to checkout branch' } });
       return;
     }
 
     ctx.send(ws, { type: 'gitCheckedOut', tabId, data: { branch, previous } });
-    // Re-fetch status after checkout - import handleGitStatus at call site
+    // Re-fetch status for the *tab's* dir (`workingDir`), not `targetDir`. When
+    // the caller targets a different directory via `worktreePath` (e.g. the
+    // main repo from a worktree-anchored tab), sending main-repo status keyed
+    // to the tab id would clobber the tab's worktree-scoped status display.
+    // The web side fires a fresh `gitStatus` + `gitWorktreeList` on the
+    // `gitCheckedOut` handler, so the main-repo branch update propagates via
+    // the worktree list refresh.
     const { handleGitStatus } = await import('./git-handlers.js');
     handleGitStatus(ctx, ws, tabId, workingDir);
   } catch (error: unknown) {

package/server/services/websocket/handler.ts

@@ -12,6 +12,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
 import type { ImprovisationSessionManager } from '../../cli/improvisation-session-manager.js';
+import type { InstanceRegistry } from '../instances.js';
 import { captureException } from '../sentry.js';
 import { getPTYManager } from '../terminal/pty-manager.js';
 import { AutocompleteService } from './autocomplete.js';
@@ -30,7 +31,7 @@ import { generateNotificationSummary, handleGetSettings, handleUpdateSettings }
 import { handleListSkills } from './skill-handlers.js';
 import { SkillsWatcher } from './skill-watcher.js';
 import { TabEventBufferRegistry } from './tab-event-buffer.js';
-import { handleCreateTab, handleGetActiveTabs, handleMarkTabViewed, handleRemoveTab, handleReorderTabs, handleSyncTabMeta } from './tab-handlers.js';
+import { handleCreateTab, handleGetActiveTabs, handleMarkTabViewed, handleRemoveTab, handleReorderTabs, handleSetTabEngine, handleSyncTabMeta } from './tab-handlers.js';
 import { cleanupTerminalSubscribers, handleTerminalMessage } from './terminal-handlers.js';
 import type { FrecencyData, WebSocketMessage, WebSocketResponse, WSContext } from './types.js';
 
@@ -55,11 +56,14 @@ export class WebSocketImproviseHandler implements HandlerContext {
   skillsWatcher: SkillsWatcher | null = null;
   tabEventBuffers: TabEventBufferRegistry = new TabEventBufferRegistry();
   msgIdTracker: MsgIdTracker = new MsgIdTracker();
+  private instanceRegistry: InstanceRegistry | null;
+  private shutdownInProgress = false;
 
-  constructor() {
+  constructor(instanceRegistry: InstanceRegistry | null = null) {
     this.frecencyPath = join(homedir(), '.mstro', 'autocomplete-frecency.json');
     const frecencyData = this.loadFrecencyData();
     this.autocompleteService = new AutocompleteService(frecencyData);
+    this.instanceRegistry = instanceRegistry;
     process.on('exit', () => {
       if (this.frecencySaveTimer) {
         clearTimeout(this.frecencySaveTimer);
@@ -201,6 +205,9 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleRemoveTab(this, ws, tabId, workingDir);
       case 'markTabViewed':
         return handleMarkTabViewed(this, ws, tabId, workingDir);
+      case 'setTabEngine':
+        if (permission === 'view') return;
+        return handleSetTabEngine(this, ws, msg, tabId, workingDir);
       case 'getSettings':
         return handleGetSettings(this, ws);
       case 'updateSettings':
@@ -208,6 +215,8 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleUpdateSettings(this, ws, msg);
       case 'listSkills':
         return handleListSkills(this, ws, workingDir);
+      case 'shutdownInstance':
+        return this.handleShutdownInstance(ws, permission);
     }
 
     // Dispatch table lookup for domain handlers
@@ -382,4 +391,52 @@ export class WebSocketImproviseHandler implements HandlerContext {
     this.sessions.delete(sessionId);
   }
 
+  /**
+   * Handle a `shutdownInstance` control message from a web client.
+   *
+   * Authorization: only the orchestra owner may shut down. The relay tags
+   * shared (view-only) users with `_permission: 'view'`; absence means the
+   * requester is the owner whose CLI this is. View-only requests are
+   * rejected with a `forbidden` error rather than silently dropped so the
+   * UI can surface "you're not the owner" to non-owners.
+   *
+   * Idempotency: a shutdown already in progress is acked (broadcast +
+   * exit timer were already scheduled) but does not stack a second timer.
+   */
+  private handleShutdownInstance(ws: WSContext, permission: 'view' | undefined): void {
+    if (permission === 'view') {
+      console.log('[WebSocketImproviseHandler] Rejecting shutdownInstance from view-only user');
+      this.send(ws, {
+        type: 'error',
+        data: {
+          code: 'forbidden',
+          message: 'Only the owner can shut down this instance.'
+        }
+      });
+      return;
+    }
+
+    if (this.shutdownInProgress) {
+      console.log('[WebSocketImproviseHandler] shutdownInstance already in progress — ignoring duplicate request');
+      return;
+    }
+    this.shutdownInProgress = true;
+
+    // The CLI knows the request came from the owner (the relay only forwards
+    // owner traffic without a `_permission` tag), but does not receive the
+    // owner's userId on the wire. Logged as 'owner' for the audit trail.
+    console.log('[WebSocketImproviseHandler] shutdownInstance requested by owner — broadcasting shuttingDown and exiting');
+
+    this.broadcastToAll({ type: 'shuttingDown', data: { reason: 'user-requested' } });
+
+    // Mirrors the HTTP /api/shutdown route's 100ms delay so the broadcast
+    // has a chance to flush before process.exit tears down the socket.
+    setTimeout(() => {
+      if (this.instanceRegistry) {
+        this.instanceRegistry.unregister();
+      }
+      process.exit(0);
+    }, 100);
+  }
+
 }

package/server/services/websocket/quality-complexity.ts

@@ -1,7 +1,7 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
 
 import { extname, relative } from 'node:path';
-import { chunkFileList, filesByExt, runCommand, type SourceFile } from './quality-tools.js';
+import { chunkFileList, filesByExt, isTestFile, runCommand, type SourceFile } from './quality-tools.js';
 import { biomeDiagToFinding, type Ecosystem, FUNCTION_LENGTH_THRESHOLD, isBiomeComplexityDiagnostic, isEslintComplexityRule, type QualityFinding } from './quality-types.js';
 
 const NODE_COMPLEXITY_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs'];
@@ -16,6 +16,26 @@ interface FunctionInfo {
   file: string;
   startLine: number;
   lines: number;
+  /** Approximate cyclomatic complexity (count of decision points). */
+  branches: number;
+}
+
+/**
+ * Decision-point keywords that approximate cyclomatic complexity. We count
+ * occurrences as a cheap proxy — McCabe's exact metric requires AST parsing,
+ * but the keyword count is highly correlated and good enough to distinguish
+ * "long but linear" (a flat sequence of statements) from "long and branchy"
+ * (deeply nested control flow).
+ *
+ * The user's task 2 requirement: "a 1000 line file might be just fine, not
+ * a violation at all, while another 1000 line file might be a severe mix of
+ * concerns" — same applies to functions. A long config-builder with one
+ * return statement is fine; a long monster with 40 if-branches is not.
+ */
+const BRANCH_KEYWORDS = /\b(?:if|else if|elif|for|while|case|catch|\?\s*\w|&&|\|\||\?\?)\b/g;
+
+function countBranches(body: string): number {
+  return (body.match(BRANCH_KEYWORDS) || []).length;
 }
 
 const JS_FUNC_PATTERN = /^(\s*)(export\s+)?(async\s+)?function\s+(\w+)|^(\s*)(export\s+)?(const|let|var)\s+(\w+)\s*=\s*(async\s+)?\(|^(\s*)(public|private|protected)?\s*(async\s+)?(\w+)\s*\(/;
@@ -56,11 +76,15 @@ function extractJsFunctions(file: SourceFile): FunctionInfo[] {
     braceDepth += countBraceDeltas(lines[i]);
 
     if (currentFunc && braceDepth <= funcStartBraceDepth && i > currentFunc.startLine - 1) {
+      const startLine = currentFunc.startLine;
+      const endLine = i + 1;
+      const body = lines.slice(startLine - 1, endLine).join('\n');
       functions.push({
         name: currentFunc.name,
         file: file.relativePath,
-        startLine: currentFunc.startLine,
-        lines: i + 1 - currentFunc.startLine + 1,
+        startLine,
+        lines: endLine - startLine + 1,
+        branches: countBranches(body),
       });
       currentFunc = null;
     }
@@ -75,35 +99,29 @@ function extractPyFunctions(file: SourceFile): FunctionInfo[] {
   const defPattern = /^(\s*)(async\s+)?def\s+(\w+)/;
   let currentFunc: { name: string; startLine: number; indent: number } | null = null;
 
+  const recordFunction = (name: string, startLine: number, endLine: number) => {
+    const body = lines.slice(startLine - 1, endLine).join('\n');
+    functions.push({
+      name,
+      file: file.relativePath,
+      startLine,
+      lines: endLine - startLine + 1,
+      branches: countBranches(body),
+    });
+  };
+
   for (let i = 0; i < lines.length; i++) {
     const match = defPattern.exec(lines[i]);
     if (match) {
-      if (currentFunc) {
-        functions.push({
-          name: currentFunc.name,
-          file: file.relativePath,
-          startLine: currentFunc.startLine,
-          lines: i - currentFunc.startLine + 1,
-        });
-      }
+      if (currentFunc) recordFunction(currentFunc.name, currentFunc.startLine, i);
       currentFunc = { name: match[3], startLine: i + 1, indent: match[1].length };
     } else if (currentFunc && lines[i].trim() && !lines[i].startsWith(' '.repeat(currentFunc.indent + 1)) && !lines[i].startsWith('\t')) {
-      functions.push({
-        name: currentFunc.name,
-        file: file.relativePath,
-        startLine: currentFunc.startLine,
-        lines: i - currentFunc.startLine + 1,
-      });
+      recordFunction(currentFunc.name, currentFunc.startLine, i);
       currentFunc = null;
     }
   }
   if (currentFunc) {
-    functions.push({
-      name: currentFunc.name,
-      file: file.relativePath,
-      startLine: currentFunc.startLine,
-      lines: lines.length - currentFunc.startLine + 1,
-    });
+    recordFunction(currentFunc.name, currentFunc.startLine, lines.length);
   }
 
   return functions;
@@ -116,9 +134,37 @@ function extractFunctions(file: SourceFile): FunctionInfo[] {
   return [];
 }
 
+/**
+ * Map a function's branch density (decision points per N lines) to a
+ * severity level for the function-length finding. Returns `null` to suppress
+ * the finding for a long but linear function — e.g., a config-builder with
+ * one return statement and 200 lines of property assignments.
+ *
+ * Heuristic: McCabe's cyclomatic complexity threshold is ~10. Above that,
+ * functions are hard to test. We grade severity by branches-per-50-lines so
+ * a 100-line function with 5 branches looks the same as a 50-line function
+ * with 5 branches (both ~industry "consider refactoring" zone).
+ *
+ * Functions absurdly long (>5x threshold) emit a finding regardless of
+ * branchiness — a 250-line function is too much to read in one sitting even
+ * if it's "linear."
+ */
+function severityFromBranchiness(branches: number, lines: number): QualityFinding['severity'] | null {
+  const branchesPer50 = (branches * 50) / Math.max(1, lines);
+  const isAbsurd = lines > FUNCTION_LENGTH_THRESHOLD * 5;
+  if (branchesPer50 < 3 && !isAbsurd) return null; // Long but linear — not really a violation.
+  if (branchesPer50 < 6) return 'low';
+  if (branchesPer50 < 10) return 'medium';
+  return 'high';
+}
+
 export function analyzeFunctionLength(files: SourceFile[]): { score: number; findings: QualityFinding[]; issueCount: number } {
   const allFunctions: FunctionInfo[] = [];
   for (const file of files) {
+    // Test files are exempt: a long `it()`/`describe()` body is normal and
+    // splitting it produces churn without improving readability. Linting
+    // and other quality checks still apply — only structural-length defers.
+    if (isTestFile(file.relativePath)) continue;
     allFunctions.push(...extractFunctions(file));
   }
 
@@ -133,13 +179,21 @@ export function analyzeFunctionLength(files: SourceFile[]): { score: number; fin
     totalScore += funcScore;
 
     if (func.lines > FUNCTION_LENGTH_THRESHOLD) {
+      const severity = severityFromBranchiness(func.branches, func.lines);
+      if (!severity) continue; // Long but linear — not flagged.
+
       findings.push({
-        severity: func.lines > FUNCTION_LENGTH_THRESHOLD * 3 ? 'high' : func.lines > FUNCTION_LENGTH_THRESHOLD * 2 ? 'medium' : 'low',
+        severity,
         category: 'function-length',
         file: func.file,
         line: func.startLine,
-        title: `${func.name}() has ${func.lines} lines (threshold: ${FUNCTION_LENGTH_THRESHOLD})`,
-        description: `Function "${func.name}" exceeds the recommended length by ${func.lines - FUNCTION_LENGTH_THRESHOLD} lines.`,
+        title: `${func.name}() has ${func.lines} lines, ~${func.branches} branches`,
+        description:
+          `Function "${func.name}" exceeds the ${FUNCTION_LENGTH_THRESHOLD}-line threshold by ${func.lines - FUNCTION_LENGTH_THRESHOLD} lines ` +
+          `with approximately ${func.branches} decision points (cyclomatic complexity proxy). ` +
+          (severity === 'high'
+            ? 'High branchiness makes this hard to test and review — extract sub-functions or simplify control flow.'
+            : 'Long but with manageable branching — consider extracting helpers if the function does multiple things.'),
       });
     }
   }