@surething/cockpit 1.0.216 → 1.0.218

package/bin/cock-browser.mjs

@@ -19,6 +19,19 @@
  *   cockpit browser abcd list   (list all connected browsers)
  */
 
+import {
+  TIMEOUT_MSG,
+  CONNECT_REFUSED_MSG,
+  CLICK_NO_OP_WARN,
+  HELP_WHEN_NOT_TO_USE,
+  HELP_INTERACTION_BY_SELECTOR,
+  HELP_FETCH,
+  HELP_HEALTH,
+  HELP_WAIT,
+  HELP_ASSERT,
+  HELP_LIFECYCLE,
+} from './cock-browser.messages.mjs';
+
 const args = process.argv.slice(2);
 
 // Help text
@@ -55,14 +68,16 @@ Three templates that always work:
   # 2) Set a React-controlled <input> via the native setter + input event:
   evaluate "(() => { const el = document.querySelector('input[name=foo]'); const set = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set; set.call(el, 'hello'); el.dispatchEvent(new Event('input', { bubbles: true })); return el.value; })()"
 
-  # 3) Click a button by aria-label / text (refs go stale after re-render):
-  evaluate "(() => { const btn = Array.from(document.querySelectorAll('button')).find(b => b.getAttribute('aria-label') === 'Send message' || b.textContent.trim() === 'Send'); if (!btn) return 'not-found'; btn.click(); return 'clicked'; })()"
+  # 3) Click a button by visible text or aria-label (refs go stale on re-render):
+  click --text "Sign in"                          # preferred shortcut
+  click --selector 'button[type="submit"]'        # exact selector
+  evaluate "(() => document.querySelector('button[aria-label=\\"Save\\"]').click())()"  # last resort
 
-Refs (e5, e23, …) returned by \`snapshot\` are valid only for the
-DOM at snapshot time. Any re-render / route change / focus shift
-invalidates them — \`Element ref "eN" not found or disconnected\`
-means you need a fresh \`snapshot\` (or just use \`evaluate\` with
-CSS selectors).
+Refs returned by \`snapshot\` are \`e<N>#v<epoch>\` — valid only until
+the next snapshot or re-render. The error message
+\`Element ref "..." is stale (current snapshot v=N)\` tells you to
+re-snapshot OR use \`click --text\` / \`click --selector\` /
+\`fill --selector\` for re-render-resilient interaction.
 
 ──────────────────────────────────────────────────────
 
@@ -74,18 +89,29 @@ Navigation:
   title                       Get page title
 
 Inspection:
-  snapshot                    Get element tree (returns refs like [e5])
-  screenshot                  Take a screenshot
+  snapshot                    a11y tree (refs like e5#v3; banner explains format)
+                              --filter <regex>           server-side grep
+                              --include-hidden-text      surface collapsed <summary>/container text
+                              --max-depth N              limit walk depth (default 12)
+  screenshot                  PNG saved to /tmp; path printed for Read tool
+
+${HELP_INTERACTION_BY_SELECTOR(prefix)}
 
-Interaction (use ref from snapshot):
-  click <ref>                 Click element  ⚠ React/SPA: may silently miss; use evaluate
-  type <ref> <text>           Type text  ⚠ React/SPA: may silently miss; use evaluate (template 1/2)
-  fill <ref> <value>          Fill input value  ⚠ Same — prefer template 2
+  type <ref> <text>           Type into ref (CDP key events; React-controlled may silently miss → use fill --selector)
   hover <ref>                 Hover element
   focus <ref>                 Focus element
   scroll --direction D        Scroll page (up/down/left/right)
   key <key>                   Press key (e.g. Enter, Ctrl+A)
-  wait --text T               Wait for text to appear
+
+${HELP_WAIT}
+
+${HELP_ASSERT}
+
+${HELP_LIFECYCLE}
+
+${HELP_FETCH}
+
+${HELP_HEALTH}
 
 DOM:
   computed <ref>              Get computed styles
@@ -111,6 +137,8 @@ Console & Debug:
   cookies                     Get cookies
   storage [--type T]          Get storage (local|session)
 
+${HELP_WHEN_NOT_TO_USE}
+
 ── Next step ──────────────────────────────────────────
 Run \`cockpit browser ${prefix} snapshot\` to inspect the page.
 It returns an element tree with refs like [e5]. Use those
@@ -191,9 +219,32 @@ const params = parseFlags(args.slice(action === 'list' ? 1 : 2));
 if (params._positional?.length) {
   const pos = params._positional;
   if (action === 'navigate' && !params.url) params.url = pos[0];
-  if (action === 'click' && !params.ref) params.ref = pos[0];
+  // click: positional is the ref (or text fallback for convenience if it does
+  // not look like a ref). Refs match e<N>#v<M>; anything else is treated as
+  // visible text so `click "Sign in"` Just Works.
+  if (action === 'click') {
+    if (!params.ref && !params.text && !params.selector) {
+      if (/^e\d+#v\d+$/.test(pos[0])) params.ref = pos[0];
+      else params.text = pos[0];
+    }
+  }
   if (action === 'type' && !params.ref) { params.ref = pos[0]; if (pos[1] && !params.text) params.text = pos[1]; }
-  if (action === 'fill' && !params.ref) { params.ref = pos[0]; if (pos[1] && !params.value) params.value = pos[1]; }
+  // fill: positional[0] is ref (when matches ref pattern) else --selector form.
+  // positional[1] is the value when ref-positional is used.
+  if (action === 'fill') {
+    if (!params.ref && !params.selector) {
+      if (/^e\d+#v\d+$/.test(pos[0])) {
+        params.ref = pos[0];
+        if (pos[1] && !params.value) params.value = pos[1];
+      } else {
+        // First positional taken as selector if it contains CSS-y chars.
+        params.selector = pos[0];
+        if (pos[1] && !params.value) params.value = pos[1];
+      }
+    } else if (params.selector && !params.value && pos[0]) {
+      params.value = pos[0];
+    }
+  }
   if (action === 'hover' && !params.ref) params.ref = pos[0];
   if (action === 'focus' && !params.ref) params.ref = pos[0];
   if (action === 'evaluate' && !params.js) params.js = pos[0];
@@ -206,9 +257,33 @@ if (params._positional?.length) {
   if (action === 'events' && !params.ref) params.ref = pos[0];
   if (action === 'network_detail' && !params.id) params.id = parseInt(pos[0]);
   if (action === 'network_record' && !params.action) params.action = pos[0] || 'status';
+  if (action === 'fetch' && !params.url) params.url = pos[0];
+  if (action === 'health' && pos[0] === '--deep') params.deep = true;
   delete params._positional;
 }
 
+// kebab → camel for new Phase 2 flags.
+if (params['network-idle']) { params.networkIdle = true; delete params['network-idle']; }
+if (params['dom-stable']) { params.domStable = true; delete params['dom-stable']; }
+if (params['extension-ready']) { params.extensionReady = true; delete params['extension-ready']; }
+if (params['quiet-ms'] != null) { params.quietMs = params['quiet-ms']; delete params['quiet-ms']; }
+if (params['max-request-age-ms'] != null) { params.maxRequestAgeMs = params['max-request-age-ms']; delete params['max-request-age-ms']; }
+if (params['fetch-status'] != null) { params.fetchStatus = params['fetch-status']; delete params['fetch-status']; }
+if (params['fetch-method']) { params.fetchMethod = params['fetch-method']; delete params['fetch-method']; }
+if (params['not-contains'] !== undefined) { params.notContains = params['not-contains']; delete params['not-contains']; }
+if (params['no-cache']) { params.noCache = true; delete params['no-cache']; }
+if (params['console-no-errors']) { params.consoleNoErrors = true; delete params['console-no-errors']; }
+if (params['same-site']) { params.sameSite = params['same-site']; delete params['same-site']; }
+if (params['http-only']) { params.httpOnly = true; delete params['http-only']; }
+if (params['verify-ms'] != null) { params.verifyMs = Number(params['verify-ms']); delete params['verify-ms']; }
+
+// kebab → camel for flags that the extension expects camel.
+if (params['include-hidden-text']) { params.includeHiddenText = true; delete params['include-hidden-text']; }
+if (params['max-depth'] != null) { params.maxDepth = params['max-depth']; delete params['max-depth']; }
+if (params['form-selector']) { params.formSelector = params['form-selector']; delete params['form-selector']; }
+if (params['skip-verify']) { params.skipVerify = true; delete params['skip-verify']; }
+if (params['no-verify']) { params.skipVerify = true; delete params['no-verify']; }
+
 // Port: env COCKPIT_PORT > ~/.cockpit/server.json > default 3457
 let port = process.env.COCKPIT_PORT || 3457;
 if (!process.env.COCKPIT_PORT) {
@@ -312,6 +387,43 @@ async function autoResolveChunked(baseUrl, id, data, cmdTimeout) {
 }
 
 // Send request
+// F2.7 — wait --extension-ready: poll the cheap server-side health endpoint
+// until the bridge reports quiet conditions for `quietMs` consecutive ms.
+// Replaces the manual `until cockpit browser X evaluate "1+1"` loop that AI
+// has historically used when an evaluate hangs on a busy page.
+async function waitExtensionReady({ quietMs = 500, timeoutMs = 60000 }) {
+  const start = Date.now();
+  let quietSince = null;
+  while (Date.now() - start < timeoutMs) {
+    let h = null;
+    try {
+      const r = await fetch(`${baseUrl}/api/browser/health`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ id, params: {}, timeout: 1000 }),
+        signal: AbortSignal.timeout(2000),
+      });
+      const j = await r.json();
+      h = j.ok ? j.data : null;
+    } catch { /* network blip — treat as not-ready */ }
+    const ready = h && h.found && h.ws === 'open' && h.pendingCommands === 0;
+    if (ready) {
+      if (quietSince == null) quietSince = Date.now();
+      if (Date.now() - quietSince >= quietMs) {
+        return { waited: `extension-ready (quiet=${quietMs}ms)`, elapsedMs: Date.now() - start };
+      }
+    } else {
+      quietSince = null;
+    }
+    await new Promise(r => setTimeout(r, 100));
+  }
+  throw new Error(
+    `wait --extension-ready timed out after ${timeoutMs}ms.\n` +
+    `  The bridge never reported quiet for ${quietMs}ms.\n` +
+    `  Consider a service-level test if the page is driven by an async LLM/agent flow.`
+  );
+}
+
 async function run() {
   // Only id provided without action → show help + status
   if (action === '_status') {
@@ -340,6 +452,22 @@ async function run() {
     return;
   }
 
+  // F2.7 — wait --extension-ready runs entirely CLI-side: it polls the cheap
+  // server-side `health` endpoint, so it works even when the page is blocked.
+  if (action === 'wait' && params.extensionReady) {
+    try {
+      const r = await waitExtensionReady({
+        quietMs: params.quietMs ?? 500,
+        timeoutMs: timeout,
+      });
+      console.log(`waited: ${r.waited} (elapsed ${formatMs(r.elapsedMs)})`);
+      return;
+    } catch (err) {
+      console.error(err.message);
+      process.exit(1);
+    }
+  }
+
   const url = `${baseUrl}/api/browser/${action}`;
   const body = { id, params, timeout };
 
@@ -427,13 +555,18 @@ async function run() {
       }
     }
 
+    // F1.7 — post-verify silent failures for click / key / submit.
+    if (POST_VERIFY_ACTIONS.has(action)) {
+      try { await postVerify(action, params, resolved); } catch { /* never fail the command */ }
+    }
+
     // Format output
     await formatOutput(action, resolved);
   } catch (err) {
     if (err.name === 'TimeoutError' || err.code === 'ABORT_ERR') {
-      console.error(`Timeout: No response within ${timeout}ms. Is the browser bubble connected?`);
+      console.error(TIMEOUT_MSG(timeout, id));
     } else if (err.cause?.code === 'ECONNREFUSED') {
-      console.error(`Connection refused: Cockpit server not running at ${baseUrl}`);
+      console.error(CONNECT_REFUSED_MSG(baseUrl));
     } else {
       console.error(`Error: ${err.message}`);
     }
@@ -441,6 +574,57 @@ async function run() {
   }
 }
 
+// F1.7 — Post-verify for click / key / submit. CDP reports "success" even when
+// the framework didn't react. Diff a cheap state probe before and after; if
+// nothing observable changed in the window, warn with actionable templates.
+//
+// Default window: 1000ms (BL-1, observation period). Was 200ms but dogfood
+// showed false positives on React pages whose batched re-renders + XHR fire
+// took >200ms to surface. Users can override per command with --verify-ms;
+// --skip-verify (or --no-verify) opts out entirely.
+const POST_VERIFY_ACTIONS = new Set(['click', 'key', 'submit']);
+const POST_VERIFY_WINDOW_MS_DEFAULT = 1000;
+
+async function probeState() {
+  const r = await fetch(`${baseUrl}/api/browser/probe_state`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ id, params: {}, timeout: 2000 }),
+    signal: AbortSignal.timeout(3000),
+  });
+  const j = await r.json();
+  return j.ok ? j.data : null;
+}
+
+async function postVerify(action, params, originalResolved) {
+  if (params.skipVerify) return;
+  const windowMs = Number.isFinite(params.verifyMs) && params.verifyMs > 0
+    ? params.verifyMs
+    : POST_VERIFY_WINDOW_MS_DEFAULT;
+  let before;
+  try { before = await probeState(); } catch { return; }
+  if (!before) return;
+  await new Promise(r => setTimeout(r, windowMs));
+  let after;
+  try { after = await probeState(); } catch { return; }
+  if (!after) return;
+  const urlChanged = before.url !== after.url;
+  const domChanged = before.domHash !== after.domHash || before.domLen !== after.domLen;
+  const newRequests = after.lastNetworkId > before.lastNetworkId;
+  if (!urlChanged && !domChanged && !newRequests) {
+    process.stderr.write(
+      '\n' +
+      CLICK_NO_OP_WARN(action, id, {
+        windowMs,
+        urlChanged,
+        domChanged,
+        newRequests,
+      }) +
+      '\n'
+    );
+  }
+}
+
 async function formatOutput(action, data) {
   if (data === undefined || data === null) {
     // evaluate-family silently returning undefined/null is a major source of
@@ -486,6 +670,86 @@ async function formatOutput(action, data) {
       console.log(data);
       return;
 
+    case 'health':
+      // Server-side bridge health snapshot.
+      if (!data.found) {
+        console.log(`browser "${id}" not registered (no bubble open?)`);
+        process.exit(2);
+      }
+      console.log(
+        `extension: ${data.ws === 'open' ? 'alive (ws=open)' : 'unreachable (ws=' + data.ws + ')'}` +
+        `   pending: ${data.pendingCommands}` +
+        (data.lastSuccessMs !== null
+          ? `   last-success: ${formatMs(data.lastSuccessMs)} ago (${data.lastSuccessAction || '?'})`
+          : '   last-success: never')
+      );
+      return;
+
+    case 'fetch':
+      // Default: pretty JSON. If jsonpath was used, print the extracted value plainly.
+      if (data && typeof data === 'object' && 'jsonpath' in data) {
+        console.log(`[${data.status}] ${data.jsonpath} =`);
+        console.log(typeof data.value === 'object' ? JSON.stringify(data.value, null, 2) : data.value);
+      } else if (data && typeof data === 'object' && 'data' in data) {
+        console.log(`[${data.status}] (${data.contentType || 'unknown'})`);
+        console.log(typeof data.data === 'object' ? JSON.stringify(data.data, null, 2) : data.data);
+      } else {
+        console.log(JSON.stringify(data, null, 2));
+      }
+      return;
+
+    case 'submit':
+      console.log(`submitted: ${data.submitted}${data.action ? `   → ${data.action}` : ''}`);
+      return;
+
+    case 'wait':
+      // Extension returned a structured ack — print one line summary.
+      if (data && data.waited) {
+        console.log(`waited: ${data.waited}${data.elapsedMs != null ? ` (elapsed ${formatMs(data.elapsedMs)})` : ''}`);
+        return;
+      }
+      break;
+
+    case 'reset':
+      if (data && Array.isArray(data.cleared)) {
+        console.log(`cleared: ${data.cleared.join(', ') || '(nothing)'}`);
+        if (data.errors?.length) {
+          for (const e of data.errors) process.stderr.write(`  ⚠ ${e}\n`);
+          process.exit(1);
+        }
+        return;
+      }
+      break;
+
+    case 'set':
+      if (data && data.set) {
+        const note = data.verified === false
+          ? '   ⚠ cookie was not accepted (different domain / SameSite / Secure?)'
+          : data.length != null ? `   (${data.length} bytes)` : '';
+        console.log(`set ${data.set}: ${data.name}${note}`);
+        if (data.verified === false) process.exit(1);
+        return;
+      }
+      break;
+
+    case 'status':
+      if (data && data.url != null) {
+        console.log(`URL:    ${data.url}`);
+        console.log(`Title:  ${data.title}   [${data.readyState}]`);
+        if (data.lastConsoleError) {
+          console.log(`Last console error:  ${data.lastConsoleError.text}   (${data.lastConsoleError.ageSec}s ago)`);
+        }
+        if (data.lastFailedRequest) {
+          const r = data.lastFailedRequest;
+          console.log(`Last failed request: ${r.method} ${r.url} [${r.status}]   (${r.ageSec}s ago)`);
+        }
+        if (Array.isArray(data.topActions) && data.topActions.length) {
+          console.log(`Top actions:         ${data.topActions.map(a => `"${a}"`).join('  ')}`);
+        }
+        return;
+      }
+      break;
+
     case 'screenshot':
       if (data.image) {
         // data URL → save as PNG file, output path (for Read tool to view)
@@ -611,5 +875,13 @@ async function formatOutput(action, data) {
   }
 }
 
+function formatMs(ms) {
+  if (ms < 1000) return `${ms}ms`;
+  const s = Math.round(ms / 1000);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  return `${m}m${s % 60}s`;
+}
+
 // Export promise for external await
 export const done = run();

package/bin/cock-codegraph.mjs

@@ -181,11 +181,17 @@ async function cmdSearch() {
   const pos = positional(subArgs);
   const q = pos[0];
   const limit = getInt(subArgs, '--limit') ?? 15;
+  // v1.0.216+: opt-in flag to also surface identifier-shaped string literals
+  // (tool names / event names / config keys / route paths) that only exist
+  // in source as strings, never as identifiers.
+  const includeLiterals = subArgs.includes('--include-literals');
   if (!q) {
     stderr.write('codegraph search: missing <query>\n');
     exit(2);
   }
-  const resp = await get('/api/projectGraph/search', { q, limit });
+  const params = { q, limit };
+  if (includeLiterals) params.includeLiterals = 'true';
+  const resp = await get('/api/projectGraph/search', params);
   const data = await resp.json();
   if (wantJson) { emitJson(data); exit(0); }
 
@@ -616,15 +622,22 @@ Examples:
 // call (which runs before this declaration is reached in module order)
 // doesn't hit a const TDZ.
 function getSubHelp() { return {
-  search: `Usage: cock codegraph search <query> [--limit N=15] [--json]
+  search: `Usage: cock codegraph search <query> [--limit N=15] [--include-literals] [--json]
 
 Purpose:  Find symbols (and files) matching a name fragment. Tokenised
-          match across name + qualifiedName + filePath. Use this when
-          you know the symbol's name but not its location.
+          match across name + qualifiedName + filePath, with case +
+          word-separator folding (so 'build_code_index' ↔ 'buildCodeIndex'
+          ↔ 'BUILD-CODE-INDEX' all collide). Use this when you know the
+          symbol's name but not its location.
 
 Flags:
-  --limit N        Max symbol hits to return (default 15)
-  --json           Emit raw JSON {files: [...], symbols: [...]}
+  --limit N            Max symbol hits to return (default 15)
+  --include-literals   Also search identifier-shaped string literals
+                       in source (tool names / event names / config
+                       keys / route paths). Off by default to keep
+                       results lean. Surfaces names that never appear
+                       as identifiers, only as strings.
+  --json               Emit raw JSON {files: [...], symbols: [...]}
 
 Output (plain, TAB-separated):
   sym <TAB> <file>:<line> <TAB> <kind> <TAB> <qname>
@@ -636,7 +649,9 @@ Exit: 0=hits, 1=no hits, 2=usage, 3=server unreachable
 
 Examples:
   cock codegraph search getCodeIndex
+  cock codegraph search build_code_index             # snake-case query, still finds buildCodeIndex
   cock codegraph search useChatStore --limit 5
+  cock codegraph search 'agent.fork' --include-literals    # find a name hiding in a literal
   cock codegraph search authenticate --json | jq '.symbols[].target'`,
 
   callers: `Usage: cock codegraph callers <qname> [--file PATH] [--json]

package/bin/cock-connection.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+/**
+ * cockpit connection — cross-type bubble enumeration.
+ *
+ * One subcommand:
+ *
+ *   cockpit connection list [--cwd PATH] [--all] [--json]
+ *
+ * Returns a unified listing of terminal + browser bubbles, each with the
+ * user-set `title` (if any). Designed for /cc slash mode and ad-hoc
+ * "what bubbles exist in this project" lookups before driving them via
+ * `cockpit terminal <id> ...` / `cockpit browser <id> ...`.
+ *
+ * By default only alive bubbles (running terminal / connected browser)
+ * are returned. Pass `--all` to include stale entries.
+ */
+import { readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+
+const argv = process.argv.slice(2);
+
+function readServerPort() {
+  try {
+    return JSON.parse(readFileSync(join(homedir(), '.cockpit', 'server.json'), 'utf8')).port;
+  } catch {
+    return null;
+  }
+}
+
+const port = process.env.COCKPIT_PORT || readServerPort() || 3457;
+const baseUrl = `http://localhost:${port}`;
+
+const { stdout, stderr, exit } = process;
+
+function printHelp() {
+  stdout.write(`Usage: cock connection list [--cwd PATH] [--all] [--json]
+
+Purpose:  Enumerate all bubbles (terminal + browser) across the running
+          Cockpit server. Each entry carries the user-set title if any
+          (set via the ✎ button next to the bubble's short id), so an
+          LLM can map cryptic 4-char ids to human-meaningful purposes.
+
+Subcommands:
+  list                List bubbles (the only subcommand)
+
+Flags:
+  --cwd PATH          Only list bubbles whose project cwd matches PATH
+                      (canonicalised). Use \$PWD to scope to the
+                      current shell.
+  --all               Include dead entries (exited terminals,
+                      disconnected browsers). Off by default.
+  --json              Emit raw JSON instead of TAB-separated lines.
+
+Output (plain, TAB-separated):
+  <type> <TAB> <shortId> <TAB> <title-or-(none)> <TAB> <projectCwd-or-?> <TAB> <command-or-empty>
+
+JSON: array of { type, shortId, title?, projectCwd?, tabId?, command?, alive }
+
+Exit: 0=hits, 1=no bubbles, 2=usage, 3=server unreachable
+
+Examples:
+  cockpit connection list                     # all alive bubbles
+  cockpit connection list --cwd \$PWD         # this project only
+  cockpit connection list --all --json | jq   # everything, programmatic
+`);
+}
+
+if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+  printHelp();
+  exit(0);
+}
+
+const sub = argv[0];
+if (sub !== 'list') {
+  stderr.write(`Unknown subcommand: ${sub}\n`);
+  stderr.write(`Run \`cockpit connection --help\` to see usage.\n`);
+  exit(2);
+}
+
+// Parse list-subcommand flags.
+const rest = argv.slice(1);
+const flags = { cwd: undefined, all: false, json: false };
+for (let i = 0; i < rest.length; i++) {
+  const tok = rest[i];
+  if (tok === '--all') flags.all = true;
+  else if (tok === '--json') flags.json = true;
+  else if (tok === '--cwd') {
+    flags.cwd = rest[++i];
+    if (!flags.cwd) {
+      stderr.write('Missing value for --cwd\n');
+      exit(2);
+    }
+  } else if (tok === '--help' || tok === '-h') {
+    printHelp();
+    exit(0);
+  } else {
+    stderr.write(`Unknown flag: ${tok}\n`);
+    exit(2);
+  }
+}
+
+// Hit the server.
+let data;
+try {
+  const body = {};
+  if (flags.cwd) body.cwd = resolve(flags.cwd);
+  if (flags.all) body.all = true;
+  const res = await fetch(`${baseUrl}/api/connection/list`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(10_000),
+  });
+  const j = await res.json().catch(() => null);
+  if (!res.ok || !j?.ok) {
+    stderr.write(`HTTP ${res.status}: ${j?.error || 'unknown error'}\n`);
+    exit(3);
+  }
+  data = j.data;
+} catch (err) {
+  if (err?.cause?.code === 'ECONNREFUSED') {
+    stderr.write(`Connection refused: Cockpit server not running at ${baseUrl}\n`);
+  } else {
+    stderr.write(`Error: ${err.message}\n`);
+  }
+  exit(3);
+}
+
+if (!Array.isArray(data) || data.length === 0) {
+  // Empty list — exit 1 so callers can short-circuit cleanly.
+  exit(1);
+}
+
+if (flags.json) {
+  stdout.write(JSON.stringify({ connections: data }, null, 2) + '\n');
+  exit(0);
+}
+
+// Plain text: TAB-separated, one line per bubble.
+//   <type>  <shortId>  <title>  <projectCwd>  <command-or-empty>
+const TYPE_LABEL = { terminal: 'term', browser: 'brow' };
+for (const c of data) {
+  const type = TYPE_LABEL[c.type] || c.type;
+  const title = c.title || '(none)';
+  const cwd = c.projectCwd || '?';
+  const command = (c.command || '').replace(/\s+/g, ' ').slice(0, 120);
+  stdout.write(`${type}\t${c.shortId}\t${title}\t${cwd}\t${command}\n`);
+}
+exit(0);

package/bin/cock.mjs

@@ -22,6 +22,7 @@ Commands:
   browser <id> <action>          Control browser bubbles
   terminal <id> <action>         Control terminal bubbles
   codegraph <subcmd> [...]       Query the project code graph (search/risk/affected/...)
+  connection list [--cwd …]      List all bubbles (term + browser) with user-set titles
   update                         Update to latest version
 
 Options:
@@ -101,6 +102,16 @@ if (process.argv[2] === 'codegraph') {
   await flushAndExit(0);
 }
 
+if (process.argv[2] === 'connection') {
+  process.argv.splice(2, 1);
+  // cock-connection.mjs handles flow + exit itself (single subcmd, simple).
+  await import('./cock-connection.mjs');
+  // import() resolves when the module finishes top-level await; that script
+  // already calls process.exit() on its own paths, so this fallback only
+  // fires for the 0-exit happy path that finished normally.
+  await flushAndExit(0);
+}
+
 if (process.argv[2] === 'update') {
   console.log('Updating @surething/cockpit...');
   const result = spawnSync('npm', ['install', '-g', '@surething/cockpit@latest'], { stdio: 'inherit' });
@@ -118,7 +129,7 @@ if (process.argv[2] === 'update') {
 const { existsSync, mkdirSync } = await import('fs');
 const { homedir } = await import('os');
 
-const knownCommands = new Set(['browser', 'terminal', 'update', 'help', 'codegraph']);
+const knownCommands = new Set(['browser', 'terminal', 'update', 'help', 'codegraph', 'connection']);
 const arg = process.argv[2];
 let projectDir = null;