mstro-app 0.4.52 → 0.5.1

package/server/services/plan/front-matter.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Front Matter Utilities — Read/write YAML front matter fields.

package/server/services/plan/issue-classification.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import type { Issue } from './types.js';
 

package/server/services/plan/issue-loader.ts

@@ -0,0 +1,63 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Issue loader: wraps parser.ts to load either board-scoped or
+ * project-level issues, emitting error/activation signals via callbacks
+ * so it stays decoupled from the EventEmitter in PlanExecutor.
+ */
+
+import { activateBoard } from './board-config.js';
+import type { WarnFn } from './issue-writer.js';
+import { parseBoardDirectory, parsePlanDirectory } from './parser.js';
+import type { Issue } from './types.js';
+
+export interface IssueLoaderHandlers {
+  /** Invoked when the board/project is in an unloadable state (not found, paused, etc.). */
+  onError: (message: string) => void;
+  /** Invoked to forward warnings from `activateBoard` side-effects. */
+  warn: WarnFn;
+}
+
+/**
+ * Load issues from a specific board, auto-activating draft boards.
+ * Returns null on error (and invokes `handlers.onError`).
+ */
+export async function loadBoardIssues(
+  pmDir: string,
+  boardId: string,
+  handlers: IssueLoaderHandlers,
+): Promise<Issue[] | null> {
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (!boardState) {
+    handlers.onError(`Board not found: ${boardId}`);
+    return null;
+  }
+  if (boardState.state.paused) {
+    handlers.onError('Board is paused');
+    return null;
+  }
+  if (boardState.board.status === 'draft') {
+    await activateBoard(pmDir, boardId, handlers.warn);
+  } else if (boardState.board.status !== 'active') {
+    handlers.onError(`Board ${boardId} is not active (status: ${boardState.board.status})`);
+    return null;
+  }
+  return boardState.issues;
+}
+
+/** Load project-level issues (legacy or no boards). Returns null on error. */
+export function loadProjectIssues(
+  workingDir: string,
+  handlers: Pick<IssueLoaderHandlers, 'onError'>,
+): Issue[] | null {
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) {
+    handlers.onError('No PM directory found');
+    return null;
+  }
+  if (fullState.state.paused) {
+    handlers.onError('Project is paused');
+    return null;
+  }
+  return fullState.issues;
+}

package/server/services/plan/issue-prompt-builder.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Issue Prompt Builder — Constructs a prompt for a single headless Claude Code instance.

package/server/services/plan/issue-retry.ts

@@ -1,8 +1,7 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
-import type { SessionResult } from '../../cli/headless/types.js';
+import type { SessionResult, ToolUseEvent } from '../../cli/headless/types.js';
 
 export interface IssueRunnerConfig {
   workingDir: string;
@@ -12,6 +11,8 @@ export interface IssueRunnerConfig {
   stallHardCapMs: number;
   stallMaxExtensions: number;
   outputCallback?: (text: string) => void;
+  thinkingCallback?: (text: string) => void;
+  toolUseCallback?: (event: ToolUseEvent) => void;
   extraEnv?: Record<string, string>;
   abortSignal?: AbortSignal;
 }
@@ -27,6 +28,8 @@ export async function runIssueWithRetry(config: IssueRunnerConfig): Promise<Sess
     stallHardCapMs: config.stallHardCapMs,
     stallMaxExtensions: config.stallMaxExtensions,
     outputCallback: config.outputCallback,
+    thinkingCallback: config.thinkingCallback,
+    toolUseCallback: config.toolUseCallback,
     verbose: true,
     extraEnv: config.extraEnv,
     abortSignal: config.abortSignal,

package/server/services/plan/issue-writer.ts

@@ -0,0 +1,136 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Issue file mutations: front-matter status updates, activity note appends,
+ * stale-issue recovery, and wave-revert logic used by the plan executor.
+ */
+
+import { readFile, writeFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { checkAllAcceptanceCriteria, setFrontMatterFieldAsync } from './front-matter.js';
+import type { Issue } from './types.js';
+
+/** Emits a warning message — caller typically maps this to executor 'output' events. */
+export type WarnFn = (message: string, issueId?: string) => void;
+
+/** Matches the `status: <value>` front-matter line (YAML-style, first occurrence). */
+const STATUS_LINE_PATTERN = /^status:\s*(\S+)/m;
+
+/**
+ * Extract the `status:` front-matter value from an issue-file body. Returns
+ * `null` if the field is missing or malformed. Lives here alongside the other
+ * front-matter mutators so all modules parse the status identically.
+ */
+export function extractIssueStatus(content: string): string | null {
+  return content.match(STATUS_LINE_PATTERN)?.[1] ?? null;
+}
+
+/**
+ * Resolve an issue's relative path against a base directory, ensuring it
+ * stays inside the base (guards against `..` and absolute-path escapes).
+ */
+export function validateIssuePath(issuePath: string, baseDir: string): string {
+  const resolvedBase = resolve(baseDir);
+  const resolvedFull = resolve(resolvedBase, issuePath);
+  const rel = relative(resolvedBase, resolvedFull);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
+  }
+  return resolvedFull;
+}
+
+/**
+ * Update an issue's `status:` front-matter field, and — when transitioning
+ * to `done` — check off any remaining acceptance-criteria checkboxes.
+ */
+export async function updateIssueFrontMatter(
+  pmDir: string,
+  issuePath: string,
+  newStatus: string,
+  warn: WarnFn,
+): Promise<void> {
+  try {
+    const fullPath = validateIssuePath(issuePath, pmDir);
+    await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
+
+    if (newStatus === 'done') {
+      const content = await readFile(fullPath, 'utf-8');
+      const updated = checkAllAcceptanceCriteria(content);
+      if (updated !== content) await writeFile(fullPath, updated, 'utf-8');
+    }
+  } catch (err) {
+    warn(`Warning: failed to update issue front matter for ${issuePath}: ${errMsg(err)}`);
+  }
+}
+
+/**
+ * After a wave fails, revert any issue still stuck in `in_progress` back to
+ * its pre-wave status. Silently skips issues already out of `in_progress`.
+ */
+export async function revertIncompleteIssues(
+  pmDir: string,
+  issues: Issue[],
+  warn: WarnFn,
+): Promise<void> {
+  for (const issue of issues) {
+    const fullPath = validateIssuePath(issue.path, pmDir);
+    try {
+      const content = await readFile(fullPath, 'utf-8');
+      if (extractIssueStatus(content) === 'in_progress') {
+        await updateIssueFrontMatter(pmDir, issue.path, issue.status, warn);
+      }
+    } catch (err) {
+      warn(`Warning: failed to revert issue status: ${errMsg(err)}`, issue.id);
+    }
+  }
+}
+
+/** Append a cancellation note to the issue's `## Activity` section. */
+export async function appendCancellationNote(
+  pmDir: string,
+  issue: Issue,
+  reason: string,
+  warn: WarnFn,
+): Promise<void> {
+  const fullPath = validateIssuePath(issue.path, pmDir);
+  try {
+    let content = await readFile(fullPath, 'utf-8');
+    const entry = `- Cancelled (${new Date().toISOString().split('T')[0]}): ${reason}`;
+    if (content.includes('## Activity')) {
+      content = content.replace(/## Activity/, `## Activity\n${entry}`);
+    } else {
+      content += `\n\n## Activity\n${entry}`;
+    }
+    await writeFile(fullPath, content, 'utf-8');
+  } catch (err) {
+    warn(`Warning: failed to append cancellation note: ${errMsg(err)}`, issue.id);
+  }
+}
+
+/**
+ * Recover from a previous interrupted execution by reverting stale
+ * `in_progress` and `in_review` issues back to `todo`. Returns the list of
+ * recovered issue descriptors (e.g. "FEAT-012 (in_progress → todo)") so the
+ * caller can emit a single summary event.
+ */
+export async function recoverStaleIssues(
+  pmDir: string,
+  issues: Issue[],
+  warn: WarnFn,
+): Promise<string[]> {
+  const staleStatuses = new Set(['in_progress', 'in_review']);
+  const recovered: string[] = [];
+
+  for (const issue of issues) {
+    if (issue.type === 'epic') continue;
+    if (staleStatuses.has(issue.status)) {
+      await updateIssueFrontMatter(pmDir, issue.path, 'todo', warn);
+      recovered.push(`${issue.id} (${issue.status} → todo)`);
+    }
+  }
+  return recovered;
+}
+
+function errMsg(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}

package/server/services/plan/output-manager.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Output Manager — Resolves output paths, lists existing docs, and publishes outputs.
@@ -9,6 +8,7 @@
 
 import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { extractIssueStatus } from './issue-writer.js';
 import { defaultPmDir, resolvePmDir } from './parser.js';
 import type { Issue } from './types.js';
 
@@ -90,7 +90,7 @@ function publishSingleOutput(
   // Only publish for confirmed-done issues
   try {
     const content = readFileSync(join(pmDir, issue.path), 'utf-8');
-    if (!content.match(/^status:\s*done$/m)) return;
+    if (extractIssueStatus(content) !== 'done') return;
   } catch { return; }
 
   const srcPath = resolveOutputPath(issue, workingDir, sprintSandboxDir);

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * YAML front-matter parsing and entity parsers for PPS (.mstro/pm/) files.

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

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Legacy → Board-centric migration for .mstro/pm/ directories.

package/server/services/plan/parser.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * PPS Parser — Public API for reading .mstro/pm/ directories.

package/server/services/plan/progress-log.ts

@@ -0,0 +1,91 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Progress log writer: ensures output directories exist and appends
+ * per-wave markdown entries to the board or PM-dir progress.md.
+ */
+
+import { existsSync } from 'node:fs';
+import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { validateIssuePath, type WarnFn } from './issue-writer.js';
+import type { Issue } from './types.js';
+
+/** Create the board's or PM dir's `out/` directory if it doesn't exist. */
+export async function ensureOutputDirs(pmDir: string | null, boardDir: string | null): Promise<void> {
+  if (boardDir) {
+    const boardOutDir = join(boardDir, 'out');
+    if (!existsSync(boardOutDir)) await mkdir(boardOutDir, { recursive: true });
+    return;
+  }
+  if (pmDir) {
+    const outDir = join(pmDir, 'out');
+    if (!existsSync(outDir)) await mkdir(outDir, { recursive: true });
+  }
+}
+
+/**
+ * Append a wave summary section to progress.md (creating the file with a
+ * `# Board Progress` header if missing). Reads each issue's on-disk status
+ * to partition completed vs failed.
+ */
+export async function appendProgressEntry(
+  pmDir: string | null,
+  boardDir: string | null,
+  issues: Issue[],
+  waveStart: number,
+  warn: WarnFn,
+): Promise<void> {
+  if (!pmDir) return;
+
+  const progressPath = boardDir ? join(boardDir, 'progress.md') : join(pmDir, 'progress.md');
+  const durationMin = Math.round((Date.now() - waveStart) / 60_000);
+  const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
+
+  const { completed, failed } = await partitionByOnDiskStatus(pmDir, issues);
+
+  const lines = [
+    '',
+    `## ${timestamp} — Wave [${issues.map(i => i.id).join(', ')}]`,
+    '',
+    `- **Duration**: ${durationMin} min`,
+    `- **Completed**: ${completed.length}/${issues.length}${completed.length > 0 ? ` (${completed.join(', ')})` : ''}`,
+  ];
+  if (failed.length > 0) {
+    lines.push(`- **Failed**: ${failed.join(', ')}`);
+  }
+  lines.push('');
+
+  await writeProgressLines(progressPath, lines, warn);
+}
+
+async function partitionByOnDiskStatus(
+  pmDir: string,
+  issues: Issue[],
+): Promise<{ completed: string[]; failed: string[] }> {
+  const completed: string[] = [];
+  const failed: string[] = [];
+  for (const issue of issues) {
+    try {
+      const content = await readFile(validateIssuePath(issue.path, pmDir), 'utf-8');
+      const statusMatch = content.match(/^status:\s*(\S+)/m);
+      if (statusMatch?.[1] === 'done') completed.push(issue.id);
+      else failed.push(issue.id);
+    } catch {
+      failed.push(issue.id);
+    }
+  }
+  return { completed, failed };
+}
+
+async function writeProgressLines(filePath: string, lines: string[], warn: WarnFn): Promise<void> {
+  try {
+    if (existsSync(filePath)) {
+      await appendFile(filePath, `\n${lines.join('\n')}`, 'utf-8');
+    } else {
+      await writeFile(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
+    }
+  } catch (err) {
+    warn(`Warning: failed to write progress log: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

package/server/services/plan/prompt-builder.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Prompt Builder — Constructs the Agent Teams coordinator prompt.
@@ -28,23 +27,40 @@ export interface CoordinatorPromptOptions {
  */
 export function buildCoordinatorPrompt(options: CoordinatorPromptOptions): string {
   const { issues, workingDir, pmDir, boardDir, existingDocs, resolveOutputPath } = options;
-  const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(workingDir, '.mstro', 'pm', 'out');
+  const outDir = resolveOutDir(workingDir, pmDir, boardDir);
+  const teamName = `pm-wave-${Date.now()}`;
+
+  const issueBlocks = issues.map(issue => buildIssueBlock(issue, existingDocs, resolveOutputPath)).join('\n\n---\n\n');
+  const teammateSpawns = issues.map(issue => buildTeammateSpawn(issue, teamName, pmDir, existingDocs, resolveOutputPath)).join('\n\n');
+
+  return assembleCoordinatorPrompt({ issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns });
+}
+
+function resolveOutDir(workingDir: string, pmDir: string | null, boardDir: string | null): string {
+  if (boardDir) return join(boardDir, 'out');
+  if (pmDir) return join(pmDir, 'out');
+  return join(workingDir, '.mstro', 'pm', 'out');
+}
 
-  const issueBlocks = issues.map(issue => {
-    const criteria = issue.acceptanceCriteria
-      .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
-      .join('\n');
+function buildIssueBlock(
+  issue: Issue,
+  existingDocs: string[],
+  resolveOutputPath: (issue: Issue) => string,
+): string {
+  const criteria = issue.acceptanceCriteria
+    .map(c => `- [${c.checked ? 'x' : ' '}] ${c.text}`)
+    .join('\n');
 
-    const files = issue.filesToModify.length > 0
-      ? `\nFiles to modify:\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}`
-      : '';
+  const files = issue.filesToModify.length > 0
+    ? `\nFiles to modify:\n${issue.filesToModify.map(f => `- ${f}`).join('\n')}`
+    : '';
 
-    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
-    const predecessorSection = predecessorDocs.length > 0
-      ? `\nPredecessor outputs to read:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
-      : '';
+  const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+  const predecessorSection = predecessorDocs.length > 0
+    ? `\nPredecessor outputs to read:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
+    : '';
 
-    return `### ${issue.id}: ${issue.title}
+  return `### ${issue.id}: ${issue.title}
 
 **Type**: ${issue.type} | **Priority**: ${issue.priority} | **Estimate**: ${issue.estimate ?? 'unestimated'}
 
@@ -59,32 +75,53 @@ ${issue.technicalNotes || 'None'}
 ${files}${predecessorSection}
 
 **Output file**: ${resolveOutputPath(issue)}`;
-  }).join('\n\n---\n\n');
-
-  const teamName = `pm-wave-${Date.now()}`;
-
-  const teammateSpawns = issues.map(issue => {
-    const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
-    const predInstr = predecessorDocs.length > 0
-      ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
-      : '';
-
-    const outputFile = resolveOutputPath(issue);
-
-    const fileOwnership = issue.filesToModify.length > 0
-      ? `\n> FILE OWNERSHIP: You own these files exclusively: ${issue.filesToModify.join(', ')}. Other teammates own all other files.`
-      : '';
+}
 
-    return `Spawn teammate **${issue.id.toLowerCase()}** using the **Agent** tool with \`team_name: "${teamName}"\` and \`name: "${issue.id.toLowerCase()}"\`:
+function buildTeammateSpawn(
+  issue: Issue,
+  teamName: string,
+  pmDir: string | null,
+  existingDocs: string[],
+  resolveOutputPath: (issue: Issue) => string,
+): string {
+  const predecessorDocs = resolvePredecessorDocs(issue, existingDocs);
+  const predInstr = predecessorDocs.length > 0
+    ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
+    : '';
+
+  const outputFile = resolveOutputPath(issue);
+
+  const fileOwnership = issue.filesToModify.length > 0
+    ? `\n> FILE OWNERSHIP: You own these files exclusively: ${issue.filesToModify.join(', ')}. Other teammates own all other files.`
+    : '';
+
+  return `Spawn teammate **${issue.id.toLowerCase()}** using the **Agent** tool with \`team_name: "${teamName}"\` and \`name: "${issue.id.toLowerCase()}"\`:
 > ${predInstr}Work on issue ${issue.id}: ${issue.title}.
 > Read the full spec at ${pmDir ? join(pmDir, issue.path) : issue.path}.
 > Execute all acceptance criteria.
 > Write all output and results to ${outputFile} — this is the handoff artifact for downstream issues.
 > After writing output, update the issue front matter: change \`status: in_progress\` to \`status: done\`.
 > The orchestrator manages STATE.md. Stay within this issue's scope.${fileOwnership}`;
-  }).join('\n\n');
+}
+
+interface AssembleArgs {
+  issues: Issue[];
+  workingDir: string;
+  pmDir: string | null;
+  outDir: string;
+  teamName: string;
+  issueBlocks: string;
+  teammateSpawns: string;
+}
+
+function assembleCoordinatorPrompt(args: AssembleArgs): string {
+  const { issues, workingDir, pmDir, outDir, teamName, issueBlocks, teammateSpawns } = args;
+  const issueCount = issues.length;
+  const plural = issueCount > 1 ? 's' : '';
+  const checklist = issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n');
+  const teammateNames = issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n');
 
-  return `You are the team lead coordinating ${issues.length} issue${issues.length > 1 ? 's' : ''} using Agent Teams.
+  return `You are the team lead coordinating ${issueCount} issue${plural} using Agent Teams.
 
 ## Project Directory
 Working directory: ${workingDir}
@@ -102,7 +139,7 @@ All team coordination uses exactly two tools:
 
 ### Step 1: Spawn all teammates in one message
 
-Send a single message containing ${issues.length} **Agent** tool calls. Include \`team_name: "${teamName}"\` and a unique \`name\` in each call. The team starts automatically when the first teammate is spawned — the \`team_name\` parameter handles all setup.
+Send a single message containing ${issueCount} **Agent** tool calls. Include \`team_name: "${teamName}"\` and a unique \`name\` in each call. The team starts automatically when the first teammate is spawned — the \`team_name\` parameter handles all setup.
 
 ${teammateSpawns}
 
@@ -113,10 +150,10 @@ After spawning, idle notifications arrive automatically as messages — you will
 Your first action after spawning all teammates: output a brief status message listing all teammates and confirming you are waiting for their idle notifications. Then wait.
 
 Track completion against this checklist — proceed to Step 3 only after all are checked:
-${issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n')}
+${checklist}
 
 Exact teammate names for SendMessage (messages to any other name are silently dropped):
-${issues.map(i => `- \`${i.id.toLowerCase()}\``).join('\n')}
+${teammateNames}
 
 When you receive an idle notification from a teammate:
 - Check off that teammate in the checklist above
@@ -143,7 +180,7 @@ After all outputs are verified:
 ## Coordination Rules
 
 - The team starts implicitly when you spawn the first teammate with \`team_name\`. Cleanup happens automatically when all teammates exit or the lead exits.
-- Wait for idle notifications from all ${issues.length} teammates before exiting — this ensures all work is saved to disk.
+- Wait for idle notifications from all ${issueCount} teammates before exiting — this ensures all work is saved to disk.
 - Each teammate writes its output to disk (the handoff artifact for downstream issues). Research kept only in conversation is lost when the teammate exits.
 - Each teammate updates its issue front matter status to \`done\` when finished.
 - One issue per teammate — each teammate stays within its assigned scope.

package/server/services/plan/readiness-planner.ts

@@ -0,0 +1,49 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Pure helpers for wave readiness: human-readable completion reasons
+ * and detection of "dead" issues stuck in non-terminal states.
+ */
+
+import type { Issue } from './types.js';
+
+const TERMINAL_STATUSES = new Set(['done', 'cancelled']);
+
+/** Build the user-facing completion message shown when no issues remain. */
+export function buildCompletionReason(issues: Issue[], epicScope: string | null): string {
+  const nonEpic = issues.filter(i => i.type !== 'epic');
+  const done = nonEpic.filter(i => TERMINAL_STATUSES.has(i.status)).length;
+  const blocked = nonEpic.filter(i => i.status === 'todo').length;
+  if (done === nonEpic.length) return epicScope ? 'All epic issues are done' : 'All issues are done';
+  if (blocked > 0) return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
+  return epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
+}
+
+/**
+ * Detect issues stuck in non-terminal states with no path to completion.
+ * Returns a human-readable reason, or null when the board is healthy.
+ */
+export function detectDeadState(issues: Issue[]): string | null {
+  const nonEpic = issues.filter(i => i.type !== 'epic');
+  const stuck = nonEpic.filter(i => !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+  if (stuck.length === 0) return null;
+
+  const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
+
+  const issueByPath = new Map(issues.map(i => [i.path, i]));
+  const blockedByStuck = nonEpic.filter(i => {
+    if (i.status !== 'todo') return false;
+    return i.blockedBy.some(bp => {
+      const blocker = issueByPath.get(bp);
+      return blocker && !TERMINAL_STATUSES.has(blocker.status);
+    });
+  });
+  const blockedIds = blockedByStuck.map(i => i.id).join(', ');
+
+  return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
+}
+
+/** True iff any non-epic issue is stuck in a non-terminal, non-todo state. */
+export function hasBlockedIssues(issues: Issue[]): boolean {
+  return issues.some(i => i.type !== 'epic' && !TERMINAL_STATUSES.has(i.status) && i.status !== 'todo');
+}