@lumenflow/cli 1.0.0 → 1.3.0

package/dist/initiative-edit.js

@@ -35,7 +35,7 @@ import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
 import { die } from '@lumenflow/core/dist/error-handler.js';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import yaml from 'js-yaml';
+import { parseYAML, stringifyYAML } from '@lumenflow/core/dist/wu-yaml.js';
 import { createWUParser } from '@lumenflow/core/dist/arg-parser.js';
 import { INIT_PATHS } from '@lumenflow/initiatives/dist/initiative-paths.js';
 import { INIT_STATUSES, PHASE_STATUSES, INIT_PATTERNS, INIT_LOG_PREFIX, INIT_COMMIT_FORMATS, } from '@lumenflow/initiatives/dist/initiative-constants.js';
@@ -230,7 +230,7 @@ function loadInitiative(id) {
     }
     // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool validates init files
     const content = readFileSync(initPath, { encoding: FILE_SYSTEM.ENCODING });
-    return yaml.load(content);
+    return parseYAML(content);
 }
 /**
  * Ensure working tree is clean
@@ -421,7 +421,7 @@ async function main() {
         execute: async ({ worktreePath }) => {
             // Write updated Initiative to micro-worktree
             const initPath = join(worktreePath, INIT_PATHS.INITIATIVE(id));
-            const yamlContent = yaml.dump(updatedInit, { lineWidth: 100 });
+            const yamlContent = stringifyYAML(updatedInit);
             // eslint-disable-next-line security/detect-non-literal-fs-filename -- CLI tool writes init files
             writeFileSync(initPath, yamlContent, { encoding: FILE_SYSTEM.ENCODING });
             console.log(`${PREFIX} Updated ${id}.yaml in micro-worktree`);

package/dist/metrics-snapshot.js

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+/**
+ * Metrics Snapshot Capture CLI (WU-1018)
+ *
+ * Captures DORA metrics, lane health, and flow state snapshots.
+ *
+ * Usage:
+ *   pnpm metrics:snapshot                     # All metrics, JSON output
+ *   pnpm metrics:snapshot --type dora         # DORA metrics only
+ *   pnpm metrics:snapshot --type lanes        # Lane health only
+ *   pnpm metrics:snapshot --type flow         # Flow state only
+ *   pnpm metrics:snapshot --dry-run           # Preview without writing
+ *   pnpm metrics:snapshot --output metrics.json
+ *
+ * @module metrics-snapshot
+ * @see {@link @lumenflow/metrics/flow/capture-metrics-snapshot}
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import fg from 'fast-glob';
+import { parse as parseYaml } from 'yaml';
+import { Command } from 'commander';
+import { captureMetricsSnapshot, } from '@lumenflow/metrics';
+import { getGitForCwd } from '@lumenflow/core/dist/git-adapter.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+/** Log prefix for console output */
+const LOG_PREFIX = '[metrics:snapshot]';
+/** Default snapshot output path */
+const DEFAULT_OUTPUT = '.beacon/snapshots/metrics-latest.json';
+/** WU directory relative to repo root */
+const WU_DIR = 'docs/04-operations/tasks/wu';
+/** Skip-gates audit file path */
+const SKIP_GATES_PATH = '.beacon/skip-gates-audit.ndjson';
+/** Snapshot type options */
+const SNAPSHOT_TYPES = ['all', 'dora', 'lanes', 'flow'];
+/**
+ * Parse command line arguments
+ */
+function parseArgs() {
+    const program = new Command()
+        .name('metrics-snapshot')
+        .description('Capture DORA metrics, lane health, and flow state snapshot')
+        .option('--type <type>', `Snapshot type: ${SNAPSHOT_TYPES.join(', ')} (default: all)`, 'all')
+        .option('--days <number>', 'Days to analyze for DORA metrics (default: 7)', '7')
+        .option('--output <path>', `Output file path (default: ${DEFAULT_OUTPUT})`, DEFAULT_OUTPUT)
+        .option('--dry-run', 'Preview snapshot without writing to file')
+        .exitOverride();
+    try {
+        program.parse(process.argv);
+        return program.opts();
+    }
+    catch (err) {
+        const error = err;
+        if (error.code === 'commander.helpDisplayed' || error.code === 'commander.version') {
+            process.exit(0);
+        }
+        throw err;
+    }
+}
+/**
+ * Calculate week date range
+ */
+function calculateWeekRange(days) {
+    const weekEnd = new Date();
+    weekEnd.setHours(23, 59, 59, 999);
+    const weekStart = new Date(weekEnd);
+    weekStart.setDate(weekStart.getDate() - days);
+    weekStart.setHours(0, 0, 0, 0);
+    return { weekStart, weekEnd };
+}
+/**
+ * Load WU metrics from YAML files
+ */
+async function loadWUMetrics(baseDir) {
+    const wuDir = join(baseDir, WU_DIR);
+    const wuFiles = await fg('WU-*.yaml', { cwd: wuDir, absolute: true });
+    const wuMetrics = [];
+    for (const file of wuFiles) {
+        try {
+            const content = await readFile(file, { encoding: 'utf-8' });
+            const wu = parseYaml(content);
+            // Map WU status to valid WUMetrics status
+            const rawStatus = wu.status;
+            let status = 'ready';
+            if (rawStatus === 'in_progress')
+                status = 'in_progress';
+            else if (rawStatus === 'blocked')
+                status = 'blocked';
+            else if (rawStatus === 'waiting')
+                status = 'waiting';
+            else if (rawStatus === 'done')
+                status = 'done';
+            else if (rawStatus === 'ready')
+                status = 'ready';
+            wuMetrics.push({
+                id: wu.id,
+                title: wu.title,
+                lane: wu.lane,
+                status,
+                priority: wu.priority,
+                claimedAt: wu.claimed_at ? new Date(wu.claimed_at) : undefined,
+                completedAt: wu.completed_at ? new Date(wu.completed_at) : undefined,
+                cycleTimeHours: calculateCycleTime(wu),
+            });
+        }
+        catch {
+            // Skip invalid WU files
+        }
+    }
+    return wuMetrics;
+}
+/**
+ * Calculate cycle time in hours from WU data
+ */
+function calculateCycleTime(wu) {
+    if (!wu.claimed_at || !wu.completed_at) {
+        return undefined;
+    }
+    const claimed = new Date(wu.claimed_at);
+    const completed = new Date(wu.completed_at);
+    const diffMs = completed.getTime() - claimed.getTime();
+    const diffHours = diffMs / (1000 * 60 * 60);
+    return Math.round(diffHours * 10) / 10;
+}
+/**
+ * Load git commits from repository
+ */
+async function loadGitCommits(weekStart, weekEnd) {
+    try {
+        const git = getGitForCwd();
+        // simple-git log() returns an object with 'all' array containing commits
+        // The actual simple-git result includes date but the adapter type is narrowed
+        const logResult = await git.log({ maxCount: 500 });
+        const commits = [];
+        for (const entry of [...logResult.all]) {
+            // Filter by date range
+            const commitDate = new Date(entry.date);
+            if (commitDate < weekStart || commitDate > weekEnd) {
+                continue;
+            }
+            const message = entry.message;
+            // Extract WU ID from commit message if present
+            const wuIdMatch = message.match(/\b(WU-\d+)\b/i);
+            const wuId = wuIdMatch ? wuIdMatch[1].toUpperCase() : undefined;
+            // Determine commit type from conventional commit prefix
+            const typeMatch = message.match(/^(feat|fix|docs|chore|refactor|test|style|perf|ci)[\(:]?/i);
+            const type = typeMatch ? typeMatch[1].toLowerCase() : undefined;
+            commits.push({
+                hash: entry.hash,
+                timestamp: commitDate,
+                message,
+                type,
+                wuId,
+            });
+        }
+        return commits;
+    }
+    catch (err) {
+        console.warn(`${LOG_PREFIX} ⚠️  Could not load git commits: ${err.message}`);
+        return [];
+    }
+}
+/**
+ * Load skip-gates audit entries
+ */
+async function loadSkipGatesEntries(baseDir) {
+    const auditPath = join(baseDir, SKIP_GATES_PATH);
+    if (!existsSync(auditPath)) {
+        return [];
+    }
+    try {
+        const content = await readFile(auditPath, { encoding: 'utf-8' });
+        const lines = content.split('\n').filter((line) => line.trim());
+        const entries = [];
+        for (const line of lines) {
+            try {
+                const raw = JSON.parse(line);
+                if (raw.timestamp && raw.wu_id && raw.reason && raw.gate) {
+                    entries.push({
+                        timestamp: new Date(raw.timestamp),
+                        wuId: raw.wu_id,
+                        reason: raw.reason,
+                        gate: raw.gate,
+                    });
+                }
+            }
+            catch {
+                // Skip invalid JSON lines
+            }
+        }
+        return entries;
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Format snapshot for display
+ */
+function formatSnapshot(snapshot, type) {
+    const lines = [];
+    lines.push('═══════════════════════════════════════════════════════════════');
+    lines.push(`  METRICS SNAPSHOT (type: ${type})`);
+    lines.push(`  Generated: ${new Date().toISOString()}`);
+    lines.push('═══════════════════════════════════════════════════════════════');
+    lines.push('');
+    if (snapshot.dora) {
+        lines.push('┌─────────────────────────────────────────────────────────────┐');
+        lines.push('│ DORA METRICS                                                │');
+        lines.push('├─────────────────────────────────────────────────────────────┤');
+        const { deploymentFrequency, leadTimeForChanges, changeFailureRate, meanTimeToRecovery } = snapshot.dora;
+        lines.push(`│ Deployment Frequency: ${deploymentFrequency.deploysPerWeek}/week (${deploymentFrequency.status})`);
+        lines.push(`│ Lead Time: ${leadTimeForChanges.medianHours}h median (${leadTimeForChanges.status})`);
+        lines.push(`│ Change Failure Rate: ${changeFailureRate.failurePercentage}% (${changeFailureRate.status})`);
+        lines.push(`│ MTTR: ${meanTimeToRecovery.averageHours}h (${meanTimeToRecovery.status})`);
+        lines.push('└─────────────────────────────────────────────────────────────┘');
+        lines.push('');
+    }
+    if (snapshot.lanes) {
+        lines.push('┌─────────────────────────────────────────────────────────────┐');
+        lines.push('│ LANE HEALTH                                                 │');
+        lines.push('├─────────────────────────────────────────────────────────────┤');
+        lines.push(`│ Total Active: ${snapshot.lanes.totalActive}  |  Blocked: ${snapshot.lanes.totalBlocked}  |  Completed: ${snapshot.lanes.totalCompleted}`);
+        lines.push('│');
+        for (const lane of snapshot.lanes.lanes) {
+            const statusIcon = lane.status === 'healthy' ? '✓' : lane.status === 'at-risk' ? '⚠' : '✗';
+            lines.push(`│ ${statusIcon} ${lane.lane.padEnd(20)} ${lane.wusCompleted} done, ${lane.wusInProgress} active, ${lane.wusBlocked} blocked`);
+        }
+        lines.push('└─────────────────────────────────────────────────────────────┘');
+        lines.push('');
+    }
+    if (snapshot.flow) {
+        lines.push('┌─────────────────────────────────────────────────────────────┐');
+        lines.push('│ FLOW STATE                                                  │');
+        lines.push('├─────────────────────────────────────────────────────────────┤');
+        lines.push(`│ Ready: ${snapshot.flow.ready}  |  In Progress: ${snapshot.flow.inProgress}`);
+        lines.push(`│ Blocked: ${snapshot.flow.blocked}  |  Waiting: ${snapshot.flow.waiting}`);
+        lines.push(`│ Done: ${snapshot.flow.done}  |  Total Active: ${snapshot.flow.totalActive}`);
+        lines.push('└─────────────────────────────────────────────────────────────┘');
+    }
+    return lines.join('\n');
+}
+/**
+ * Main function
+ */
+async function main() {
+    const opts = parseArgs();
+    const baseDir = process.cwd();
+    const type = opts.type;
+    const days = parseInt(opts.days, 10);
+    // Validate snapshot type
+    if (!SNAPSHOT_TYPES.includes(type)) {
+        die(`Invalid snapshot type: ${type}\n\nValid types: ${SNAPSHOT_TYPES.join(', ')}`);
+    }
+    console.log(`${LOG_PREFIX} Capturing ${type} metrics snapshot...`);
+    const { weekStart, weekEnd } = calculateWeekRange(days);
+    console.log(`${LOG_PREFIX} Date range: ${weekStart.toISOString().split('T')[0]} to ${weekEnd.toISOString().split('T')[0]}`);
+    // Load data
+    console.log(`${LOG_PREFIX} Loading WU data...`);
+    const wuMetrics = await loadWUMetrics(baseDir);
+    console.log(`${LOG_PREFIX} Found ${wuMetrics.length} WUs`);
+    console.log(`${LOG_PREFIX} Loading git commits...`);
+    const commits = await loadGitCommits(weekStart, weekEnd);
+    console.log(`${LOG_PREFIX} Found ${commits.length} commits`);
+    console.log(`${LOG_PREFIX} Loading skip-gates audit entries...`);
+    const skipGatesEntries = await loadSkipGatesEntries(baseDir);
+    console.log(`${LOG_PREFIX} Found ${skipGatesEntries.length} skip-gates entries`);
+    // Capture snapshot
+    const input = {
+        commits,
+        wuMetrics,
+        skipGatesEntries,
+        weekStart,
+        weekEnd,
+        type,
+    };
+    const snapshot = captureMetricsSnapshot(input);
+    // Output
+    console.log('');
+    console.log(formatSnapshot(snapshot, type));
+    console.log('');
+    // Write to file (unless dry-run)
+    if (opts.dryRun) {
+        console.log(`${LOG_PREFIX} Dry run - not writing to file.`);
+        console.log(`${LOG_PREFIX} Would write to: ${opts.output}`);
+    }
+    else {
+        const outputPath = join(baseDir, opts.output);
+        const outputDir = dirname(outputPath);
+        // Ensure directory exists
+        if (!existsSync(outputDir)) {
+            await mkdir(outputDir, { recursive: true });
+        }
+        const outputData = {
+            capturedAt: new Date().toISOString(),
+            type,
+            dateRange: {
+                start: weekStart.toISOString(),
+                end: weekEnd.toISOString(),
+            },
+            snapshot,
+        };
+        await writeFile(outputPath, JSON.stringify(outputData, null, 2), { encoding: 'utf-8' });
+        console.log(`${LOG_PREFIX} ✅ Snapshot written to: ${outputPath}`);
+    }
+}
+// Guard main() for testability (WU-1366)
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main().catch((err) => {
+        die(`Metrics snapshot failed: ${err.message}`);
+    });
+}

package/dist/orchestrate-init-status.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+/**
+ * Orchestrate Initiative Status CLI
+ *
+ * Compact status view for initiative orchestration.
+ * Shows progress of WUs in an initiative.
+ *
+ * Usage:
+ *   pnpm orchestrate:init-status --initiative INIT-001
+ */
+import { Command } from 'commander';
+import { existsSync, readdirSync } from 'node:fs';
+import { loadInitiativeWUs, calculateProgress, formatProgress } from '@lumenflow/initiatives';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import chalk from 'chalk';
+const LOG_PREFIX = '[orchestrate:init-status]';
+const STAMPS_DIR = '.beacon/stamps';
+function getCompletedWUs(wuIds) {
+    const completed = new Set();
+    if (!existsSync(STAMPS_DIR)) {
+        return completed;
+    }
+    const files = readdirSync(STAMPS_DIR);
+    for (const wuId of wuIds) {
+        if (files.includes(`${wuId}.done`)) {
+            completed.add(wuId);
+        }
+    }
+    return completed;
+}
+const program = new Command()
+    .name('orchestrate:init-status')
+    .description('Show initiative progress status')
+    .requiredOption('-i, --initiative <id>', 'Initiative ID (e.g., INIT-001)')
+    .action(async (opts) => {
+    try {
+        console.log(chalk.cyan(`${LOG_PREFIX} Loading initiative ${opts.initiative}...`));
+        const { initiative, wus } = loadInitiativeWUs(opts.initiative);
+        console.log(chalk.bold(`\nInitiative: ${initiative.id} - ${initiative.title}`));
+        console.log('');
+        const progress = calculateProgress(wus);
+        console.log(chalk.bold('Progress:'));
+        console.log(formatProgress(progress));
+        console.log('');
+        // Show WU status breakdown
+        const completed = getCompletedWUs(wus.map((w) => w.id));
+        console.log(chalk.bold('WUs:'));
+        for (const wu of wus) {
+            const status = completed.has(wu.id)
+                ? chalk.green('✓ done')
+                : wu.doc.status === 'in_progress'
+                    ? chalk.yellow('⟳ in_progress')
+                    : wu.doc.status === 'blocked'
+                        ? chalk.red('⛔ blocked')
+                        : chalk.gray('○ ready');
+            console.log(`  ${wu.id}: ${wu.doc.title} [${status}]`);
+        }
+    }
+    catch (err) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${err.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+program.parse();

package/dist/orchestrate-initiative.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Orchestrate Initiative CLI
+ *
+ * Orchestrate initiative execution with parallel agent spawning.
+ * Builds execution plan based on WU dependencies and manages wave-based execution.
+ *
+ * Usage:
+ *   pnpm orchestrate:initiative --initiative INIT-001
+ *   pnpm orchestrate:initiative --initiative INIT-001 --dry-run
+ */
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { loadInitiativeWUs, loadMultipleInitiatives, buildExecutionPlan, formatExecutionPlan, calculateProgress, formatProgress, buildCheckpointWave, formatCheckpointOutput, validateCheckpointFlags, resolveCheckpointMode, LOG_PREFIX, } from '@lumenflow/initiatives';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+const program = new Command()
+    .name('orchestrate-initiative')
+    .description('Orchestrate initiative execution with parallel agent spawning')
+    .option('-i, --initiative <ids...>', 'Initiative ID(s) to orchestrate')
+    .option('-d, --dry-run', 'Show execution plan without spawning agents')
+    .option('-p, --progress', 'Show current progress only')
+    .option('-c, --checkpoint-per-wave', 'Spawn next wave then exit (no polling)')
+    .option('--no-checkpoint', 'Force polling mode')
+    .action(async (options) => {
+    const { initiative: initIds, dryRun, progress: progressOnly, checkpointPerWave, checkpoint, } = options;
+    const noCheckpoint = checkpoint === false;
+    try {
+        validateCheckpointFlags({ checkpointPerWave, dryRun, noCheckpoint });
+    }
+    catch (error) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${error.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+    if (!initIds || initIds.length === 0) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: --initiative is required`));
+        console.error('');
+        console.error('Usage:');
+        console.error('  pnpm orchestrate:initiative --initiative INIT-001');
+        console.error('  pnpm orchestrate:initiative --initiative INIT-001 --dry-run');
+        process.exit(EXIT_CODES.ERROR);
+    }
+    try {
+        console.log(chalk.cyan(`${LOG_PREFIX} Loading initiative(s): ${initIds.join(', ')}`));
+        let wus;
+        let initiative;
+        if (initIds.length === 1) {
+            const result = loadInitiativeWUs(initIds[0]);
+            initiative = result.initiative;
+            wus = result.wus;
+        }
+        else {
+            wus = loadMultipleInitiatives(initIds);
+            initiative = { id: 'MULTI', title: `Combined: ${initIds.join(', ')}` };
+        }
+        console.log(chalk.green(`${LOG_PREFIX} Loaded ${wus.length} WU(s)`));
+        console.log('');
+        const progress = calculateProgress(wus);
+        console.log(chalk.bold('Progress:'));
+        console.log(formatProgress(progress));
+        console.log('');
+        if (progressOnly) {
+            return;
+        }
+        const checkpointDecision = resolveCheckpointMode({ checkpointPerWave, noCheckpoint, dryRun }, wus);
+        if (checkpointDecision.enabled) {
+            if (initIds.length > 1) {
+                console.error(chalk.red(`${LOG_PREFIX} Error: Checkpoint mode only supports single initiative`));
+                process.exit(EXIT_CODES.ERROR);
+            }
+            const waveData = buildCheckpointWave(initIds[0], { dryRun });
+            if (!waveData) {
+                console.log(chalk.green(`${LOG_PREFIX} All WUs are complete! Nothing to spawn.`));
+                return;
+            }
+            console.log(formatCheckpointOutput({ ...waveData, dryRun }));
+            return;
+        }
+        console.log(chalk.cyan(`${LOG_PREFIX} Building execution plan...`));
+        const plan = buildExecutionPlan(wus);
+        if (plan.waves.length === 0) {
+            console.log(chalk.green(`${LOG_PREFIX} All WUs are complete! Nothing to execute.`));
+            return;
+        }
+        console.log('');
+        console.log(chalk.bold('Execution Plan:'));
+        console.log(formatExecutionPlan(initiative, plan));
+        if (dryRun) {
+            console.log(chalk.yellow(`${LOG_PREFIX} Dry run mode - no agents spawned`));
+            console.log(chalk.cyan('To execute this plan, remove the --dry-run flag.'));
+            return;
+        }
+        console.log(chalk.green(`${LOG_PREFIX} Execution plan output complete.`));
+        console.log(chalk.cyan('Copy the spawn commands above to execute.'));
+    }
+    catch (error) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${error.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+program.parse();

package/dist/orchestrate-monitor.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Orchestrate Monitor CLI
+ *
+ * Monitors spawned agent progress using mem:inbox signals.
+ * Designed to prevent context exhaustion by using compact signal output.
+ *
+ * Usage:
+ *   pnpm orchestrate:monitor --since 30m
+ */
+import { Command } from 'commander';
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EXIT_CODES } from '@lumenflow/core/dist/wu-constants.js';
+import chalk from 'chalk';
+import ms from 'ms';
+const LOG_PREFIX = '[orchestrate:monitor]';
+const MEMORY_DIR = '.beacon/memory';
+function parseTimeString(timeStr) {
+    const msValue = ms(timeStr);
+    if (typeof msValue === 'number') {
+        return new Date(Date.now() - msValue);
+    }
+    const date = new Date(timeStr);
+    if (isNaN(date.getTime())) {
+        throw new Error(`Invalid time format: ${timeStr}`);
+    }
+    return date;
+}
+function loadRecentSignals(since) {
+    const signals = [];
+    if (!existsSync(MEMORY_DIR)) {
+        return signals;
+    }
+    const files = readdirSync(MEMORY_DIR).filter((f) => f.endsWith('.ndjson'));
+    for (const file of files) {
+        const filePath = join(MEMORY_DIR, file);
+        const content = readFileSync(filePath, 'utf-8');
+        const lines = content.trim().split('\n').filter(Boolean);
+        for (const line of lines) {
+            try {
+                const signal = JSON.parse(line);
+                const signalTime = new Date(signal.timestamp);
+                if (signalTime >= since) {
+                    signals.push(signal);
+                }
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return signals.sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+}
+const program = new Command()
+    .name('orchestrate:monitor')
+    .description('Monitor spawned agent progress')
+    .option('--since <time>', 'Show signals since (e.g., 30m, 1h)', '30m')
+    .option('--wu <id>', 'Filter by WU ID')
+    .action((opts) => {
+    try {
+        const since = parseTimeString(opts.since);
+        console.log(chalk.cyan(`${LOG_PREFIX} Loading signals since ${since.toISOString()}...`));
+        const signals = loadRecentSignals(since);
+        if (signals.length === 0) {
+            console.log(chalk.yellow(`${LOG_PREFIX} No signals found.`));
+            console.log(chalk.gray('Agents may still be starting up, or memory layer not initialized.'));
+            return;
+        }
+        const filtered = opts.wu ? signals.filter((s) => s.wuId === opts.wu) : signals;
+        console.log(chalk.bold(`\nRecent Signals (${filtered.length}):\n`));
+        for (const signal of filtered) {
+            const time = new Date(signal.timestamp).toLocaleTimeString();
+            const wu = signal.wuId ? chalk.cyan(signal.wuId) : chalk.gray('system');
+            const type = signal.type === 'complete'
+                ? chalk.green(signal.type)
+                : signal.type === 'error'
+                    ? chalk.red(signal.type)
+                    : chalk.yellow(signal.type);
+            console.log(`  ${chalk.gray(time)} [${wu}] ${type}: ${signal.message || ''}`);
+        }
+        console.log('');
+        console.log(chalk.gray(`Use: pnpm mem:inbox --since ${opts.since} for more details`));
+    }
+    catch (err) {
+        console.error(chalk.red(`${LOG_PREFIX} Error: ${err.message}`));
+        process.exit(EXIT_CODES.ERROR);
+    }
+});
+program.parse();