mstro-app 0.5.1 → 0.5.5

package/server/mcp/classifier/factory.ts

@@ -0,0 +1,195 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Bouncer classifier factory.
+ *
+ * Two entry points:
+ *
+ * - `getClassifier()` — production path. Reads
+ *   `settings.bouncerClassifier: { engine, model }` and returns the
+ *   matching `BouncerClassifier` instance. If the persisted config is
+ *   missing, malformed, or names a non-eligible model, it logs a clear
+ *   warning and falls back to `ClaudeBouncerClassifier` + Haiku — the
+ *   Bouncer must always have a classifier to call, so "no config" and
+ *   "bad config" both collapse to the known-safe default rather than
+ *   throwing.
+ *
+ * - `createBouncerClassifier(options?)` — direct-construction helper used
+ *   by the engineSwap feature-flag gate (see `engine-swap-flag.test.ts`).
+ *   Accepts an explicit `engineId` and is deliberately feature-flag-aware:
+ *   when `engineSwap` is disabled, the flag short-circuits to Claude.
+ *
+ * New callers should prefer `getClassifier()` so the user-selected model
+ * takes effect without plumbing. The bouncer-integration layer constructs
+ * its default classifier lazily so env var changes and settings edits
+ * propagate on the next classification call.
+ */
+
+import { OpenCodeServerManager } from '../../engines/opencode/OpenCodeServerManager.js';
+import type { EngineId } from '../../engines/types.js';
+import {
+  BOUNCER_ELIGIBLE_MODELS,
+  type BouncerClassifierConfig,
+  DEFAULT_BOUNCER_CLASSIFIER,
+  getBouncerClassifier,
+  isEngineSwapEnabled,
+} from '../../services/settings.js';
+import type { BouncerClassifier } from './BouncerClassifier.js';
+import { ClaudeBouncerClassifier } from './ClaudeBouncerClassifier.js';
+import { OpenCodeBouncerClassifier } from './OpenCodeBouncerClassifier.js';
+
+/** Options accepted by every classifier implementation. */
+export interface ClassifierFactoryOptions {
+  /**
+   * Which engine backs the classifier. With `engineSwap` off this is
+   * ignored and `'claude-code'` is used; with the flag on, non-Claude
+   * engines throw until their implementations land (Epic 4).
+   */
+  engineId?: EngineId;
+}
+
+/**
+ * Construct the Layer-2 Bouncer classifier by engine id (no settings
+ * lookup). Exists for the `engineSwap` feature-flag gate, which asserts
+ * that the factory is flag-aware in both on/off states. New production
+ * callers should route through {@link getClassifier} instead.
+ */
+export function createBouncerClassifier(
+  options: ClassifierFactoryOptions = {},
+): BouncerClassifier {
+  if (!isEngineSwapEnabled()) {
+    return new ClaudeBouncerClassifier();
+  }
+  const engineId = options.engineId ?? 'claude-code';
+  switch (engineId) {
+    case 'claude-code':
+      return new ClaudeBouncerClassifier();
+    case 'opencode':
+      // Wired through `getClassifier()` (settings path). Direct engine-id
+      // construction stays intentionally narrow — callers that want the
+      // OpenCode classifier should pick it via the Settings UI so the
+      // shared `OpenCodeServerManager` is available.
+      throw new Error(
+        'OpenCode bouncer classifier is not implemented yet (Epic 4). ' +
+          'Keep engineSwap off until the OpenCode classifier ships.',
+      );
+    default: {
+      const exhaustive: never = engineId;
+      throw new Error(`Unknown classifier engine id: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Process-lifetime singleton for the `opencode serve` subprocess used by
+ * the classifier. Deliberately separate from the engines-side manager so
+ * tests can inject a mock client without touching the engine factory.
+ * Lazy: never created until an OpenCode classifier is first requested.
+ */
+let sharedOpenCodeManager: OpenCodeServerManager | null = null;
+let openCodeManagerFactory: () => OpenCodeServerManager = () =>
+  new OpenCodeServerManager({ registerProcessHandlers: true });
+
+function getSharedOpenCodeServerManager(): OpenCodeServerManager {
+  if (!sharedOpenCodeManager) {
+    sharedOpenCodeManager = openCodeManagerFactory();
+  }
+  return sharedOpenCodeManager;
+}
+
+/**
+ * Override the OpenCode manager used by the classifier factory. Test-only;
+ * production code never calls this. Pass `null` to reset to the default.
+ */
+export function __setOpenCodeManagerFactoryForTests(
+  factory: (() => OpenCodeServerManager) | null,
+): void {
+  sharedOpenCodeManager = null;
+  openCodeManagerFactory = factory
+    ?? (() => new OpenCodeServerManager({ registerProcessHandlers: true }));
+}
+
+/**
+ * Log a fallback reason in a single place so grep + log analysis surface
+ * every path where we silently dropped back to Claude+Haiku. Goes to
+ * stderr (matching the rest of the Bouncer logs) so it shows up in the
+ * CLI's `--trace` output and in audit transcripts.
+ */
+function logFallback(reason: string): void {
+  console.warn(
+    `[Bouncer] Classifier config invalid, falling back to Claude+Haiku: ${reason}`,
+  );
+}
+
+/**
+ * Construct a `BouncerClassifier` for the provided config. Throws on bad
+ * config — callers that need fallback semantics should use
+ * {@link getClassifier} instead.
+ */
+export function createClassifierForConfig(
+  config: BouncerClassifierConfig,
+): BouncerClassifier {
+  const eligible = BOUNCER_ELIGIBLE_MODELS[config.engine];
+  if (!eligible || !eligible.includes(config.model)) {
+    throw new Error(
+      `Model '${config.model}' is not bouncer-eligible for engine '${config.engine}'`,
+    );
+  }
+  switch (config.engine) {
+    case 'claude-code':
+      // The Claude classifier currently hardcodes `--model haiku` in the
+      // subprocess call. Passing `sonnet` still returns Haiku until a
+      // later issue threads the model through — the eligibility check
+      // guards correctness; the subprocess args are a follow-up.
+      return new ClaudeBouncerClassifier();
+    case 'opencode':
+      return new OpenCodeBouncerClassifier({
+        manager: getSharedOpenCodeServerManager(),
+        model: config.model,
+      });
+    default: {
+      const exhaustive: never = config.engine;
+      throw new Error(`Unknown classifier engine id: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Production classifier accessor. Reads the user's current Bouncer
+ * classifier choice from persistent settings and returns a fresh
+ * `BouncerClassifier` instance. Invalid or missing config logs a clear
+ * warning and falls back to the default Claude+Haiku classifier — the
+ * Bouncer is a required security layer, so "no classifier available" is
+ * never an acceptable outcome.
+ *
+ * Called on every `reviewOperation()` path (indirectly via the
+ * integration layer's lazy default); cheap because classifier
+ * construction is synchronous and does not spawn subprocesses until the
+ * first `classify()` call.
+ */
+export function getClassifier(): BouncerClassifier {
+  let config: BouncerClassifierConfig;
+  try {
+    config = getBouncerClassifier();
+  } catch (err) {
+    logFallback(err instanceof Error ? err.message : String(err));
+    return new ClaudeBouncerClassifier();
+  }
+
+  try {
+    return createClassifierForConfig(config);
+  } catch (err) {
+    logFallback(err instanceof Error ? err.message : String(err));
+    // Last-resort fallback — if even the default config can't build the
+    // classifier (e.g. OpenCode catalogue edit broke the model list), we
+    // still return Claude+Haiku so the Bouncer keeps functioning.
+    if (
+      config.engine === DEFAULT_BOUNCER_CLASSIFIER.engine &&
+      config.model === DEFAULT_BOUNCER_CLASSIFIER.model
+    ) {
+      return new ClaudeBouncerClassifier();
+    }
+    return new ClaudeBouncerClassifier();
+  }
+}

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

@@ -0,0 +1,115 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+
+/**
+ * Agent Resolver — Maps issue.agents hints to subagents installed on the user's system.
+ *
+ * Issue front matter may specify `agents` as either canonical Claude Code subagent
+ * names (e.g. `backend-architect`) or general role pointers (e.g. `backend engineer`).
+ * This module bridges the two: it consults AgentManager (project / global / bundled
+ * `.claude/agents/`) and resolves each hint to a concrete agent name when possible,
+ * falling back to the original hint when no match is found so the executor can still
+ * surface the user's intent in the prompt.
+ */
+
+import { type AgentInfo, agentManager } from '../../utils/agent-manager.js';
+
+export interface ResolvedAgent {
+  /** The original hint as written in the issue front matter. */
+  hint: string;
+  /** The resolved canonical agent name, or null if no installed agent matched. */
+  resolvedName: string | null;
+  /** The matching agent info, or null if no installed agent matched. */
+  info: AgentInfo | null;
+}
+
+const NON_WORD = /[^a-z0-9]+/g;
+
+function normalize(input: string): string {
+  return input.toLowerCase().replace(NON_WORD, ' ').trim();
+}
+
+function tokenize(input: string): string[] {
+  return normalize(input).split(' ').filter(Boolean);
+}
+
+/**
+ * Discover every available agent across project / global / bundled directories.
+ * Project entries shadow global, which shadows bundled (deduped by canonical name).
+ */
+function listAvailableAgents(workingDir: string): AgentInfo[] {
+  const seen = new Map<string, AgentInfo>();
+  const layers = [
+    agentManager.listProjectAgents(workingDir),
+    agentManager.listGlobalAgents(),
+    agentManager.listBundledAgents(),
+  ];
+  for (const layer of layers) {
+    for (const agent of layer) {
+      if (!seen.has(agent.name)) seen.set(agent.name, agent);
+    }
+  }
+  return Array.from(seen.values());
+}
+
+/**
+ * Score how well an agent matches a hint. Returns 0 when there is no token overlap.
+ * Higher is better. Exact normalized matches return Infinity.
+ */
+function matchScore(hint: string, agent: AgentInfo): number {
+  const normalizedHint = normalize(hint);
+  const normalizedName = normalize(agent.name);
+  if (normalizedHint === normalizedName) return Number.POSITIVE_INFINITY;
+
+  const hintTokens = tokenize(hint);
+  if (hintTokens.length === 0) return 0;
+
+  const haystack = `${normalizedName} ${normalize(agent.description ?? '')}`;
+  let matched = 0;
+  for (const token of hintTokens) {
+    if (token.length < 2) continue;
+    if (haystack.includes(token)) matched++;
+  }
+  if (matched === 0) return 0;
+
+  // Reward agents whose name (not just description) contains hint tokens.
+  const nameMatches = hintTokens.filter(t => t.length >= 2 && normalizedName.includes(t)).length;
+  return matched + nameMatches * 0.5;
+}
+
+/**
+ * Resolve a single hint against the catalog of available agents.
+ * Returns the highest-scoring agent, or null when no agent has any token overlap.
+ */
+function resolveHint(hint: string, available: AgentInfo[]): AgentInfo | null {
+  let bestScore = 0;
+  let best: AgentInfo | null = null;
+  for (const agent of available) {
+    const score = matchScore(hint, agent);
+    if (score > bestScore) {
+      bestScore = score;
+      best = agent;
+    }
+  }
+  return best;
+}
+
+/**
+ * Resolve every hint in `agents` against the user's installed Claude Code subagents.
+ * Hints with no match are preserved (resolvedName: null) so the executor can still
+ * mention them in the prompt with a graceful fallback note.
+ */
+export function resolveAgentHints(agents: string[], workingDir: string): ResolvedAgent[] {
+  if (!agents || agents.length === 0) return [];
+  const available = listAvailableAgents(workingDir);
+  return agents
+    .map(raw => raw.trim())
+    .filter(Boolean)
+    .map(hint => {
+      const info = resolveHint(hint, available);
+      return {
+        hint,
+        resolvedName: info?.name ?? null,
+        info,
+      };
+    });
+}

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

@@ -74,19 +74,49 @@ For each finding, use this reasoning process:
 
 ## Scoring Guidelines
 
-The overall grade is computed deterministically from your findings, not from a number you supply. Severity and category on each finding are what drive the grade — pick them carefully.
+The overall grade is computed deterministically from your findings, not from a number you supply. **Severity and category on each finding are what drive the grade — pick them carefully.** When in doubt, downgrade.
 
-Three independent dimension grades are computed:
+### Severity Ladder — calibrate by likelihood × user impact, not just by topic
 
-- **Security** (category: `security`) — uses a severity-threshold rule: A = 0 findings, B = only low, C = ≥1 medium, D = ≥1 high, F = ≥1 critical.
-- **Reliability** (categories: `bugs`, `logic`, `performance`) — severity-threshold rule, slightly more lenient: A = 0 findings or ≤1 low, B = ≥2 low or ≤2 medium, C = ≥3 medium or ≥1 high, D = ≥2 high, F = ≥1 critical.
-- **Maintainability** (categories: `architecture`, `oop`, `maintainability`) — density-based (issues per 1000 lines), with a severity escape hatch: any high finding caps at C, any critical caps at D.
+Severity should answer two questions:
+1. **How likely is this to actually trigger?** (Common path vs. edge case vs. theoretical)
+2. **What happens when it triggers?** (User-visible breakage / data loss vs. internal-only / cosmetic)
 
-Overall grade = the worst of the three dimensions. A single critical security finding caps the entire codebase at F.
+Use this ladder. Worked examples follow each level.
 
-This means **severity is load-bearing**: marking something `high` when it's really `low` will swing the grade unfairly. When in doubt, downgrade. A finding without clear evidence of harm is `low`.
+- **`critical`** — Reserved for "this is broken in production today on common code paths." Active data corruption, RCE, auth bypass for normal users, unrecoverable crash on the happy path. If the on-call would page at 3 AM for it, it's critical.
+  - ✅ SQL injection on a public form. Hard-coded production credentials in a deployed file. A `null`-deref on the homepage render path.
+  - ❌ "Could become a problem if traffic 100×". "Edge case where two clients race within 50ms." A theoretical bug in error-handling code that has never run.
 
-You may still emit `score`, `grade`, and `scoreRationale` for reference — they are persisted but ignored when computing the displayed grade. Focus your effort on accurate findings, not on guessing the overall number.
+- **`high`** — A real bug or vulnerability that **definitely affects normal users on common code paths** with **user-visible consequences** (broken UI, wrong data shown, action silently fails). Or an exploitable security issue that requires only realistic conditions.
+  - ✅ Wrong state shown after a successful save (UI/UX bug). XSS via reflected URL parameter on a logged-in dashboard. Wrong calculation in a money-handling code path. Memory leak that grows on every page-view.
+  - ❌ Race condition on degraded shutdown paths. Edge-case exploit gated behind admin auth on a feature that hasn't shipped. A theoretical SSRF on an internal endpoint with no user reach. Defense-in-depth gaps (rate limit absent, header missing) — those are `low`.
+
+- **`medium`** — Real issue but affects an edge case OR has limited user impact OR requires unusual conditions to trigger. Worth fixing eventually; not blocking.
+  - ✅ Missing error handling on a rarely-failing dependency. Logic bug in an admin-only page. A bug only reachable when two specific feature flags are both on. Performance issue that adds 50 ms but isn't user-perceptible.
+  - ❌ "Best practice" preferences with no user impact. Theoretical bugs in unreachable code.
+
+- **`low`** — Improbable, theoretical, or cosmetic. Defense-in-depth missing, style/preference, "could be cleaner." Many of these are fine to leave for years.
+  - ✅ Missing rate limit on a low-traffic admin endpoint. SQL injection-shaped pattern that ends up safely parameterized. A `console.log` left in code. A nullable field that's only null in a code path that never executes.
+
+### Likelihood-weighted severity rules
+
+Apply these as veto rules **after** you've chosen a severity from topic alone:
+
+- If the bug only fires on a path that **realistically never executes in production**, downgrade by at least one step (high→medium, medium→low). A bug that requires "the network connection drops between line 42 and 43 of the shutdown handler" is `low` even if its consequences would be severe.
+- If the issue has **no user-visible effect** (no UI/UX impact, no incorrect data shown, no security boundary crossed), it caps at `medium`. UI/UX wiring bugs and broken interactive flows skew higher; pure-internal architecture / observability gaps skew lower.
+- If the issue is a **defense-in-depth gap** (rate limits, hardening headers, additional validation on already-validated input), cap at `low` unless you can articulate the realistic exploit chain that survives the existing defenses.
+- If exploitability requires **conditions that only matter at high traffic / wide user attack surface**, downgrade for early-stage projects: this is `low` or `medium`, not `high`. (Make this explicit in the description so the reader knows the call.)
+
+### Three dimension grades the engine derives
+
+- **Security** (category: `security`) — strictest. A = 0 findings, B = only low, C = ≥1 medium, F = ≥1 high, F- = ≥1 critical.
+- **Reliability** (categories: `bugs`, `logic`, `performance`) — density-based grade per KLOC with severity escape: critical → F, any high → caps at C. Multiple medium findings escalate gradually rather than auto-failing.
+- **Maintainability** (categories: `architecture`, `oop`, `maintainability`) — density-based with severity escape: critical → F, any high → C.
+
+Overall grade = the worst of the three. A single critical security finding caps the entire codebase at F-.
+
+You may still emit `score`, `grade`, and `scoreRationale` for reference — they are persisted but ignored when computing the displayed grade. Focus your effort on accurate severity classification, not on guessing the overall number.
 
 ## Output
 

package/server/services/plan/composer.ts

@@ -10,6 +10,7 @@
 
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEtaProfileCached } from '../../cli/eta-estimator.js';
 import type { ToolUseEvent } from '../../cli/headless/index.js';
 import { ResilientRunner } from '../../cli/headless/resilient-runner.js';
 import { cleanupAttachments, preparePromptAndAttachments } from '../../cli/improvisation-attachments.js';
@@ -28,6 +29,21 @@ const PROMPT_TOOL_MESSAGES: Record<string, string> = {
   Bash: 'Running commands...',
 };
 
+/**
+ * Resolve the ETA quantile profile used by the planning indicator. Reads
+ * .mstro/history (chat improv movements) since planning-prompt durations
+ * cluster in the same range. Failures degrade silently to undefined — the
+ * indicator falls back to elapsed-only display.
+ */
+async function resolvePromptEtaProfile(workingDir: string): Promise<NonNullable<Awaited<ReturnType<typeof getEtaProfileCached>>> | undefined> {
+  try {
+    const profile = await getEtaProfileCached(join(workingDir, '.mstro', 'history'));
+    return profile ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function getPromptToolCompleteMessage(event: ToolUseEvent): string | null {
   const input = event.completeInput;
   if (!input) return null;
@@ -229,6 +245,7 @@ blocks: []                 # Use backlog-relative paths: backlog/IS-NNN.md
 review_gate: auto
 output_type: auto          # code = modify source files, document = produce written artifact, auto = infer
 output_file: null
+agents: []                 # Agent hints — see "agents field rules" below
 ---
 
 # IS-NNN: Title
@@ -268,6 +285,21 @@ Implementation guidance.
 - When output_type is \`document\`, "Files to Modify" entries are treated as references, not files to edit. The AI produces a document artifact and is reviewed on document quality.
 - When output_type is \`code\`, "Files to Modify" lists actual source files the AI must edit. The review gate verifies source files were changed.
 
+## agents field rules
+
+The \`agents\` field is a list of agent hints for the executing Claude Code session. The executor uses Claude Code's Task tool to delegate work to matching subagents in the user's \`.claude/agents/\` directory (project / global / bundled), with a fallback to the general-purpose agent when no match is found.
+
+- ALWAYS populate \`agents\` with the most relevant 1–4 agents for the work the issue describes. Empty arrays mean "no hints" — only use \`[]\` when no agent type plausibly applies (rare).
+- Entries can be specific agent file names (e.g. \`backend-architect\`, \`frontend-developer\`, \`code-reviewer\`, \`security-auditor\`) OR general role pointers the user's system can match (e.g. \`backend engineer\`, \`product designer\`, \`marketing\`). Prefer specific names — they resolve more reliably.
+- Match agents to the actual work, not the issue's surface topic. A "fix login button" issue is frontend work (\`frontend-developer\`); a "design login flow" issue is product/design (\`product-designer\`, \`ux-writer\`).
+- Common pairings:
+  - Code implementation: pick from \`frontend-developer\`, \`backend-architect\`, \`typescript-pro\`, \`python-pro\`, \`golang-pro\`, etc., based on stack
+  - UI/design work: \`ui-designer\`, \`product-designer\`, \`design-system-architect\`, \`ux-writer\`
+  - Data/DB: \`database-architect\`, \`database-optimizer\`, \`data-engineer\`, \`sql-pro\`
+  - Quality: pair an implementation agent with \`code-reviewer\`, \`test-automator\`, or \`security-auditor\` for sensitive issues
+  - Product/strategy: \`product-manager\`, \`product-marketing\`, \`business-analyst\`
+- YAML format: inline \`agents: [backend-architect, code-reviewer]\` or block list with \`-\` items both work.
+
 ## Epic creation rules
 
 - Create an EP-*.md file in ${cc.backlogPath} with type: epic and a children: [] field in front matter
@@ -287,11 +319,27 @@ User request: ${userPrompt}`;
     prepareAttachmentPrompt(ctx, enrichedPrompt, attachments, workingDir, cc.effectiveBoardId);
 
   const streamBoardId = cc.effectiveBoardId ?? null;
+  const etaProfile = await resolvePromptEtaProfile(workingDir);
+
+  // Tracks whether `planPromptResponse` has been broadcast. The web side
+  // treats this event as the authoritative completion signal — without it,
+  // the composer todo list stays stuck on a spinner. The finally block
+  // guarantees a completion broadcast even if the runner throws or exits
+  // through an unexpected path.
+  let responseSent = false;
+  const sendResponse = (response: string, success: boolean, error: string | null) => {
+    if (responseSent) return;
+    responseSent = true;
+    ctx.broadcastToAll({
+      type: 'planPromptResponse',
+      data: { response, success, error, boardId: streamBoardId },
+    });
+  };
 
   try {
     ctx.broadcastToAll({
       type: 'planPromptProgress',
-      data: { message: 'Starting project planning...', boardId: streamBoardId },
+      data: { message: 'Starting project planning...', boardId: streamBoardId, etaProfile },
     });
 
     const runner = new ResilientRunner({
@@ -339,15 +387,11 @@ User request: ${userPrompt}`;
       data: { message: 'Finalizing project plan...', boardId: streamBoardId },
     });
 
-    ctx.broadcastToAll({
-      type: 'planPromptResponse',
-      data: {
-        response: result.completed ? 'Prompt executed successfully.' : (result.error || 'Unknown error'),
-        success: result.completed,
-        error: result.error || null,
-        boardId: streamBoardId,
-      },
-    });
+    sendResponse(
+      result.completed ? 'Prompt executed successfully.' : (result.error || 'Unknown error'),
+      result.completed,
+      result.error || null,
+    );
 
     // Re-parse and broadcast updated state
     const updatedState = parsePlanDirectory(workingDir);
@@ -355,11 +399,19 @@ User request: ${userPrompt}`;
       ctx.broadcastToAll({ type: 'planStateUpdated', data: updatedState });
     }
   } catch (error) {
+    const errorMsg = error instanceof Error ? error.message : String(error);
     ctx.broadcastToAll({
       type: 'planError',
-      data: { error: error instanceof Error ? error.message : String(error), boardId: streamBoardId },
+      data: { error: errorMsg, boardId: streamBoardId },
     });
+    // Send a completion signal too — `planError` clears streaming on the web
+    // but doesn't set the response banner. Without this, the user sees a
+    // half-finished UI (no spinner, no message).
+    sendResponse(errorMsg, false, errorMsg);
   } finally {
     cleanupAttachments(workingDir, attachmentSessionId);
+    // Defense in depth: guarantee a completion broadcast for any control
+    // flow not covered above (process abort, unexpected throw types, etc.).
+    sendResponse('Prompt execution ended unexpectedly.', false, 'No completion signal');
   }
 }

package/server/services/plan/executor.ts

@@ -265,7 +265,6 @@ export class PlanExecutor extends EventEmitter {
   /** Run waves until done, paused, stopped, or stalled. */
   private async runWaveLoop(): Promise<'done' | 'stalled' | 'dead'> {
     let consecutiveZeroCompletions = 0;
-    const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
 
     while (!this.shouldStop && !this.shouldPause) {
       const readyIssues = await this.pickReadyIssues();
@@ -274,6 +273,9 @@ export class PlanExecutor extends EventEmitter {
         return await this.hasDeadIssues() ? 'dead' : 'done';
       }
 
+      // Re-read on each wave so users can scale agents up/down mid-execution
+      // without restarting — the new value takes effect at the next wave boundary.
+      const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
       const completedCount = await this.executeWave(readyIssues.slice(0, maxParallel));
 
       if (completedCount > 0) {

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

@@ -8,6 +8,7 @@
  */
 
 import { join } from 'node:path';
+import { type ResolvedAgent, resolveAgentHints } from './agent-resolver.js';
 import { resolveIsCodeTask } from './issue-classification.js';
 import type { Issue } from './types.js';
 
@@ -21,6 +22,41 @@ export interface IssuePromptOptions {
   outputPath: string;
 }
 
+/**
+ * Render the Agents section of an issue prompt. Splits resolved hints from
+ * unresolved ones so Claude knows which names are real subagents to delegate to
+ * via the Task tool, vs. role hints for which the user has no installed match.
+ */
+function renderAgentsSection(resolved: ResolvedAgent[]): string {
+  if (resolved.length === 0) return '';
+
+  const matched = resolved.filter(r => r.resolvedName);
+  const unmatched = resolved.filter(r => !r.resolvedName);
+
+  const lines: string[] = ['', '## Suggested Agents'];
+
+  if (matched.length > 0) {
+    lines.push('Delegate the relevant portions of this work to these subagents using the Task tool (subagent_type = the agent name). Use them as primary executors when the work matches their expertise:');
+    for (const r of matched) {
+      const desc = r.info?.description ? ` — ${r.info.description}` : '';
+      const labelHint = r.hint.toLowerCase() !== (r.resolvedName ?? '').toLowerCase()
+        ? ` (matched from "${r.hint}")`
+        : '';
+      lines.push(`- \`${r.resolvedName}\`${labelHint}${desc}`);
+    }
+  }
+
+  if (unmatched.length > 0) {
+    lines.push('');
+    lines.push('Role hints with no installed subagent match — use the general-purpose agent (or your best judgment) for work in these areas:');
+    for (const r of unmatched) {
+      lines.push(`- ${r.hint}`);
+    }
+  }
+
+  return `\n${lines.join('\n')}`;
+}
+
 /**
  * Build a self-contained prompt for one issue.
  * The resulting Claude Code session will work independently —
@@ -45,6 +81,8 @@ export function buildIssuePrompt(options: IssuePromptOptions): string {
     ? `\n## Predecessor Outputs\nRead these before starting — they contain context from upstream issues:\n${predecessorDocs.map(d => `- ${d}`).join('\n')}`
     : '';
 
+  const agentSection = renderAgentsSection(resolveAgentHints(issue.agents, workingDir));
+
   const outDir = boardDir ? join(boardDir, 'out') : pmDir ? join(pmDir, 'out') : join(workingDir, '.mstro', 'pm', 'out');
 
   return `You are executing issue ${issue.id}: ${issue.title}.
@@ -67,7 +105,7 @@ ${criteria || 'No specific criteria defined.'}
 
 ### Technical Notes
 ${issue.technicalNotes || 'None'}
-${files}${predecessorSection}
+${files}${predecessorSection}${agentSection}
 
 ## Your Task
 

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

@@ -287,6 +287,7 @@ export function parseIssue(content: string, filePath: string): Issue {
     reviewGate: (['none', 'auto', 'required'].includes(String(fm.review_gate)) ? String(fm.review_gate) : 'auto') as Issue['reviewGate'],
     outputType: (['code', 'document', 'auto'].includes(String(fm.output_type)) ? String(fm.output_type) : 'auto') as Issue['outputType'],
     outputFile: optionalString(fm.output_file),
+    agents: toStringArray(fm.agents),
     body,
     path: filePath,
   };

package/server/services/plan/types.ts

@@ -98,6 +98,10 @@ export interface Issue {
   outputType: 'code' | 'document' | 'auto';
   // Planned output file path (from front matter output_file, relative to working dir)
   outputFile: string | null;
+  // Agent hints for the executing Claude Code session — names or general roles
+  // (e.g. ["backend-architect", "database-architect"], ["product, design"]).
+  // Empty = no agent hints; the executor uses default behavior.
+  agents: string[];
   // Full markdown body
   body: string;
   // File path relative to .mstro/pm/