mstro-app 0.3.9 → 0.4.0

package/server/cli/headless/stall-assessor.ts

@@ -49,6 +49,35 @@ export interface StallVerdict {
   reason: string;
 }
 
+/** Check if Task/Agent subagents are currently pending (producing expected silence) */
+function hasSubagentPending(pendingNames: Set<string>, lastToolName: string | undefined, hasPendingTools: boolean): boolean {
+  return pendingNames.has('Task') || pendingNames.has('Agent')
+    || ((lastToolName === 'Task' || lastToolName === 'Agent') && hasPendingTools);
+}
+
+/**
+ * Check if an Agent Teams lead is idle-waiting for teammate notifications.
+ * After spawning teammates (Agent tool calls complete), the lead has no pending
+ * tools but is legitimately waiting for teammate idle events.
+ */
+function checkAgentTeamsWaiting(ctx: StallContext, hasPendingTools: boolean): StallVerdict | null {
+  // The lead may use any tool while waiting (Glob to verify outputs, Bash to
+  // check disk, ToolSearch, etc.), so don't gate on lastToolName. The key
+  // signal is: prompt contains team_name, tools were called, nothing pending.
+  if (
+    !hasPendingTools &&
+    ctx.totalToolCalls > 0 &&
+    ctx.originalPrompt.includes('team_name')
+  ) {
+    return {
+      action: 'extend',
+      extensionMs: 30 * 60_000,
+      reason: 'Agent Teams lead waiting for teammate idle notifications — extending 30 min',
+    };
+  }
+  return null;
+}
+
 /**
  * Fast heuristic for known long-running patterns.
  * Returns a verdict immediately if the pattern is recognized, null otherwise.
@@ -87,11 +116,7 @@ function quickHeuristic(ctx: StallContext, toolWatchdogActive = false): StallVer
 
   // Task/subagent launches are known to produce long silence periods.
   // The parent Claude process emits nothing while waiting for subagent results.
-  // Check pendingToolNames (reliable) first, fall back to lastToolName (legacy).
-  // Claude Code renamed Task → Agent; check both for backward compatibility
-  const hasTaskPending = pendingNames.has('Task') || pendingNames.has('Agent')
-    || ((ctx.lastToolName === 'Task' || ctx.lastToolName === 'Agent') && hasPendingTools);
-  if (hasTaskPending) {
+  if (hasSubagentPending(pendingNames, ctx.lastToolName, hasPendingTools)) {
     const extensionMin = Math.min(30, 10 + ctx.pendingToolCount * 5);
     return {
       action: 'extend',
@@ -100,6 +125,10 @@ function quickHeuristic(ctx: StallContext, toolWatchdogActive = false): StallVer
     };
   }
 
+  // Agent Teams lead waiting for teammate idle notifications (extracted for complexity)
+  const agentTeamsVerdict = checkAgentTeamsWaiting(ctx, hasPendingTools);
+  if (agentTeamsVerdict) return agentTeamsVerdict;
+
   // Multiple parallel tool calls (e.g., parallel Bash, parallel Read/Grep)
   if (ctx.pendingToolCount >= 3) {
     return {

package/server/cli/improvisation-session-manager.ts

@@ -1089,7 +1089,7 @@ export class ImprovisationSessionManager extends EventEmitter {
     isMaxTokens: boolean,
   ): void {
     state.retryNumber++;
-    const reason = isMaxTokens ? 'max_tokens hit' : 'incomplete end_turn (Haiku assessment)';
+    const reason = isMaxTokens ? 'Output limit reached' : 'Task appears unfinished (AI assessment)';
 
     state.retryLog.push({
       retryNumber: state.retryNumber,
@@ -1113,7 +1113,7 @@ export class ImprovisationSessionManager extends EventEmitter {
     });
 
     this.queueOutput(
-      `\n[[MSTRO_AUTO_CONTINUE]] Task incomplete (${reason}) — resuming session (retry ${state.retryNumber}/${maxRetries}).\n`
+      `\n[[MSTRO_AUTO_CONTINUE]] ${reason} — resuming session (retry ${state.retryNumber}/${maxRetries}).\n`
     );
     this.flushOutputQueue();
 

package/server/services/plan/dependency-resolver.ts

@@ -158,6 +158,9 @@ export function computeCriticalPath(issues: Issue[]): Issue[] {
       return [];
     }
 
+    // Set sentinel before recursing to break cycles
+    longestFrom.set(path, [issue]);
+
     let best: Issue[] = [];
     for (const dep of issue.blocks) {
       const sub = getLongest(dep);

package/server/services/plan/executor.ts

@@ -10,8 +10,8 @@
  */
 
 import { EventEmitter } from 'node:events';
-import { existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
 import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
 import { HeadlessRunner } from '../../cli/headless/index.js';
 import { generateMcpConfig } from '../../cli/headless/mcp-config.js';
@@ -121,11 +121,19 @@ export class PlanExecutor extends EventEmitter {
   // ── Wave execution (Agent Teams) ──────────────────────────────
 
   private async executeWave(issues: Issue[]): Promise<void> {
+    const waveStart = Date.now();
     const waveIds = issues.map(i => i.id);
     this.metrics.currentWaveIds = waveIds;
     this.metrics.issuesAttempted += issues.length;
     this.emit('waveStarted', { issueIds: waveIds });
 
+    // Ensure .pm/out/ exists for execution output
+    const pmDir = resolvePmDir(this.workingDir);
+    if (pmDir) {
+      const outDir = join(pmDir, 'out');
+      if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+    }
+
     // Pre-approve tools so teammates don't hit interactive permission prompts
     this.installTeammatePermissions();
 
@@ -171,22 +179,30 @@ export class PlanExecutor extends EventEmitter {
         error: error instanceof Error ? error.message : String(error),
       });
       this.revertIncompleteIssues(issues);
+    } finally {
+      // Clean up temporary configs — must run even if wave throws
+      this.uninstallBouncerForSubagents();
+      this.uninstallTeammatePermissions();
     }
 
-    // Clean up temporary configs
-    this.uninstallBouncerForSubagents();
-    this.uninstallTeammatePermissions();
-
-    // Reconcile STATE.md after wave
+    // Reconcile STATE.md and sprint statuses after wave
     reconcileState(this.workingDir);
     this.emit('stateUpdated');
+
+    // Copy confirmed-done outputs to user-specified output_file paths
+    this.publishOutputs(issues);
+
+    // Append progress log entry
+    this.appendProgressEntry(issues, waveStart);
+
     this.metrics.currentWaveIds = [];
   }
 
   /**
    * After a wave, check each issue's status on disk.
-   * The coordinator agent is instructed to mark issues as done via front matter,
-   * so we trust the disk state and update metrics accordingly.
+   * `status: done` in issue front matter is the single completion signal.
+   * Output doc existence is NOT used as a proxy — code-focused issues
+   * (bug fixes, refactors) don't produce docs but are still valid completions.
    */
   private reconcileWaveResults(issues: Issue[]): void {
     const pmDir = resolvePmDir(this.workingDir);
@@ -202,49 +218,20 @@ export class PlanExecutor extends EventEmitter {
         if (currentStatus === 'done') {
           this.metrics.issuesCompleted++;
           this.emit('issueCompleted', issue);
-        } else if (currentStatus === 'in_progress') {
-          // Agent didn't finish — check if output doc exists (partial completion)
-          const outputDoc = this.findOutputDoc(issue.id);
-          if (outputDoc) {
-            // Output was written but status not updated — mark done
-            this.updateIssueFrontMatter(issue.path, 'done');
-            this.metrics.issuesCompleted++;
-            this.emit('issueCompleted', issue);
-          } else {
-            // Genuinely incomplete — revert to prior status
-            this.updateIssueFrontMatter(issue.path, issue.status);
-            this.emit('issueError', {
-              issueId: issue.id,
-              error: 'Issue did not complete during wave execution',
-            });
-          }
+        } else {
+          // Not done — revert to prior status
+          this.updateIssueFrontMatter(issue.path, issue.status);
+          this.emit('issueError', {
+            issueId: issue.id,
+            error: 'Issue did not complete during wave execution',
+          });
         }
       } catch {
-        // File read error — treat as incomplete
         this.emit('issueError', { issueId: issue.id, error: 'Could not read issue file after wave' });
       }
     }
   }
 
-  /**
-   * Look for an output document matching an issue ID in .pm/docs/.
-   */
-  private findOutputDoc(issueId: string): string | null {
-    const pmDir = resolvePmDir(this.workingDir);
-    if (!pmDir) return null;
-    const docsDir = join(pmDir, 'docs');
-    if (!existsSync(docsDir)) return null;
-
-    try {
-      const files = readdirSync(docsDir);
-      const prefix = issueId.toLowerCase();
-      const match = files.find(f => f.toLowerCase().startsWith(prefix) && f.endsWith('.md'));
-      return match ? join(docsDir, match) : null;
-    } catch {
-      return null;
-    }
-  }
-
   // ── Issue picking ─────────────────────────────────────────────
 
   private pickReadyIssues(): Issue[] {
@@ -268,12 +255,13 @@ export class PlanExecutor extends EventEmitter {
 
   /**
    * Build the team lead prompt for a wave of issues.
-   * Uses Agent Teams (TeamCreate/SendMessage) for true parallel execution
-   * as separate processes — each teammate gets its own context window.
+   * Uses Agent Teams for true parallel execution as separate processes —
+   * each teammate gets its own context window and sends idle notifications
+   * when done. The team is created implicitly by the first Agent(team_name=...) call.
    */
   private buildCoordinatorPrompt(issues: Issue[]): string {
     const pmDir = resolvePmDir(this.workingDir);
-    const docsDir = pmDir ? join(pmDir, 'docs') : '.pm/docs';
+    const outDir = pmDir ? join(pmDir, 'out') : join(this.workingDir, '.pm', 'out');
 
     // Collect existing output docs that issues may need as input
     const existingDocs = this.listExistingDocs();
@@ -313,10 +301,9 @@ ${criteria || 'No specific criteria defined.'}
 ${issue.technicalNotes || 'None'}
 ${files}${predecessorSection}
 
-**Output file**: ${docsDir}/${issue.id}-${this.slugify(issue.title)}.md`;
+**Output file**: ${this.resolveOutputPath(issue)}`;
     }).join('\n\n---\n\n');
 
-    const teammateNames = issues.map(i => i.id.toLowerCase()).join(', ');
     const teamName = `pm-wave-${Date.now()}`;
 
     const teammateSpawns = issues.map(issue => {
@@ -331,7 +318,7 @@ ${files}${predecessorSection}
         ? `Read these predecessor output docs before starting: ${predecessorDocs.join(', ')}. `
         : '';
 
-      const outputFile = `${docsDir}/${issue.id}-${this.slugify(issue.title)}.md`;
+      const outputFile = this.resolveOutputPath(issue);
 
       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}.
@@ -354,40 +341,41 @@ ${issueBlocks}
 
 ## Execution Protocol — Agent Teams
 
-### Step 1: Create the team
+### Step 1: Spawn teammates
 
-Use **TeamCreate** to create a team named \`${teamName}\`.
+Spawn all ${issues.length} teammates in parallel by sending a single message with ${issues.length} **Agent** tool calls. Each call must include \`team_name: "${teamName}"\` and a unique \`name\`. The team is created automatically when you spawn the first teammate with \`team_name\` — no separate setup step is needed.
 
-### Step 2: Spawn teammates
+${teammateSpawns}
 
-Spawn all ${issues.length} teammates in parallel using the **Agent** tool with \`team_name\` and \`name\` parameters. Send a single message with ${issues.length} Agent tool calls.
+### Step 2: Wait for ALL teammates to complete
 
-${teammateSpawns}
+CRITICAL: After spawning, you MUST remain active and wait for every single teammate to finish. Each teammate automatically sends you an **idle notification** when they complete their work.
+
+Track completion against this checklist — ALL must report idle before you proceed:
+${issues.map(i => `- [ ] ${i.id.toLowerCase()}`).join('\n')}
 
-### Step 3: Monitor completion
+While waiting:
+- As each teammate goes idle, verify their output file exists on disk using the **Read** tool
+- If a teammate has not gone idle after 15 minutes, use **SendMessage** to check on them
+- Do NOT proceed to Step 3 until you have received idle notifications from ALL ${issues.length} teammates
 
-After spawning all teammates, poll for completion:
-1. Use **SendMessage** to each teammate (${teammateNames}) asking for status
-2. A teammate is done when its output file exists on disk AND the issue status is \`done\`
-3. If a teammate reports completion, verify by reading the output file yourself
-4. If a teammate is struggling, provide guidance via SendMessage
+WARNING: The #1 failure mode is exiting before all teammates finish. If you exit early, all teammate processes are killed and their work is permanently lost. When in doubt, keep waiting. Err on the side of waiting too long rather than exiting too early.
 
-### Step 4: Verify and clean up
+### Step 3: Verify outputs
 
-Once all teammates report done:
-1. Verify each output file exists in ${docsDir}/
+Once every teammate has gone idle:
+1. Verify each output file exists in ${outDir}/ using **Read** or **Glob**
 2. Verify each issue's front matter status is \`done\`
 3. If any teammate failed to write output or update status, do it yourself
-4. Use **TeamDelete** to clean up the team \`${teamName}\`
-5. Do NOT modify STATE.md — the orchestrator handles that
+4. Do NOT modify STATE.md — the orchestrator handles that
 
 ## Critical Rules
 
-- Create ONE team with TeamCreate, then spawn teammates with Agent(team_name="${teamName}", name="...").
-- Each teammate MUST write its output to disk. Research only in conversation is LOST.
+- The team is created implicitly when you spawn the first teammate with \`team_name\`, and cleaned up automatically when all teammates exit. Your only job is to spawn teammates, wait, and verify.
+- You MUST wait for idle notifications from ALL ${issues.length} teammates before exiting. Exiting early kills all teammate processes and permanently loses their work.
+- Each teammate MUST write its output to disk — research only in conversation is LOST.
 - Each teammate MUST update the issue front matter status to \`done\`.
-- One issue per teammate — no cross-issue work.
-- Do not exit until ALL teammates have completed and output files are verified.`;
+- One issue per teammate — no cross-issue work.`;
   }
 
   /**
@@ -509,10 +497,7 @@ Once all teammates report done:
   private installBouncerForSubagents(): void {
     const mcpJsonPath = join(this.workingDir, '.mcp.json');
 
-    // Generate the standard MCP config (for parent --mcp-config)
-    generateMcpConfig(this.workingDir);
-
-    // Read the generated config and write it as .mcp.json for sub-agent discovery
+    // Generate the standard MCP config (for parent --mcp-config) and reuse for sub-agents
     try {
       const generatedPath = generateMcpConfig(this.workingDir);
       if (!generatedPath) return;
@@ -566,21 +551,82 @@ Once all teammates report done:
 
   // ── Helpers ───────────────────────────────────────────────────
 
+  /**
+   * Resolve the canonical output path for an issue in .pm/out/.
+   * This is the PM system's internal execution artifact — always under
+   * PM control. User-facing delivery to output_file happens via publishOutputs().
+   */
+  private resolveOutputPath(issue: Issue): string {
+    const pmDir = resolvePmDir(this.workingDir);
+    const outDir = pmDir ? join(pmDir, 'out') : join(this.workingDir, '.pm', 'out');
+    return join(outDir, `${issue.id}-${this.slugify(issue.title)}.md`);
+  }
+
+  /**
+   * List existing execution output docs in .pm/out/.
+   * Single canonical location — no split-brain lookup.
+   */
   private listExistingDocs(): string[] {
     const pmDir = resolvePmDir(this.workingDir);
     if (!pmDir) return [];
-    const docsDir = join(pmDir, 'docs');
-    if (!existsSync(docsDir)) return [];
+    const outDir = join(pmDir, 'out');
+    if (!existsSync(outDir)) return [];
 
     try {
-      return readdirSync(docsDir, { recursive: true })
-        .filter((f): f is string => typeof f === 'string' && f.endsWith('.md'))
-        .map(f => join(docsDir, f));
+      return readdirSync(outDir)
+        .filter(f => f.endsWith('.md'))
+        .map(f => join(outDir, f));
     } catch {
       return [];
     }
   }
 
+  /**
+   * Copy confirmed-done outputs from .pm/out/ to user-specified output_file paths.
+   * Only copies for issues that completed successfully and have output_file set.
+   * Failures are non-fatal — the canonical artifact in .pm/out/ is always safe.
+   */
+  private publishOutputs(issues: Issue[]): void {
+    const pmDir = resolvePmDir(this.workingDir);
+    if (!pmDir) return;
+
+    for (const issue of issues) {
+      if (!issue.outputFile) continue;
+
+      // Only publish for confirmed-done issues
+      try {
+        const content = readFileSync(join(pmDir, issue.path), 'utf-8');
+        if (!content.match(/^status:\s*done$/m)) continue;
+      } catch { continue; }
+
+      const srcPath = this.resolveOutputPath(issue);
+      if (!existsSync(srcPath)) continue;
+
+      // Guard against path traversal — output_file must resolve within workingDir
+      const destPath = resolve(this.workingDir, issue.outputFile);
+      if (!destPath.startsWith(this.workingDir + '/') && destPath !== this.workingDir) {
+        this.emit('output', {
+          issueId: issue.id,
+          text: `Warning: output_file "${issue.outputFile}" escapes project directory — skipping`,
+        });
+        continue;
+      }
+
+      try {
+        // Ensure destination directory exists
+        const destDir = join(destPath, '..');
+        if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true });
+        copyFileSync(srcPath, destPath);
+      } catch {
+        // Non-fatal — canonical artifact is safe in .pm/out/
+        this.emit('output', {
+          issueId: issue.id,
+          text: `Warning: could not copy output to ${issue.outputFile}`,
+        });
+      }
+    }
+  }
+
   private slugify(text: string): string {
     return text
       .toLowerCase()
@@ -601,4 +647,54 @@ Once all teammates report done:
       // Ignore errors — file may have been moved
     }
   }
+
+  /**
+   * Append a progress log entry after a wave completes.
+   * Re-reads issue files from disk to determine which actually completed.
+   */
+  private appendProgressEntry(issues: Issue[], waveStart: number): void {
+    const pmDir = resolvePmDir(this.workingDir);
+    if (!pmDir) return;
+    const progressPath = join(pmDir, 'progress.md');
+    if (!existsSync(progressPath)) return;
+
+    const durationMin = Math.round((Date.now() - waveStart) / 60_000);
+    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
+
+    // Re-read issue statuses from disk to get accurate completion count
+    const completed: string[] = [];
+    const failed: string[] = [];
+    for (const issue of issues) {
+      try {
+        const content = readFileSync(join(pmDir, issue.path), '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);
+      }
+    }
+
+    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('');
+
+    try {
+      const existing = readFileSync(progressPath, 'utf-8');
+      writeFileSync(progressPath, existing.trimEnd() + '\n' + lines.join('\n'), 'utf-8');
+    } catch {
+      // Non-fatal
+    }
+  }
 }

package/server/services/plan/parser.ts

@@ -60,13 +60,29 @@ function parseFrontMatter(content: string): ParsedFile {
     return { frontMatter: {}, body: content };
   }
   const frontMatter: Record<string, unknown> = {};
+  const lines = match[1].split('\n');
 
-  for (const line of match[1].split('\n')) {
-    const trimmed = line.trim();
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
     if (!trimmed || trimmed.startsWith('#')) continue;
     const colonIdx = trimmed.indexOf(':');
     if (colonIdx === -1) continue;
-    frontMatter[trimmed.slice(0, colonIdx).trim()] = parseYamlValue(trimmed.slice(colonIdx + 1).trim());
+
+    const key = trimmed.slice(0, colonIdx).trim();
+    const rawValue = trimmed.slice(colonIdx + 1).trim();
+
+    // Handle multi-line indented YAML lists (key:\n  - item1\n  - item2)
+    if (!rawValue) {
+      const items: string[] = [];
+      while (i + 1 < lines.length && /^\s+-\s/.test(lines[i + 1])) {
+        i++;
+        const item = lines[i].trim().replace(/^-\s+/, '');
+        items.push(stripQuotes(item));
+      }
+      frontMatter[key] = items.length > 0 ? items : null;
+    } else {
+      frontMatter[key] = parseYamlValue(rawValue);
+    }
   }
 
   return { frontMatter, body: match[2] };
@@ -241,7 +257,9 @@ function toStringArray(val: unknown): string[] {
 }
 
 function optionalString(val: unknown): string | null {
-  return (val as string) || null;
+  if (val == null) return null;
+  const s = String(val);
+  return s === '' ? null : s;
 }
 
 function parseIssue(content: string, filePath: string): Issue {
@@ -273,6 +291,7 @@ function parseIssue(content: string, filePath: string): Issue {
     technicalNotes: sections.get('Technical Notes') || null,
     filesToModify: parseListItems(sections.get('Files to Modify') || ''),
     activity: parseListItems(sections.get('Activity') || ''),
+    outputFile: optionalString(fm.output_file),
     body,
     path: filePath,
   };
@@ -304,17 +323,28 @@ function parseSprint(content: string, filePath: string): Sprint {
   const { frontMatter: fm, body } = parseFrontMatter(content);
   const sections = extractSections(body);
 
+  // Table-based parsing (markdown links in table rows)
+  let issues = parseSprintIssues(sections.get('Issues'));
+
+  // Fallback: front matter issues array (e.g., ["backlog/IS-001.md", ...])
+  if (issues.length === 0 && Array.isArray(fm.issues)) {
+    issues = (fm.issues as string[]).map(path => {
+      const id = path.replace(/^backlog\//, '').replace(/\.md$/, '');
+      return { id, path, title: '', points: null, status: '' };
+    });
+  }
+
   return {
     id: String(fm.id || ''),
     title: String(fm.title || ''),
     status: (fm.status as Sprint['status']) || 'planned',
-    start: String(fm.start || ''),
-    end: String(fm.end || ''),
-    goal: String(fm.goal || sections.get('Goal') || ''),
+    start: String(fm.start || fm.start_date || ''),
+    end: String(fm.end || fm.end_date || ''),
+    goal: String(fm.goal || sections.get('Goal') || sections.get('Sprint Goal') || ''),
     capacity: optionalNumber(fm.capacity),
     committed: optionalNumber(fm.committed),
     completed: optionalNumber(fm.completed),
-    issues: parseSprintIssues(sections.get('Issues')),
+    issues,
     path: filePath,
   };
 }
@@ -447,9 +477,11 @@ export function parseSingleMilestone(workingDir: string, milestonePath: string):
 
 /** Compute the next available ID for a given prefix (e.g., "IS" → "IS-004") */
 export function getNextId(issues: Issue[], prefix: string): string {
+  const escaped = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`^${escaped}-(\\d+)$`);
   let max = 0;
   for (const issue of issues) {
-    const match = issue.id.match(new RegExp(`^${prefix}-(\\d+)$`));
+    const match = issue.id.match(pattern);
     if (match) {
       const num = Number.parseInt(match[1], 10);
       if (num > max) max = num;

package/server/services/plan/state-reconciler.ts

@@ -12,7 +12,7 @@ import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { resolveReadyToWork } from './dependency-resolver.js';
 import { parsePlanDirectory, resolvePmDir } from './parser.js';
-import type { Issue } from './types.js';
+import type { Issue, Sprint } from './types.js';
 
 interface CategorizedIssues {
   inProgress: Issue[];
@@ -107,6 +107,45 @@ function buildStateMarkdown(
   return `---\n${frontMatter}\n---\n\n${sections.join('\n')}`;
 }
 
+/**
+ * Derive sprint status from its issues' actual statuses.
+ * - All issues done/cancelled → completed
+ * - Any issue in_progress/in_review → active
+ * - Otherwise → planned (unchanged)
+ */
+function deriveSprintStatus(sprint: Sprint, issueByPath: Map<string, Issue>): Sprint['status'] | null {
+  // Sprint references issues by path (e.g., "backlog/IS-001.md")
+  const issuePaths = sprint.issues.map(si => si.path);
+  if (issuePaths.length === 0) return null;
+
+  const statuses = issuePaths.map(p => issueByPath.get(p)?.status).filter(Boolean) as string[];
+  if (statuses.length === 0) return null;
+
+  const allFinished = statuses.every(s => s === 'done' || s === 'cancelled');
+  if (allFinished) return 'completed';
+
+  const anyStarted = statuses.some(s => s === 'in_progress' || s === 'in_review');
+  if (anyStarted) return 'active';
+
+  return null;
+}
+
+function reconcileSprintStatuses(pmDir: string, sprints: Sprint[], issueByPath: Map<string, Issue>): void {
+  for (const sprint of sprints) {
+    const derived = deriveSprintStatus(sprint, issueByPath);
+    if (!derived || derived === sprint.status) continue;
+
+    const sprintPath = join(pmDir, sprint.path);
+    try {
+      let content = readFileSync(sprintPath, 'utf-8');
+      content = content.replace(/^(status:\s*).+$/m, `$1${derived}`);
+      writeFileSync(sprintPath, content, 'utf-8');
+    } catch {
+      // Sprint file may be missing or unwritable
+    }
+  }
+}
+
 export function reconcileState(workingDir: string): void {
   const pmDir = resolvePmDir(workingDir);
   if (!pmDir) return;
@@ -116,7 +155,7 @@ export function reconcileState(workingDir: string): void {
   const fullState = parsePlanDirectory(workingDir);
   if (!fullState) return;
 
-  const { issues, project } = fullState;
+  const { issues, sprints, project } = fullState;
 
   const issueByPath = new Map(issues.map(i => [i.path, i]));
   const categories = categorizeIssues(issues, issueByPath);
@@ -129,4 +168,7 @@ export function reconcileState(workingDir: string): void {
 
   const newContent = buildStateMarkdown(frontMatter, categories, warnings, issueByPath);
   writeFileSync(statePath, newContent, 'utf-8');
+
+  // Reconcile sprint statuses from actual issue statuses
+  reconcileSprintStatuses(pmDir, sprints, issueByPath);
 }

package/server/services/plan/types.ts

@@ -92,6 +92,8 @@ export interface Issue {
   children: string[];
   // Progress (for epics)
   progress: string | null;
+  // Planned output file path (from front matter output_file, relative to working dir)
+  outputFile: string | null;
   // Full markdown body
   body: string;
   // File path relative to .pm/