@matware/e2e-runner 1.2.1 → 1.3.0

package/agents/test-creator.md

@@ -69,6 +69,17 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 - Clear field → `clear`
 - Submit → `click` on submit button or `press` Enter
 
+### Storage
+- Set localStorage key → `set_storage` with `value: "key=val"`
+- Set sessionStorage key → `set_storage` with `value: "key=val"`, `selector: "session"`
+- Assert storage key exists → `assert_storage` with `value: "key"`
+- Assert storage value → `assert_storage` with `value: "key=expected"`
+
+### Smart Clicks
+- Click icon button → `click_icon` with `value` (icon identifier like "edit", "delete")
+- Click menu item → `click_menu_item` with `text` (after opening the menu)
+- Click element in a specific row/card → `click_in_context` with `text` (row text) + `selector` (child to click)
+
 ### Waiting
 - Element appears → `wait` with `selector`
 - Text appears → `wait` with `text`
@@ -86,12 +97,54 @@ You are a specialist in creating robust E2E tests for web applications. You expl
 - CSS class → `assert_class`
 - URL → `assert_url`
 
+### Naming Rules (CRITICAL)
+- **Suite file names MUST be unique and specific** to the feature, issue, or user flow being tested
+- NEVER use generic names like `all`, `test`, `tests`, `debug`, `new`, `temp`, `main`, `suite`
+- Include the feature or issue context: `login-valid-credentials`, `issue-1743-auth-redirect`, `checkout-payment-flow`
+- If testing a GitHub/GitLab issue, include the issue number: `issue-1743-auth-timeout`, `bug-502-duplicate-submit`
+- Before creating a test, call `e2e_list` and verify your chosen name doesn't already exist
+- Individual test names within a suite must also be unique and descriptive
+
+### Variables
+- Use `{{var.KEY}}` to reference project variables instead of hardcoding sensitive values (tokens, IDs, secrets)
+- Use `{{env.KEY}}` to reference environment variables from `process.env`
+- Variables are stored in SQLite and managed via `e2e_vars` MCP tool or the dashboard UI
+- Suite-scoped variables override project-scoped variables with the same key
+- Example: `{ "type": "set_storage", "value": "accessToken={{var.JWT_TOKEN}}" }`
+- Example: `{ "type": "goto", "value": "/patient/{{var.PATIENT_ID}}" }`
+
+### DRY Patterns (CRITICAL)
+
+Before creating tests, **always check existing modules** with `Glob` on `e2e/modules/*.json`. Reuse existing modules instead of duplicating actions.
+
+**Use `beforeEach` when auth or setup is repeated across tests:**
+When multiple tests in a suite share the same setup (e.g., same auth-jwt call), use the object format with `beforeEach` instead of repeating it in every test:
+
+```json
+{
+  "beforeEach": [
+    { "$use": "auth-jwt", "params": { "token": "{{var.JWT_TOKEN}}", "institutionId": "{{var.INST_ID}}" } }
+  ],
+  "tests": [
+    { "name": "test-one", "actions": [...] },
+    { "name": "test-two", "actions": [...] }
+  ]
+}
+```
+
+**Create modules for repeated action patterns:**
+When 3+ tests repeat the same sequence (e.g., goto → wait → screenshot), create a module first with `e2e_create_module`, then use `$use` in the tests. This reduces test size by 70-80%.
+
+**Use the object format (not array) when hooks are needed:**
+- Array format: `[{ "name": ..., "actions": [...] }]` — no hooks
+- Object format: `{ "beforeEach": [...], "tests": [...] }` — with hooks
+
 ### Best Practices
 - Never use `evaluate` when a built-in action exists
+- **Never hardcode tokens, passwords, or IDs in test files** — use `{{var.KEY}}` variables instead
 - Add `retries` to actions on dynamically loaded elements
 - Mark state-sharing tests as `serial: true`
 - Use `screenshot` actions at key points for debugging
-- Keep test names descriptive and kebab-case (`login-valid-credentials`)
 
 ## Output
 

package/agents/test-improver.md

@@ -73,6 +73,11 @@ When you find an `evaluate` action, check if it matches one of these patterns
 | `MuiAutocomplete-root...input.focus()` | `focus_autocomplete` with `text` |
 | `querySelectorAll('button').filter(regex)...click()` | `click_regex` with `text` + optional `selector` + `value` |
 | `querySelectorAll('[class*="Chip"]')...click()` | `click_chip` with `text` |
+| `localStorage.setItem(key, val)` or `sessionStorage.setItem(...)` | `set_storage` with `value: "key=val"`, `selector: "session"` for session |
+| `localStorage.getItem(key)` check or `sessionStorage.getItem(...)` | `assert_storage` with `value: "key"` or `"key=expected"`, `selector: "session"` for session |
+| `querySelector('svg[data-testid]').closest('button').click()` | `click_icon` with `value` (icon identifier) + optional `selector` (scope) |
+| `querySelectorAll('[role="menuitem"]')...click()` | `click_menu_item` with `text` + optional `selector` (scope) |
+| Container-by-text then child click: `rows.find(r => r.textContent.includes(text))...querySelector(child).click()` | `click_in_context` with `text` (container) + `selector` (child) |
 | `document.title` or simple property read | `get_text` or `evaluate` (keep if no built-in equivalent) |
 
 ### Replacement Examples
@@ -101,6 +106,38 @@ When you find an `evaluate` action, check if it matches one of these patterns
 { "type": "click_option", "text": "Cefalea" }
 ```
 
+```json
+// BEFORE: evaluate for localStorage
+{ "type": "evaluate", "value": "localStorage.setItem('authToken', 'abc123')" }
+
+// AFTER: one action
+{ "type": "set_storage", "value": "authToken=abc123" }
+```
+
+```json
+// BEFORE: evaluate for icon click
+{ "type": "evaluate", "value": "document.querySelector('svg[data-testid=\"EditIcon\"]').closest('button').click()" }
+
+// AFTER: one action
+{ "type": "click_icon", "value": "Edit" }
+```
+
+```json
+// BEFORE: evaluate for menu item click
+{ "type": "evaluate", "value": "const items = [...document.querySelectorAll('[role=\"menuitem\"]')]; items.find(el => el.textContent.includes('Delete')).click();" }
+
+// AFTER: one action
+{ "type": "click_menu_item", "text": "Delete" }
+```
+
+```json
+// BEFORE: evaluate for contextual click
+{ "type": "evaluate", "value": "const rows = [...document.querySelectorAll('tr')]; const row = rows.find(r => r.textContent.includes('John Doe')); row.querySelector('button.edit').click();" }
+
+// AFTER: one action
+{ "type": "click_in_context", "text": "John Doe", "selector": "button.edit" }
+```
+
 ## Duplication Detection
 
 Look for these common duplication patterns:

package/bin/cli.js

@@ -14,6 +14,8 @@
  *   e2e-runner pool status                Show pool status
  *   e2e-runner pool restart               Restart the pool
  *   e2e-runner dashboard                   Start the web dashboard
+ *   e2e-runner watch --interval 15m       Watch mode: scheduled test runs
+ *   e2e-runner watch --git                Watch mode: run on git changes
  *   e2e-runner capture <url>              Capture a screenshot of any URL
  *   e2e-runner issue <url>                Fetch issue and show details
  *   e2e-runner issue <url> --generate     Generate test file via Claude API
@@ -29,10 +31,12 @@ import path from 'path';
 import http from 'http';
 import { fileURLToPath } from 'url';
 import { loadConfig } from '../src/config.js';
-import { startPool, stopPool, restartPool, getPoolStatus, waitForPool, connectToPool } from '../src/pool.js';
+import { startPool, stopPool, restartPool, connectToPool } from '../src/pool.js';
+import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool, selectPool } from '../src/pool-manager.js';
 import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from '../src/runner.js';
-import { generateReport, saveReport, printReport, persistRun } from '../src/reporter.js';
+import { generateReport, saveReport, printReport, persistRun, printInsights } from '../src/reporter.js';
 import { startDashboard } from '../src/dashboard.js';
+import { startWatch } from '../src/watch.js';
 import { fetchIssue } from '../src/issues.js';
 import { buildPrompt, generateTests, hasApiKey } from '../src/ai-generate.js';
 import { verifyIssue } from '../src/verify.js';
@@ -41,6 +45,22 @@ import { log, colors as C } from '../src/logger.js';
 import { listModules } from '../src/module-resolver.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from '../src/learner-sqlite.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from '../src/neo4j-pool.js';
+import { 
+  generateApiKey, 
+  generateTotpSecret, 
+  generateTotpUri, 
+  generateMasterKey,
+  hashApiKey,
+  migrateSyncSchema,
+  createInstance,
+  getInstance,
+  listInstances,
+  updateInstanceStatus,
+  getHubConnection,
+  getQueueStats,
+  getSyncClient,
+  pullRuns,
+} from '../src/sync/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -63,6 +83,7 @@ function parseCLIConfig() {
   const cliArgs = {};
   if (getFlag('--base-url')) cliArgs.baseUrl = getFlag('--base-url');
   if (getFlag('--pool-url')) cliArgs.poolUrl = getFlag('--pool-url');
+  if (getFlag('--pool-urls')) cliArgs.poolUrls = getFlag('--pool-urls').split(',').map(u => u.trim()).filter(Boolean);
   if (getFlag('--tests-dir')) cliArgs.testsDir = getFlag('--tests-dir');
   if (getFlag('--modules-dir')) cliArgs.modulesDir = getFlag('--modules-dir');
   if (getFlag('--screenshots-dir')) cliArgs.screenshotsDir = getFlag('--screenshots-dir');
@@ -84,6 +105,19 @@ function parseCLIConfig() {
   if (getFlag('--auth-token')) cliArgs.authToken = getFlag('--auth-token');
   if (getFlag('--auth-storage-key')) cliArgs.authStorageKey = getFlag('--auth-storage-key');
   if (getFlag('--test-type')) cliArgs.testType = getFlag('--test-type');
+  if (getFlag('--network-ignore-domains')) cliArgs.networkIgnoreDomains = getFlag('--network-ignore-domains').split(',').map(d => d.trim()).filter(Boolean);
+  if (getFlag('--auth-login-endpoint')) cliArgs.authLoginEndpoint = getFlag('--auth-login-endpoint');
+  if (getFlag('--auth-token-path')) cliArgs.authTokenPath = getFlag('--auth-token-path');
+  if (getFlag('--gql-endpoint')) cliArgs.gqlEndpoint = getFlag('--gql-endpoint');
+  if (getFlag('--gql-auth-header')) cliArgs.gqlAuthHeader = getFlag('--gql-auth-header');
+  if (getFlag('--gql-auth-key')) cliArgs.gqlAuthKey = getFlag('--gql-auth-key');
+  if (getFlag('--gql-auth-prefix')) cliArgs.gqlAuthPrefix = getFlag('--gql-auth-prefix');
+  if (getFlag('--verification-strictness')) {
+    const val = getFlag('--verification-strictness');
+    if (['strict', 'moderate', 'lenient'].includes(val)) {
+      cliArgs.verificationStrictness = val;
+    }
+  }
   return cliArgs;
 }
 
@@ -103,6 +137,12 @@ ${C.bold}Usage:${C.reset}
   e2e-runner dashboard                  Start the web dashboard
   e2e-runner dashboard --port <port>    Custom port (default: 8484)
 
+  e2e-runner watch --interval 15m       Watch mode: run tests on schedule
+  e2e-runner watch --git                Watch mode: run on git changes
+  e2e-runner watch --interval 15m --git Both triggers
+  e2e-runner watch --webhook <url>      Notify on failure/recovery
+  e2e-runner watch --projects <file>    Multi-project watch
+
   e2e-runner capture <url>               Capture a screenshot of any URL
   e2e-runner capture <url> --full-page  Capture full scrollable page
   e2e-runner capture <url> --selector <sel>  Wait for selector before capture
@@ -127,11 +167,20 @@ ${C.bold}Usage:${C.reset}
   e2e-runner neo4j stop                 Stop the Neo4j container
   e2e-runner neo4j status               Show Neo4j status
 
+  e2e-runner sync status                Show sync connection status
+  e2e-runner sync add-instance          Register new agent (hub mode)
+  e2e-runner sync list-instances        List registered agents (hub mode)
+  e2e-runner sync approve <id>          Approve pending agent (hub mode)
+  e2e-runner sync revoke <id>           Suspend an agent (hub mode)
+  e2e-runner sync push                  Process sync queue (agent mode)
+  e2e-runner sync pull                  Pull runs from hub (agent mode)
+
   e2e-runner init                       Scaffold e2e/ in the current project
 
 ${C.bold}Options:${C.reset}
   --base-url <url>         App base URL (default: http://host.docker.internal:3000)
   --pool-url <ws-url>      Chrome Pool URL (default: ws://localhost:3333)
+  --pool-urls <urls>       Multiple Chrome Pool URLs, comma-separated (distributes tests)
   --tests-dir <dir>        Tests directory (default: e2e/tests)
   --modules-dir <dir>      Reusable modules directory (default: e2e/modules)
   --screenshots-dir <dir>  Screenshots directory (default: e2e/screenshots)
@@ -146,6 +195,20 @@ ${C.bold}Options:${C.reset}
   --env <name>             Environment profile from config (default: default)
   --project-name <name>    Project display name for dashboard (default: directory name)
   --fail-on-network-error  Fail tests when network requests fail (e.g. ERR_CONNECTION_REFUSED)
+  --network-ignore-domains <d1,d2>  Ignore network errors from these domains (comma-separated)
+  --auth-login-endpoint <url>  Auto-login: POST credentials to this URL to get auth token
+  --auth-token-path <path>     Dot-path to token in auth response (default: token)
+  --verification-strictness <level>  Visual verification: strict, moderate (default), lenient
+
+${C.bold}Watch Options:${C.reset}
+  --interval <time>          Run interval: 15m, 1h, 30s (required for schedule mode)
+  --git                      Poll git for new commits
+  --git-branch <branch>      Branch to watch (default: HEAD)
+  --git-interval <time>      Git poll frequency (default: 30s)
+  --webhook <url>            Webhook URL for notifications
+  --webhook-events <events>  When to notify: failure (default), recovery, always
+  --projects <file.json>     Multi-project config file
+  --no-run-on-start          Skip initial run on startup
 
 ${C.bold}Config:${C.reset}
   Looks for e2e.config.js or e2e.config.json in the current directory.
@@ -160,8 +223,10 @@ async function cmdRun() {
   let tests = [];
   let hooks = {};
 
+  const poolUrls = getPoolUrls(config);
   console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
-  console.log(`${C.dim}Pool: ${config.poolUrl} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
+  const poolDisplay = poolUrls.length > 1 ? `${poolUrls.length} pools` : config.poolUrl;
+  console.log(`${C.dim}Pool: ${poolDisplay} | Base: ${config.baseUrl} | Concurrency: ${config.concurrency}${C.reset}\n`);
 
   if (hasFlag('--all')) {
     const loaded = loadAllSuites(config.testsDir, config.modulesDir, config.exclude);
@@ -198,8 +263,8 @@ async function cmdRun() {
   }
 
   // Verify pool connectivity
-  log('🔌', 'Checking Chrome Pool...');
-  const pressure = await waitForPool(config.poolUrl);
+  log('🔌', `Checking Chrome Pool${poolUrls.length > 1 ? 's' : ''}...`);
+  const pressure = await waitForAnyPool(poolUrls);
   log('✅', `Pool ready (${pressure.running}/${pressure.maxConcurrent} sessions, queued: ${pressure.queued})`);
 
   // Wire up live progress to dashboard if running
@@ -222,12 +287,17 @@ async function cmdRun() {
 
   // Execute tests
   console.log('');
-  const suiteName = getFlag('--suite') || (hasFlag('--all') ? null : null);
+  // Derive suite name: --suite flag > --tests file basename > null (for --all/--inline)
+  let suiteName = getFlag('--suite') || null;
+  if (!suiteName && getFlag('--tests')) {
+    suiteName = path.basename(getFlag('--tests'), '.json');
+  }
   const results = await runTestsParallel(tests, config, hooks);
   const report = generateReport(results);
   saveReport(report, config.screenshotsDir, config);
-  persistRun(report, config, suiteName);
+  await persistRun(report, config, suiteName);
   printReport(report, config.screenshotsDir);
+  printInsights(report, config);
 
   // Wait for the last dashboard broadcast (run:complete) to flush before exiting
   if (_lastBroadcast) await _lastBroadcast;
@@ -280,15 +350,32 @@ async function cmdPool() {
       break;
 
     case 'status': {
-      const status = await getPoolStatus(config.poolUrl);
+      const statusPoolUrls = getPoolUrls(config);
+      const aggregated = await getAggregatedPoolStatus(statusPoolUrls);
       console.log(`\n${C.bold}Chrome Pool Status:${C.reset}\n`);
-      if (status.error) {
-        console.log(`  ${C.red}Offline${C.reset}: ${status.error}`);
+
+      if (statusPoolUrls.length > 1) {
+        console.log(`  Pools:      ${aggregated.totalPools} (${aggregated.availableCount} available)`);
+        console.log(`  Running:    ${aggregated.totalRunning}/${aggregated.totalMaxConcurrent}`);
+        console.log(`  Queued:     ${aggregated.totalQueued}`);
+        console.log('');
+        for (const pool of aggregated.pools) {
+          const label = pool.available ? `${C.green}Available${C.reset}` : pool.error ? `${C.red}Offline${C.reset}` : `${C.red}Busy${C.reset}`;
+          console.log(`  ${C.cyan}${pool.url}${C.reset}`);
+          console.log(`    Status:   ${label}${pool.error ? ` (${pool.error})` : ''}`);
+          console.log(`    Running:  ${pool.running}/${pool.maxConcurrent}`);
+          console.log(`    Queued:   ${pool.queued}`);
+        }
       } else {
-        console.log(`  Status:     ${status.available ? `${C.green}Available${C.reset}` : `${C.red}Busy${C.reset}`}`);
-        console.log(`  Running:    ${status.running}/${status.maxConcurrent}`);
-        console.log(`  Queued:     ${status.queued}`);
-        console.log(`  Sessions:   ${status.sessions.length}`);
+        const pool = aggregated.pools[0];
+        if (pool.error) {
+          console.log(`  ${C.red}Offline${C.reset}: ${pool.error}`);
+        } else {
+          console.log(`  Status:     ${pool.available ? `${C.green}Available${C.reset}` : `${C.red}Busy${C.reset}`}`);
+          console.log(`  Running:    ${pool.running}/${pool.maxConcurrent}`);
+          console.log(`  Queued:     ${pool.queued}`);
+          console.log(`  Sessions:   ${pool.sessions?.length ?? 0}`);
+        }
       }
       console.log('');
       break;
@@ -405,12 +492,14 @@ async function cmdCapture() {
 
   console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
 
+  const capturePoolUrls = getPoolUrls(config);
   log('🔌', 'Checking Chrome Pool...');
-  await waitForPool(config.poolUrl);
+  await waitForAnyPool(capturePoolUrls);
 
   let browser;
   try {
-    browser = await connectToPool(config.poolUrl);
+    const capturePool = await selectPool(capturePoolUrls);
+    browser = await connectToPool(capturePool);
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
 
@@ -547,6 +636,46 @@ async function cmdIssue() {
   console.log('');
 }
 
+async function cmdWatch() {
+  const cliArgs = parseCLIConfig();
+
+  // Parse watch-specific flags
+  if (getFlag('--interval')) cliArgs.watchInterval = getFlag('--interval');
+  if (getFlag('--webhook')) cliArgs.watchWebhookUrl = getFlag('--webhook');
+  if (getFlag('--webhook-events')) cliArgs.watchWebhookEvents = getFlag('--webhook-events');
+  if (hasFlag('--git')) cliArgs.watchGitPoll = true;
+  if (getFlag('--git-branch')) cliArgs.watchGitBranch = getFlag('--git-branch');
+  if (getFlag('--git-interval')) cliArgs.watchGitInterval = getFlag('--git-interval');
+  if (hasFlag('--no-run-on-start')) cliArgs.watchRunOnStart = false;
+
+  // Multi-project file
+  const projectsFile = getFlag('--projects');
+  if (projectsFile) {
+    const resolved = path.resolve(projectsFile);
+    if (!fs.existsSync(resolved)) {
+      console.error(`${C.red}Projects file not found: ${resolved}${C.reset}`);
+      process.exit(1);
+    }
+    cliArgs.watchProjects = JSON.parse(fs.readFileSync(resolved, 'utf-8'));
+  }
+
+  const config = await loadConfig(cliArgs);
+
+  console.log(`\n${C.bold}${C.cyan}@matware/e2e-runner${C.reset} v${pkg.version}`);
+  console.log(`${C.dim}Watch mode — dashboard on port ${config.dashboardPort}${C.reset}\n`);
+
+  const handle = await startWatch(config);
+
+  // Graceful shutdown
+  const shutdown = () => {
+    console.log(`\n${C.dim}Stopping watch...${C.reset}`);
+    handle.stop();
+    process.exit(0);
+  };
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
 async function cmdLearnings() {
   const cliArgs = parseCLIConfig();
   const config = await loadConfig(cliArgs);
@@ -696,6 +825,261 @@ async function cmdNeo4j() {
   }
 }
 
+// ==================== Sync ====================
+
+async function cmdSync() {
+  const subCmd = args[1];
+  const cliArgs = parseCLIConfig();
+  const config = await loadConfig(cliArgs);
+  
+  // Ensure schema is migrated
+  migrateSyncSchema();
+
+  switch (subCmd) {
+    case 'status': {
+      const mode = config.sync?.mode || 'standalone';
+      console.log(`\n${C.bold}Sync Status:${C.reset}\n`);
+      console.log(`  Mode:     ${C.cyan}${mode}${C.reset}`);
+      
+      if (mode === 'hub') {
+        const instances = listInstances();
+        const active = instances.filter(i => i.status === 'active').length;
+        const online = instances.filter(i => {
+          if (!i.last_seen) return false;
+          const lastSeen = new Date(i.last_seen + 'Z').getTime();
+          return Date.now() - lastSeen < 5 * 60 * 1000;
+        }).length;
+        console.log(`  Instances: ${instances.length} total, ${active} active, ${online} online`);
+      } else if (mode === 'agent') {
+        const conn = getHubConnection();
+        if (conn) {
+          console.log(`  Hub URL:   ${C.cyan}${conn.hub_url}${C.reset}`);
+          console.log(`  Instance:  ${conn.instance_id}`);
+          console.log(`  Status:    ${conn.status === 'connected' ? C.green : C.red}${conn.status}${C.reset}`);
+          console.log(`  Last push: ${conn.last_push || 'never'}`);
+          console.log(`  Last pull: ${conn.last_pull || 'never'}`);
+        } else {
+          console.log(`  ${C.dim}Not connected to any hub${C.reset}`);
+        }
+        
+        const queueStats = getQueueStats();
+        if (queueStats.length > 0) {
+          const pending = queueStats.find(s => s.status === 'pending')?.count || 0;
+          if (pending > 0) {
+            console.log(`  Queue:     ${C.yellow}${pending} pending${C.reset}`);
+          }
+        }
+      }
+      console.log('');
+      break;
+    }
+    
+    case 'add-instance': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = getFlag('--id') || `instance-${Date.now().toString(36)}`;
+      const displayName = getFlag('--name') || instanceId;
+      const role = getFlag('--role') || 'member';
+      const environment = getFlag('--env') || 'development';
+      
+      // Check if already exists
+      if (getInstance(instanceId)) {
+        console.error(`${C.red}Error: Instance '${instanceId}' already exists${C.reset}`);
+        process.exit(1);
+      }
+      
+      // Generate credentials
+      const apiKey = generateApiKey();
+      const totpSecret = generateTotpSecret();
+      
+      // Create instance
+      createInstance({
+        instanceId,
+        displayName,
+        hostname: null,
+        environment,
+        apiKeyHash: hashApiKey(apiKey),
+        totpSecret,
+        role,
+        status: config.sync?.hub?.requireApproval ? 'pending' : 'active',
+      });
+      
+      console.log(`\n${C.green}${C.bold}Instance created successfully!${C.reset}\n`);
+      console.log(`${C.bold}Instance ID:${C.reset}    ${instanceId}`);
+      console.log(`${C.bold}Display Name:${C.reset}   ${displayName}`);
+      console.log(`${C.bold}Role:${C.reset}           ${role}`);
+      console.log(`${C.bold}Status:${C.reset}         ${config.sync?.hub?.requireApproval ? 'pending' : 'active'}`);
+      console.log('');
+      console.log(`${C.bold}${C.yellow}SAVE THESE CREDENTIALS (shown only once):${C.reset}`);
+      console.log(`${C.bold}API Key:${C.reset}        ${apiKey}`);
+      console.log(`${C.bold}TOTP Secret:${C.reset}    ${totpSecret}`);
+      console.log(`${C.bold}TOTP URI:${C.reset}       ${generateTotpUri(totpSecret, instanceId)}`);
+      console.log('');
+      console.log(`${C.dim}Configure the agent with:${C.reset}`);
+      console.log(`  export E2E_SYNC_API_KEY="${apiKey}"`);
+      console.log(`  export E2E_SYNC_TOTP="${totpSecret}"`);
+      console.log('');
+      break;
+    }
+    
+    case 'list-instances': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const status = getFlag('--status');
+      const instances = listInstances(status);
+      
+      console.log(`\n${C.bold}Registered Instances:${C.reset}\n`);
+      
+      if (instances.length === 0) {
+        console.log(`  ${C.dim}No instances registered${C.reset}`);
+      } else {
+        for (const inst of instances) {
+          const isOnline = inst.last_seen && (Date.now() - new Date(inst.last_seen + 'Z').getTime() < 5 * 60 * 1000);
+          const statusColor = inst.status === 'active' ? C.green : inst.status === 'pending' ? C.yellow : C.red;
+          const onlineIndicator = isOnline ? `${C.green}*${C.reset}` : ' ';
+          
+          console.log(`  ${onlineIndicator} ${C.bold}${inst.instance_id}${C.reset}`);
+          console.log(`      Name:   ${inst.display_name}`);
+          console.log(`      Status: ${statusColor}${inst.status}${C.reset}`);
+          console.log(`      Role:   ${inst.role}`);
+          console.log(`      Seen:   ${inst.last_seen || 'never'}`);
+          console.log('');
+        }
+      }
+      break;
+    }
+    
+    case 'approve': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = args[2];
+      if (!instanceId) {
+        console.error(`${C.red}Error: Instance ID required${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instance = getInstance(instanceId);
+      if (!instance) {
+        console.error(`${C.red}Error: Instance '${instanceId}' not found${C.reset}`);
+        process.exit(1);
+      }
+      
+      updateInstanceStatus(instanceId, 'active');
+      console.log(`${C.green}Instance '${instanceId}' approved and activated${C.reset}`);
+      break;
+    }
+    
+    case 'revoke': {
+      if (config.sync?.mode !== 'hub') {
+        console.error(`${C.red}Error: This command only works in hub mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const instanceId = args[2];
+      if (!instanceId) {
+        console.error(`${C.red}Error: Instance ID required${C.reset}`);
+        process.exit(1);
+      }
+      
+      updateInstanceStatus(instanceId, 'suspended');
+      console.log(`${C.yellow}Instance '${instanceId}' suspended${C.reset}`);
+      break;
+    }
+    
+    case 'push': {
+      if (config.sync?.mode !== 'agent') {
+        console.error(`${C.red}Error: This command only works in agent mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const client = await getSyncClient(config);
+      if (!client.isConfigured()) {
+        console.error(`${C.red}Error: Sync credentials not configured${C.reset}`);
+        console.log(`${C.dim}Set E2E_SYNC_API_KEY and E2E_SYNC_TOTP environment variables${C.reset}`);
+        process.exit(1);
+      }
+      
+      console.log('Processing sync queue...');
+      await client.processQueue();
+      console.log(`${C.green}Queue processed${C.reset}`);
+      break;
+    }
+    
+    case 'pull': {
+      if (config.sync?.mode !== 'agent') {
+        console.error(`${C.red}Error: This command only works in agent mode${C.reset}`);
+        process.exit(1);
+      }
+      
+      const since = getFlag('--since');
+      const project = getFlag('--project');
+      const limit = getFlag('--limit') ? parseInt(getFlag('--limit')) : 50;
+      
+      console.log('Pulling runs from hub...');
+      const result = await pullRuns(config, { since, project, limit });
+      
+      if (result) {
+        console.log(`${C.green}Pulled ${result.runs?.length || 0} runs${C.reset}`);
+        
+        if (result.runs?.length > 0) {
+          console.log('');
+          for (const run of result.runs.slice(0, 10)) {
+            const status = run.failed > 0 ? C.red + 'FAIL' : C.green + 'PASS';
+            console.log(`  ${status}${C.reset} ${run.project_name} - ${run.suite_name || 'default'} (${run.passed}/${run.total})`);
+          }
+          if (result.runs.length > 10) {
+            console.log(`  ${C.dim}... and ${result.runs.length - 10} more${C.reset}`);
+          }
+        }
+      } else {
+        console.log(`${C.yellow}No runs pulled (check configuration)${C.reset}`);
+      }
+      break;
+    }
+    
+    case 'generate-master-key': {
+      const key = generateMasterKey();
+      console.log(`\n${C.bold}Generated Master Key:${C.reset}\n`);
+      console.log(`  ${key}`);
+      console.log('');
+      console.log(`${C.dim}Set this in your hub environment:${C.reset}`);
+      console.log(`  export E2E_SYNC_MASTER_KEY="${key}"`);
+      console.log('');
+      break;
+    }
+    
+    default:
+      console.log(`\n${C.bold}Sync Commands:${C.reset}\n`);
+      console.log('  status              Show sync status');
+      console.log('  add-instance        Register a new agent (hub mode)');
+      console.log('  list-instances      List registered agents (hub mode)');
+      console.log('  approve <id>        Approve pending agent (hub mode)');
+      console.log('  revoke <id>         Suspend an agent (hub mode)');
+      console.log('  push                Process sync queue (agent mode)');
+      console.log('  pull                Pull runs from hub (agent mode)');
+      console.log('  generate-master-key Generate encryption master key');
+      console.log('');
+      console.log(`${C.bold}Options:${C.reset}`);
+      console.log('  --id <id>           Instance ID for add-instance');
+      console.log('  --name <name>       Display name for add-instance');
+      console.log('  --role <role>       Role: admin, member, readonly');
+      console.log('  --status <status>   Filter by status: pending, active, suspended');
+      console.log('  --since <datetime>  Pull runs since timestamp');
+      console.log('  --project <slug>    Filter by project');
+      console.log('  --limit <n>         Limit number of runs to pull');
+      console.log('');
+  }
+}
+
 // ==================== Main ====================
 
 async function main() {
@@ -728,6 +1112,10 @@ async function main() {
       await cmdDashboard();
       break;
 
+    case 'watch':
+      await cmdWatch();
+      break;
+
     case 'capture':
       await cmdCapture();
       break;
@@ -744,6 +1132,10 @@ async function main() {
       await cmdNeo4j();
       break;
 
+    case 'sync':
+      await cmdSync();
+      break;
+
     case 'init':
       cmdInit();
       break;