@atlassian/chippy 0.0.1-beta.1 → 0.0.1-beta.2

package/lib/mcp-skill/scripts/chippy-helper-server.js

@@ -11,6 +11,8 @@ const {
 } = require('../browser-scripts/playwright-session');
 const { createProbeAnnotationChannel } = require('./probe-annotation-channel');
 const helperAccess = require('./helper-access');
+const pageSocketTrust = require('./page-socket-trust');
+const helperProxy = require('./helper-proxy');
  
 // ─── Config ───────────────────────────────────────────────────────────────────
 
@@ -74,6 +76,21 @@ function waitForPendingResult(pendingMap, requestId, timeoutMs, timeoutError) {
   });
 }
 
+// The page answered, but without the Avalanche runtime it cannot run the
+// command. Report that as an unavailable runtime instead of an empty result.
+const BRIDGE_MODULE_MISSING_HINT = 'The page has the Chippy bridge but not the Avalanche runtime (avalanche.iife.js). '
+  + 'Load it after inject.js, import /__chippy/inject.mjs instead, or reload a page managed by the extension or proxy.';
+
+function pageResultStatus(result) {
+  if (!result.ok) return 504;
+  return result.result && result.result.code === 'bridge-module-missing' ? 503 : 200;
+}
+
+function withPageResultHint(result) {
+  if (pageResultStatus(result) !== 503) return result;
+  return { ...result, ok: false, error: result.result.error, hint: BRIDGE_MODULE_MISSING_HINT };
+}
+
 function resolvePendingResult(pendingMap, requestId, result) {
   const pending = pendingMap.get(requestId);
   if (!pending) return false;
@@ -138,10 +155,11 @@ async function requestProbeCommand(clientId, command, timeoutMs = 10_000) {
     Math.max(100, Number(timeoutMs || 10_000)),
     'Timeout waiting for probe command result'
   );
+  const status = pageResultStatus(result);
   return {
-    ok: result.ok,
-    code: result.ok ? 200 : 504,
-    payload: { ...result, targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId },
+    ok: status === 200,
+    code: status,
+    payload: { ...withPageResultHint(result), targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId },
   };
 }
 
@@ -262,7 +280,7 @@ async function handoffToPlaywright({ clientId, url, probeIds, browserName, headl
 }
  
 // When active, non-Chippy requests are forwarded to targetPort (proxy mode).
-const proxyState = { active: false, targetPort: null, originalUrl: null, startedAt: null };
+const proxyState = { active: false, targetPort: null, originalUrl: null, target: null, startedAt: null };
 
 // ─── Proxy HTML injection ─────────────────────────────────────────────────────
 
@@ -298,15 +316,21 @@ function buildProxyInlineBundle() {
   ].join('\n');
 }
 
+// Without the extension, the proxy does its job: the DevTools hook shim and the
+// Avalanche runtime load before page code, and the page bridge connects last.
+// startup-handoff.js turns an armed reload's stored arm into the startup config
+// before Avalanche evaluates, so the detector installs before React commits.
+const PROXY_EARLY_SCRIPTS = [
+  `${CHIPPY_PREFIX}/devtools-hook-shim.js`,
+  `${CHIPPY_PREFIX}/startup-handoff.js`,
+  `${CHIPPY_PREFIX}/avalanche.iife.js`,
+];
+
 function injectIntoHtmlDocument(html) {
-  const bundle = buildProxyInlineBundle();
-  const lower = html.toLowerCase();
-  // Insert just before </body> or </html>, whichever comes last
-  for (const tag of ['</body>', '</html>']) {
-    const i = lower.lastIndexOf(tag);
-    if (i >= 0) return `${html.slice(0, i)}${bundle}\n${html.slice(i)}`;
-  }
-  return `${html}\n${bundle}`;
+  return helperProxy.injectProxyDocument(html, {
+    earlyScripts: PROXY_EARLY_SCRIPTS,
+    bridgeBundle: buildProxyInlineBundle(),
+  });
 }
 
 function stripHopHeaders(headers, bodyBuffer, stripCsp = false) {
@@ -384,6 +408,15 @@ const CORS_HEADERS = {
   'Cache-Control': 'no-store',
 };
 
+// The detector's canonical modes. An unknown string would reach
+// createAvalancheDetector and leave its mode state unset.
+const DETECTION_MODES = ['sources', 'full', 'stats', 'amplifiers'];
+function detectionModeError(options) {
+  const mode = options && typeof options === 'object' ? options.detectionMode : undefined;
+  if (mode === undefined || DETECTION_MODES.includes(mode)) return null;
+  return `detectionMode must be one of ${DETECTION_MODES.join(', ')} (got ${JSON.stringify(mode)})`;
+}
+
 function json(res, code, payload) {
   res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', ...CORS_HEADERS });
   res.end(JSON.stringify(payload, null, 2));
@@ -633,20 +666,26 @@ function isChippyPath(p) { return p === CHIPPY_PREFIX || p.startsWith(`${CHIPPY_
 
 function getProxySummary() {
   if (!proxyState.active) return null;
-  return { active: true, targetPort: proxyState.targetPort, originalUrl: proxyState.originalUrl, injectTarget: getProxyInjectTarget(), startedAt: proxyState.startedAt };
+  return {
+    active: true,
+    targetPort: proxyState.targetPort,
+    targetHost: proxyState.target?.hostHeader || null,
+    originalUrl: proxyState.originalUrl,
+    injectTarget: getProxyInjectTarget(),
+    startedAt: proxyState.startedAt,
+  };
 }
 
 function startProxy(targetPort, originalUrl) {
-  const p = Number(targetPort);
-  if (!Number.isFinite(p) || p < 1 || p > 65535) throw new Error(`Invalid target port: ${targetPort}`);
-  Object.assign(proxyState, { active: true, targetPort: p, originalUrl: originalUrl || null, startedAt: nowIso() });
-  console.log(`[proxy] enabled -> port=${p}${originalUrl ? ` url=${originalUrl}` : ''}`);
+  const target = helperProxy.resolveProxyTarget(targetPort, originalUrl);
+  Object.assign(proxyState, { active: true, targetPort: target.port, originalUrl: originalUrl || null, target, startedAt: nowIso() });
+  console.log(`[proxy] enabled -> ${target.hostHeader}${originalUrl ? ` url=${originalUrl}` : ''}`);
   return getProxySummary();
 }
 
 function stopProxy() {
   const prev = getProxySummary();
-  Object.assign(proxyState, { active: false, targetPort: null, originalUrl: null, startedAt: null });
+  Object.assign(proxyState, { active: false, targetPort: null, originalUrl: null, target: null, startedAt: null });
   console.log(`[proxy] disabled${prev?.targetPort ? ` (was ${prev.targetPort})` : ''}`);
   return { active: false };
 }
@@ -661,11 +700,11 @@ function forwardHeaders(headers, targetHost) {
 }
 
 function proxyRequest(req, res) {
-  const targetHost = `127.0.0.1:${proxyState.targetPort}`;
-  const url = `http://${targetHost}${req.url}`;
-  console.log(`[proxy] ${req.method} ${req.url} -> ${url}`);
+  const target = proxyState.target;
+  console.log(`[proxy] ${req.method} ${req.url} -> http://${target.hostHeader}${req.url}`);
 
-  const upstream = http.request(url, { method: req.method, headers: forwardHeaders(req.headers, targetHost) }, (upRes) => {
+  const options = helperProxy.upstreamRequestOptions(target, req, forwardHeaders(req.headers, target.hostHeader));
+  const upstream = http.request(options, (upRes) => {
     console.log(`[proxy] ${req.method} ${req.url} <- ${upRes.statusCode}`);
     if (!shouldInjectIntoProxyHtml(req, upRes)) {
       res.writeHead(upRes.statusCode || 502, upRes.statusMessage, upRes.headers);
@@ -701,12 +740,13 @@ function proxyRequest(req, res) {
 }
 
 function proxyUpgrade(req, socket, head) {
-  const targetHost = `127.0.0.1:${proxyState.targetPort}`;
-  console.log(`[proxy-ws] ${req.url} -> ${targetHost}`);
-  const upstream = http.request(`http://${targetHost}${req.url}`, {
-    method: 'GET',
-    headers: { ...forwardHeaders(req.headers, targetHost), connection: req.headers.connection || 'Upgrade', upgrade: req.headers.upgrade || 'websocket' },
-  });
+  const target = proxyState.target;
+  console.log(`[proxy-ws] ${req.url} -> ${target.hostHeader}`);
+  const upstream = http.request(helperProxy.upstreamRequestOptions(target, { url: req.url, method: 'GET' }, {
+    ...forwardHeaders(req.headers, target.hostHeader),
+    connection: req.headers.connection || 'Upgrade',
+    upgrade: req.headers.upgrade || 'websocket',
+  }));
   upstream.on('upgrade', (upRes, upSock, upHead) => {
     const lines = [`HTTP/1.1 ${upRes.statusCode || 101} ${upRes.statusMessage || 'Switching Protocols'}`];
     for (const [k, v] of Object.entries(upRes.headers)) {
@@ -820,8 +860,11 @@ function updateClientFromMessage(client, msg) {
 
 // ─── WebSocket attachment ─────────────────────────────────────────────────────
 
-function attachSocket(socket) {
+const clientIdBindings = pageSocketTrust.createClientIdBindings();
+
+function attachSocket(socket, socketOrigin) {
   const id = crypto.randomUUID();
+  clientIdBindings.claim(id, socketOrigin);
   const client = {
     socket, clientId: id,
     connectedAt: nowIso(), lastMessageAt: nowIso(), lastHelloAt: null,
@@ -848,6 +891,15 @@ function attachSocket(socket) {
       if (frame.opcode !== 0x1) continue;
       try {
         const msg = JSON.parse(frame.payload.toString('utf8'));
+        const rejected = pageSocketTrust.checkPageMessage({
+          bindings: clientIdBindings, socketOrigin, currentClientId: client.clientId, msg,
+        });
+        if (rejected) {
+          console.warn(`[ws] rejected message from origin=${socketOrigin || 'none'}: ${rejected}`);
+          wsSend(socket, JSON.stringify({ type: 'error', message: rejected }));
+          socket.destroy();
+          return;
+        }
         const prevId = client.clientId;
         updateClientFromMessage(client, msg);
         if (client.clientId !== prevId) { clients.delete(prevId); clients.set(client.clientId, client); }
@@ -871,6 +923,8 @@ function attachSocket(socket) {
             ack: true,
             action: msg.action || 'page-reload',
             clientId: client.clientId,
+            ...(typeof msg.earlyStartup === 'string' ? { earlyStartup: msg.earlyStartup } : {}),
+            ...(msg.ok === false && typeof msg.error === 'string' ? { error: msg.error } : {}),
           });
         }
       } catch (e) {
@@ -1091,6 +1145,11 @@ async function handleChippyHttp(req, res, url) {
     return true;
   }
 
+  if (method === 'GET' && p === `${CHIPPY_PREFIX}/startup-handoff.js`) {
+    serveExtensionFile(res, 'startup-handoff.js', 'application/javascript; charset=utf-8');
+    return true;
+  }
+
   if (method === 'GET' && p === `${CHIPPY_PREFIX}/avalanche.iife.js`) {
     serveExtensionFile(res, 'avalanche.iife.js', 'application/javascript; charset=utf-8', (src) =>
       `${src}\n;(() => {\n  const api = globalThis.__AVALANCHE__;\n  if (api && api.default && typeof api.default === 'object') {\n    Object.assign(api, api.default);\n  }\n})();\n`);
@@ -1199,6 +1258,8 @@ async function handleChippyHttp(req, res, url) {
     const clientId = p.split('/')[4];
     try {
       const body = await parseJsonBody(req);
+      const modeError = detectionModeError(body?.options);
+      if (modeError) { json(res, 400, { ok: false, error: modeError }); return true; }
       const result = await requestAvalanche(clientId, body);
       json(res, result.code, result.payload);
     } catch (e) {
@@ -1389,9 +1450,8 @@ async function handleChippyHttp(req, res, url) {
       const autoStart = body.autoStart !== false;
       if (autoStart) {
         const incomingOptions = body.options && typeof body.options === 'object' ? body.options : {};
-        // TODO: Validate detectionMode against the detector's canonical
-        // modes at this transport boundary. An arbitrary string can currently
-        // reach createAvalancheDetector and leave its internal mode state unset.
+        const modeError = detectionModeError(incomingOptions);
+        if (modeError) { json(res, 400, { ok: false, error: modeError }); return true; }
         const arm = {
           autoStart: true,
           options: {
@@ -1439,10 +1499,22 @@ async function handleChippyHttp(req, res, url) {
       const action = resolved.client.integration?.kind === 'storybook'
         ? 'storybook-force-remount'
         : 'reload';
-      const sent = sendToClient(resolved.clientId, { type: action, requestId });
+      // An armed page gets its arm with the reload or remount, so Avalanche is
+      // installed before React's first commit.
+      const pageOrigin = normalizeArmOrigin(resolved.client.page?.url || '');
+      const arm = armedAvalancheByClient.get(resolved.clientId) || (pageOrigin && armedAvalanche.get(pageOrigin)) || null;
+      const command = arm ? { type: action, requestId, avalanche: arm } : { type: action, requestId };
+      const sent = sendToClient(resolved.clientId, command);
       if (!sent.ok) { json(res, sent.code, { ok: false, error: sent.error }); return true; }
       const ack = await waitForPendingResult(pendingReloadAck, requestId, 1500, 'Timeout waiting for reload ack');
-      json(res, ack.ok ? 200 : 504, { ...ack, reloading: sent.clientId, resolvedFrom: sent.resolvedFrom, requestId });
+      // 504: no ack arrived. 409: the page answered but could not reload.
+      const refused = ack.ok && ack.result?.ok === false;
+      const status = !ack.ok ? 504 : refused ? 409 : 200;
+      json(res, status, {
+        ...ack,
+        ...(refused ? { ok: false, error: ack.result.error || 'The page did not reload' } : {}),
+        reloading: sent.clientId, resolvedFrom: sent.resolvedFrom, requestId,
+      });
     } catch (e) { json(res, 400, { ok: false, error: e.message }); }
     return true;
   }
@@ -1497,7 +1569,7 @@ async function handleChippyHttp(req, res, url) {
       if (!delivered.ok) { json(res, delivered.code, { ok: false, error: delivered.error }); return true; }
       // Wait for computed-style-result from the page
       const result = await waitForPendingResult(pendingComputedStyle, requestId, timeoutMs, 'Timeout waiting for computed style result');
-      json(res, result.ok ? 200 : 504, { ...result, targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId });
+      json(res, pageResultStatus(result), { ...withPageResultHint(result), targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId });
     } catch (e) { json(res, 400, { ok: false, error: e.message }); }
     return true;
   }
@@ -1615,7 +1687,7 @@ async function handleChippyHttp(req, res, url) {
       const delivered = sendToClient(clientId, wsCommand);
       if (!delivered.ok) { json(res, delivered.code, { ok: false, error: delivered.error }); return true; }
       const result = await waitForPendingResult(pendingEvalProbe, requestId, timeoutMs, 'Timeout waiting for eval-probe result');
-      json(res, result.ok ? 200 : 504, { ...result, targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId });
+      json(res, pageResultStatus(result), { ...withPageResultHint(result), targetClientId: delivered.clientId, resolvedFrom: delivered.resolvedFrom, requestId });
     } catch (e) { json(res, 400, { ok: false, error: e.message }); }
     return true;
   }
@@ -1633,22 +1705,6 @@ async function handleChippyHttp(req, res, url) {
     return true;
   }
 
-  // Proxy bootstrap (browser redirect)
-  if (method === 'GET' && p === `${CHIPPY_PREFIX}/proxy/go`) {
-    try {
-      const targetPort = url.searchParams.get('targetPort');
-      const originalUrl = url.searchParams.get('originalUrl') || null;
-      const redirectTo = url.searchParams.get('redirectTo') || '/';
-      startProxy(targetPort, originalUrl);
-      console.log(`[proxy-bootstrap] redirect -> ${redirectTo}`);
-      text(res, 200, `<!doctype html><meta http-equiv="refresh" content="0;url=${redirectTo.replace(/"/g, '&quot;')}"><title>Chippy</title><p>Redirecting…</p>`, 'text/html; charset=utf-8');
-    } catch (e) {
-      console.error(`[proxy-bootstrap] failed: ${e.message}`);
-      text(res, 400, `Could not start proxy: ${e.message}`);
-    }
-    return true;
-  }
-
   return false;
 }
 
@@ -1657,7 +1713,7 @@ function handleChippyUpgrade(req, socket) {
   if (!key) { socket.write('HTTP/1.1 400 Bad Request\r\n\r\n'); socket.destroy(); return; }
   const accept = crypto.createHash('sha1').update(key + WS_GUID).digest('base64');
   socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
-  attachSocket(socket);
+  attachSocket(socket, pageSocketTrust.handshakeOrigin(req.headers));
 }
 
 // ─── Server ───────────────────────────────────────────────────────────────────
@@ -1666,10 +1722,11 @@ function chippyRoute(pathname) {
   return isChippyPath(pathname) ? pathname.slice(CHIPPY_PREFIX.length) : null;
 }
 
-function rejectUnauthorized(req, pathname) {
+function rejectUnauthorized(req, url) {
   return helperAccess.authorizeRequest({
     method: req.method || 'GET',
-    route: chippyRoute(pathname),
+    route: chippyRoute(url.pathname),
+    query: url.searchParams,
     headers: req.headers,
     token: helperToken,
     loopback: loopbackBind,
@@ -1678,7 +1735,7 @@ function rejectUnauthorized(req, pathname) {
 
 const server = http.createServer(async (req, res) => {
   const url = new URL(req.url, baseUrlFromReq(req));
-  const denied = rejectUnauthorized(req, url.pathname);
+  const denied = rejectUnauthorized(req, url);
   if (denied) { json(res, denied.status, { ok: false, error: denied.error }); return; }
   if (isChippyPath(url.pathname)) {
     if (!(await handleChippyHttp(req, res, url))) json(res, 404, { ok: false, error: 'Chippy route not found' });
@@ -1689,8 +1746,9 @@ const server = http.createServer(async (req, res) => {
 });
 
 server.on('upgrade', (req, socket, head) => {
-  const p = new URL(req.url, 'http://127.0.0.1').pathname;
-  const denied = rejectUnauthorized(req, p);
+  const upgradeUrl = new URL(req.url, 'http://127.0.0.1');
+  const p = upgradeUrl.pathname;
+  const denied = rejectUnauthorized(req, upgradeUrl);
   if (denied) { socket.write(`HTTP/1.1 ${denied.status} ${denied.status === 401 ? 'Unauthorized' : 'Forbidden'}\r\n\r\n`); socket.destroy(); return; }
   if (p === `${CHIPPY_PREFIX}/ws`) { handleChippyUpgrade(req, socket); return; }
   if (proxyState.active && !isChippyPath(p)) { proxyUpgrade(req, socket, head); return; }

package/lib/mcp-skill/scripts/chippy.sh

@@ -179,6 +179,22 @@ stop_helper() {
   return 1
 }
 
+# The helper explains failures in its JSON body (`error`, `hint`); show them
+# instead of leaving only the HTTP status.
+print_helper_error_body() {
+  [[ -s "$1" ]] || return 0
+  node -e '
+    const fs = require("fs");
+    const raw = fs.readFileSync(process.argv[1], "utf8");
+    let body;
+    try { body = JSON.parse(raw); } catch { process.stdout.write(`  helper: ${raw.trim().slice(0, 500)}\n`); process.exit(0); }
+    for (const key of ["error", "hint", "next"]) {
+      const value = body && body[key];
+      if (value) process.stdout.write(`  ${key}: ${typeof value === "string" ? value : JSON.stringify(value)}\n`);
+    }
+  ' "$1" 2>/dev/null || true
+}
+
 run_curl() {
   local method="$1"
   local url="$2"
@@ -245,6 +261,7 @@ run_curl() {
   if [[ -n "$stderr_text" ]]; then
     echo "  → curl: $stderr_text" >&2
   fi
+  print_helper_error_body "$response_file" >&2
   rm -f "$response_file" "$stderr_file"
   if [[ "$http_code" =~ ^[0-9]+$ && "$http_code" -ge 400 ]]; then
     return 22
@@ -252,6 +269,16 @@ run_curl() {
   return "$code"
 }
 
+require_detection_mode() {
+  case "$2" in
+    sources|full|stats|amplifiers) ;;
+    *)
+      echo "$1 detectionMode must be sources, full, stats, or amplifiers (got '$2')" >&2
+      exit 1
+      ;;
+  esac
+}
+
 post_json() {
   local path="$1"
   local body="$2"
@@ -303,6 +330,7 @@ case "$cmd" in
     ;;
   inject-url)
     echo "Import integration is document-scoped: a full reload/navigation removes Chippy and requires the user or automation to inject it again." >&2
+    echo "The classic inject.js installs Chippy only; load $BASE_URL/avalanche.iife.js after it for bridge and Avalanche commands, or import $BASE_URL/inject.mjs instead." >&2
     printf '%s/inject.js\n' "$BASE_URL"
     ;;
   recipes)
@@ -964,6 +992,7 @@ case "$cmd" in
       echo "avalanche-install requires <clientId> [detectionMode]" >&2
       exit 1
     fi
+    require_detection_mode avalanche-install "$detection_mode"
     body="{\"action\":\"install\",\"options\":{\"captureFibers\":true,\"detectionMode\":\"$detection_mode\",\"historySize\":1000}}"
     post_avalanche "$client_id" "$body"
     ;;
@@ -974,6 +1003,7 @@ case "$cmd" in
       echo "avalanche-recapture requires <clientId> [detectionMode]" >&2
       exit 1
     fi
+    require_detection_mode avalanche-recapture "$detection_mode"
     body="{\"action\":\"install\",\"options\":{\"captureFibers\":true,\"detectionMode\":\"$detection_mode\",\"historySize\":1000}}"
     post_avalanche "$client_id" "$body" >/dev/null
     post_avalanche "$client_id" '{"action":"clear"}' >/dev/null
@@ -1083,10 +1113,7 @@ case "$cmd" in
       echo "avalanche-arm captureFibers must be true or false" >&2
       exit 1
     fi
-    if [[ "$detection_mode" != "sources" && "$detection_mode" != "full" && "$detection_mode" != "stats" && "$detection_mode" != "amplifiers" ]]; then
-      echo "avalanche-arm detectionMode must be sources, full, stats, or amplifiers" >&2
-      exit 1
-    fi
+    require_detection_mode avalanche-arm "$detection_mode"
     body="{\"clientId\":$(json_escape "$client_id"),\"origin\":$(json_escape "$origin"),\"autoStart\":true,\"max\":$max_commits,\"options\":{\"captureFibers\":$capture_fibers,\"detectionMode\":\"$detection_mode\"}}"
     post_json "/api/avalanche-arm" "$body" >/dev/null
     # Reset first (clear prior capture), then install detector — no reload needed
@@ -1142,7 +1169,15 @@ case "$cmd" in
     "$0" page-reload "$client_id"
     echo >&2
     echo "== wait ==" >&2
-    "$0" page-wait-reload "$client_id" "$timeout_ms"
+    wait_result=$("$0" page-wait-reload "$client_id" "$timeout_ms")
+    printf '%s\n' "$wait_result"
+    if ! printf '%s' "$wait_result" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{process.exit(JSON.parse(s).reloaded===true?0:1)}catch{process.exit(1)}})'; then
+      echo "reload-with-avalanche: the page did not reconnect within ${timeout_ms}ms after the reload." >&2
+      echo "  meaning: Chippy was not loaded again in the new document, so nothing captured its commits" >&2
+      echo "  next: with Mode A, load the runtimes as init scripts (installHelpers(page, { init: true })) so they return on reload," >&2
+      echo "        or skip the reload: avalanche-install, then trigger the interaction and read avalanche-status" >&2
+      exit 1
+    fi
     if [[ "$settle_ms" -gt 0 ]]; then
       echo >&2
       echo "== settle (${settle_ms}ms) ==" >&2
@@ -1187,8 +1222,7 @@ case "$cmd" in
       };
       process.stdout.write(JSON.stringify(body));
     ' "$url" "$probe_json" "$browser_name" "$headless") || exit 1
-    curl -fsSL ${AUTH_HEADER[@]+"${AUTH_HEADER[@]}"} -X POST -H 'content-type: application/json' \
-      "$BASE_URL/api/pages/$client_id/handoff-to-playwright" --data-binary "$body"
+    post_json "/api/pages/$client_id/handoff-to-playwright" "$body"
     ;;
   proxy-state)
     curl "${CURL_OPTS[@]}" "$BASE_URL/api/proxy/state"

package/lib/mcp-skill/scripts/helper-access.js

@@ -29,16 +29,15 @@ const PUBLIC_GET_PATHS = new Set([
   '/avalanche.es.js.map',
   '/avalanche.iife.js.map',
   '/devtools-hook-shim.js',
-  '/api/avalanche-arm',
-  '/proxy/go',
+  '/startup-handoff.js',
   '/ws',
 ]);
 
 // Routes the published browser extension calls from its service worker. The
 // extension sends no token, so these stay open to extension origins and
-// non-browser clients on every bind. They list pages and arm capture; they do
-// not run page code.
-const EXTENSION_ROUTES = new Set(['GET /api/pages', 'POST /api/avalanche-arm']);
+// non-browser clients on every bind. They list pages and read or arm capture;
+// they do not run page code.
+const EXTENSION_ROUTES = new Set(['GET /api/pages', 'GET /api/avalanche-arm', 'POST /api/avalanche-arm']);
 
 function stateDirectory(env = process.env) {
   return env.CHIPPY_STATE_DIR || path.join(os.homedir(), '.chippy');
@@ -109,6 +108,19 @@ function isExtensionOrigin(origin) {
   return typeof origin === 'string' && /^(chrome|moz)-extension:\/\//.test(origin);
 }
 
+function originOf(value) {
+  try { return new URL(value).origin; } catch { return null; }
+}
+
+// A page may ask whether its own origin is armed (the Storybook addon does this
+// at preview start). It may not list other origins or look up client ids.
+function isSelfArmLookup(method, route, origin, query) {
+  if (method !== 'GET' || route !== '/api/avalanche-arm' || !query || typeof origin !== 'string') return false;
+  if (query.get('clientId')) return false;
+  const asked = query.get('origin');
+  return !!asked && originOf(asked) === origin;
+}
+
 function tokensMatch(expected, received) {
   if (typeof received !== 'string' || !expected) return false;
   const a = Buffer.from(expected);
@@ -117,7 +129,8 @@ function tokensMatch(expected, received) {
 }
 
 // Returns null when the request may proceed, otherwise { status, error }.
-function authorizeRequest({ method, route, headers, token, loopback, env = process.env }) {
+// `query` is the request's URLSearchParams.
+function authorizeRequest({ method, route, headers, token, loopback, query = null, env = process.env }) {
   if (loopback && !isAllowedHost(headers.host, env)) {
     return { status: 403, error: 'Host header is not a loopback host; set CHIPPY_HELPER_ALLOWED_HOSTS to allow it' };
   }
@@ -127,6 +140,7 @@ function authorizeRequest({ method, route, headers, token, loopback, env = proce
   if (kind === 'extension') {
     const origin = headers.origin;
     if (origin === undefined || isExtensionOrigin(origin)) return null;
+    if (isSelfArmLookup(method, route, origin, query)) return null;
   }
   return { status: 401, error: 'Missing or invalid X-Chippy-Token header' };
 }

package/lib/mcp-skill/scripts/helper-proxy.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+// Pure helpers for the helper's proxy mode: where to forward requests, and how
+// to put Chippy into the proxied HTML document.
+
+const LOOPBACK_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+
+function isLoopbackHostname(hostname) {
+  const name = String(hostname || '').toLowerCase().replace(/^\[|\]$/g, '');
+  return LOOPBACK_HOSTNAMES.has(name) || /^127(?:\.\d{1,3}){3}$/.test(name) || name.endsWith('.localhost');
+}
+
+// The proxy forwards only to this machine. Dev servers bind `localhost`,
+// `127.0.0.1`, or `::1` depending on the tool and platform (Vite on macOS binds
+// `::1`), so the original page URL decides the loopback name when it names one.
+// `localhost` is the default because it resolves to both address families.
+function resolveProxyTarget(targetPort, originalUrl) {
+  const port = Number(targetPort);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`Invalid target port: ${targetPort}`);
+  let hostname = 'localhost';
+  if (originalUrl) {
+    let parsed;
+    try { parsed = new URL(String(originalUrl)); } catch { throw new Error(`Invalid originalUrl: ${originalUrl}`); }
+    const named = parsed.hostname.replace(/^\[|\]$/g, '');
+    if (!isLoopbackHostname(named)) {
+      throw new Error(`Proxy targets must be on this machine; originalUrl host ${parsed.hostname} is not a loopback name`);
+    }
+    hostname = named;
+  }
+  const hostHeader = `${hostname.includes(':') ? `[${hostname}]` : hostname}:${port}`;
+  return { hostname, port, hostHeader };
+}
+
+// Options for http.request. `autoSelectFamily` tries every address `localhost`
+// resolves to, so a server listening on only one family is still reached.
+function upstreamRequestOptions(target, req, headers) {
+  return {
+    host: target.hostname,
+    port: target.port,
+    path: req.url,
+    method: req.method,
+    headers,
+    autoSelectFamily: true,
+  };
+}
+
+const HEAD_OPEN = /<head(?:\s[^>]*)?>/i;
+const HTML_OPEN = /<html(?:\s[^>]*)?>/i;
+const DOCTYPE = /^\s*<!doctype[^>]*>/i;
+
+// Classic scripts at the start of <head> run before the document's module
+// scripts, so the DevTools hook exists when react-dom evaluates.
+function insertAtHeadStart(html, markup) {
+  for (const pattern of [HEAD_OPEN, HTML_OPEN, DOCTYPE]) {
+    const match = pattern.exec(html);
+    if (match) {
+      const at = match.index + match[0].length;
+      return `${html.slice(0, at)}\n${markup}\n${html.slice(at)}`;
+    }
+  }
+  return `${markup}\n${html}`;
+}
+
+function insertAtBodyEnd(html, markup) {
+  const lower = html.toLowerCase();
+  for (const tag of ['</body>', '</html>']) {
+    const i = lower.lastIndexOf(tag);
+    if (i >= 0) return `${html.slice(0, i)}${markup}\n${html.slice(i)}`;
+  }
+  return `${html}\n${markup}`;
+}
+
+// `earlyScripts` are helper-relative script paths that must run before page
+// code; `bridgeBundle` is inline markup that connects the page to the helper.
+function injectProxyDocument(html, { earlyScripts = [], bridgeBundle = '' } = {}) {
+  const early = earlyScripts
+    .map((src) => `<script data-chippy-proxy-early="true" src="${src}"></script>`)
+    .join('\n');
+  const withEarly = early ? insertAtHeadStart(html, early) : html;
+  return bridgeBundle ? insertAtBodyEnd(withEarly, bridgeBundle) : withEarly;
+}
+
+module.exports = {
+  injectProxyDocument,
+  isLoopbackHostname,
+  resolveProxyTarget,
+  upstreamRequestOptions,
+};