querysub 0.452.0 → 0.454.0

package/.claude/settings.local.json

@@ -16,7 +16,14 @@
       "Bash(sleep:*)",
       "Bash(date:*)",
       "Bash(ls:*)",
-      "Bash(git:*)"
+      "Bash(git:*)",
+      "mcp__node-debugger__listScripts",
+      "mcp__node-debugger__setBreakpoint",
+      "mcp__node-debugger__waitForPause",
+      "mcp__node-debugger__resume",
+      "mcp__node-debugger__listBreakpoints",
+      "mcp__node-debugger__removeBreakpoint",
+      "mcp__hottest__runTest"
     ]
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "querysub",
-  "version": "0.452.0",
+  "version": "0.454.0",
   "main": "index.js",
   "license": "MIT",
   "note1": "note on node-forge fork, see https://github.com/digitalbazaar/forge/issues/744 for details",

package/src/-a-archives/archivesBackBlaze.ts

@@ -509,7 +509,10 @@ export class ArchivesBackblaze {
     private last503Reset = 0;
     // IMPORTANT! We must always CATCH AROUND the apiRetryLogic, NEVER inside of fnc. Otherwise we won't
     //  be able to recreate the auth token.
+    //  `context` is a short label (verb + file path) included in every retry/error log so a stuck
+    //   silent-retry loop is identifiable from the logs.
     private async apiRetryLogic<T>(
+        context: string,
         fnc: (api: B2Api) => Promise<T>,
         retries = 3
     ): Promise<T> {
@@ -519,33 +522,33 @@ export class ArchivesBackblaze {
         } catch (err: any) {
             if (retries <= 0) throw err;
 
-            // If it's a 503 and it's been a minute since we last reset, then Wait and reset. 
+            // If it's a 503 and it's been a minute since we last reset, then Wait and reset.
             if (
                 (err.stack.includes(`"status": 503`)
                     || err.stack.includes(`"service_unavailable"`)
                     || err.stack.includes(`"internal_error"`)
                     || err.stack.includes(`ENOBUFS`)
                 ) && Date.now() - this.last503Reset > 60 * 1000) {
-                console.error("503 error, waiting a minute and resetting: " + err.message);
-                this.log("503 error, waiting a minute and resetting: " + err.message);
+                console.error(`[${context}] 503 error, waiting and resetting: ${err.message}`);
+                this.log(`[${context}] 503 error, waiting and resetting: ${err.message}`);
                 await delay(10 * 1000);
-                // We check again in case, and in the very likely case that this is being run in parallel, we only want to reset once. 
+                // We check again in case, and in the very likely case that this is being run in parallel, we only want to reset once.
                 if (Date.now() - this.last503Reset > 60 * 1000) {
-                    this.log("Resetting getAPI and getBucketAPI: " + err.message);
+                    this.log(`[${context}] Resetting getAPI and getBucketAPI: ${err.message}`);
                     this.last503Reset = Date.now();
                     getAPI.reset();
                     this.getBucketAPI.reset();
                 }
-                return this.apiRetryLogic(fnc, retries - 1);
+                return this.apiRetryLogic(context, fnc, retries - 1);
             }
 
             // If the error is that the authorization token is invalid, reset getBucketAPI and getAPI
             // If the error is that the bucket isn't found, reset getBucketAPI
             if (err.stack.includes(`"expired_auth_token"`)) {
-                this.log("Authorization token expired");
+                this.log(`[${context}] Authorization token expired`);
                 getAPI.reset();
                 this.getBucketAPI.reset();
-                return this.apiRetryLogic(fnc, retries - 1);
+                return this.apiRetryLogic(context, fnc, retries - 1);
             }
 
             if (
@@ -560,10 +563,10 @@ export class ArchivesBackblaze {
                 || err.stack.includes(`ECONNREFUSED`)
                 || err.stack.includes(`ENOBUFS`)
             ) {
-                console.error("Retrying in 5s: " + err.message);
-                this.log(err.message + " retrying in 5s");
+                console.error(`[${context}] Retrying in 5s: ${err.message}`);
+                this.log(`[${context}] ${err.message} retrying in 5s`);
                 await delay(5000);
-                return this.apiRetryLogic(fnc, retries - 1);
+                return this.apiRetryLogic(context, fnc, retries - 1);
             }
 
             if (err.stack.includes(`getaddrinfo ENOTFOUND`)) {
@@ -579,10 +582,11 @@ export class ArchivesBackblaze {
                         resolve(addresses);
                     });
                 });
-                console.error(`getaddrinfo ENOTFOUND ${hostname}`, { lookupAddresses, resolveAddresses, apiUrl: api.apiUrl, fullError: err.stack });
+                console.error(`[${context}] getaddrinfo ENOTFOUND ${hostname}`, { lookupAddresses, resolveAddresses, apiUrl: api.apiUrl, fullError: err.stack });
             }
 
             // TODO: Handle if the bucket is deleted?
+            console.error(`[${context}] giving up after ${3 - retries + 1} attempts: ${err.stack ?? err}`);
             throw err;
         }
     }
@@ -597,7 +601,7 @@ export class ArchivesBackblaze {
                 setTimeout(downloadPoll, 5000);
             };
             setTimeout(downloadPoll, 5000);
-            let result = await this.apiRetryLogic(async (api) => {
+            let result = await this.apiRetryLogic(`get ${fileName}`, async (api) => {
                 let range = config?.range;
                 if (range) {
                     let fileInfo = await this.getInfo(fileName);
@@ -649,7 +653,7 @@ export class ArchivesBackblaze {
     public async set(fileName: string, data: Buffer): Promise<void> {
         this.log(`backblaze upload (${formatNumber(data.length)}B) ${fileName}`);
         let f = fileName;
-        await this.apiRetryLogic(async (api) => {
+        await this.apiRetryLogic(`uploadFile ${fileName}`, async (api) => {
             await api.uploadFile({ bucketId: this.bucketId, fileName, data: data, });
         });
         let existsChecks = 30;
@@ -677,7 +681,7 @@ export class ArchivesBackblaze {
     public async del(fileName: string): Promise<void> {
         this.log(`backblaze delete ${fileName}`);
         try {
-            await this.apiRetryLogic(async (api) => {
+            await this.apiRetryLogic(`hideFile ${fileName}`, async (api) => {
                 await api.hideFile({ bucketId: this.bucketId, fileName: fileName });
             });
         } catch (e: any) {
@@ -746,7 +750,7 @@ export class ArchivesBackblaze {
             dataQueue.unshift(data, secondData);
 
 
-            let uploadInfo = await this.apiRetryLogic(async (api) => {
+            let uploadInfo = await this.apiRetryLogic(`startLargeFile ${fileName}`, async (api) => {
                 return await api.startLargeFile({
                     bucketId: this.bucketId,
                     fileName: fileName,
@@ -755,7 +759,7 @@ export class ArchivesBackblaze {
                 });
             });
             onError.push(async () => {
-                await this.apiRetryLogic(async (api) => {
+                await this.apiRetryLogic(`cancelLargeFile ${fileName}`, async (api) => {
                     await api.cancelLargeFile({ fileId: uploadInfo.fileId });
                 });
             });
@@ -792,7 +796,7 @@ export class ArchivesBackblaze {
                 sha1.update(data);
                 let sha1Hex = sha1.digest("hex");
                 partSha1Array.push(sha1Hex);
-                await this.apiRetryLogic(async (api) => {
+                await this.apiRetryLogic(`uploadPart#${partNumber} ${fileName}`, async (api) => {
                     if (!data) throw new Error("Impossible, data is undefined");
 
                     let timeStr = formatTime(Date.now() - time);
@@ -818,7 +822,7 @@ export class ArchivesBackblaze {
             }
             this.log(`Finished uploading large file uploaded ${green(formatNumber(totalBytes))}B`);
 
-            await this.apiRetryLogic(async (api) => {
+            await this.apiRetryLogic(`finishLargeFile ${fileName}`, async (api) => {
                 await api.finishLargeFile({
                     fileId: uploadInfo.fileId,
                     partSha1Array: partSha1Array,
@@ -838,7 +842,7 @@ export class ArchivesBackblaze {
     }
 
     public async getInfo(fileName: string): Promise<{ writeTime: number; size: number; } | undefined> {
-        return await this.apiRetryLogic(async (api) => {
+        return await this.apiRetryLogic(`getInfo ${fileName}`, async (api) => {
             try {
                 // NOTE: Apparently, there's no other way to do this, as the file name does not equal the file ID, and git file info requires the file ID. 
                 let info = await api.listFileNames({ bucketId: this.bucketId, prefix: fileName, maxFileCount: 10 });
@@ -868,7 +872,7 @@ export class ArchivesBackblaze {
         return result.map(x => x.path);
     }
     public async findInfo(prefix: string, config?: { shallow?: boolean; type: "files" | "folders" }): Promise<{ path: string; createTime: number; size: number; }[]> {
-        return await this.apiRetryLogic(async (api) => {
+        return await this.apiRetryLogic(`findInfo ${prefix}`, async (api) => {
             if (!config?.shallow && config?.type === "folders") {
                 let allFiles = await this.findInfo(prefix);
                 let allFolders = new Map<string, { path: string; createTime: number; size: number }>();
@@ -935,7 +939,7 @@ export class ArchivesBackblaze {
         if (target instanceof ArchivesBackblaze) {
             let targetBucketId = target.bucketId;
             if (targetBucketId === this.bucketId && path === targetPath) return;
-            await this.apiRetryLogic(async (api) => {
+            await this.apiRetryLogic(`move ${path} -> ${targetPath}`, async (api) => {
                 // Ugh... listing the file name sucks, but... I guess it's still better than
                 //  downloading and re-uploading the entire file.
                 let info = await api.listFileNames({ bucketId: this.bucketId, prefix: path, maxFileCount: 10 });
@@ -974,7 +978,7 @@ export class ArchivesBackblaze {
     }
 
     public async getURL(path: string) {
-        return await this.apiRetryLogic(async (api) => {
+        return await this.apiRetryLogic(`getURL ${path}`, async (api) => {
             if (path.startsWith("/")) {
                 path = path.slice(1);
             }
@@ -996,7 +1000,7 @@ export class ArchivesBackblaze {
         fileNamePrefix: string;
         authorizationToken: string;
     }> {
-        return await this.apiRetryLogic(async (api) => {
+        return await this.apiRetryLogic(`getDownloadAuthorization ${config.fileNamePrefix ?? ""}`, async (api) => {
             return await api.getDownloadAuthorization({
                 bucketId: this.bucketId,
                 fileNamePrefix: config.fileNamePrefix ?? "",

package/src/0-path-value-core/pathValueArchives.ts

@@ -208,11 +208,12 @@ export class PathValueArchives {
             let fullPath = pathIdentifier + "/" + file;
             console.log(`Write archive file ${fullPath}, with size ${formatNumber(data.byteLength)}B, and count ${formatNumber(values.length)}`);
             try {
+
                 await retryFunctional(() => archives().set(fullPath, data), {
                     maxRetries: 10,
                     minDelay: 1000,
                     maxDelay: 5000,
-                });
+                })();
             } catch (e) {
                 console.error(`Error writing archive file ${fullPath}. THIS IS BAD! WE ARE SHUTTING DOWN SO THIS ERROR IS LOUDER! WHAT'S THE POINT OF A DB THAT DOESN'T SAVE DATA!: ${(e as Error).stack ?? e}`);
                 await delay(5000);
@@ -420,10 +421,10 @@ export class PathValueArchives {
                 skipValues: config.skipValues,
             });
             if (dataValues.length !== decodedObj.valueCount) {
-                console.error(`Bad archive data file at ${config.path}, Decoded count ${formatNumber(decodedObj.valueCount)} !== count in file name ${formatNumber(dataValues.length)} (${decodedObj.valueCount} !== ${dataValues.length})`);
+                console.warn(`Bad archive data file at ${config.path}, Decoded count ${formatNumber(decodedObj.valueCount)} !== count in file name ${formatNumber(dataValues.length)} (${decodedObj.valueCount} !== ${dataValues.length})`);
             }
         } catch (e: any) {
-            console.log(red(`Bad archive data file at ${config.path}, error: ${e.stack}`));
+            console.warn(`Bad archive data file at ${config.path}, error: ${e.stack}`);
         }
         let rawCount = dataValues.length;
 

package/src/4-querysub/Querysub.ts

@@ -44,7 +44,7 @@ import { waitForFirstTimeSync } from "socket-function/time/trueTimeShim";
 import { logMeasureTable, measureBlock, measureFnc, measureWrap, startMeasure } from "socket-function/src/profiling/measure";
 import { delay } from "socket-function/src/batching";
 import { MaybePromise } from "socket-function/src/types";
-import { devDebugbreak, getDomain, isBootstrapOnly, isDynamicallyLoading, isPublic, noSyncing } from "../config";
+import { devDebugbreak, getDomain, isBootstrapOnly, isDynamicallyLoading, isPublic, isRecovery, noSyncing } from "../config";
 import { Schema2, Schema2T, t } from "../2-proxy/schema2";
 import { CALL_PERMISSIONS_KEY } from "./permissionsShared";
 import yargs, { check } from "yargs";
@@ -1035,19 +1035,21 @@ export class Querysub {
             return module;
         }
 
-        RequireController.addMapGetModules(async (result, args) => {
-            let configObj = args[2] as { signedIdentity: SignedIdentity | undefined } | undefined;
-            if (!await isAllowedToSeeSource(configObj?.signedIdentity)) {
-                await isAllowedToSeeSource(configObj?.signedIdentity);
-                //console.log(red(`Not allowed to see source`));
-                for (let [key, value] of Object.entries(result.modules)) {
-                    result.modules[key] = stripSource(value);
+        if (!isRecovery()) {
+            RequireController.addMapGetModules(async (result, args) => {
+                let configObj = args[2] as { signedIdentity: SignedIdentity | undefined } | undefined;
+                if (!await isAllowedToSeeSource(configObj?.signedIdentity)) {
+                    await isAllowedToSeeSource(configObj?.signedIdentity);
+                    //console.log(red(`Not allowed to see source`));
+                    for (let [key, value] of Object.entries(result.modules)) {
+                        result.modules[key] = stripSource(value);
+                    }
+                } else {
+                    //console.log(green(`Allowed to see source`));
                 }
-            } else {
-                //console.log(green(`Allowed to see source`));
-            }
-            return result;
-        });
+                return result;
+            });
+        }
     }
 
     public static async hostService(name: string, port = 0) {

package/src/deployManager/LaunchTrackingHeader.tsx

@@ -5,7 +5,7 @@ import { css } from "typesafecss";
 import { getBrowserUrlNode } from "../-f-node-discovery/NodeDiscovery";
 import { MachineServiceController } from "./machineSchema";
 
-const SINCE_DAYS = 7;
+const SINCE_DAYS = 2;
 const CRASH_HUE = 0;
 const OTHER_HUE = 210;
 
@@ -31,23 +31,19 @@ export class LaunchTrackingHeader extends qreact.Component {
             else entry.other++;
         }
 
-        let top: { serviceKey: string; crashes: number; other: number } | undefined;
+        let ranked: { serviceKey: string; crashes: number; other: number }[] = [];
         for (let [serviceKey, c] of perKey) {
-            let candidate = { serviceKey, crashes: c.crashes, other: c.other };
-            if (!top) {
-                top = candidate;
-                continue;
-            }
-            if (candidate.crashes > top.crashes) {
-                top = candidate;
-            } else if (candidate.crashes === top.crashes && (candidate.crashes + candidate.other) > (top.crashes + top.other)) {
-                top = candidate;
-            }
+            ranked.push({ serviceKey, crashes: c.crashes, other: c.other });
         }
+        ranked.sort((a, b) => {
+            if (b.crashes !== a.crashes) return b.crashes - a.crashes;
+            return (b.crashes + b.other) - (a.crashes + a.other);
+        });
+        let top = ranked[0];
 
         let title = `Launches in last ${SINCE_DAYS} days: ${totalCrashes} crashed, ${totalOther} other`;
-        if (top && top.crashes > 0) {
-            title += ` -- top by crashes: ${top.serviceKey} (${top.crashes} crashed, ${top.other} other)`;
+        for (let r of ranked) {
+            title += `\n${r.serviceKey}: ${r.crashes} crashed, ${r.other} other`;
         }
 
         return <div title={title} className={css.hbox(6).colorhsl(0, 0, 20)}>

package/src/deployManager/machineApplyMainCode.ts

@@ -870,6 +870,92 @@ async function getPPID(pid: string) {
     }
 }
 
+// Node prints this when the process has exited but the V8 inspector is still
+//  holding it open waiting for a debugger client to detach. If a debugger client
+//  drops uncleanly the process can sit on this forever, holding the screen and
+//  preventing the supervisor from spawning a fresh instance. The watcher below
+//  polls each screen's pipe.txt for this phrase and sends Ctrl+C to break it out.
+const DEBUGGER_DISCONNECT_MESSAGE = "Waiting for the debugger to disconnect...";
+
+// To avoid false positives from app code that happens to log a string
+//  containing the phrase, the wedge is only reported when:
+//    1. the phrase is on its own line (start-of-string or after a newline), AND
+//    2. nothing else has been logged after it (only trailing whitespace/EOF).
+//  In a real wedge, this line is the very last thing Node writes before going
+//  silent — so any later output rules out the wedge interpretation.
+const DEBUGGER_DISCONNECT_TAIL_PATTERN = /(?:^|\r?\n)Waiting for the debugger to disconnect\.\.\.\s*$/;
+
+// How often the wedge watcher scans every service's pipe.txt.
+const DEBUGGER_WEDGE_POLL_INTERVAL = timeInSecond * 15;
+// How much of the tail of pipe.txt to read on each scan. The phrase is short
+//  and appears near the very end of the log when a process is stuck, so a few
+//  KB is plenty and keeps scans cheap.
+const DEBUGGER_WEDGE_TAIL_BYTES = 8 * 1024;
+// Suppress repeated Ctrl+C bursts to the same screen while it tears down; if
+//  the first signal didn't break the wait, give it this long before we try again.
+const DEBUGGER_WEDGE_RESIGNAL_DELAY = timeInMinute;
+// After a first match, wait this long and re-check before signaling. If the
+//  process is still alive and just happened to log a message ending in the
+//  phrase, more output will appear in the meantime and the second check fails.
+const DEBUGGER_WEDGE_RECHECK_DELAY = timeInSecond * 3;
+
+// screenName -> last time we sent Ctrl+C because of a debugger wedge.
+const lastDebuggerWedgeSignal = new Map<string, number>();
+
+async function readPipeFileTail(pipeFile: string, maxBytes: number): Promise<string> {
+    let handle: fs.promises.FileHandle | undefined;
+    try {
+        handle = await fs.promises.open(pipeFile, "r");
+        let stat = await handle.stat();
+        let start = Math.max(0, stat.size - maxBytes);
+        let length = stat.size - start;
+        if (length <= 0) return "";
+        let buf = Buffer.alloc(length);
+        await handle.read(buf, 0, length, start);
+        return buf.toString("utf8");
+    } catch {
+        // File doesn't exist yet, or got truncated mid-read — treat as empty.
+        return "";
+    } finally {
+        if (handle) {
+            try {
+                await handle.close();
+            } catch {
+                // ignore
+            }
+        }
+    }
+}
+
+async function unwedgeStuckDebuggerScreens(): Promise<void> {
+    let prefix = getTmuxPrefix();
+    let screens = await getScreenState(false);
+    for (let { screenName } of screens) {
+        let pipeFile = os.homedir() + "/" + SERVICE_FOLDER + screenName + "/pipe.txt";
+        let tail1 = await readPipeFileTail(pipeFile, DEBUGGER_WEDGE_TAIL_BYTES);
+        if (!DEBUGGER_DISCONNECT_TAIL_PATTERN.test(tail1)) continue;
+
+        // Confirm the process is actually wedged and not just briefly idle by
+        //  re-checking after a short delay. A live process will write more
+        //  output in this window, which moves the phrase away from the end
+        //  and fails the second match.
+        await delay(DEBUGGER_WEDGE_RECHECK_DELAY);
+        let tail2 = await readPipeFileTail(pipeFile, DEBUGGER_WEDGE_TAIL_BYTES);
+        if (!DEBUGGER_DISCONNECT_TAIL_PATTERN.test(tail2)) continue;
+
+        let last = lastDebuggerWedgeSignal.get(screenName) ?? 0;
+        if (Date.now() - last < DEBUGGER_WEDGE_RESIGNAL_DELAY) continue;
+        lastDebuggerWedgeSignal.set(screenName, Date.now());
+
+        console.warn(red(`Detected stuck "${DEBUGGER_DISCONNECT_MESSAGE}" in ${screenName} (confirmed across two checks ${DEBUGGER_WEDGE_RECHECK_DELAY}ms apart); sending Ctrl+C to unblock it.`));
+        try {
+            await runPromise(`${prefix}tmux send-keys -t ${screenName} 'C-c' Enter`);
+        } catch (e: any) {
+            console.warn(`Failed to send Ctrl+C to ${screenName}: ${e.stack ?? e}`);
+        }
+    }
+}
+
 export async function machineApplyMain() {
     let parentPID = process.argv[2];
     // Wait for the console to get shimmed
@@ -898,6 +984,14 @@ export async function machineApplyMain() {
     await Querysub.hostService("machine-apply");
     onServiceConfigChange(resyncServices);
 
+    runInfinitePoll(DEBUGGER_WEDGE_POLL_INTERVAL, async () => {
+        try {
+            await unwedgeStuckDebuggerScreens();
+        } catch (e: any) {
+            console.error(`Error in debugger-wedge watcher: ${e.stack ?? e}`);
+        }
+    });
+
     runInfinitePoll(timeInMinute * 3, async () => {
         //console.log(magenta(`Quick outdated check at ${new Date().toISOString()}`));
         // console.log(magenta("Likely outdated, resyncing now"));

package/src/diagnostics/debugger/mcp-server.ts

@@ -3,8 +3,9 @@
  *
  * Exposes the V8 inspector / Chrome DevTools Protocol as MCP tools:
  *
- *   attach       - connect to a debug target, keep the connection open, and
- *                  return a short sessionId used by every other tool.
+ *   attachNode   - connect to a Querysub cluster node by nodeId (deciding
+ *                  local vs remote via getExternalIP), keep the connection
+ *                  open, and return a short sessionId used by every other tool.
  *   detach       - close a session.
  *   listScripts  - list scripts loaded in the target.
  *   getSource    - get a script's source (optionally a line range).
@@ -23,7 +24,6 @@
 module.hotreload = false;
 
 import * as http from "http";
-import * as path from "path";
 import * as dns from "dns";
 
 // Allow callers to point this process at a different project root (so we use
@@ -49,7 +49,6 @@ import { getExternalIP } from "../../misc/networking";
 import { getNodeIdDomain } from "socket-function/src/nodeCache";
 
 const DEFAULT_MCP_PORT = 3001;
-const DEFAULT_PORT_FILE = path.join(process.cwd(), "debugger-port.json");
 const PROTOCOL_VERSION = "2025-06-18";
 // Per-node budget for the getEntryPoint / getInspectURL probes in listNodes;
 // a node that doesn't answer in time is reported with those fields undefined.
@@ -78,10 +77,38 @@ interface ScriptParsed {
     url: string;
 }
 
+interface PausedState {
+    /** Reason CDP reported for the pause (e.g. "other" for breakpoint, "step"). */
+    reason: string;
+    /** CDP breakpointIds that fired this pause, if any. */
+    hitBreakpoints: string[];
+    /** CDP call frames, top-most first. */
+    callFrames: any[];
+}
+
+interface BreakpointEntry {
+    /** CDP breakpointId (also used as the user-facing handle). */
+    breakpointId: string;
+    /** URL the breakpoint was placed on. */
+    url: string;
+    /** Requested line number, 1-based. */
+    requestedLine: number;
+    /** Actual resolved line number, 1-based; undefined if it didn't bind. */
+    actualLine?: number;
+    /** Optional condition expression that gates the pause. */
+    condition?: string;
+}
+
 interface Session {
     id: string;
     remote: DebuggerRemote;
     scripts: ScriptParsed[];
+    /** Active pausing breakpoints, keyed by CDP breakpointId. */
+    breakpoints: Map<string, BreakpointEntry>;
+    /** Set while the target is paused; cleared on resume. */
+    paused?: PausedState;
+    /** Resolvers waiting for the next pause event. */
+    pauseWaiters: Array<() => void>;
 }
 
 const sessions = new Map<string, Session>();
@@ -129,17 +156,60 @@ function resolveScript(session: Session, query: string): ScriptParsed {
  * other tools can find it by sessionId.
  */
 async function openSession(remote: DebuggerRemote): Promise<Session> {
-    const session: Session = { id: newSessionId(), remote, scripts: [] };
+    const session: Session = {
+        id: newSessionId(),
+        remote,
+        scripts: [],
+        breakpoints: new Map(),
+        pauseWaiters: [],
+    };
     // Register before enabling so we capture the initial script dump.
     remote.on("Debugger.scriptParsed", (p: ScriptParsed) =>
         session.scripts.push({ scriptId: p.scriptId, url: p.url }),
     );
+    // Track pause/resume so other tools (evaluate, waitForPause) can see
+    // whether the target is currently stopped at a breakpoint.
+    remote.on("Debugger.paused", (p: any) => {
+        session.paused = {
+            reason: p.reason ?? "other",
+            hitBreakpoints: p.hitBreakpoints ?? [],
+            callFrames: p.callFrames ?? [],
+        };
+        const waiters = session.pauseWaiters.splice(0);
+        for (const w of waiters) w();
+    });
+    remote.on("Debugger.resumed", () => {
+        session.paused = undefined;
+    });
     await remote.send("Runtime.enable");
     await remote.send("Debugger.enable");
     sessions.set(session.id, session);
     return session;
 }
 
+/** Short summary of a paused state, suitable for tool output. */
+function describePaused(session: Session): string {
+    if (!session.paused) return "(not paused)";
+    const { reason, hitBreakpoints, callFrames } = session.paused;
+    const hit = hitBreakpoints.length
+        ? ` (hit ${hitBreakpoints.join(", ")})`
+        : "";
+    const stack = callFrames
+        .slice(0, 8)
+        .map((f: any, i: number) => {
+            const url = f.url || "?";
+            const line = (f.location?.lineNumber ?? 0) + 1;
+            const col = (f.location?.columnNumber ?? 0) + 1;
+            return `  #${i} ${f.functionName || "<anon>"} at ${url}:${line}:${col}`;
+        })
+        .join("\n");
+    return (
+        `Paused (reason=${reason})${hit}\n` +
+        `Top call frame id: ${callFrames[0]?.callFrameId ?? "(none)"}\n` +
+        `Call stack:\n${stack || "  (empty)"}`
+    );
+}
+
 /** Human-readable "Attached. sessionId=… + user scripts" summary for a session. */
 function describeSession(session: Session): string {
     const userScripts = session.scripts.filter((s) => isUserScript(s.url));
@@ -168,17 +238,13 @@ async function getNodeInfos(): Promise<NodeInfo[]> {
     const nodes = await getAllNodeIds();
     return Promise.all(
         nodes.map(async (nodeId): Promise<NodeInfo> => {
-            const [metadata, inspectUrl] = await Promise.all([
+            const [metadata] = await Promise.all([
                 timeoutToUndefinedSilent(
                     NODE_INFO_TIMEOUT_MS,
                     NodeCapabilitiesController.nodes[nodeId].getMetadata(),
-                ),
-                timeoutToUndefinedSilent(
-                    NODE_INFO_TIMEOUT_MS,
-                    NodeCapabilitiesController.nodes[nodeId].getInspectURL(),
-                ),
+                )
             ]);
-            return { nodeId, entryPoint: metadata?.entryPoint, inspectUrl };
+            return { nodeId, entryPoint: metadata?.entryPoint };
         }),
     );
 }
@@ -267,9 +333,8 @@ const tools: Record<string, ToolDef> = {
         description:
             "List every node in the Querysub cluster, with each node's process " +
             "entry point and V8 inspector (devtools) URL. Returns an array of " +
-            "{ nodeId, entryPoint, inspectUrl }. A node that does not answer in " +
-            "time has entryPoint / inspectUrl left undefined. Use a node's " +
-            "inspectUrl to point the `attach` tool at it for debugging.",
+            "{ nodeId, entryPoint }. A node that does not answer in " +
+            "time has entryPoint left undefined",
         inputSchema: {
             type: "object",
             properties: {},
@@ -286,8 +351,7 @@ const tools: Record<string, ToolDef> = {
             "and return a sessionId usable by every other tool. Works out " +
             "whether the node is on this machine or remote — a local node is " +
             "debugged directly; a remote node is reached by asking it to open a " +
-            "one-time external debug port locked to this machine's IP. Prefer " +
-            "this over `attach` when working with cluster nodes.",
+            "one-time external debug port locked to this machine's IP.",
         inputSchema: {
             type: "object",
             properties: {
@@ -308,39 +372,6 @@ const tools: Record<string, ToolDef> = {
         },
     },
 
-    attach: {
-        description:
-            "Attach to a running Node.js process over its V8 inspector (debugger) " +
-            "port. Keeps the connection open and returns a short sessionId for use " +
-            "by every other tool. Provide one of portFile / port / wsUrl; defaults " +
-            "to the ./debugger-port.json written by test.ts. Retries for ~10s if " +
-            "the target is not listening yet.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                portFile: {
-                    type: "string",
-                    description: "Path to a debugger-port.json file. Default: ./debugger-port.json",
-                },
-                port: { type: "number", description: "Inspector HTTP port (alternative to portFile)." },
-                wsUrl: { type: "string", description: "Direct CDP WebSocket URL (alternative to portFile/port)." },
-            },
-        },
-        handler: async (args) => {
-            let remote: DebuggerRemote;
-            if (typeof args.wsUrl === "string") {
-                remote = new DebuggerRemote({ wsUrl: args.wsUrl });
-            } else if (typeof args.port === "number") {
-                remote = new DebuggerRemote({ port: args.port });
-            } else {
-                remote = new DebuggerRemote({ portFile: args.portFile ?? DEFAULT_PORT_FILE });
-            }
-            const session = await openSession(remote);
-            log(`attached session ${session.id} (${session.scripts.length} scripts)`);
-            return describeSession(session);
-        },
-    },
-
     detach: {
         description: "Close a debugger session and disconnect from the target.",
         inputSchema: {
@@ -424,8 +455,10 @@ const tools: Record<string, ToolDef> = {
     evaluate: {
         description:
             "Evaluate a JavaScript expression inside the target process and return " +
-            "the result. Runs in the global context and awaits promises. Tip: " +
-            "`process.exit(0)` cleanly terminates the target.",
+            "the result. When the target is paused at a breakpoint, the expression " +
+            "runs in the top call frame's scope so locals and parameters are visible; " +
+            "otherwise it runs in the global context. Awaits promises. Tip: " +
+            "`process.exit(0)` cleanly terminates the target (when not paused).",
         inputSchema: {
             type: "object",
             properties: {
@@ -439,6 +472,21 @@ const tools: Record<string, ToolDef> = {
             if (typeof args.expression !== "string") {
                 throw new Error("expression must be a string");
             }
+            if (session.paused?.callFrames?.length) {
+                const topFrame = session.paused.callFrames[0];
+                const res = await session.remote.send("Debugger.evaluateOnCallFrame", {
+                    callFrameId: topFrame.callFrameId,
+                    expression: args.expression,
+                    returnByValue: true,
+                });
+                if (res.exceptionDetails) {
+                    throw new Error(`Remote threw: ${JSON.stringify(res.exceptionDetails)}`);
+                }
+                const value = res.result?.value;
+                return value === undefined
+                    ? "undefined (or non-serializable result)"
+                    : JSON.stringify(value, null, 2);
+            }
             const value = await session.remote.evaluate(args.expression);
             return value === undefined
                 ? "undefined (or non-serializable result)"
@@ -578,6 +626,232 @@ const tools: Record<string, ToolDef> = {
             return `${header}\n${body}`;
         },
     },
+
+    setBreakpoint: {
+        description:
+            "Install a real breakpoint that PAUSES the target when hit. Unlike " +
+            "logpoint, this stops execution so you can inspect state (via evaluate, " +
+            "which uses the paused call frame's scope) and add more breakpoints " +
+            "before resuming. Returns a breakpointId. Use waitForPause to block " +
+            "until the breakpoint actually fires. IMPORTANT: while paused, the " +
+            "target's entire event loop is stopped (no heartbeats, no I/O) — " +
+            "external watchdogs may kill long-paused processes, so resume promptly.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                script: { type: "string", description: "scriptId or URL substring." },
+                lineNumber: {
+                    type: "number",
+                    description: "1-based line to set the breakpoint on (matches getSource output).",
+                },
+                condition: {
+                    type: "string",
+                    description:
+                        "Optional JS boolean expression. The target only pauses when it is truthy.",
+                },
+            },
+            required: ["sessionId", "script", "lineNumber"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            const script = resolveScript(session, String(args.script));
+            const lineNumber = Math.floor(args.lineNumber);
+            if (!(lineNumber >= 1)) {
+                throw new Error("lineNumber must be a positive integer (1-based).");
+            }
+            if (args.condition !== undefined && typeof args.condition !== "string") {
+                throw new Error("condition must be a string if provided.");
+            }
+
+            const params: any = {
+                url: script.url,
+                lineNumber: lineNumber - 1,
+            };
+            if (typeof args.condition === "string" && args.condition.trim()) {
+                params.condition = args.condition;
+            }
+
+            const res = await session.remote.send("Debugger.setBreakpointByUrl", params);
+            const breakpointId: string = res.breakpointId;
+            const locations: any[] = res.locations ?? [];
+            const bound = locations.length > 0;
+            const actualLine = bound ? locations[0].lineNumber + 1 : undefined;
+
+            session.breakpoints.set(breakpointId, {
+                breakpointId,
+                url: script.url,
+                requestedLine: lineNumber,
+                actualLine,
+                condition: params.condition,
+            });
+
+            if (!bound) {
+                return (
+                    `Breakpoint set but did NOT bind: line ${lineNumber} of ${script.url} ` +
+                    `has no executable code right now. It will bind later if the source is ` +
+                    `(re)loaded. breakpointId=${breakpointId}`
+                );
+            }
+            return (
+                `Breakpoint set. breakpointId=${breakpointId}\n` +
+                `Location: ${script.url}:${actualLine}` +
+                (actualLine !== lineNumber ? ` (requested ${lineNumber})` : "") +
+                (params.condition ? `\nCondition: ${params.condition}` : "")
+            );
+        },
+    },
+
+    removeBreakpoint: {
+        description: "Remove a pausing breakpoint by its breakpointId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                breakpointId: { type: "string" },
+            },
+            required: ["sessionId", "breakpointId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (typeof args.breakpointId !== "string" || !args.breakpointId) {
+                throw new Error("breakpointId must be a non-empty string.");
+            }
+            await session.remote.send("Debugger.removeBreakpoint", {
+                breakpointId: args.breakpointId,
+            });
+            const existed = session.breakpoints.delete(args.breakpointId);
+            return existed
+                ? `Removed breakpoint ${args.breakpointId}.`
+                : `Removed breakpoint ${args.breakpointId} (was not in this session's table).`;
+        },
+    },
+
+    listBreakpoints: {
+        description: "List the pausing breakpoints currently set on this session.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (session.breakpoints.size === 0) return "(no breakpoints set)";
+            const lines: string[] = [];
+            for (const bp of session.breakpoints.values()) {
+                const loc = bp.actualLine !== undefined
+                    ? `${bp.url}:${bp.actualLine}`
+                    : `${bp.url}:${bp.requestedLine} (NOT BOUND)`;
+                const cond = bp.condition ? `  condition=${bp.condition}` : "";
+                lines.push(`${bp.breakpointId}  ${loc}${cond}`);
+            }
+            return lines.join("\n");
+        },
+    },
+
+    waitForPause: {
+        description:
+            "Block until the target is paused at a breakpoint (or already is), and " +
+            "return a summary of the paused state including call stack and the top " +
+            "callFrameId. If the timeout elapses before a pause, returns a not-paused " +
+            "message and does NOT throw.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                sessionId: { type: "string" },
+                timeoutMs: {
+                    type: "number",
+                    description: "How long to wait for a pause, in ms. Default 30000.",
+                },
+            },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (session.paused) {
+                return describePaused(session);
+            }
+            const timeoutMs = Math.max(1, Math.floor(args.timeoutMs ?? 30_000));
+            let timedOut = false;
+            await new Promise<void>((resolve) => {
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    // Drop our waiter so a later pause doesn't double-resolve.
+                    const idx = session.pauseWaiters.indexOf(resolve);
+                    if (idx >= 0) session.pauseWaiters.splice(idx, 1);
+                    resolve();
+                }, timeoutMs);
+                session.pauseWaiters.push(() => {
+                    clearTimeout(timer);
+                    resolve();
+                });
+            });
+            if (timedOut && !session.paused) {
+                return `Timed out after ${timeoutMs}ms — target is not paused.`;
+            }
+            return describePaused(session);
+        },
+    },
+
+    resume: {
+        description: "Resume the paused target (Debugger.resume).",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) return "Target is not paused — nothing to resume.";
+            await session.remote.send("Debugger.resume");
+            return "Resumed.";
+        },
+    },
+
+    stepOver: {
+        description: "Step over the next statement (Debugger.stepOver). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepOver");
+            return "Stepped over.";
+        },
+    },
+
+    stepInto: {
+        description: "Step into the next function call (Debugger.stepInto). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepInto");
+            return "Stepped into.";
+        },
+    },
+
+    stepOut: {
+        description: "Step out of the current function (Debugger.stepOut). Target must be paused.",
+        inputSchema: {
+            type: "object",
+            properties: { sessionId: { type: "string" } },
+            required: ["sessionId"],
+        },
+        handler: async (args) => {
+            const session = getSession(args.sessionId);
+            if (!session.paused) throw new Error("Target is not paused.");
+            await session.remote.send("Debugger.stepOut");
+            return "Stepped out.";
+        },
+    },
 };
 
 // --------------------------------------------------------------------------

package/src/diagnostics/misc-pages/AuthoritySpecPage.tsx

@@ -61,32 +61,33 @@ class AuthorityRangeBar extends qreact.Component<{ start: number; end: number }>
 }
 
 class AuthorityNodeRow extends qreact.Component<{ info: NodeAuthorityInfo }> {
+    state = {
+        expanded: false,
+    };
     render() {
         let info = this.props.info;
-        let spec = info.spec;
-        return <div className={css.vbox(6).pad2(10).fillWidth.bord2(0, 0, 85).hsl(0, 0, 99)}>
+        let spec = info.spec!;
+        let expanded = this.state.expanded;
+        return <div
+            className={css.button.vbox(6).pad2(10).fillWidth.bord2(0, 0, 85).hsl(0, 0, 99)}
+            onClick={() => this.state.expanded = !expanded}
+        >
             <div className={css.hbox(10).fillWidth}>
+                <span>{expanded ? "▼" : "▶"}</span>
                 <span className={css.boldStyle}>{info.nodeId}</span>
+                <span>{spec.routeStart.toFixed(4)} - {spec.routeEnd.toFixed(4)}</span>
+                <AuthorityRangeBar start={spec.routeStart} end={spec.routeEnd} />
+                <span className={css.colorhsl(0, 0, 50)}>width {(spec.routeEnd - spec.routeStart).toFixed(4)}</span>
+                {spec.excludeDefault && <span className={css.colorhsl(0, 70, 35)}>(excludes default)</span>}
                 <span className={css.colorhsl(0, 0, 40).ellipsis.flexFillWidth}>{info.entryPoint || "(no entry point)"}</span>
             </div>
-            {!spec &&
-                <div className={css.colorhsl(0, 60, 35)}>(no authority spec returned)</div>
-            }
-            {spec &&
-                <div className={css.vbox(6).fillWidth}>
-                    <div className={css.hbox(10)}>
-                        <span>{spec.routeStart.toFixed(4)} - {spec.routeEnd.toFixed(4)}</span>
-                        <AuthorityRangeBar start={spec.routeStart} end={spec.routeEnd} />
-                        <span className={css.colorhsl(0, 0, 50)}>width {(spec.routeEnd - spec.routeStart).toFixed(4)}</span>
-                        {spec.excludeDefault && <span className={css.colorhsl(0, 70, 35)}>(excludes default)</span>}
-                    </div>
-                    <div className={css.vbox(2)}>
-                        <div className={css.boldStyle}>Prefixes ({spec.prefixes.length}):</div>
-                        {spec.prefixes.length === 0 && <div className={css.colorhsl(0, 0, 50)}>(none)</div>}
-                        {spec.prefixes.map(p =>
-                            <div key={p.originalPrefix} className={css.colorhsl(0, 0, 25)}>{p.originalPrefix}</div>
-                        )}
-                    </div>
+            {expanded &&
+                <div className={css.vbox(2)}>
+                    <div className={css.boldStyle}>Prefixes ({spec.prefixes.length}):</div>
+                    {spec.prefixes.length === 0 && <div className={css.colorhsl(0, 0, 50)}>(none)</div>}
+                    {spec.prefixes.map(p =>
+                        <div key={p.originalPrefix} className={css.colorhsl(0, 0, 25)}>{p.originalPrefix}</div>
+                    )}
                 </div>
             }
         </div>;
@@ -99,13 +100,13 @@ export class AuthoritySpecPage extends qreact.Component {
         if (!infos) {
             return <div className={css.pad2(16)}>Loading authority specs...</div>;
         }
-        let sorted = [...infos];
-        sort(sorted, x => x.spec ? x.spec.routeStart : 2);
+        infos = infos.filter(x => x.spec && x.spec.routeStart >= 0 && x.spec.routeEnd >= 0);
+        sort(infos, x => x.spec!.routeStart);
 
         return <div className={css.vbox(12).pad2(16).fillWidth}>
             <h2>Node Authority Specs ({infos.length})</h2>
             <div className={css.vbox(8).fillWidth}>
-                {sorted.map(info => <AuthorityNodeRow key={info.nodeId} info={info} />)}
+                {infos.map(info => <AuthorityNodeRow key={info.nodeId} info={info} />)}
             </div>
         </div>;
     }