brain-dev 0.1.1 → 0.2.0

package/bin/brain-tools.cjs

@@ -133,7 +133,11 @@ async function main() {
       break;
 
     case 'execute':
-      await require('./lib/commands/execute.cjs').run(args.slice(1));
+      if (args.includes('--auto') || args.includes('--dry-run') || args.includes('--stop')) {
+        await require('./lib/commands/auto.cjs').run(args.slice(1));
+      } else {
+        await require('./lib/commands/execute.cjs').run(args.slice(1));
+      }
       break;
 
     case 'verify':
@@ -162,6 +166,10 @@ async function main() {
       await require('./lib/commands/config.cjs').run(args.slice(1), path.join(process.cwd(), '.brain'));
       break;
 
+    case 'update':
+      await require('./lib/commands/update.cjs').run(args.slice(1));
+      break;
+
     case 'health':
       await require('./lib/commands/health.cjs').run(args.slice(1));
       break;
@@ -170,6 +178,18 @@ async function main() {
       await require('./lib/commands/map.cjs').run(args.slice(1));
       break;
 
+    case 'recover':
+      await require('./lib/commands/recover.cjs').run(args.slice(1));
+      break;
+
+    case 'dashboard':
+      await require('./lib/commands/dashboard.cjs').run(args.slice(1));
+      break;
+
+    case 'auto':
+      await require('./lib/commands/auto.cjs').run(args.slice(1));
+      break;
+
     default:
       // Unimplemented command: show full help text
       if (!cmdEntry.implemented) {

package/bin/lib/bridge.cjs

@@ -0,0 +1,47 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { atomicWriteSync } = require('./state.cjs');
+
+/**
+ * Write a bridge file atomically.
+ * Bridge files are ephemeral JSON files for inter-process communication.
+ * Convention: .brain/.<name>-bridge.json
+ * @param {string} brainDir - Path to .brain/ directory
+ * @param {string} name - Bridge name (e.g., 'context', 'stuck', 'cost')
+ * @param {object} data - JSON-serializable data
+ */
+function writeBridge(brainDir, name, data) {
+  const filePath = path.join(brainDir, `.${name}-bridge.json`);
+  atomicWriteSync(filePath, JSON.stringify(data, null, 2));
+}
+
+/**
+ * Read a bridge file. Returns null on any error (missing, corrupt, etc.).
+ * @param {string} brainDir
+ * @param {string} name
+ * @returns {object|null}
+ */
+function readBridge(brainDir, name) {
+  try {
+    const filePath = path.join(brainDir, `.${name}-bridge.json`);
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Remove a bridge file.
+ * @param {string} brainDir
+ * @param {string} name
+ */
+function cleanBridge(brainDir, name) {
+  try {
+    const filePath = path.join(brainDir, `.${name}-bridge.json`);
+    fs.unlinkSync(filePath);
+  } catch { /* ignore if already missing */ }
+}
+
+module.exports = { writeBridge, readBridge, cleanBridge };

package/bin/lib/commands/auto.cjs

@@ -0,0 +1,337 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const path = require('node:path');
+const fs = require('node:fs');
+const { output, error, success, prefix } = require('../core.cjs');
+const { readState, writeState } = require('../state.cjs');
+const { acquireLock, releaseLock } = require('../lock.cjs');
+const { canSpend } = require('../cost.cjs');
+const { checkTimeouts } = require('../stuck.cjs');
+const { logEvent } = require('../logger.cjs');
+
+/**
+ * Run the auto command — the autonomous execution engine.
+ *
+ * Generates a "runbook" — a sequence of steps that tells Claude Code
+ * how to chain the agent calls. Auto does NOT directly execute agents.
+ * It calls the existing command modules (plan, execute, verify, complete)
+ * which generate prompts. Auto chains these prompts into a single
+ * compound instruction.
+ *
+ * Flags:
+ *   --dry-run  Show the runbook without acquiring a lock or modifying state
+ *   --stop     Stop auto mode, release lock, record history
+ *   --phase N  Start from a specific phase number
+ *   --json     Force JSON output
+ *
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir for testing)
+ * @returns {object} Structured result
+ */
+async function run(args = [], opts = {}) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      'dry-run': { type: 'boolean', default: false },
+      stop: { type: 'boolean', default: false },
+      phase: { type: 'string' },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false
+  });
+
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (!state) {
+    error("No brain state found. Run 'brain-dev init' first.");
+    return { error: 'no-state' };
+  }
+
+  // Handle --stop
+  if (values.stop) return handleStop(brainDir, state);
+
+  // Handle --dry-run
+  if (values['dry-run']) return handleDryRun(brainDir, state, values);
+
+  // Pre-flight checks
+  if (!state.project || !state.project.initialized) {
+    error("Project not initialized. Run '/brain:new-project' first.");
+    return { error: 'not-initialized' };
+  }
+
+  // Budget pre-flight: estimate a conservative cost for the auto run
+  const budgetCheck = canSpend(brainDir, 0);
+  if (!budgetCheck.allowed) {
+    error(`Budget exceeded: ${budgetCheck.reason}`);
+    return { error: 'budget-exceeded', reason: budgetCheck.reason, budget_status: budgetCheck.budget_status };
+  }
+
+  // Timeout pre-flight: check if already stuck
+  const timeoutCheck = checkTimeouts(brainDir, state);
+  if (timeoutCheck.tier === 'hard') {
+    error(`Hard timeout active: ${timeoutCheck.message}`);
+    return { error: 'hard-timeout', message: timeoutCheck.message };
+  }
+
+  // Acquire lock
+  const lockResult = acquireLock(brainDir, {
+    phase: state.phase.current,
+    operation: 'auto',
+    agent: 'orchestrator'
+  });
+  if (!lockResult.acquired) {
+    error('Another operation is in progress. Use /brain:recover if this is a stale lock.');
+    return { error: 'lock-held', previousLock: lockResult.previousLock };
+  }
+
+  // Update state for auto mode
+  state.auto.active = true;
+  state.auto.started_at = new Date().toISOString();
+  state.auto.current_step = 'starting';
+  state.auto.error_count = 0;
+  state.auto.phases_completed = 0;
+  writeState(brainDir, state);
+
+  logEvent(brainDir, state.phase.current, {
+    type: 'auto_start',
+    phase: state.phase.current
+  });
+
+  // Build runbook
+  const runbook = buildRunbook(brainDir, state, values);
+
+  // Build result
+  const result = {
+    action: 'auto-run',
+    ...runbook,
+    lockHeld: true,
+    instructions: buildInstructions(runbook, brainDir)
+  };
+
+  const humanLines = [
+    prefix('Auto mode started'),
+    prefix(`Phases: ${runbook.startPhase} → ${runbook.endPhase} (${runbook.phases.length} phases, ${runbook.totalSteps} steps)`),
+    prefix(`Guardrails: max ${runbook.config.max_errors} errors, ${runbook.config.max_operations} ops, ${runbook.config.max_duration_minutes}m`),
+    '',
+    result.instructions
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+/**
+ * Build the runbook — a structured plan of phases and steps to execute.
+ * @param {string} brainDir
+ * @param {object} state
+ * @param {object} options - Parsed CLI values
+ * @returns {object} Runbook with phases, steps, and config
+ */
+function buildRunbook(brainDir, state, options) {
+  const startPhase = options.phase ? parseInt(options.phase, 10) : state.phase.current;
+  const maxPhases = state.auto.max_phases || state.phase.total;
+  const endPhase = Math.min(startPhase + maxPhases - 1, state.phase.total);
+
+  const phases = [];
+  for (let p = startPhase; p <= endPhase; p++) {
+    const phaseInfo = Array.isArray(state.phase.phases)
+      ? state.phase.phases.find(ph => typeof ph === 'object' && ph.number === p)
+      : null;
+
+    if (!phaseInfo) continue;
+    if (phaseInfo.status === 'complete') continue;
+
+    phases.push({
+      number: p,
+      name: phaseInfo.name || `Phase ${p}`,
+      status: phaseInfo.status || 'pending',
+      steps: determineSteps(phaseInfo.status || 'pending', state)
+    });
+  }
+
+  return {
+    startPhase,
+    endPhase,
+    phases,
+    totalSteps: phases.reduce((sum, p) => sum + p.steps.length, 0),
+    config: {
+      max_errors: state.auto.max_errors || 3,
+      max_operations: state.auto.max_operations || 100,
+      max_duration_minutes: state.auto.max_duration_minutes || 120,
+      skip_discuss: state.auto.skip_discuss || false
+    }
+  };
+}
+
+/**
+ * Determine which steps remain for a phase based on its current status.
+ * The full pipeline is: discuss → plan → execute → verify → complete.
+ * @param {string} currentStatus - Phase status string
+ * @param {object} state - Brain state (for config flags)
+ * @returns {string[]} Remaining step names
+ */
+function determineSteps(currentStatus, state) {
+  const allSteps = ['discuss', 'plan', 'execute', 'verify', 'complete'];
+  const statusToStep = {
+    'initialized': 0,
+    'pending': 0,
+    'discussing': 0,
+    'discussed': 1,
+    'planning': 1,
+    'planned': 2,
+    'executing': 2,
+    'executed': 3,
+    'verifying': 3,
+    'verified': 4,
+    'complete': 5
+  };
+
+  const startIdx = statusToStep[currentStatus] || 0;
+  let steps = allSteps.slice(startIdx);
+
+  // Skip discuss if configured or if auto mode has skip_discuss
+  if (state.auto && state.auto.skip_discuss && steps[0] === 'discuss') {
+    steps = steps.slice(1);
+  }
+
+  return steps;
+}
+
+/**
+ * Build human-readable instructions for Claude Code to follow.
+ * This is the core output — a markdown runbook that tells the agent
+ * exactly which commands to run in sequence.
+ * @param {object} runbook - Built runbook
+ * @param {string} brainDir - Path to .brain/
+ * @returns {string} Markdown instruction text
+ */
+function buildInstructions(runbook, brainDir) {
+  const lines = [];
+  lines.push(`## Auto Mode — ${runbook.phases.length} phase${runbook.phases.length !== 1 ? 's' : ''}, ${runbook.totalSteps} steps`);
+  lines.push(`Guardrails: max ${runbook.config.max_errors} errors, ${runbook.config.max_operations} operations, ${runbook.config.max_duration_minutes}m duration`);
+  lines.push('');
+
+  for (const phase of runbook.phases) {
+    lines.push(`### Phase ${phase.number}: ${phase.name}`);
+    lines.push(`Current status: ${phase.status}`);
+    lines.push('');
+
+    let stepNum = 1;
+    for (const step of phase.steps) {
+      switch (step) {
+        case 'discuss':
+          lines.push(`${stepNum}. Run: \`npx brain-dev discuss --phase ${phase.number}\` → follow the discuss agent prompt`);
+          break;
+        case 'plan':
+          lines.push(`${stepNum}. Run: \`npx brain-dev plan --phase ${phase.number}\` → follow the planner agent prompt, then plan-checker loop`);
+          break;
+        case 'execute':
+          lines.push(`${stepNum}. Run: \`npx brain-dev execute --phase ${phase.number}\` → repeat until all plans executed`);
+          break;
+        case 'verify':
+          lines.push(`${stepNum}. Run: \`npx brain-dev verify --phase ${phase.number}\` → follow the verifier agent prompt`);
+          break;
+        case 'complete':
+          lines.push(`${stepNum}. Run: \`npx brain-dev complete --phase ${phase.number}\` → advance to next phase`);
+          break;
+      }
+      stepNum++;
+    }
+    lines.push('');
+  }
+
+  lines.push('### Error Handling');
+  lines.push('- If any step fails, retry once. If it fails again, run: `npx brain-dev auto --stop`');
+  lines.push('- Budget check: run `npx brain-dev progress --cost` between phases');
+  lines.push('- Timeout check: run `npx brain-dev progress --stuck` if a step takes too long');
+  lines.push('');
+  lines.push('### Completion');
+  lines.push('- When all phases complete or auto stops, run: `npx brain-dev auto --stop` to release the lock');
+
+  return lines.join('\n');
+}
+
+/**
+ * Handle --stop: deactivate auto mode, release lock, record history.
+ * @param {string} brainDir
+ * @param {object} state
+ * @returns {object} Result
+ */
+function handleStop(brainDir, state) {
+  const wasActive = state.auto.active;
+
+  state.auto.active = false;
+  state.auto.current_step = 'stopped';
+
+  // Record history entry
+  if (state.auto.started_at) {
+    if (!Array.isArray(state.auto.history)) {
+      state.auto.history = [];
+    }
+    state.auto.history.push({
+      started: state.auto.started_at,
+      ended: new Date().toISOString(),
+      phases_completed: state.auto.phases_completed || 0,
+      result: 'stopped',
+      errors: state.auto.error_count || 0
+    });
+  }
+
+  writeState(brainDir, state);
+  releaseLock(brainDir);
+
+  logEvent(brainDir, state.phase.current, {
+    type: 'auto_stop',
+    phases_completed: state.auto.phases_completed || 0
+  });
+
+  const result = {
+    action: 'auto-stopped',
+    phases_completed: state.auto.phases_completed || 0,
+    was_active: wasActive
+  };
+
+  const msg = wasActive
+    ? `Auto mode stopped. ${result.phases_completed} phase(s) completed.`
+    : 'Auto mode was not active. Lock released.';
+  output(result, prefix(msg));
+
+  return result;
+}
+
+/**
+ * Handle --dry-run: build and display the runbook without modifying state.
+ * @param {string} brainDir
+ * @param {object} state
+ * @param {object} options - Parsed CLI values
+ * @returns {object} Result
+ */
+function handleDryRun(brainDir, state, options) {
+  if (!state.project || !state.project.initialized) {
+    error("Project not initialized. Run '/brain:new-project' first.");
+    return { error: 'not-initialized' };
+  }
+
+  const runbook = buildRunbook(brainDir, state, options);
+  const instructions = buildInstructions(runbook, brainDir);
+
+  const result = {
+    action: 'auto-dry-run',
+    ...runbook,
+    instructions
+  };
+
+  const humanLines = [
+    prefix('Auto mode dry run (no state changes)'),
+    prefix(`Phases: ${runbook.startPhase} → ${runbook.endPhase} (${runbook.phases.length} phases, ${runbook.totalSteps} steps)`),
+    '',
+    instructions
+  ];
+  output(result, humanLines.join('\n'));
+
+  return result;
+}
+
+module.exports = { run };

package/bin/lib/commands/dashboard.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+const { parseArgs } = require('node:util');
+const path = require('node:path');
+const fs = require('node:fs');
+const { output, error, success, prefix } = require('../core.cjs');
+const { readState } = require('../state.cjs');
+const { collectState } = require('../dashboard-collector.cjs');
+
+/**
+ * brain-dev dashboard command.
+ * Modes: TUI (default), --browser (deferred), --json, --stop, --status.
+ * @param {string[]} args - CLI arguments
+ * @param {object} [opts] - Options (brainDir override)
+ * @returns {object} Action result
+ */
+async function run(args = [], opts = {}) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      browser: { type: 'boolean', default: false },
+      stop: { type: 'boolean', default: false },
+      status: { type: 'boolean', default: false },
+      port: { type: 'string' },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false
+  });
+
+  const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
+  const state = readState(brainDir);
+
+  if (values.stop) return handleStop(brainDir);
+  if (values.status) return handleStatus(brainDir);
+
+  if (values.browser) {
+    // Web dashboard — defer to server module
+    return { action: 'dashboard-browser', message: 'Web dashboard coming in next iteration. Use TUI mode (default).' };
+  }
+
+  // Default: TUI mode
+  return renderTUI(brainDir, state, values);
+}
+
+/**
+ * Render a text-based dashboard to stdout.
+ * @param {string} brainDir
+ * @param {object} state
+ * @param {object} options - Parsed CLI flags
+ * @returns {object} Action result with snapshot data
+ */
+function renderTUI(brainDir, state, options) {
+  const snapshot = collectState(brainDir);
+
+  if (options.json) {
+    return output(snapshot);
+  }
+
+  const lines = [];
+  const { styleText } = require('node:util');
+
+  lines.push(prefix('') + styleText('bold', ' Dashboard') + '                                     ' + new Date().toLocaleString());
+  lines.push('\u2500'.repeat(72));
+
+  // Project info
+  lines.push(`Project: ${styleText('bold', snapshot.project.name)} (${snapshot.project.mode}, ${snapshot.project.depth})` +
+    (snapshot.milestone?.current ? `    Milestone: ${snapshot.milestone.current}` : ''));
+  lines.push('');
+
+  // Phase progress
+  lines.push(`Phase Progress [${snapshot.phases.current}/${snapshot.phases.total}]`);
+  for (const phase of snapshot.phases.list) {
+    const isCurrent = phase.number === snapshot.phases.current;
+    const bar = renderProgressBar(phase.status);
+    const marker = isCurrent ? '  <--' : '';
+    const statusColor = phase.status === 'complete' ? 'green' : (isCurrent ? 'yellow' : 'dim');
+    lines.push(`  ${String(phase.number).padStart(2, ' ')}. ${phase.name.padEnd(16)} ${bar}  ${styleText(statusColor, phase.status)}${marker}`);
+  }
+  lines.push('');
+
+  // Timing
+  if (snapshot.timing.phaseElapsed > 0) {
+    const elapsed = formatDuration(snapshot.timing.phaseElapsed);
+    lines.push(`Timing: ${elapsed} elapsed`);
+  }
+
+  // Context + Cost
+  const contextStr = snapshot.context.remainingPct !== null
+    ? `Context: ${snapshot.context.remainingPct}% (${snapshot.context.level})`
+    : 'Context: unknown';
+  let costStr = '';
+  if (snapshot.cost.spent > 0) {
+    costStr = ` | Cost: $${snapshot.cost.spent.toFixed(2)}`;
+    if (snapshot.cost.ceiling) costStr += `/$${snapshot.cost.ceiling}`;
+    costStr += ` (${snapshot.cost.status})`;
+  }
+  lines.push(contextStr + costStr);
+  lines.push('');
+
+  // Recent events
+  if (snapshot.events.length > 0) {
+    lines.push('Recent Events:');
+    const recent = snapshot.events.slice(-5);
+    for (const evt of recent) {
+      const time = evt.timestamp ? new Date(evt.timestamp).toLocaleTimeString().slice(0, 5) : '??:??';
+      lines.push(`  ${time}  ${(evt.type || '?').padEnd(12)} ${evt.plan ? 'plan-' + evt.plan : ''} ${evt.agent || ''}`);
+    }
+    lines.push('');
+  }
+
+  // Health / Stuck / Lock
+  const healthStr = snapshot.health.stateValid ? 'OK' : 'ERROR';
+  const stuckStr = snapshot.stuck.detected ? styleText('red', `YES (${snapshot.stuck.tier})`) : 'No';
+  const lockStr = snapshot.lock.active ? (snapshot.lock.stale ? styleText('red', 'stale') : 'active (auto)') : 'none';
+  lines.push(`Health: ${healthStr} | Stuck: ${stuckStr} | Lock: ${lockStr}`);
+
+  const text = lines.join('\n');
+  console.log(text);
+  return { action: 'dashboard-tui', data: snapshot };
+}
+
+/**
+ * Render an ASCII progress bar based on phase status.
+ * @param {string} status
+ * @returns {string} 22-char progress bar like [====          ]
+ */
+function renderProgressBar(status) {
+  const pct = status === 'complete' ? 100 :
+    status === 'verified' ? 90 :
+    status === 'executing' ? 55 :
+    status === 'planning' ? 25 :
+    status === 'discussing' ? 10 : 0;
+  const filled = Math.round(pct / 5);
+  const empty = 20 - filled;
+  return '[' + '='.repeat(filled) + ' '.repeat(empty) + ']';
+}
+
+/**
+ * Format seconds into human-readable "Xm Ys" string.
+ * @param {number} seconds
+ * @returns {string}
+ */
+function formatDuration(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return `${m}m ${s}s`;
+}
+
+/**
+ * Handle --stop: remove dashboard server port file.
+ * @param {string} brainDir
+ * @returns {object}
+ */
+function handleStop(brainDir) {
+  const portFile = path.join(brainDir, '.dashboard-port');
+  if (!fs.existsSync(portFile)) {
+    return { action: 'dashboard-not-running', message: 'No dashboard server running.' };
+  }
+  try { fs.unlinkSync(portFile); } catch {}
+  return { action: 'dashboard-stopped' };
+}
+
+/**
+ * Handle --status: check if a dashboard server is running.
+ * @param {string} brainDir
+ * @returns {object}
+ */
+function handleStatus(brainDir) {
+  const portFile = path.join(brainDir, '.dashboard-port');
+  if (fs.existsSync(portFile)) {
+    const port = fs.readFileSync(portFile, 'utf8').trim();
+    return { action: 'dashboard-status', running: true, url: `http://localhost:${port}` };
+  }
+  return { action: 'dashboard-status', running: false };
+}
+
+module.exports = { run };

package/bin/lib/commands/execute.cjs

@@ -7,6 +7,8 @@ const { loadTemplate, interpolate } = require('../templates.cjs');
 const { getAgent, resolveModel } = require('../agents.cjs');
 const { logEvent } = require('../logger.cjs');
 const { output, error } = require('../core.cjs');
+const { recordInvocation, estimateTokens } = require('../cost.cjs');
+const { acquireLock, releaseLock } = require('../lock.cjs');
 
 /**
  * Find a phase directory under .brain/phases/ matching a phase number.
@@ -366,8 +368,24 @@ async function run(args = [], opts = {}) {
     `> ${debuggerSpawnInstruction}`
   ].join('\n');
 
+  // Record cost estimate
+  try {
+    const inputTokens = estimateTokens(fullPrompt || prompt || '');
+    recordInvocation(brainDir, {
+      agent: 'executor',
+      phase: phaseNumber,
+      plan: padded,
+      model: model || 'inherit',
+      input_tokens: inputTokens,
+      output_tokens: 0  // Will be updated when SUMMARY is written
+    });
+  } catch { /* cost tracking failure is non-fatal */ }
+
   // Update state to executing
   state.phase.status = 'executing';
+  if (!state.phase.execution_started_at) {
+    state.phase.execution_started_at = new Date().toISOString();
+  }
   writeState(brainDir, state);
 
   // Check auto-recover config

package/bin/lib/commands/progress.cjs

@@ -1,6 +1,7 @@
 'use strict';
 
 const path = require('node:path');
+const { parseArgs } = require('node:util');
 const { readState } = require('../state.cjs');
 const { output, prefix, error } = require('../core.cjs');
 
@@ -58,6 +59,17 @@ function nextAction(state) {
  * @returns {object} Structured result for piping/testing
  */
 async function run(args = [], opts = {}) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      verbose: { type: 'boolean', default: false },
+      cost: { type: 'boolean', default: false },
+      breakdown: { type: 'string' },
+      json: { type: 'boolean', default: false }
+    },
+    strict: false
+  });
+
   const brainDir = opts.brainDir || path.join(process.cwd(), '.brain');
   const state = readState(brainDir);
 
@@ -66,7 +78,7 @@ async function run(args = [], opts = {}) {
     return { error: 'no-state' };
   }
 
-  const verbose = args.includes('--verbose');
+  const verbose = values.verbose || args.includes('--verbose');
   const phase = state.phase || {};
   const phases = phase.phases || [];
   const session = state.session || {};
@@ -160,6 +172,30 @@ async function run(args = [], opts = {}) {
     contextWarning
   };
 
+  // Cost display (--cost flag)
+  if (values.cost) {
+    try {
+      const { readMetrics, checkBudget, getAgentBreakdown, getPhaseBreakdown } = require('../cost.cjs');
+      const metrics = readMetrics(brainDir);
+      const budgetStatus = checkBudget(metrics);
+      result.cost = {
+        spent: metrics.totals?.estimated_cost_usd || 0,
+        ceiling: state.budget?.ceiling_usd || null,
+        budget_status: budgetStatus.status,
+        invocations: metrics.totals?.agent_invocations || 0
+      };
+      if (values.breakdown === 'agent') {
+        result.cost.breakdown = getAgentBreakdown(metrics);
+      } else if (values.breakdown === 'phase') {
+        result.cost.breakdown = getPhaseBreakdown(metrics);
+      }
+      let costLine = prefix(`Cost: $${result.cost.spent.toFixed(2)}`);
+      if (result.cost.ceiling) costLine += ` / $${result.cost.ceiling} (${budgetStatus.status})`;
+      costLine += ` | ${result.cost.invocations} invocations`;
+      lines.push(costLine);
+    } catch { /* cost not available */ }
+  }
+
   output(result, lines.join('\n'));
   return result;
 }