@polymorphism-tech/morph-spec 4.10.5 → 4.10.7

package/src/commands/agents/manage-agents.js

@@ -0,0 +1,352 @@
+/**
+ * manage-agents.js — CLI command handlers for agent management
+ *
+ * Thin wrappers around agents-manager.js core functions.
+ * Each handler: parses args -> calls core -> formats output via logger.
+ *
+ * @module manage-agents
+ */
+
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createInterface } from 'node:readline';
+import { existsSync, readFileSync } from 'node:fs';
+import chalk from 'chalk';
+import { logger } from '../../utils/logger.js';
+import {
+  loadAgentsFile,
+  saveAgentsFile,
+  listAgents,
+  showAgent,
+  addAgent,
+  editAgent,
+  removeAgent,
+  TIER_LABELS,
+  KNOWN_PHASES,
+} from '../../lib/agents/agents-manager.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const AGENTS_PATH = join(__dirname, '../../../framework/agents.json');
+
+/**
+ * Resolve the agents.json path.
+ * Uses the canonical framework/agents.json (v4 schema).
+ * If running inside a client project (not the framework repo), falls back
+ * to .morph/framework/agents.json.
+ */
+function getAgentsPath() {
+  // Prefer the framework source file (always v4 schema)
+  if (existsSync(AGENTS_PATH)) return AGENTS_PATH;
+  // Fallback for client projects
+  const clientPath = join(process.cwd(), '.morph', 'framework', 'agents.json');
+  if (existsSync(clientPath)) return clientPath;
+  return AGENTS_PATH;
+}
+
+// ── List ────────────────────────────────────────────────────────────────────────
+
+export async function agentListCommand(options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const filters = {};
+  if (options.group) filters.group = options.group;
+  if (options.tier) filters.tier = parseInt(options.tier, 10);
+
+  const result = listAgents(agentsData, filters);
+
+  if (options.json) {
+    console.log(JSON.stringify(result.agents, null, 2));
+    return;
+  }
+
+  if (result.total === 0) {
+    logger.info('No agents found matching filters.');
+    return;
+  }
+
+  logger.header(`Agents (${result.total} total)`);
+
+  // Table header
+  const header = `  ${'ID'.padEnd(28)} ${'Tier'.padEnd(6)} ${'Group'.padEnd(18)} ${'Phases'.padEnd(16)} Keywords`;
+  console.log(chalk.dim(header));
+  console.log(chalk.dim('  ' + '\u2500'.repeat(90)));
+
+  for (const a of result.agents) {
+    const tierLabel = `T${a.tier}`;
+    const group = (a.group || '\u2014').padEnd(18);
+    const phases = (a.phases || '*').padEnd(16);
+    console.log(`  ${a.id.padEnd(28)} ${tierLabel.padEnd(6)} ${group} ${phases} ${a.keywords || '\u2014'}`);
+  }
+
+  logger.blank();
+  const groups = Object.entries(result.groupCounts).map(([g, c]) => `${g}(${c})`).join(' ');
+  logger.dim(`Groups: ${groups}`);
+}
+
+// ── Show ────────────────────────────────────────────────────────────────────────
+
+export async function agentShowCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const agent = showAgent(agentsData, id);
+
+  if (!agent) {
+    const ids = Object.keys(agentsData.agents || {});
+    const similar = ids.filter(aid => levenshtein(aid, id) <= 3);
+    logger.error(`Agent '${id}' not found.`);
+    if (similar.length > 0) {
+      logger.dim(`Did you mean: ${similar.join(', ')}?`);
+    }
+    process.exitCode = 1;
+    return;
+  }
+
+  if (options.json) {
+    console.log(JSON.stringify({ [id]: agent }, null, 2));
+    return;
+  }
+
+  logger.header(`Agent: ${id}`);
+  logger.info(`Title:        ${agent.title}`);
+  logger.info(`Tier:         ${agent.tier} (${TIER_LABELS[agent.tier] || '?'})`);
+  logger.info(`Group:        ${agent.group}`);
+  logger.info(`Phases:       ${(agent.active_phases || []).join(', ')}`);
+  logger.info(`Reports to:   ${agent.reports_to}`);
+  logger.info(`Domains:      ${(agent.domains || []).join(', ') || '\u2014'}`);
+  logger.info(`Keywords:     ${(agent.keywords || []).join(', ') || '\u2014'}`);
+  logger.info(`Validators:   ${(agent.validators || []).join(', ') || '\u2014'}`);
+
+  if (agent.stacks?.length > 0) {
+    logger.info(`Stacks:       ${agent.stacks.join(', ')}`);
+  }
+
+  if (agent.standards?.length > 0) {
+    logger.blank();
+    logger.info('Standards:');
+    for (const s of agent.standards) {
+      logger.dim(`  ${s.id} (scope: ${s.scope}, priority: ${s.priority})`);
+    }
+  }
+
+  if (agent.teammate) {
+    logger.blank();
+    logger.info('Teammate:');
+    logger.dim(`  Role: ${agent.teammate.role}`);
+    logger.dim(`  Icon: ${agent.teammate.icon}`);
+    const prompt = agent.teammate.spawn_prompt || '';
+    const truncated = options.full ? prompt : (prompt.length > 200 ? prompt.slice(0, 200) + '...' : prompt);
+    logger.dim(`  Prompt: ${truncated}`);
+  } else {
+    logger.blank();
+    logger.dim('No teammate configured.');
+  }
+}
+
+// ── Add ─────────────────────────────────────────────────────────────────────────
+
+export async function agentAddCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+
+  let fields;
+  if (options.nonInteractive) {
+    fields = parseNonInteractiveFlags(options);
+  } else {
+    fields = await runAddWizard(id, agentsData);
+  }
+
+  const result = addAgent(agentsData, id, fields);
+
+  if (!result.success) {
+    for (const e of result.errors) logger.error(e);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (result.warnings?.length > 0) {
+    for (const w of result.warnings) logger.warn(w);
+  }
+
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Created agent '${id}' in agents.json`);
+  logger.dim(`Run 'morph-spec setup-infra' to install the .claude/agents/ file`);
+}
+
+// ── Edit ────────────────────────────────────────────────────────────────────────
+
+export async function agentEditCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const changes = {};
+
+  if (options.tier) changes.tier = parseInt(options.tier, 10);
+  if (options.title) changes.title = options.title;
+  if (options.group) changes.group = options.group;
+  if (options.activePhases) changes.active_phases = options.activePhases.split(',').map(s => s.trim());
+  if (options.reportsTo) changes.reports_to = options.reportsTo;
+  if (options.keywords) changes.keywords = options.keywords.split(',').map(s => s.trim());
+  if (options.domains) changes.domains = options.domains.split(',').map(s => s.trim());
+  if (options.spawnPrompt) changes.spawn_prompt = options.spawnPrompt;
+
+  if (Object.keys(changes).length === 0) {
+    logger.error('No changes specified. Use flags like --title, --tier, --keywords, etc.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const result = editAgent(agentsData, id, changes);
+
+  if (!result.success) {
+    for (const e of result.errors) logger.error(e);
+    process.exitCode = 1;
+    return;
+  }
+
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Updated agent '${id}'`);
+  for (const c of result.changes) logger.dim(`  ${c}`);
+}
+
+// ── Remove ──────────────────────────────────────────────────────────────────────
+
+export async function agentRemoveCommand(id, options) {
+  const agentsData = loadAgentsFile(getAgentsPath());
+  const agent = showAgent(agentsData, id);
+
+  if (!agent) {
+    logger.error(`Agent '${id}' not found.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  // Show summary
+  logger.info(`Agent: ${id} (T${agent.tier} ${agent.group})`);
+
+  // Check for dependents
+  const dependents = Object.entries(agentsData.agents)
+    .filter(([aid, a]) => aid !== id && a.reports_to === id)
+    .map(([aid]) => aid);
+
+  if (dependents.length > 0) {
+    logger.warn(`These agents report to '${id}': ${dependents.join(', ')}`);
+  }
+
+  // Check state.json for active references (advisory)
+  checkActiveFeatures(id);
+
+  if (!options.force) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise(resolve => {
+      rl.question(chalk.yellow('  Remove this agent? (y/N) '), resolve);
+    });
+    rl.close();
+    if (answer.toLowerCase() !== 'y') {
+      logger.info('Cancelled.');
+      return;
+    }
+  }
+
+  const result = removeAgent(agentsData, id);
+  saveAgentsFile(getAgentsPath(), result.data);
+  logger.success(`Removed agent '${id}' from agents.json`);
+  logger.dim(`Run 'morph-spec setup-infra' to clean up .claude/agents/ files`);
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Levenshtein distance between two strings.
+ * Used for "did you mean?" suggestions on typos.
+ */
+export function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, (_, i) => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  for (let j = 0; j <= n; j++) dp[0][j] = j;
+  for (let i = 1; i <= m; i++) {
+    for (let j = 1; j <= n; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+    }
+  }
+  return dp[m][n];
+}
+
+/**
+ * Interactive wizard for adding an agent.
+ */
+async function runAddWizard(id, agentsData) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(resolve => rl.question(q, resolve));
+
+  console.log(chalk.bold(`\n  Adding agent: ${id}\n`));
+
+  const knownGroups = [...new Set(Object.values(agentsData.agents || {}).map(a => a.group))];
+
+  const tier = parseInt(await ask(`  ? Tier (1=${TIER_LABELS[1]}, 2=${TIER_LABELS[2]}, 3=${TIER_LABELS[3]}, 4=${TIER_LABELS[4]}): `), 10);
+  const title = await ask('  ? Title: ');
+  console.log(chalk.dim(`    Known groups: ${knownGroups.join(', ')}`));
+  const group = await ask('  ? Group: ');
+  const phasesRaw = await ask('  ? Active phases (comma-sep, or * for all): ');
+  const active_phases = phasesRaw.trim() === '*' ? ['*'] : phasesRaw.split(',').map(s => s.trim());
+
+  const existingIds = Object.keys(agentsData.agents || {});
+  console.log(chalk.dim(`    Valid: ${existingIds.slice(0, 5).join(', ')}... or "user"`));
+  const reports_to = await ask('  ? Reports to: ');
+
+  const domainsRaw = await ask('  ? Domains (comma-sep): ');
+  const domains = domainsRaw.split(',').map(s => s.trim()).filter(Boolean);
+  const keywordsRaw = await ask('  ? Keywords (comma-sep): ');
+  const keywords = keywordsRaw.split(',').map(s => s.trim()).filter(Boolean);
+
+  let teammate = null;
+  if (tier >= 3) {
+    const role = await ask('  ? Teammate role: ');
+    const icon = await ask('  ? Teammate icon (emoji): ');
+    const spawn_prompt = await ask('  ? Spawn prompt: ');
+    teammate = { role, icon, spawn_prompt };
+  }
+
+  rl.close();
+
+  return { tier, title, group, active_phases, reports_to, domains, keywords, teammate };
+}
+
+/**
+ * Parse --non-interactive flags into fields object.
+ */
+function parseNonInteractiveFlags(options) {
+  return {
+    tier: options.tier ? parseInt(options.tier, 10) : undefined,
+    title: options.title,
+    group: options.group,
+    active_phases: options.activePhases ? options.activePhases.split(',').map(s => s.trim()) : ['implement'],
+    reports_to: options.reportsTo || 'user',
+    domains: options.domains ? options.domains.split(',').map(s => s.trim()) : [],
+    keywords: options.keywords ? options.keywords.split(',').map(s => s.trim()) : [],
+    teammate: options.spawnPrompt ? {
+      role: options.role || 'specialist',
+      icon: options.icon || '\u{1F527}',
+      spawn_prompt: options.spawnPrompt,
+    } : null,
+  };
+}
+
+/**
+ * Advisory check: is this agent referenced in active features?
+ * Fail-open — any errors are silently ignored.
+ */
+function checkActiveFeatures(agentId) {
+  try {
+    const statePath = join(process.cwd(), '.morph', 'state.json');
+    if (!existsSync(statePath)) return;
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    const activeIn = [];
+    for (const [fname, fdata] of Object.entries(state.features || {})) {
+      if (fdata.activeAgents?.includes(agentId)) activeIn.push(fname);
+    }
+    if (activeIn.length > 0) {
+      logger.warn(`Agent '${agentId}' is active in features: ${activeIn.join(', ')}. Removing from agents.json does not affect state.`);
+    }
+  } catch {
+    /* ignore — state check is advisory */
+  }
+}

package/src/commands/project/doctor.js

@@ -199,6 +199,20 @@ async function doctorFullCommand(frameworkRoot) {
     check('agents.json', false, false, 'file not found');
   }
 
+  // ── 6. agents.json version freshness ──────────────────────────────────
+  const canonicalAgentsPath = join(frameworkRoot, 'framework/agents.json');
+  if (await pathExists(agentsPath) && await pathExists(canonicalAgentsPath)) {
+    try {
+      const installed = JSON.parse(await fs.readFile(agentsPath, 'utf8'));
+      const canonical = JSON.parse(await fs.readFile(canonicalAgentsPath, 'utf8'));
+      const installedVer = installed.version || 'unknown';
+      const canonicalVer = canonical.version || 'unknown';
+      const isFresh = installedVer === canonicalVer;
+      check(`agents.json version (${installedVer})`, isFresh, true,
+        isFresh ? '' : `stale — canonical is v${canonicalVer}, run 'morph-spec update' to sync`);
+    } catch { /* ignore parse errors — already caught above */ }
+  }
+
   // ── 7. Workflow Configs ──────────────────────────────────────────────────
   console.log(chalk.cyan('\n  framework/workflows/ — Workflow Configs'));
   const stdPath = join(frameworkRoot, 'framework/workflows/configs/standard.json');
@@ -599,6 +613,51 @@ export async function doctorCommand(options = {}) {
       } else {
         checks.push({ name: 'agents.json tier counts', status: 'ok' });
       }
+
+      // Check 4: v4 schema validation
+      const version = agentsData.version || 'unknown';
+      const isV4 = version.startsWith('4.');
+      const v3Fields = [];
+      const missingV4Fields = [];
+
+      for (const [id, data] of agentEntries) {
+        if (data.role !== undefined) v3Fields.push(`${id}.role`);
+        if (data.always_active !== undefined) v3Fields.push(`${id}.always_active`);
+        if (data.relationships !== undefined) v3Fields.push(`${id}.relationships`);
+        if (!data.group) missingV4Fields.push(`${id}.group`);
+        if (!Array.isArray(data.active_phases)) missingV4Fields.push(`${id}.active_phases`);
+      }
+
+      if (isV4) {
+        checks.push({ name: `agents.json schema (v${version})`, status: 'ok' });
+      } else {
+        checks.push({
+          name: `agents.json schema (v${version})`,
+          status: 'warn',
+          msg: 'expected v4.x — run agents migration'
+        });
+        hasWarnings = true;
+      }
+
+      if (v3Fields.length > 0) {
+        const sample = v3Fields.slice(0, 3).join(', ');
+        checks.push({
+          name: 'agents.json deprecated fields',
+          status: 'warn',
+          msg: `${v3Fields.length} v3 field(s) found: ${sample}${v3Fields.length > 3 ? '...' : ''}`
+        });
+        hasWarnings = true;
+      }
+
+      if (missingV4Fields.length > 0 && isV4) {
+        const sample = missingV4Fields.slice(0, 3).join(', ');
+        checks.push({
+          name: 'agents.json v4 required fields',
+          status: 'warn',
+          msg: `${missingV4Fields.length} missing: ${sample}${missingV4Fields.length > 3 ? '...' : ''}`
+        });
+        hasWarnings = true;
+      }
     } catch {
       checks.push({ name: 'agents.json', status: 'error', msg: 'invalid JSON' });
       hasErrors = true;
@@ -707,7 +766,7 @@ export async function doctorCommand(options = {}) {
               checks.push({
                 name: 'agents completeness',
                 status: 'warn',
-                msg: `${missing.length} agent(s) missing for [${projectTags.join(', ')}]: ${names} — run morph-spec init --force`
+                msg: `${missing.length} agent(s) missing for [${projectTags.join(', ')}]: ${names} — run morph-spec setup-infra`
               });
               hasWarnings = true;
             } else {
@@ -871,7 +930,7 @@ export async function doctorCommand(options = {}) {
   logger.blank();
 
   if (hasErrors) {
-    logger.error('Some checks failed. Run "morph-spec init --force" to fix.');
+    logger.error('Some checks failed. Run "morph-spec setup-infra" to fix.');
     process.exit(1);
   } else if (hasWarnings) {
     logger.warn('Some checks need attention.');

package/src/commands/project/init.js

@@ -10,7 +10,7 @@ import {
   writeJson,
   writeFile
 } from '../../utils/file-copier.js';
-import { getInstalledCLIVersion } from '../../utils/version-checker.js';
+import { getInstalledCLIVersion, checkProjectOutdated } from '../../utils/version-checker.js';
 import { installClaudeHooks } from '../../utils/claude-settings-manager.js';
 import inquirer from 'inquirer';
 import { detectProject } from '../../lib/detectors/index.js';
@@ -27,6 +27,7 @@ import { setupInfra, installRulesForStack } from '../../scripts/setup-infra.js';
 import { installSkills } from '../../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../../utils/agents-installer.js';
 import { getProjectTags } from '../../lib/stack-filter.js';
+import { updateCommand } from './update.js';
 
 export async function initCommand(options) {
   const targetPath = options.path || process.cwd();
@@ -39,7 +40,14 @@ export async function initCommand(options) {
   const morphPath = join(targetPath, '.morph');
   if (await pathExists(morphPath)) {
     if (!options.force) {
-      logger.warn('MORPH already initialized in this directory.');
+      // Check if project version is outdated — auto-update instead of blocking
+      const projectCheck = await checkProjectOutdated(targetPath);
+      if (projectCheck.isOutdated) {
+        logger.info(`MORPH already initialized (v${projectCheck.current}). Framework update available (v${projectCheck.cliVersion}).`);
+        logger.blank();
+        return updateCommand(options);
+      }
+      logger.warn('MORPH already initialized in this directory (up to date).');
       logger.dim('Use --force to overwrite existing installation.');
       process.exit(1);
     }

package/src/commands/project/update.js

@@ -25,10 +25,11 @@ import {
   getUpdateInstructions,
   detectInstallMethod
 } from '../../utils/version-checker.js';
-import { installClaudeHooks, installGlobalStatusline, installVSCodeTerminalSettings, installShellIntegration } from '../../utils/claude-settings-manager.js';
+import { installClaudeHooks, installGlobalStatusline } from '../../utils/claude-settings-manager.js';
 import { installSkills } from '../../utils/skills-installer.js';
 import { installAgents, installDomainAgents } from '../../utils/agents-installer.js';
 import { injectMorphImport } from '../../utils/claude-md-injector.js';
+import { getProjectTags } from '../../lib/stack-filter.js';
 
 /**
  * Backup user's config.json before cleaning
@@ -262,19 +263,21 @@ export async function updateCommand(options) {
       logger.warn('  ⚠ framework/commands/ source missing — commands not updated');
     }
 
+    // Compute project tags for stack-aware installation of skills, agents, and rules
+    let projectTags = [];
+    try {
+      const cfg = await readJson(join(morphPath, 'config', 'config.json'));
+      projectTags = getProjectTags(cfg);
+    } catch { /* ignore — config may not exist yet */ }
+
     // Sync morph skills to .claude/skills/ for native Claude Code discovery
     updateSpinner.text = 'Syncing morph skills to .claude/skills/...';
-    await installSkills(targetPath);
+    await installSkills(targetPath, { projectTags });
 
     // Sync native subagents to .claude/agents/
     updateSpinner.text = 'Syncing agents to .claude/agents/...';
-    let projectStack = null;
-    try {
-      const cfg = await readJson(join(morphPath, 'config', 'config.json'));
-      projectStack = cfg?.project?.stack ?? null;
-    } catch { /* ignore — config may not exist yet */ }
-    await installAgents(targetPath, frameworkDir, { projectStack });
-    await installDomainAgents(targetPath, frameworkDir);
+    await installAgents(targetPath, frameworkDir, { projectTags });
+    await installDomainAgents(targetPath, frameworkDir, { projectTags });
 
     // Sync path-scoped rules to .claude/rules/
     updateSpinner.text = 'Syncing rules to .claude/rules/...';
@@ -306,22 +309,6 @@ export async function updateCommand(options) {
     updateSpinner.text = 'Updating Claude Code hooks...';
     const hooksResult = await installClaudeHooks(targetPath);
 
-    // Install shell integration (terminal title watcher)
-    updateSpinner.text = 'Installing shell integration...';
-    try {
-      await installShellIntegration();
-    } catch {
-      logger.dim('  ⚠ Could not install shell integration (non-critical)');
-    }
-
-    // Configure VS Code terminal settings (enable OSC title sequences)
-    updateSpinner.text = 'Configuring VS Code terminal settings...';
-    try {
-      await installVSCodeTerminalSettings();
-    } catch {
-      logger.dim('  ⚠ Could not configure VS Code terminal settings (non-critical)');
-    }
-
     // Ensure root CLAUDE.md has morph-spec @import (preserves user content)
     updateSpinner.text = 'Checking CLAUDE.md import...';
     const claudeMdDest = join(targetPath, 'CLAUDE.md');

package/src/commands/state/advance-phase.js

@@ -269,9 +269,6 @@ export async function advancePhaseCommand(feature, options = {}) {
 
       if (!specContentValidation.valid) {
         console.log(chalk.red('\n✗ Spec content validation failed:'));
-        specContentValidation.missing.forEach(section => {
-          console.log(chalk.red(`  - Missing section: ${section}`));
-        });
         specContentValidation.errors.forEach(error => {
           console.log(chalk.red(`  - ${error}`));
         });
@@ -441,6 +438,17 @@ export async function advancePhaseCommand(feature, options = {}) {
     // Hook executor unavailable — non-blocking
   }
 
+  // Agent detection refresh (fail-open)
+  try {
+    const { refreshAgents, displayDetectionDiff } = await import('../agents/detect-agents.js');
+    const refreshResult = await refreshAgents(process.cwd(), feature);
+    if (refreshResult.added.length > 0) {
+      displayDetectionDiff(refreshResult, currentPhase, nextPhase);
+    }
+  } catch {
+    // Refresh is diagnostic — fail-open, phase advance already completed
+  }
+
   // Emit Tier-4 validator dispatch when advancing into implement or sync phase
   const phasesNeedingValidation = ['implement', 'sync'];
   if (phasesNeedingValidation.includes(nextPhase) || phasesNeedingValidation.includes(currentPhase)) {

package/src/core/state/state-manager.js

@@ -279,6 +279,7 @@ async function ensureFeature(featureName, options = {}) {
         pending: 0
       },
       checkpoints: [],
+      dispatchLog: [],
       trustConfig: {},
       contextBundles: [],
       fileChanges: []
@@ -420,6 +421,29 @@ export function removeAgent(featureName, agentId) {
   return false;
 }
 
+/**
+ * Log a dispatch event to state.json.
+ * Appends entry to feature.dispatchLog, capped at 50 entries (oldest trimmed).
+ *
+ * @param {string} featureName - Feature name
+ * @param {{ timestamp: string, phase: string, mode: string, agents: Array<{ id: string, subagentType: string, group: string, tasks: string[] }> }} entry - Dispatch event to log
+ */
+export function logDispatch(featureName, entry) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  if (!Array.isArray(feature.dispatchLog)) feature.dispatchLog = [];
+  feature.dispatchLog.push(entry);
+
+  // Cap at 50 entries
+  if (feature.dispatchLog.length > 50) {
+    feature.dispatchLog = feature.dispatchLog.slice(-50);
+  }
+
+  saveState(state);
+}
+
 /**
  * Normalize output type from kebab-case to camelCase (BUG-002 fix - Enhanced)
  * Supports both kebab-case and camelCase input formats for all output types
@@ -807,3 +831,60 @@ export function getApprovalHistory(featureName) {
   // Sort by timestamp
   return history.sort((a, b) => new Date(a.timestamp) - new Date(b.timestamp));
 }
+
+/**
+ * Find which agent was assigned a specific task in the latest dispatch.
+ * Searches only the last dispatchLog entry.
+ *
+ * @param {string} featureName
+ * @param {string} taskId
+ * @returns {string|null} Agent ID or null if not found
+ */
+export function resolveAgentForTask(featureName, taskId) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return null;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return null;
+
+  const latest = log[log.length - 1];
+  for (const agent of latest.agents || []) {
+    if (Array.isArray(agent.tasks) && agent.tasks.includes(taskId)) {
+      return agent.id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Update timing fields on a specific agent in the latest dispatch entry.
+ * Fail-open: returns silently if feature/dispatch/agent not found.
+ *
+ * @param {string} featureName
+ * @param {string} agentId - Agent ID to update
+ * @param {Object} updates - Fields to merge (startedAt, completedAt, tasksCompleted)
+ */
+export function updateDispatchAgentTiming(featureName, agentId, updates) {
+  const state = loadState();
+  const feature = state.features?.[featureName];
+  if (!feature) return;
+
+  const log = feature.dispatchLog;
+  if (!Array.isArray(log) || log.length === 0) return;
+
+  const latest = log[log.length - 1];
+  const agent = (latest.agents || []).find(a => a.id === agentId);
+  if (!agent) return;
+
+  Object.assign(agent, updates);
+
+  // If all agents now have completedAt, set entry.completedAt to the latest
+  const allComplete = (latest.agents || []).every(a => a.completedAt);
+  if (allComplete && latest.agents.length > 0) {
+    const timestamps = latest.agents.map(a => new Date(a.completedAt).getTime());
+    latest.completedAt = new Date(Math.max(...timestamps)).toISOString();
+  }
+
+  saveState(state);
+}