@ait-co/devtools 0.1.32 → 0.1.34

package/dist/mcp/cli.js

@@ -8,9 +8,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import { EventEmitter } from "node:events";
 import { WebSocket } from "ws";
 import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { Tunnel, bin, install } from "cloudflared";
-import qrcode from "qrcode-terminal";
 //#region src/mcp/ait-chii-source.ts
 function isObject$2(value) {
 	return typeof value === "object" && value !== null;
@@ -239,6 +238,23 @@ var ChiiCdpConnection = class {
 *
 * Node-only: `chii` pulls in Koa + ws. Never bundled into the browser/in-app
 * entries.
+*
+* TOTP auth (relay-side, authoritative gate):
+*   When `verifyAuth` is provided, this module registers an HTTP upgrade
+*   listener on the server BEFORE calling `chii.start({server})`. Node's
+*   `http.Server` allows multiple 'upgrade' listeners; the first to call
+*   `socket.destroy()` wins. Invalid auth → 401 + destroy (chii never sees
+*   the connection). Valid auth → return without side-effect (chii handles it).
+*
+* Threat model: "URL leak" — someone obtains the tunnel URL (Slack paste, QR
+*   screenshot, shoulder-surfing) but does not have the shared TOTP secret.
+*   Rotating 6-digit code makes the URL stale after 30 s.
+*   A determined attacker who extracts the secret from the dogfood bundle can
+*   still compute valid codes; that is out of scope (see umbrella CLAUDE.md §4).
+*
+* SECRET-HANDLING: The secret value and computed TOTP codes MUST NOT appear
+*   in any log, error message, or process output. `verifyAuth` is a black-box
+*   predicate from the caller's perspective; this module only forwards pass/fail.
 */
 const require = createRequire(import.meta.url);
 function loadChiiServer() {
@@ -246,26 +262,49 @@ function loadChiiServer() {
 	if (typeof mod === "object" && mod !== null && "start" in mod && typeof mod.start === "function") return mod;
 	throw new Error("chii server module did not expose start()");
 }
-/** Starts the Chii relay on the given port and resolves once listening. */
+/**
+* Starts the Chii relay and resolves once listening.
+*
+* Default port is 0 (OS-assigned). With port 0 the OS picks a free ephemeral
+* port on every start, so a stale cloudflared orphan holding any particular
+* port cannot cause EADDRINUSE. The resolved `ChiiRelay.port` and `baseUrl`
+* always reflect the actual bound port.
+*
+* chii.start() is called with `server` (our pre-created httpServer) BEFORE
+* httpServer.listen(). This is intentional: chii attaches its Koa handler and
+* WS upgrade listener to the server object, but the actual TCP bind is
+* performed by our httpServer.listen() call below. The `port`/`domain` values
+* passed to chii.start() are used for display/banner purposes inside chii and
+* do not affect which port the server binds. The connection path (clients
+* connecting to `relay.baseUrl`) always uses the post-listen confirmed port.
+*/
 async function startChiiRelay(options = {}) {
-	const port = options.port ?? 9100;
+	const requestedPort = options.port ?? 0;
 	const host = options.host ?? "127.0.0.1";
+	const { verifyAuth } = options;
 	const httpServer = createServer();
+	if (verifyAuth) httpServer.on("upgrade", (req, socket) => {
+		if (!verifyAuth(req)) {
+			socket.write("HTTP/1.1 401 Unauthorized\r\nContent-Length: 0\r\n\r\n");
+			socket.destroy();
+			return;
+		}
+	});
 	await loadChiiServer().start({
 		server: httpServer,
-		domain: `${host}:${port}`,
-		port
+		domain: `${host}:${requestedPort}`,
+		port: requestedPort
 	});
-	await new Promise((resolve, reject) => {
+	const actualPort = await new Promise((resolve, reject) => {
 		httpServer.once("error", reject);
-		httpServer.listen(port, host, () => {
+		httpServer.listen(requestedPort, host, () => {
 			httpServer.off("error", reject);
-			resolve();
+			resolve(httpServer.address().port);
 		});
 	});
 	return {
-		port,
-		baseUrl: `http://${host}:${port}`,
+		port: actualPort,
+		baseUrl: `http://${host}:${actualPort}`,
 		close: () => new Promise((resolve) => {
 			httpServer.close(() => resolve());
 		})
@@ -278,21 +317,25 @@ function stripExisting(query, key) {
 	return query.split("&").filter((pair) => pair !== "" && pair.split("=")[0] !== key).join("&");
 }
 /**
-* Splices `debug=1` and `relay=<wssUrl>` into a scheme URL's query string,
-* preserving everything else (scheme, authority, path, hash, and the existing
-* `_deploymentId` param). If `debug` or `relay` is already present it is
-* replaced so the helper is idempotent.
+* Splices `debug=1`, `relay=<wssUrl>`, and (optionally) `at=<totpCode>` into a
+* scheme URL's query string, preserving everything else (scheme, authority,
+* path, hash, and the existing `_deploymentId` param). If any of the spliced
+* params is already present it is replaced so the helper is idempotent.
 *
 * @param schemeUrl - The `intoss-private://…?_deploymentId=<uuid>` URL printed
 *   by `ait deploy --scheme-only`. Must already carry `_deploymentId` (Layer B
 *   of the gate); this helper does not invent one.
 * @param wssUrl - The live relay URL (`wss://…trycloudflare.com`) from the
 *   running debug MCP server's quick tunnel.
-* @returns The same URL with `debug=1&relay=<encoded wssUrl>` appended.
+* @param totpCode - Optional current TOTP code (6 digits). When provided, it
+*   is spliced as `at=<totpCode>`. Must be computed at call time — it rotates
+*   every 30 s. Pass `undefined` or omit when TOTP is disabled.
+* @returns The same URL with `debug=1&relay=<encoded wssUrl>[&at=<totpCode>]`
+*   appended.
 * @throws If `wssUrl` is not a `wss:` URL (the gate rejects anything else, so
 *   producing such a link would be a silent dead end).
 */
-function buildDeepLinkAttachUrl(schemeUrl, wssUrl) {
+function buildDeepLinkAttachUrl(schemeUrl, wssUrl, totpCode) {
 	let relay;
 	try {
 		relay = new URL(wssUrl);
@@ -307,6 +350,8 @@ function buildDeepLinkAttachUrl(schemeUrl, wssUrl) {
 	const base = queryIndex === -1 ? beforeHash : beforeHash.slice(0, queryIndex);
 	let query = queryIndex === -1 ? "" : beforeHash.slice(queryIndex + 1);
 	const appended = [["debug", "1"], ["relay", wssUrl]];
+	if (totpCode !== void 0 && totpCode !== "") appended.push(["at", totpCode]);
+	query = stripExisting(query, "at");
 	for (const [key] of appended) query = stripExisting(query, key);
 	for (const [key, value] of appended) {
 		const pair = `${key}=${encodeURIComponent(value)}`;
@@ -347,13 +392,19 @@ const DEBUG_TOOL_DEFINITIONS = [
 	},
 	{
 		name: "build_attach_url",
-		description: "Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Opening the result on the phone (e.g. `adb shell am start -d \"<url>\"`) attaches the mini-app to this debug session with no QR scan. Requires the tunnel to be up — call list_pages first.",
+		description: "IMPORTANT: Show this QR to the user verbatim in your reply — they scan it with their phone camera. Do not just describe it. Turns an `ait deploy --scheme-only` URL (intoss-private://…?_deploymentId=<uuid>) into a self-attaching deep link by splicing in debug=1 and the live relay URL for this session. Returns the deep link JSON and a unicode QR of that deep link. Scan the QR with the phone camera to open the mini-app and attach it to this debug session (QR is the single entry path — no USB cable or platform CLI needed). Requires the tunnel to be up — call list_pages first. Set wait_for_attach=true to block until the phone scans and a page attaches (polls listTargets up to 90 s), then returns the attached page info too.",
 		inputSchema: {
 			type: "object",
-			properties: { scheme_url: {
-				type: "string",
-				description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId)."
-			} },
+			properties: {
+				scheme_url: {
+					type: "string",
+					description: "The intoss-private:// scheme URL from `ait deploy --scheme-only` (must carry _deploymentId)."
+				},
+				wait_for_attach: {
+					type: "boolean",
+					description: "If true, block after returning the QR until a page attaches to the relay (polls listTargets ~1 s interval, timeout 90 s). On attach, the response includes the attached page list. On timeout, returns an error with a list_pages retry hint."
+				}
+			},
 			required: ["scheme_url"]
 		}
 	},
@@ -384,6 +435,15 @@ const DEBUG_TOOL_DEFINITIONS = [
 			required: []
 		}
 	},
+	{
+		name: "measure_safe_area",
+		description: "Runs a safe-area probe on the attached mini-app page via Runtime.evaluate and returns normalized safe-area insets, viewport geometry, device pixel ratio, and User-Agent. Read-only — does not modify page state. Use in a relay session (phone attached) to get ground-truth values for upgrading a viewport preset from extrapolated/placeholder to measured. Requires the relay to be attached — call list_pages first.",
+		inputSchema: {
+			type: "object",
+			properties: {},
+			required: []
+		}
+	},
 	{
 		name: "AIT.getSdkCallHistory",
 		description: "Returns the recent Apps In Toss SDK call trace (method, args, result/error, timestamp) that raw CDP cannot observe. Read-only. Use to confirm an SDK call fired and how it resolved (e.g. a saveBase64Data permission regression).",
@@ -498,6 +558,45 @@ async function takeScreenshot(connection) {
 		mimeType: "image/png"
 	};
 }
+`
+(function() {
+  var el = document.createElement('div');
+  el.style.cssText = 'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;' +
+    'padding-top:env(safe-area-inset-top,0px);' +
+    'padding-right:env(safe-area-inset-right,0px);' +
+    'padding-bottom:env(safe-area-inset-bottom,0px);' +
+    'padding-left:env(safe-area-inset-left,0px)';
+  document.documentElement.appendChild(el);
+  var cs = window.getComputedStyle(el);
+  var cssEnv = {
+    top: parseFloat(cs.paddingTop) || 0,
+    right: parseFloat(cs.paddingRight) || 0,
+    bottom: parseFloat(cs.paddingBottom) || 0,
+    left: parseFloat(cs.paddingLeft) || 0
+  };
+  document.documentElement.removeChild(el);
+  var sdkInsets = null;
+  try {
+    if (typeof SafeAreaInsets !== 'undefined' && SafeAreaInsets && typeof SafeAreaInsets.get === 'function') {
+      sdkInsets = SafeAreaInsets.get();
+    }
+  } catch(_) {}
+  var navBarHeight = null;
+  try {
+    var nb = document.querySelector('.ait-navbar');
+    if (nb) navBarHeight = nb.getBoundingClientRect().height;
+  } catch(_) {}
+  return JSON.stringify({
+    cssEnv: cssEnv,
+    sdkInsets: sdkInsets,
+    navBarHeight: navBarHeight,
+    innerWidth: window.innerWidth,
+    innerHeight: window.innerHeight,
+    devicePixelRatio: window.devicePixelRatio,
+    userAgent: navigator.userAgent
+  });
+})()
+`.trim();
 /** Set of tool names served by the AIT source rather than the CDP connection. */
 const AIT_TOOL_NAMES = new Set([
 	"AIT.getSdkCallHistory",
@@ -521,16 +620,97 @@ function getOperationalEnvironment(source) {
 	return source.get("AIT.getOperationalEnvironment");
 }
 //#endregion
+//#region src/mcp/totp.ts
+/**
+* RFC 6238 TOTP implementation (Node.js, node:crypto only).
+*
+* External TOTP libraries (otplib, speakeasy, …) are intentionally NOT used
+* to keep the dependency surface minimal. This hand-roll is ~30 lines and
+* covers exactly what relay-side auth needs.
+*
+* Algorithm summary (RFC 6238 + RFC 4226):
+*   T  = floor(now / 30)          — 30-second time step counter
+*   K  = Buffer.from(secret, 'hex') — shared secret (raw bytes, hex-encoded)
+*   MAC = HMAC-SHA1(K, T as 8-byte big-endian uint64)
+*   offset = MAC[19] & 0x0f
+*   code = (MAC[offset..offset+4] & 0x7fffffff) % 10^6  — 6 digits
+*
+* Security note (keep this comment accurate):
+*   The baked-in secret in a dogfood build is extractable from the bundle by a
+*   determined reverse engineer. This mechanism raises the bar from
+*   "anyone with the URL" to "URL + bundle extraction + live TOTP calculation".
+*   Casual URL leaks (Slack paste, QR screenshot, shoulder-surfing) are
+*   blocked; deliberate reverse engineering is not. See threat model in
+*   src/mcp/chii-relay.ts and umbrella CLAUDE.md §4.
+*
+* SECRET-HANDLING: secret values and computed codes MUST NOT appear in any
+* log, error message, or string visible outside this module. Only boolean
+* pass/fail and reason enum values are safe to surface.
+*/
+/** Time step window in seconds (RFC 6238 default). */
+const TIME_STEP = 30;
+/** Number of digits in the generated code. */
+const DIGITS = 6;
+/**
+* Derives a 6-digit TOTP code from a hex-encoded secret at the given wall-
+* clock time.
+*
+* @param secret - The shared secret as a hex string (e.g. 64 hex chars = 32
+*   bytes). Must be the output of `generateAttachToken()` or compatible.
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @returns A zero-padded 6-digit decimal string, e.g. `"042193"`.
+*/
+function generateTotp(secret, when = Date.now()) {
+	const key = Buffer.from(secret, "hex");
+	const counter = Math.max(0, Math.floor(when / 1e3 / TIME_STEP));
+	const counterBuf = Buffer.alloc(8);
+	const hi = Math.floor(counter / 4294967296);
+	const lo = counter >>> 0;
+	counterBuf.writeUInt32BE(hi, 0);
+	counterBuf.writeUInt32BE(lo, 4);
+	const mac = createHmac("sha1", key).update(counterBuf).digest();
+	const offset = mac[19] & 15;
+	return (((mac[offset] & 127) << 24 | (mac[offset + 1] & 255) << 16 | (mac[offset + 2] & 255) << 8 | mac[offset + 3] & 255) % 10 ** DIGITS).toString().padStart(DIGITS, "0");
+}
+/**
+* Verifies a TOTP code against the secret, accepting ±`skew` time steps to
+* tolerate clock drift between the relay host and the client device.
+*
+* Uses `timingSafeEqual` for constant-time comparison to prevent timing
+* side-channel attacks.
+*
+* @param secret - Hex-encoded shared secret.
+* @param code - The 6-digit code to verify (string or numeric).
+* @param when - Unix timestamp in milliseconds. Defaults to `Date.now()`.
+* @param skew - Number of adjacent steps to accept on either side. Default 1
+*   (accepts T-1, T, T+1 — a 90-second acceptance window).
+* @returns `true` if the code matches any accepted step, `false` otherwise.
+*/
+function verifyTotp(secret, code, when = Date.now(), skew = 1) {
+	const normalised = String(code).padStart(DIGITS, "0");
+	if (normalised.length !== DIGITS || !/^\d{6}$/.test(normalised)) return false;
+	const candidateBuf = Buffer.from(normalised, "utf8");
+	for (let delta = -skew; delta <= skew; delta++) {
+		const expected = generateTotp(secret, when + delta * TIME_STEP * 1e3);
+		if (timingSafeEqual(Buffer.from(expected, "utf8"), candidateBuf)) return true;
+	}
+	return false;
+}
+//#endregion
 //#region src/mcp/tunnel.ts
 /**
 * cloudflared quick tunnel + attach banner for the debug-mode MCP server.
 *
 * On spawn, the debug server opens an accountless `*.trycloudflare.com` quick
 * tunnel to the local Chii relay so the phone can attach over a public wss URL,
-* then prints that URL + an attach token + an ASCII QR to the terminal. The
-* phone scans the QR (or pastes the URL) to attach; the in-app side passes the
-* token back. The token is generated + displayed as a pairing hint; relay-side
-* validation (ACL enforcement) is a later phase.
+* then prints a unicode half-block QR + attach instructions. When TOTP auth is
+* enabled (`AIT_DEBUG_TOTP_SECRET` is set), the QR encodes only the base relay
+* URL — the TOTP code (`at=`) is NOT included because it rotates every 30 s
+* and would be stale by the time a human scans. The in-app deep-link builder
+* splices the live code at attach time.
+*
+* SECRET-HANDLING: The TOTP secret and computed code values MUST NOT appear
+* in any output from this module.
 *
 * Node-only: spawns the cloudflared binary and writes to stdout/stderr.
 */
@@ -580,22 +760,68 @@ async function startQuickTunnel(localPort) {
 		}
 	};
 }
-/** Renders the attach banner (URL + token + ASCII QR) as a string. */
+/**
+* Renders a pure unicode half-block QR string for the given text.
+*
+* Uses `qrcode` (Node full lib) to get the raw bit matrix, then encodes every
+* two vertical modules into a single half-block character:
+*   - both dark  → `█`
+*   - top only   → `▀`
+*   - bottom only → `▄`
+*   - both light → ` ` (space)
+*
+* The output contains **zero ANSI escape codes**, so it renders correctly in
+* every surface (terminal, VS Code, JetBrains, web) and can be scanned by a
+* phone camera when shown verbatim in an agent response.
+*
+* Shared by `renderAttachBanner` (relay wssUrl QR) and the `build_attach_url`
+* MCP tool response (attach deep-link QR).
+*/
+async function renderQr(text) {
+	const { default: QRCode } = await import("qrcode");
+	const qr = QRCode.create(text, { errorCorrectionLevel: "M" });
+	const size = qr.modules.size;
+	const data = qr.modules.data;
+	const isDark = (x, y) => {
+		if (x < 0 || y < 0 || x >= size || y >= size) return false;
+		return data[y * size + x] === 1;
+	};
+	const QUIET = 1;
+	const lines = [];
+	for (let y = -QUIET; y < size + QUIET; y += 2) {
+		let line = "";
+		for (let x = -QUIET; x < size + QUIET; x++) {
+			const top = isDark(x, y);
+			const bot = isDark(x, y + 1);
+			line += top && bot ? "█" : top ? "▀" : bot ? "▄" : " ";
+		}
+		lines.push(line);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
+* Renders the attach banner (relay URL + ASCII QR) as a string.
+*
+* The QR encodes the base `wssUrl` only. When `totpEnabled` is true, a note
+* is added that attach URLs generated by `build_attach_url` will include a
+* live TOTP code (`at=`) appended at call time.
+*
+* SECRET-HANDLING: no secret value, TOTP code, or intermediate value is
+* included in this output.
+*/
 async function renderAttachBanner(input) {
-	const payload = `${input.wssUrl}?token=${input.token}`;
-	const qr = await new Promise((resolve) => {
-		qrcode.generate(payload, { small: true }, (rendered) => resolve(rendered));
-	});
+	const qr = await renderQr(input.wssUrl);
+	const authNote = input.totpEnabled ? "  auth:          TOTP enabled — attach URLs include a rotating code (at=)." : "  auth:          none (set AIT_DEBUG_TOTP_SECRET to enable TOTP).";
 	return [
 		"",
 		"AIT debug — attach a mini-app to this session",
 		"",
 		`  relay (wss):   ${input.wssUrl}`,
-		`  attach token:  ${input.token}`,
-		`  (token is a pairing hint — relay-side validation lands in a later phase)`,
+		authNote,
 		"",
-		"  Open the dogfood mini-app with ?debug=1, then scan the QR",
-		"  (or paste the relay URL + token in the in-app attach form):",
+		"  Use build_attach_url to generate a deep link with the current TOTP code.",
+		"  Scan the QR to locate the relay (open the dogfood URL separately with",
+		"  ?debug=1&relay=<wss>&at=<code> or use the build_attach_url tool):",
 		"",
 		qr
 	].join("\n");
@@ -613,12 +839,24 @@ async function printAttachBanner(input) {
 * Lets an AI coding agent attach to a running mini-app (real Toss WebView, or a
 * browser in dev mode) and read its console/network/DOM/screenshot over CDP plus
 * the AIT.* domain, without a human watching a phone. Transport is CDP-via-Chii:
-* a local Chii relay :9100 exposed through a cloudflared quick tunnel; the phone
-* attaches over the public wss URL.
+* a local Chii relay on an OS-assigned port (default 0) exposed through a
+* cloudflared quick tunnel; the phone attaches over the public wss URL.
 *
-*   AI host  --stdio-->  this server  --CDP client WS-->  Chii relay :9100
+*   AI host  --stdio-->  this server  --CDP client WS-->  Chii relay :<OS-port>
 *                                                          ^-- target WS -- phone
 *
+* Port 0 (default): the OS picks a free ephemeral port on every startup.
+* This prevents EADDRINUSE when a stale cloudflared child (orphaned after
+* SIGKILL, PPID 1) still holds a fixed port — which previously caused the MCP
+* handshake to fail with -32000. With port 0 any orphaned cloudflared is
+* harmless; the new relay always gets a fresh port.
+*
+* Best-effort child cleanup: SIGINT/SIGTERM/SIGHUP handlers call shutdown() to
+* stop cloudflared and the relay. uncaughtException/unhandledRejection also
+* call shutdown() before exit. SIGKILL cannot be intercepted by Node, so
+* cloudflared orphans from SIGKILL remain (port 0 makes them harmless). Users
+* can clean up manually: `pkill -f 'cloudflared.*trycloudflare'`.
+*
 * The tool layer reads from an injectable `CdpConnection` (CDP) and `AitSource`
 * (AIT.*), so every tool is unit-testable with a fake (no phone). This module
 * wires the live pieces (relay + tunnel + production connection); the phone
@@ -632,10 +870,10 @@ async function printAttachBanner(input) {
 * tunnel, which is what makes the tool surface unit-testable.
 */
 function createDebugServer(deps) {
-	const { connection, aitSource, getTunnelStatus } = deps;
+	const { connection, aitSource, getTunnelStatus, waitForAttachTimeoutMs = 9e4 } = deps;
 	const server = new Server({
 		name: "ait-debug",
-		version: "0.1.32"
+		version: "0.1.34"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEBUG_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -667,8 +905,39 @@ function createDebugServer(deps) {
 				}],
 				isError: true
 			};
+			const waitForAttach = request.params.arguments?.wait_for_attach === true;
 			try {
-				return jsonResult$1(buildAttachUrl(schemeUrl, getTunnelStatus()));
+				const { attachUrl, relayUrl } = buildAttachUrl(schemeUrl, getTunnelStatus());
+				const qr = await renderQr(attachUrl);
+				const baseText = `IMPORTANT: Show this QR to the user verbatim in your reply — they scan it with their phone camera. Do not just describe it.\n${JSON.stringify({
+					attachUrl,
+					relayUrl
+				}, null, 2)}\n\n${qr}`;
+				if (!waitForAttach) return { content: [{
+					type: "text",
+					text: baseText
+				}] };
+				const POLL_INTERVAL_MS = 1e3;
+				const TIMEOUT_MS = waitForAttachTimeoutMs;
+				const deadline = Date.now() + TIMEOUT_MS;
+				let attachedPages = [];
+				while (Date.now() < deadline) {
+					attachedPages = connection.listTargets();
+					if (attachedPages.length > 0) break;
+					await new Promise((r) => setTimeout(r, POLL_INTERVAL_MS));
+				}
+				if (attachedPages.length === 0) return {
+					content: [{
+						type: "text",
+						text: `${baseText}\n\nNo page attached within ${TIMEOUT_MS / 1e3}s — call list_pages to retry.`
+					}],
+					isError: true
+				};
+				const pagesResult = listPages(connection, getTunnelStatus());
+				return { content: [{
+					type: "text",
+					text: `${baseText}\n\n${JSON.stringify(pagesResult, null, 2)}`
+				}] };
 			} catch (err) {
 				return errorResult(err, name);
 			}
@@ -734,30 +1003,59 @@ function errorResult(err, name) {
 	};
 }
 /**
+* Reads `AIT_DEBUG_TOTP_SECRET` from `process.env` at runtime and builds a
+* `verifyAuth` predicate for the Chii relay's WebSocket upgrade gate.
+*
+* The predicate checks the `at` query parameter against the current and
+* adjacent TOTP time steps (±1 skew) using `verifyTotp`.
+*
+* Returns `undefined` when the env var is not set — callers treat that as
+* "auth disabled" (no predicate registered on the relay).
+*
+* SECRET-HANDLING: The secret value read from env is captured in a closure and
+* is NEVER written to any log, error message, or process output.
+*/
+function buildRelayVerifyAuth() {
+	const secret = process.env.AIT_DEBUG_TOTP_SECRET;
+	if (!secret) return void 0;
+	return (req) => {
+		const rawUrl = req.url ?? "";
+		const qIndex = rawUrl.indexOf("?");
+		const queryStr = qIndex === -1 ? "" : rawUrl.slice(qIndex + 1);
+		return verifyTotp(secret, new URLSearchParams(queryStr).get("at") ?? "");
+	};
+}
+/**
 * Boots the live debug stack and serves it over stdio:
-*   1. start the Chii relay,
-*   2. open a cloudflared quick tunnel to it,
-*   3. print QR + secret token,
+*   1. start the Chii relay on an OS-assigned port (with TOTP auth if
+*      AIT_DEBUG_TOTP_SECRET is set),
+*   2. open a cloudflared quick tunnel to the relay's confirmed port,
+*   3. print relay URL + attach instructions,
 *   4. expose the debug tools backed by a `ChiiCdpConnection` + `ChiiAitSource`.
 */
 async function runDebugServer(options = {}) {
-	const relayPort = options.relayPort ?? 9100;
-	const relay = await startChiiRelay({ port: relayPort });
+	const relayPort = options.relayPort ?? 0;
+	const verifyAuth = buildRelayVerifyAuth();
+	const totpEnabled = verifyAuth !== void 0;
+	const relay = await startChiiRelay({
+		port: relayPort,
+		verifyAuth
+	});
 	let tunnel = null;
 	let tunnelStatus = {
 		up: false,
 		wssUrl: null
 	};
-	const token = generateAttachToken();
+	generateAttachToken();
 	try {
-		tunnel = await startQuickTunnel(relayPort);
+		tunnel = await startQuickTunnel(relay.port);
 		tunnelStatus = {
 			up: true,
 			wssUrl: tunnel.wssUrl
 		};
 		await printAttachBanner({
 			wssUrl: tunnel.wssUrl,
-			token
+			totpEnabled
 		});
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
@@ -771,7 +1069,10 @@ async function runDebugServer(options = {}) {
 		getTunnelStatus: () => tunnelStatus
 	});
 	const transport = new StdioServerTransport();
+	let closed = false;
 	const shutdown = () => {
+		if (closed) return;
+		closed = true;
 		connection.close();
 		tunnel?.stop();
 		relay.close();
@@ -779,6 +1080,23 @@ async function runDebugServer(options = {}) {
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
+	process.once("SIGHUP", shutdown);
+	process.on("exit", () => {
+		if (!closed) {
+			closed = true;
+			tunnel?.stop();
+		}
+	});
+	process.on("uncaughtException", (err) => {
+		process.stderr.write(`[ait-debug] uncaughtException: ${String(err)}\n`);
+		shutdown();
+		process.exit(1);
+	});
+	process.on("unhandledRejection", (reason) => {
+		process.stderr.write(`[ait-debug] unhandledRejection: ${String(reason)}\n`);
+		shutdown();
+		process.exit(1);
+	});
 	await server.connect(transport);
 }
 //#endregion
@@ -809,7 +1127,10 @@ var HttpAitSource = class {
 					sdkVersion: typeof state.appVersion === "string" ? state.appVersion : null
 				};
 			}
-			case "AIT.getSdkCallHistory": return { calls: [] };
+			case "AIT.getSdkCallHistory": {
+				const raw = (await this.fetchState()).sdkCallLog;
+				return { calls: Array.isArray(raw) ? raw : [] };
+			}
 			default: throw new Error(`Unknown AIT method: ${String(method)}`);
 		}
 	}
@@ -897,7 +1218,7 @@ function createDevServer(deps = {}) {
 	const aitSource = deps.aitSource ?? new HttpAitSource({ stateEndpoint });
 	const server = new Server({
 		name: "ait-devtools",
-		version: "0.1.32"
+		version: "0.1.34"
 	}, { capabilities: { tools: {} } });
 	server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: DEV_TOOL_DEFINITIONS.map((tool) => ({ ...tool })) }));
 	server.setRequestHandler(CallToolRequestSchema, async (request) => {