pyre-cli 10.3.0 → 10.5.0

package/src/completions.ts

@@ -4,6 +4,16 @@ export function generateZshCompletions(): string {
 _pyre() {
     local -a commands
     commands=(
+        'menu:Interactive TUI command center and tools navigator'
+        'tui:Alias for menu'
+        'launcher:Alias for menu'
+        'playbook:Execute sequenced multi-step macro recipes'
+        'flight:Forensic flight recorder black box'
+        'run:Performance budgeting runner for CI/CD gates'
+        'bench-git:Cross-branch git performance differ'
+        'statusline:Headless terminal statusline string'
+        'inspect:Process deep-dive inspector'
+        'containers:Container and micro-VM telemetry'
         'live:Start interactive live monitoring dashboard'
         'info:Display static system overview'
         'doctor:Run system permissions and diagnostic checks'
@@ -15,6 +25,7 @@ _pyre() {
         'ssh:Stream metrics over SSH'
         'bench:Benchmark command while logging system stats'
         'completions:Generate shell completion scripts'
+        'optimize:Mac optimizer (quit idle apps, memory, caches, trash, startup, dns)'
     )
 
     _arguments -s \\
@@ -58,8 +69,8 @@ _pyre_completions() {
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
-    commands="live info doctor web ui launch config p2p ssh bench completions"
-    opts="--json --html --md --csv --tsv --detailed --theme --interval --once --out --export-dir --log --tree --sort --packets --limit --alert-cpu --alert-temp --temp-unit"
+    commands="menu tui launcher playbook flight run bench-git statusline inspect containers live info doctor web ui launch config p2p ssh bench completions optimize"
+    opts="--json --html --md --csv --tsv --detailed --theme --interval --once --out --export-dir --log --tree --sort --packets --limit --alert-cpu --alert-temp --temp-unit --idle --keep --yes --force --clean --empty --dry-run --auto-quit -m --menu -i --interactive --budget-cpu --budget-mem --budget-time --markdown --nice --format"
 
     case "${prev}" in
         --theme)
@@ -82,6 +93,22 @@ _pyre_completions() {
             COMPREPLY=( $(compgen -W "server connect" -- ${cur}) )
             return 0
             ;;
+        optimize)
+            COMPREPLY=( $(compgen -W "apps track memory caches trash startup dns protect unprotect help" -- ${cur}) )
+            return 0
+            ;;
+        playbook)
+            COMPREPLY=( $(compgen -W "run list audit clean triage bench" -- ${cur}) )
+            return 0
+            ;;
+        flight)
+            COMPREPLY=( $(compgen -W "dump status record" -- ${cur}) )
+            return 0
+            ;;
+        statusline)
+            COMPREPLY=( $(compgen -W "tmux starship json pango plain" -- ${cur}) )
+            return 0
+            ;;
     esac
 
     if [[ ${cur} == -* ]] ; then
@@ -99,6 +126,16 @@ complete -F _pyre_completions pyre
 export function generateFishCompletions(): string {
   return `# fish completion for pyre
 
+complete -c pyre -n "__fish_use_subcommand" -a menu -d "Interactive TUI command center and tools navigator"
+complete -c pyre -n "__fish_use_subcommand" -a tui -d "Alias for menu"
+complete -c pyre -n "__fish_use_subcommand" -a launcher -d "Alias for menu"
+complete -c pyre -n "__fish_use_subcommand" -a playbook -d "Execute sequenced multi-step macro recipes"
+complete -c pyre -n "__fish_use_subcommand" -a flight -d "Forensic flight recorder black box"
+complete -c pyre -n "__fish_use_subcommand" -a run -d "Performance budgeting runner for CI/CD gates"
+complete -c pyre -n "__fish_use_subcommand" -a bench-git -d "Cross-branch git performance differ"
+complete -c pyre -n "__fish_use_subcommand" -a statusline -d "Headless terminal statusline string"
+complete -c pyre -n "__fish_use_subcommand" -a inspect -d "Process deep-dive inspector"
+complete -c pyre -n "__fish_use_subcommand" -a containers -d "Container and micro-VM telemetry"
 complete -c pyre -n "__fish_use_subcommand" -a live -d "Start interactive live monitoring dashboard"
 complete -c pyre -n "__fish_use_subcommand" -a info -d "Display static system overview"
 complete -c pyre -n "__fish_use_subcommand" -a doctor -d "Run system diagnostics"
@@ -108,6 +145,8 @@ complete -c pyre -n "__fish_use_subcommand" -a launch -d "Launch Activity Monito
 complete -c pyre -n "__fish_use_subcommand" -a config -d "Show or reset configuration options"
 complete -c pyre -n "__fish_use_subcommand" -a p2p -d "P2P streaming mode"
 complete -c pyre -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
+complete -c pyre -n "__fish_use_subcommand" -a optimize -d "Mac optimizer: quit idle apps, clean caches"
+complete -c pyre -n "__fish_seen_subcommand_from optimize" -a "apps track memory caches trash startup dns protect unprotect help"
 
 complete -c pyre -l json -s j -d "Output snapshot as JSON"
 complete -c pyre -l html -d "Output snapshot as HTML"
@@ -125,7 +164,7 @@ export function generatePowerShellCompletions(): string {
   return `# PowerShell completion for pyre
 Register-ArgumentCompleter -Native -CommandName pyre -ScriptBlock {
     param($wordToComplete, $commandAst, $cursorPosition)
-    $commands = @('live', 'check', 'pipe', 'stress', 'ui', 'launch', 'web', 'ssh', 'fleet', 'bench', 'benchmark', 'anomalies', 'doctor', 'extensions', 'brew', 'update', 'profile', 'config', 'history', 'diff', 'info', 'completions', 'p2p', 'blender', 'prometheus', 'smart', 'replay', 'explain')
+    $commands = @('menu', 'tui', 'launcher', 'playbook', 'flight', 'run', 'bench-git', 'statusline', 'inspect', 'containers', 'live', 'check', 'pipe', 'stress', 'ui', 'launch', 'web', 'ssh', 'fleet', 'bench', 'benchmark', 'anomalies', 'doctor', 'extensions', 'brew', 'update', 'profile', 'config', 'history', 'diff', 'info', 'completions', 'p2p', 'blender', 'prometheus', 'smart', 'replay', 'explain', 'optimize')
     $options = @('--json', '--html', '--md', '--csv', '--tsv', '--detailed', '--theme', '--interval', '--once', '--out', '--export-dir', '--log', '--tree', '--sort', '--packets', '--limit', '--alert-cpu', '--alert-temp', '--temp-unit', '--plain', '--help', '--version')
 
     $elements = $commandAst.CommandElements

package/src/containersCmd.ts

@@ -0,0 +1,106 @@
+/**
+ * pyre containers — Container & Micro-VM Telemetry.
+ *
+ * Discovers running containers across Docker, Podman, and OrbStack,
+ * reporting container names, CPU load, memory consumption, and network I/O.
+ */
+import { execSync } from 'node:child_process';
+import chalk from 'chalk';
+
+export interface ContainerStats {
+  id: string;
+  name: string;
+  engine: 'docker' | 'podman' | 'orbstack';
+  cpuPct: string;
+  memUsage: string;
+  memPct: string;
+  netIO: string;
+}
+
+export function detectContainerEngine(): 'docker' | 'podman' | null {
+  try {
+    execSync('docker --version', { stdio: 'ignore' });
+    return 'docker';
+  } catch {
+    try {
+      execSync('podman --version', { stdio: 'ignore' });
+      return 'podman';
+    } catch {
+      return null;
+    }
+  }
+}
+
+export function collectContainerStats(): ContainerStats[] {
+  const engine = detectContainerEngine();
+  if (!engine) return [];
+
+  try {
+    const raw = execSync(`${engine} stats --no-stream --format "{{.ID}}\t{{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}\t{{.MemPerc}}\t{{.NetIO}}" 2>/dev/null`, {
+      encoding: 'utf-8',
+      timeout: 3000,
+    });
+
+    const lines = raw.trim().split('\n').filter(Boolean);
+    const stats: ContainerStats[] = [];
+
+    for (const l of lines) {
+      const parts = l.split('\t');
+      if (parts.length >= 6) {
+        stats.push({
+          id: parts[0]?.trim() || '',
+          name: parts[1]?.trim() || '',
+          engine,
+          cpuPct: parts[2]?.trim() || '0%',
+          memUsage: parts[3]?.trim() || '0B',
+          memPct: parts[4]?.trim() || '0%',
+          netIO: parts[5]?.trim() || '0B/0B',
+        });
+      }
+    }
+
+    return stats;
+  } catch {
+    // Engine daemon might not be running
+    return [];
+  }
+}
+
+export async function runContainersCommand(opts?: { json?: boolean }): Promise<void> {
+  const stats = collectContainerStats();
+  const engine = detectContainerEngine();
+
+  if (opts?.json) {
+    console.log(JSON.stringify({ engine: engine || 'none', containers: stats }, null, 2));
+    return;
+  }
+
+  console.log(chalk.bold('\n  🔥 pyre containers — Container & Micro-VM Telemetry\n'));
+
+  if (!engine) {
+    console.log(chalk.yellow('  No container engine (Docker / Podman) detected in PATH.'));
+    console.log(chalk.dim('  Install Docker or Podman to enable container performance telemetry.\n'));
+    return;
+  }
+
+  if (stats.length === 0) {
+    console.log(chalk.dim(`  Engine: ${engine} (Active, 0 running containers detected)\n`));
+    return;
+  }
+
+  console.log(chalk.dim(`  Engine: ${engine} (${stats.length} active containers)\n`));
+
+  console.log(`  ${'ID'.padEnd(14)} ${'Name'.padEnd(24)} ${'CPU %'.padEnd(10)} ${'Memory Usage'.padEnd(22)} ${'Net I/O'}`);
+  console.log(chalk.dim('  ─'.repeat(40)));
+
+  for (const c of stats) {
+    const idCol = chalk.dim(c.id.padEnd(14));
+    const nameCol = chalk.bold.cyan(c.name.slice(0, 22).padEnd(24));
+    const cpuCol = chalk.yellow(c.cpuPct.padEnd(10));
+    const memCol = chalk.magenta(`${c.memUsage} (${c.memPct})`.padEnd(22));
+    const netCol = chalk.dim(c.netIO);
+    console.log(`  ${idCol} ${nameCol} ${cpuCol} ${memCol} ${netCol}`);
+  }
+
+  console.log();
+}

package/src/doctor.ts

@@ -336,14 +336,15 @@ async function runWindowsDoctor(): Promise<DoctorCheck[]> {
     });
   }
 
-  // 2. PowerShell / WMI Interface
+  // 2. PowerShell / WMI Interface (modern CIM check)
   try {
-    const wmiCheck = await run('wmic os get Caption 2>nul || powershell -Command "(Get-CimInstance Win32_OperatingSystem).Caption"', '');
+    const { runPowerShell } = await import('./monitors/run.js');
+    const wmiCheck = await runPowerShell('(Get-CimInstance Win32_OperatingSystem -ErrorAction SilentlyContinue).Caption', '');
     if (wmiCheck.toLowerCase().includes('windows')) {
       checks.push({
         name: 'WMI / CIM Subsystem',
         status: 'ok',
-        message: 'WMI/CIM management queries responsive.',
+        message: `WMI/CIM management queries responsive (${wmiCheck}).`,
       });
     } else {
       checks.push({
@@ -357,11 +358,90 @@ async function runWindowsDoctor(): Promise<DoctorCheck[]> {
     checks.push({
       name: 'WMI / CIM Subsystem',
       status: 'warn',
-      message: 'Could not execute WMI query.',
+      message: 'Could not execute WMI/CIM query.',
     });
   }
 
-  // 3. Network Reachability
+  // 3. Windows Defender / Antivirus Protection
+  try {
+    const { runPowerShell } = await import('./monitors/run.js');
+    const avRaw = await runPowerShell(
+      `$av = Get-CimInstance -Namespace root/SecurityCenter2 -ClassName AntiVirusProduct -ErrorAction SilentlyContinue; if ($av) { ($av | Select-Object -ExpandProperty displayName) -join ', ' } else { '' }`,
+      ''
+    );
+    if (avRaw.trim()) {
+      checks.push({
+        name: 'Antivirus Protection',
+        status: 'ok',
+        message: `Antivirus active (${avRaw.trim()}).`,
+      });
+    } else {
+      checks.push({
+        name: 'Antivirus Protection',
+        status: 'warn',
+        message: 'No third-party Antivirus reported via SecurityCenter2; Windows Defender active.',
+      });
+    }
+  } catch {
+    checks.push({
+      name: 'Antivirus Protection',
+      status: 'warn',
+      message: 'Could not query SecurityCenter2 status.',
+    });
+  }
+
+  // 4. User Account Control (UAC) Status
+  try {
+    const { runPowerShell } = await import('./monitors/run.js');
+    const uacRaw = await runPowerShell(
+      `(Get-ItemProperty -Path 'HKLM:\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Policies\\System' -Name EnableLUA -ErrorAction SilentlyContinue).EnableLUA`,
+      ''
+    );
+    if (uacRaw.trim() === '1') {
+      checks.push({
+        name: 'User Account Control',
+        status: 'ok',
+        message: 'UAC is enabled.',
+      });
+    } else {
+      checks.push({
+        name: 'User Account Control',
+        status: 'warn',
+        message: 'UAC is disabled or restricted.',
+        details: 'Running with UAC disabled allows processes elevated privileges without prompts.',
+      });
+    }
+  } catch {
+    checks.push({
+      name: 'User Account Control',
+      status: 'warn',
+      message: 'Could not query UAC registry status.',
+    });
+  }
+
+  // 5. Hardware Inventory (Intel / AMD CPU, NVIDIA / AMD / Intel GPU)
+  try {
+    const { runPowerShell } = await import('./monitors/run.js');
+    const cpuName = await runPowerShell('(Get-CimInstance Win32_Processor -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty Name)', '');
+    const gpuName = await runPowerShell('(Get-CimInstance Win32_VideoController -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty Name)', '');
+    const cpuVendor = cpuName.toLowerCase().includes('amd') ? 'AMD' : cpuName.toLowerCase().includes('intel') ? 'Intel' : 'x86/x64';
+    const gpuVendor = gpuName.toLowerCase().includes('nvidia') ? 'NVIDIA' : gpuName.toLowerCase().includes('amd') || gpuName.toLowerCase().includes('radeon') ? 'AMD' : gpuName.toLowerCase().includes('intel') ? 'Intel' : 'Standard';
+
+    checks.push({
+      name: 'Hardware Telemetry',
+      status: 'ok',
+      message: `${cpuVendor} CPU & ${gpuVendor} GPU recognized.`,
+      details: `CPU: ${cpuName.trim() || 'Generic'} | GPU: ${gpuName.trim() || 'Generic'}`,
+    });
+  } catch {
+    checks.push({
+      name: 'Hardware Telemetry',
+      status: 'warn',
+      message: 'Hardware inspection incomplete.',
+    });
+  }
+
+  // 6. Network Reachability
   try {
     const netCheck = await run('netstat -rn 2>nul', '');
     if (netCheck.includes('0.0.0.0')) {
@@ -385,7 +465,7 @@ async function runWindowsDoctor(): Promise<DoctorCheck[]> {
     });
   }
 
-  // 4. Config file integrity
+  // 7. Config file integrity
   checks.push(checkConfigIntegrity());
 
   return checks;

package/src/easy_features.test.ts

@@ -230,3 +230,86 @@ describe('Pyre Preferences, Autostart Service, and Settings UI', () => {
 
 
 
+describe('Mac Optimizer (pyre optimize)', async () => {
+  const opt = await import('./optimizeCmd.js');
+
+  it('parses durations', () => {
+    assert.strictEqual(opt.parseDuration('2h', 0), 7_200_000);
+    assert.strictEqual(opt.parseDuration('30m', 0), 1_800_000);
+    assert.strictEqual(opt.parseDuration('90s', 0), 90_000);
+    assert.strictEqual(opt.parseDuration('1d', 0), 86_400_000);
+    assert.strictEqual(opt.parseDuration('15', 0), 900_000);
+    assert.strictEqual(opt.parseDuration(undefined, 42), 42);
+    assert.ok(Number.isNaN(opt.parseDuration('soon', 0)));
+  });
+
+  it('parses lsappinfo list output (Foreground apps only)', () => {
+    const raw = ` 1) "loginwindow" ASN:0x0-0x3003: 
+    bundleID="com.apple.loginwindow"
+    pid = 414 type="UIElement" flavor=3
+ 4) "Terminal" ASN:0x0-0xa00a: 
+    bundleID="com.apple.Terminal"
+    pid = 615 type="Foreground" flavor=3 Version="470.2"
+    checkin time = 2026/10/10 09:07:09 ( 2 days ago )
+ 5) "Safari" ASN:0x0-0xb00b: 
+    bundleID="com.apple.Safari"
+    pid = 619 type="Foreground" flavor=3
+`;
+    const apps = opt.parseLsappinfoList(raw);
+    assert.strictEqual(apps.length, 2);
+    assert.deepStrictEqual(apps.map(a => a.bundleId), ['com.apple.Terminal', 'com.apple.Safari']);
+    assert.strictEqual(apps[0].pid, 615);
+    assert.strictEqual(apps[0].asn, 'ASN:0x0-0xa00a');
+    assert.strictEqual(apps[0].launchedAt, new Date(2026, 9, 10, 9, 7, 9).getTime());
+  });
+
+  it('parses visible process order', () => {
+    const order = opt.parseAsnList('ASN:0x0-0xb00b-"Safari": ASN:0x0-0x598598-"Antigravity": ASN:0x0-0xb00b-"Safari":');
+    assert.deepStrictEqual(order, ['ASN:0x0-0xb00b', 'ASN:0x0-0x598598']);
+  });
+
+  const now = new Date(2026, 9, 12, 12, 0, 0).getTime();
+  const H = 3_600_000;
+  const mk = (name: string, rank: number, extra: Partial<import('./optimizeCmd.js').RunningApp> = {}) => ({
+    asn: `ASN:0x0-0x${rank}`, name, bundleId: `com.test.${name.toLowerCase()}`, pid: 1000 + rank,
+    launchedAt: now - 24 * H, rank, cpu: 0, rssKb: 100_000, frontmost: false, ...extra,
+  });
+  const baseCtx = { now, idleThresholdMs: 2 * H, keepRecent: 2, protectedApps: [] as string[], selfPids: new Set<number>() };
+
+  it('selects by rank when no tracking data, honoring keep/protected/busy/self', () => {
+    const apps = [
+      mk('Front', 0, { frontmost: true }),
+      mk('Recent', 1),
+      mk('Finder', 2, { bundleId: 'com.apple.finder' }),
+      mk('Busy', 3, { cpu: 30 }),
+      mk('Mine', 4, { pid: 777 }),
+      mk('Fresh', 5, { launchedAt: now - 10 * 60_000 }),
+      mk('Music', 6, { bundleId: 'com.apple.Music', cpu: 2 }),
+      mk('Old', 7),
+      mk('Custom', 8),
+    ];
+    const { candidates, skipped } = opt.selectIdleApps(apps, { ...baseCtx, protectedApps: ['custom'], selfPids: new Set([777]) });
+    assert.deepStrictEqual(candidates.map(c => c.app.name), ['Old']);
+    assert.strictEqual(candidates[0].idleMs, undefined);
+    assert.strictEqual(skipped.length, 8);
+  });
+
+  it('uses fresh tracking data for real idle times', () => {
+    const usage = {
+      version: 1 as const, trackingSince: now - 10 * H, updatedAt: now - 5000,
+      apps: { 'com.test.used': { name: 'Used', lastActive: now - 30 * 60_000 }, 'com.test.stale': { name: 'Stale', lastActive: now - 5 * H } },
+    };
+    const apps = [mk('A', 0), mk('B', 1), mk('Used', 2), mk('Stale', 3), mk('Never', 4)];
+    const { candidates } = opt.selectIdleApps(apps, { ...baseCtx, usage });
+    assert.deepStrictEqual(candidates.map(c => c.app.name), ['Stale', 'Never']);
+    assert.strictEqual(candidates[0].idleMs, 5 * H);
+    // Never seen since tracking began 10h ago → idle bounded by trackingSince
+    assert.strictEqual(candidates[1].idleMs, 10 * H);
+  });
+
+  it('ignores stale tracking data (tracker not running)', () => {
+    const usage = { version: 1 as const, trackingSince: now - 10 * H, updatedAt: now - 3 * H, apps: {} };
+    assert.strictEqual(opt.isTrackingFresh(usage, now), false);
+    assert.strictEqual(opt.computeIdleMs(mk('X', 5), usage, now), undefined);
+  });
+});

package/src/flightRecorder.ts

@@ -0,0 +1,214 @@
+/**
+ * pyre flight — In-Memory Forensic Flight Recorder (Black Box).
+ *
+ * Maintains a circular memory buffer of recent high-resolution telemetry frames.
+ * Dumps structured post-mortem forensic reports when freezes, thermal throttles,
+ * or runaway process spikes occur.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import chalk from 'chalk';
+import { collectAll } from './monitors/collectors.js';
+import { getConfigDir } from './state/config.js';
+
+export interface FlightFrame {
+  timestamp: string;
+  cpu: {
+    usage: number;
+    temp?: number;
+    loadAvg: number[];
+  };
+  memory: {
+    usagePercent: number;
+    usedBytes: number;
+    totalBytes: number;
+  };
+  network: {
+    rxPackets: number;
+    txPackets: number;
+  };
+  topProcesses: Array<{
+    pid: number;
+    name: string;
+    cpu: number;
+    mem: number;
+  }>;
+}
+
+export interface FlightReport {
+  generatedAt: string;
+  frameCount: number;
+  timeSpanSec: number;
+  summary: {
+    peakCpuUsage: number;
+    peakMemUsage: number;
+    peakTempC?: number;
+    highestCpuProcess?: { name: string; pid: number; cpu: number };
+    highestMemProcess?: { name: string; pid: number; mem: number };
+  };
+  frames: FlightFrame[];
+}
+
+export class FlightRecorder {
+  private buffer: FlightFrame[] = [];
+  private maxFrames: number;
+
+  constructor(maxFrames = 600) {
+    this.maxFrames = maxFrames;
+  }
+
+  public push(frame: FlightFrame): void {
+    if (this.buffer.length >= this.maxFrames) {
+      this.buffer.shift();
+    }
+    this.buffer.push(frame);
+  }
+
+  public size(): number {
+    return this.buffer.length;
+  }
+
+  public getFrames(): FlightFrame[] {
+    return [...this.buffer];
+  }
+
+  public clear(): void {
+    this.buffer = [];
+  }
+
+  public generateReport(): FlightReport {
+    const frames = this.getFrames();
+    let peakCpu = 0;
+    let peakMem = 0;
+    let peakTemp: number | undefined = undefined;
+    let highestCpuProc: { name: string; pid: number; cpu: number } | undefined = undefined;
+    let highestMemProc: { name: string; pid: number; mem: number } | undefined = undefined;
+
+    for (const f of frames) {
+      if (f.cpu.usage > peakCpu) peakCpu = f.cpu.usage;
+      if (f.memory.usagePercent > peakMem) peakMem = f.memory.usagePercent;
+      if (f.cpu.temp !== undefined) {
+        if (peakTemp === undefined || f.cpu.temp > peakTemp) peakTemp = f.cpu.temp;
+      }
+      for (const p of f.topProcesses) {
+        if (!highestCpuProc || p.cpu > highestCpuProc.cpu) {
+          highestCpuProc = { name: p.name, pid: p.pid, cpu: p.cpu };
+        }
+        if (!highestMemProc || p.mem > highestMemProc.mem) {
+          highestMemProc = { name: p.name, pid: p.pid, mem: p.mem };
+        }
+      }
+    }
+
+    const timeSpanSec = frames.length > 1
+      ? Math.round((new Date(frames[frames.length - 1].timestamp).getTime() - new Date(frames[0].timestamp).getTime()) / 1000)
+      : 0;
+
+    return {
+      generatedAt: new Date().toISOString(),
+      frameCount: frames.length,
+      timeSpanSec,
+      summary: {
+        peakCpuUsage: peakCpu,
+        peakMemUsage: peakMem,
+        peakTempC: peakTemp,
+        highestCpuProcess: highestCpuProc,
+        highestMemProcess: highestMemProc,
+      },
+      frames,
+    };
+  }
+
+  public dump(outDir?: string): string {
+    const report = this.generateReport();
+    const targetDir = outDir || path.join(process.cwd(), 'pyre-exports');
+    if (!fs.existsSync(targetDir)) {
+      fs.mkdirSync(targetDir, { recursive: true });
+    }
+    const filename = `pyre-flight-${Date.now()}.json`;
+    const fullPath = path.join(targetDir, filename);
+    fs.writeFileSync(fullPath, JSON.stringify(report, null, 2), 'utf-8');
+    return fullPath;
+  }
+}
+
+// Global shared recorder instance
+export const globalFlightRecorder = new FlightRecorder(600);
+
+export async function captureCurrentFlightFrame(): Promise<FlightFrame> {
+  const data = await collectAll();
+  const sortedProcs = [...(data.processes || [])].sort((a, b) => b.cpu - a.cpu).slice(0, 5);
+
+  return {
+    timestamp: new Date().toISOString(),
+    cpu: {
+      usage: data.cpu.usage,
+      temp: data.cpu.temperature,
+      loadAvg: data.cpu.loadAvg || [],
+    },
+    memory: {
+      usagePercent: data.memory.usagePercent,
+      usedBytes: data.memory.used,
+      totalBytes: data.memory.total,
+    },
+    network: {
+      rxPackets: data.network.rxPackets,
+      txPackets: data.network.txPackets,
+    },
+    topProcesses: sortedProcs.map((p) => ({
+      pid: p.pid,
+      name: p.command,
+      cpu: p.cpu,
+      mem: p.mem,
+    })),
+  };
+}
+
+export async function runFlightCommand(subcommand = 'dump', opts?: { out?: string; duration?: number }): Promise<void> {
+  if (subcommand === 'status') {
+    const size = globalFlightRecorder.size();
+    console.log(chalk.bold('\n  🔥 pyre Flight Recorder Status\n'));
+    console.log(`  Buffer Frames: ${chalk.green(size)} / 600`);
+    console.log(`  RAM Footprint: ~${((size * 1.5) / 1024).toFixed(2)} MB`);
+    console.log(chalk.dim('  Run `pyre flight dump` to generate a post-mortem forensic file.\n'));
+    return;
+  }
+
+  if (subcommand === 'record') {
+    const durationSec = opts?.duration || 10;
+    console.log(chalk.bold(`\n  🔥 Sampling Flight Recorder for ${durationSec}s...\n`));
+    for (let i = 0; i < durationSec; i++) {
+      const frame = await captureCurrentFlightFrame();
+      globalFlightRecorder.push(frame);
+      process.stdout.write(`\r  Sampled frame ${i + 1}/${durationSec}...`);
+      await new Promise((r) => setTimeout(r, 1000));
+    }
+    console.log('\n');
+    const file = globalFlightRecorder.dump(opts?.out);
+    console.log(chalk.green(`  ✔ Flight recording saved to: ${file}\n`));
+    return;
+  }
+
+  // Default: dump
+  // Capture at least one fresh frame if buffer empty
+  if (globalFlightRecorder.size() === 0) {
+    const frame = await captureCurrentFlightFrame();
+    globalFlightRecorder.push(frame);
+  }
+
+  const file = globalFlightRecorder.dump(opts?.out);
+  const report = globalFlightRecorder.generateReport();
+
+  console.log(chalk.bold('\n  🔥 pyre Flight Recorder — Forensic Dump\n'));
+  console.log(chalk.dim(`  Output File:  ${file}`));
+  console.log(`  Frames:       ${chalk.bold(report.frameCount)}`);
+  console.log(`  Peak CPU:     ${chalk.yellow(report.summary.peakCpuUsage.toFixed(1) + '%')}`);
+  console.log(`  Peak Memory:  ${chalk.magenta(report.summary.peakMemUsage.toFixed(1) + '%')}`);
+  if (report.summary.peakTempC !== undefined) {
+    console.log(`  Peak Temp:    ${chalk.red(report.summary.peakTempC.toFixed(1) + '°C')}`);
+  }
+  if (report.summary.highestCpuProcess) {
+    console.log(`  Top CPU Proc: ${chalk.cyan(report.summary.highestCpuProcess.name)} (PID: ${report.summary.highestCpuProcess.pid}, ${report.summary.highestCpuProcess.cpu.toFixed(1)}%)`);
+  }
+  console.log();
+}