feat: connection health tracking and wait command (#27)

* feat: add connection health tracking

Track connect, disconnect, and reconnect events with timestamps in
DevToolsBridge. Show last connection event in status output and a
contextual hint when get-tree returns empty after a disconnect.

* feat: add wait command

Add wait --connected and wait --component <name> to block until
a condition is met. Uses long-poll over IPC with onStateChange
listener. Supports --timeout (default 30s), exits non-zero on timeout.

* fix: gate reconnect on 0→1 transition and validate --component arg

Reconnect events now only fire when going from zero connected apps
to one within the reconnect window, avoiding false reconnect events
in multi-app sessions. Also use typeof check for --component flag
to reject missing argument before the IPC call.

* fix: validate numeric CLI flags with parseNumericFlag helper

Extract a shared parseNumericFlag() that validates parseInt results
and exits with a clear error on non-numeric input. Replaces inline
parseInt calls for --port, --depth, --timeout, and --limit flags.

Author: piotrski

.changeset/connection-health.md

@@ -0,0 +1,8 @@
+---
+"agent-react-devtools": minor
+---
+
+Show connection health in `status` and `get tree`
+
+- Show last connection event in `status` (e.g. "app reconnected 3s ago")
+- Show contextual hint when `get tree` returns empty after a disconnect

.changeset/wait-command.md

@@ -0,0 +1,9 @@
+---
+"agent-react-devtools": minor
+---
+
+Add `wait` command
+
+- `wait --connected` — block until a React app connects
+- `wait --component <name>` — block until a named component appears in the tree
+- Both support `--timeout` (default 30s) and exit non-zero on timeout

README.md

@@ -35,6 +35,7 @@ agent-react-devtools status
 Daemon: running (port 8097)
 Apps: 1 connected, 24 components
 Uptime: 12s
+Last event: app connected 3s ago
 ```
 
 Browse the component tree:
@@ -122,6 +123,17 @@ agent-react-devtools count                          # Component count by type
 
 Components are labeled `@c1`, `@c2`, etc. You can use these labels or numeric IDs interchangeably.
 
+### Wait
+
+Block until a condition is met. Useful in scripts or agent workflows where the daemon starts before the app:
+
+```sh
+agent-react-devtools wait --connected [--timeout 30]          # Block until an app connects
+agent-react-devtools wait --component App [--timeout 30]      # Block until a component appears
+```
+
+Exits with code 0 when the condition is met, or code 1 on timeout.
+
 ### Profiling
 
 ```sh

packages/agent-react-devtools/skills/react-devtools/SKILL.md

@@ -10,7 +10,7 @@ CLI that connects to a running React or React Native app via the React DevTools
 
 ## Core Workflow
 
-1. **Ensure connection** — check `agent-react-devtools status`. If the daemon is not running, start it with `agent-react-devtools start`.
+1. **Ensure connection** — check `agent-react-devtools status`. If the daemon is not running, start it with `agent-react-devtools start`. Use `agent-react-devtools wait --connected` to block until a React app connects.
 2. **Inspect** — get the component tree, search for components, inspect props/state/hooks.
 3. **Profile** — start profiling, trigger the interaction (or ask the user to), stop profiling, analyze results.
 4. **Act** — use the data to fix the bug, optimize performance, or explain what's happening.
@@ -22,7 +22,9 @@ CLI that connects to a running React or React Native app via the React DevTools
 ```bash
 agent-react-devtools start              # Start daemon (auto-starts on first command)
 agent-react-devtools stop               # Stop daemon
-agent-react-devtools status             # Check connection: port, connected apps, component count
+agent-react-devtools status             # Check connection, component count, last event
+agent-react-devtools wait --connected   # Block until a React app connects
+agent-react-devtools wait --component App # Block until a component appears
 ```
 
 ### Component Inspection
@@ -95,6 +97,15 @@ Render causes: `props-changed`, `state-changed`, `hooks-changed`, `parent-render
 
 ## Common Patterns
 
+### Wait for the app to connect after a reload
+
+```bash
+agent-react-devtools wait --connected --timeout 10
+agent-react-devtools get tree
+```
+
+Use this after triggering a page reload or HMR update to avoid querying empty state.
+
 ### Diagnose slow interactions
 
 ```bash
@@ -135,7 +146,7 @@ agent-react-devtools status  # Should show 1 connected app
 
 ## Important Rules
 
-- **Labels reset** when the app reloads or components unmount/remount. Always re-check with `get tree` or `find` after a page reload.
+- **Labels reset** when the app reloads or components unmount/remount. After a reload, use `wait --connected` then re-check with `get tree` or `find`.
 - **`status` first** — if status shows 0 connected apps, the React app is not connected. The user may need to run `npx agent-react-devtools init` in their project first.
 - **Headed browser required** — if using `agent-browser`, always use `--headed` mode. Headless Chromium does not properly load the devtools connect script.
 - **Profile while interacting** — profiling only captures renders that happen between `profile start` and `profile stop`. Make sure the relevant interaction happens during that window.

packages/agent-react-devtools/skills/react-devtools/references/commands.md

@@ -9,17 +9,24 @@ Start the background daemon. Default port: 8097. The daemon listens for WebSocke
 Stop the daemon process. All connection state is lost.
 
 ### `agent-react-devtools status`
-Show daemon status: port, connected apps, component count, profiling state, uptime.
+Show daemon status: port, connected apps, component count, profiling state, uptime, and last connection event.
 
 Output:
 ```
 Daemon: running (port 8097)
 Apps: 1 connected, 42 components
+Last event: app connected 3s ago
 Uptime: 120s
 ```
 
 If profiling is active, shows `Profiling: active`.
 
+### `agent-react-devtools wait --connected [--timeout S]`
+Block until at least one React app connects via WebSocket. Resolves immediately if already connected. Default timeout: 30s. Exits non-zero on timeout.
+
+### `agent-react-devtools wait --component <name> [--timeout S]`
+Block until a component with the given display name appears in the tree. Uses exact name matching. Useful after a reload to wait for a specific part of the UI to render. Default timeout: 30s. Exits non-zero on timeout.
+
 ## Component Inspection
 
 ### `agent-react-devtools get tree [--depth N]`

packages/agent-react-devtools/src/__tests__/formatters.test.ts

@@ -5,6 +5,7 @@ import {
   formatSearchResults,
   formatCount,
   formatStatus,
+  formatAgo,
   formatProfileSummary,
   formatProfileReport,
   formatSlowest,
@@ -13,12 +14,18 @@ import {
   formatCommitDetail,
 } from '../formatters.js';
 import type { TreeNode } from '../component-tree.js';
-import type { InspectedElement, StatusInfo, ComponentRenderReport } from '../types.js';
+import type { InspectedElement, StatusInfo, ComponentRenderReport, ConnectionHealth } from '../types.js';
 import type { ProfileSummary, TimelineEntry, CommitDetail } from '../profiler.js';
 
 describe('formatTree', () => {
   it('should format empty tree', () => {
     expect(formatTree([])).toContain('No components');
+    expect(formatTree([])).toContain('is a React app connected?');
+  });
+
+  it('should show hint when provided for empty tree', () => {
+    const result = formatTree([], 'app disconnected 5s ago, waiting for reconnect...');
+    expect(result).toBe('No components (app disconnected 5s ago, waiting for reconnect...)');
   });
 
   it('should format a simple tree', () => {
@@ -123,6 +130,13 @@ describe('formatCount', () => {
 });
 
 describe('formatStatus', () => {
+  const baseConnection: ConnectionHealth = {
+    connectedApps: 1,
+    hasEverConnected: true,
+    lastDisconnectAt: null,
+    recentEvents: [],
+  };
+
   it('should format status info', () => {
     const status: StatusInfo = {
       daemonRunning: true,
@@ -131,6 +145,7 @@ describe('formatStatus', () => {
       componentCount: 47,
       profilingActive: false,
       uptime: 12000,
+      connection: baseConnection,
     };
 
     const result = formatStatus(status);
@@ -139,6 +154,64 @@ describe('formatStatus', () => {
     expect(result).toContain('1 connected');
     expect(result).toContain('47 components');
   });
+
+  it('should show last connection event', () => {
+    const now = Date.now();
+    const status: StatusInfo = {
+      daemonRunning: true,
+      port: 8097,
+      connectedApps: 1,
+      componentCount: 10,
+      profilingActive: false,
+      uptime: 5000,
+      connection: {
+        ...baseConnection,
+        recentEvents: [
+          { type: 'connected', timestamp: now - 3000 },
+        ],
+      },
+    };
+
+    const result = formatStatus(status);
+    expect(result).toContain('Last event: app connected 3s ago');
+  });
+
+  it('should show reconnected event', () => {
+    const now = Date.now();
+    const status: StatusInfo = {
+      daemonRunning: true,
+      port: 8097,
+      connectedApps: 1,
+      componentCount: 10,
+      profilingActive: false,
+      uptime: 5000,
+      connection: {
+        ...baseConnection,
+        recentEvents: [
+          { type: 'disconnected', timestamp: now - 4000 },
+          { type: 'reconnected', timestamp: now - 2000 },
+        ],
+      },
+    };
+
+    const result = formatStatus(status);
+    expect(result).toContain('Last event: app reconnected 2s ago');
+  });
+
+  it('should not show events line when no events', () => {
+    const status: StatusInfo = {
+      daemonRunning: true,
+      port: 8097,
+      connectedApps: 0,
+      componentCount: 0,
+      profilingActive: false,
+      uptime: 1000,
+      connection: baseConnection,
+    };
+
+    const result = formatStatus(status);
+    expect(result).not.toContain('Last event');
+  });
 });
 
 describe('formatProfileSummary', () => {

packages/agent-react-devtools/src/cli.ts

@@ -37,6 +37,10 @@ Components:
   find <name> [--exact]         Search by display name
   count                         Component count by type
 
+Wait:
+  wait --connected [--timeout S]       Block until an app connects
+  wait --component <name> [--timeout S]  Block until a component appears
+
 Profiling:
   profile start [name]          Start profiling session
   profile stop                  Stop profiling, collect data
@@ -78,6 +82,21 @@ function parseArgs(argv: string[]): {
   return { command, flags };
 }
 
+function parseNumericFlag(
+  flags: Record<string, string | boolean>,
+  name: string,
+  defaultValue?: number,
+): number | undefined {
+  const raw = flags[name];
+  if (raw === undefined || raw === true) return defaultValue;
+  const n = parseInt(raw as string, 10);
+  if (isNaN(n)) {
+    console.error(`Invalid value for --${name}: expected a number`);
+    process.exit(1);
+  }
+  return n;
+}
+
 async function main(): Promise<void> {
   const { command, flags } = parseArgs(process.argv.slice(2));
 
@@ -104,7 +123,7 @@ async function main(): Promise<void> {
 
     // ── Daemon management ──
     if (cmd0 === 'start') {
-      const port = flags['port'] ? parseInt(flags['port'] as string, 10) : undefined;
+      const port = parseNumericFlag(flags, 'port');
       await ensureDaemon(port);
       const resp = await sendCommand({ type: 'status' });
       if (resp.ok) {
@@ -145,13 +164,11 @@ async function main(): Promise<void> {
 
     // ── Component inspection ──
     if (cmd0 === 'get' && cmd1 === 'tree') {
-      const depth = flags['depth']
-        ? parseInt(flags['depth'] as string, 10)
-        : undefined;
+      const depth = parseNumericFlag(flags, 'depth');
       const ipcCmd: IpcCommand = { type: 'get-tree', depth };
       const resp = await sendCommand(ipcCmd);
       if (resp.ok) {
-        console.log(formatTree(resp.data as any));
+        console.log(formatTree(resp.data as any, resp.hint));
       } else {
         console.error(resp.error);
         process.exit(1);
@@ -208,6 +225,42 @@ async function main(): Promise<void> {
       return;
     }
 
+    // ── Wait ──
+    if (cmd0 === 'wait') {
+      const timeoutSec = parseNumericFlag(flags, 'timeout', 30)!;
+      const timeoutMs = timeoutSec * 1000;
+      const socketTimeout = timeoutMs + 5000;
+
+      let ipcCmd: IpcCommand;
+      if (flags['connected'] !== undefined) {
+        ipcCmd = { type: 'wait', condition: 'connected', timeout: timeoutMs };
+      } else if (flags['component'] !== undefined) {
+        if (typeof flags['component'] !== 'string') {
+          console.error('Usage: devtools wait --component <name> [--timeout S]');
+          process.exit(1);
+        }
+        ipcCmd = { type: 'wait', condition: 'component', name: flags['component'], timeout: timeoutMs };
+      } else {
+        console.error('Usage: devtools wait --connected|--component <name> [--timeout S]');
+        process.exit(1);
+      }
+
+      const resp = await sendCommand(ipcCmd, socketTimeout);
+      if (resp.ok) {
+        const result = resp.data as { met: boolean; condition: string; timeout?: boolean };
+        if (result.met) {
+          console.log(`Condition met: ${result.condition}`);
+        } else {
+          console.error(`Timed out waiting for: ${result.condition}`);
+          process.exit(1);
+        }
+      } else {
+        console.error(resp.error);
+        process.exit(1);
+      }
+      return;
+    }
+
     // ── Profiling ──
     if (cmd0 === 'profile' && cmd1 === 'start') {
       const name = command[2];
@@ -254,7 +307,7 @@ async function main(): Promise<void> {
     }
 
     if (cmd0 === 'profile' && cmd1 === 'slow') {
-      const limit = flags['limit'] ? parseInt(flags['limit'] as string, 10) : undefined;
+      const limit = parseNumericFlag(flags, 'limit');
       const resp = await sendCommand({ type: 'profile-slow', limit });
       if (resp.ok) {
         console.log(formatSlowest(resp.data as any));
@@ -266,7 +319,7 @@ async function main(): Promise<void> {
     }
 
     if (cmd0 === 'profile' && cmd1 === 'rerenders') {
-      const limit = flags['limit'] ? parseInt(flags['limit'] as string, 10) : undefined;
+      const limit = parseNumericFlag(flags, 'limit');
       const resp = await sendCommand({ type: 'profile-rerenders', limit });
       if (resp.ok) {
         console.log(formatRerenders(resp.data as any));
@@ -288,7 +341,7 @@ async function main(): Promise<void> {
         console.error('Usage: devtools profile commit <N | #N>');
         process.exit(1);
       }
-      const limit = flags['limit'] ? parseInt(flags['limit'] as string, 10) : undefined;
+      const limit = parseNumericFlag(flags, 'limit');
       const resp = await sendCommand({ type: 'profile-commit', index, limit });
       if (resp.ok) {
         console.log(formatCommitDetail(resp.data as any));
@@ -300,7 +353,7 @@ async function main(): Promise<void> {
     }
 
     if (cmd0 === 'profile' && cmd1 === 'timeline') {
-      const limit = flags['limit'] ? parseInt(flags['limit'] as string, 10) : undefined;
+      const limit = parseNumericFlag(flags, 'limit');
       const resp = await sendCommand({ type: 'profile-timeline', limit });
       if (resp.ok) {
         console.log(formatTimeline(resp.data as any));

packages/agent-react-devtools/src/daemon-client.ts

@@ -108,7 +108,7 @@ export function stopDaemon(): boolean {
   }
 }
 
-export function sendCommand(cmd: IpcCommand): Promise<IpcResponse> {
+export function sendCommand(cmd: IpcCommand, socketTimeout = 30_000): Promise<IpcResponse> {
   return new Promise((resolve, reject) => {
     const socketPath = getSocketPath();
 
@@ -135,8 +135,7 @@ export function sendCommand(cmd: IpcCommand): Promise<IpcResponse> {
       reject(new Error(`Cannot connect to daemon: ${err.message}`));
     });
 
-    // Timeout after 30 seconds
-    conn.setTimeout(30_000, () => {
+    conn.setTimeout(socketTimeout, () => {
       conn.destroy();
       reject(new Error('Command timed out'));
     });