@wrongstack/webui-server 0.301.0 → 0.302.0

package/dist/index.js

@@ -6463,28 +6463,28 @@ async function restartMailboxServer(projectRoot) {
 var RESTART_POLL_INTERVAL_MS = 250;
 var RESTART_DEADLINE_MS = 3e3;
 function isEndpointAlive(endpoint) {
-  return new Promise((resolve16) => {
+  return new Promise((resolve17) => {
     const sock = net.createConnection(endpoint);
     const timer = setTimeout(() => {
       sock.destroy();
-      resolve16(false);
+      resolve17(false);
     }, 500);
     timer.unref?.();
     sock.once("connect", () => {
       clearTimeout(timer);
       sock.destroy();
-      resolve16(true);
+      resolve17(true);
     });
     sock.once("error", () => {
       clearTimeout(timer);
       sock.destroy();
-      resolve16(false);
+      resolve17(false);
     });
   });
 }
 async function waitForShutdown(probe) {
   if (!probe) {
-    await new Promise((resolve16) => setTimeout(resolve16, RESTART_POLL_INTERVAL_MS));
+    await new Promise((resolve17) => setTimeout(resolve17, RESTART_POLL_INTERVAL_MS));
     return;
   }
   const deadline = Date.now() + RESTART_DEADLINE_MS;
@@ -6495,7 +6495,7 @@ async function waitForShutdown(probe) {
     } catch {
       return;
     }
-    await new Promise((resolve16) => setTimeout(resolve16, RESTART_POLL_INTERVAL_MS));
+    await new Promise((resolve17) => setTimeout(resolve17, RESTART_POLL_INTERVAL_MS));
   }
 }
 function failureService(id, label, required, mode, error2, latencyMs) {
@@ -6658,9 +6658,9 @@ async function handleGitInfo(ws, projectRoot) {
   const cwd = projectRoot || void 0;
   try {
     const { execFile: ef } = await import("node:child_process");
-    const git = (args) => new Promise((resolve16) => {
+    const git = (args) => new Promise((resolve17) => {
       ef("git", args, { cwd, timeout: 3e3 }, (err, stdout) => {
-        resolve16(err ? "" : stdout.trim());
+        resolve17(err ? "" : stdout.trim());
       });
     });
     const [branchRaw, diffRaw, statusRaw, upstreamRaw] = await Promise.all([
@@ -6686,12 +6686,12 @@ async function handleGitInfo(ws, projectRoot) {
 function makeGit(cwd) {
   return async (args) => {
     const { execFile: ef } = await import("node:child_process");
-    return new Promise((resolve16) => {
+    return new Promise((resolve17) => {
       ef(
         "git",
         args,
         { cwd, timeout: 5e3, maxBuffer: 1024 * 1024 * 16 },
-        (err, stdout) => resolve16(err ? "" : stdout)
+        (err, stdout) => resolve17(err ? "" : stdout)
       );
     });
   };
@@ -6856,7 +6856,7 @@ import { execFile } from "node:child_process";
 var GIT_TIMEOUT_MS = 1e4;
 var GIT_MAX_OUTPUT_BYTES = 1024 * 1024;
 function gitStdout(cwd, args) {
-  return new Promise((resolve16) => {
+  return new Promise((resolve17) => {
     execFile(
       "git",
       [...args],
@@ -6867,7 +6867,7 @@ function gitStdout(cwd, args) {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: GIT_MAX_OUTPUT_BYTES
       },
-      (error2, stdout) => resolve16(error2 ? null : stdout)
+      (error2, stdout) => resolve17(error2 ? null : stdout)
     );
   });
 }
@@ -7158,14 +7158,14 @@ var GoalWebSocketHandler = class {
         const cwd = env?.cwd ?? this.projectRoot;
         try {
           const { execFile: execFile2 } = await import("node:child_process");
-          const result = await new Promise((resolve16) => {
+          const result = await new Promise((resolve17) => {
             const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx";
             execFile2(npxCommand, ["tsc", "--noEmit"], { cwd, timeout: 6e4 }, (err, stdout, stderr) => {
               if (err && err.code === "ENOENT") {
-                resolve16("[verify] tsc not found \u2014 skipping");
+                resolve17("[verify] tsc not found \u2014 skipping");
                 return;
               }
-              resolve16(stdout + stderr);
+              resolve17(stdout + stderr);
             });
           });
           if (result.includes("[verify]") || result.trim().length === 0) {
@@ -7903,7 +7903,7 @@ function pushEvent(event) {
   }
 }
 function parseBody(req) {
-  return new Promise((resolve16, reject) => {
+  return new Promise((resolve17, reject) => {
     let body = "";
     let bodyBytes = 0;
     let tooLarge = false;
@@ -7923,7 +7923,7 @@ function parseBody(req) {
         return;
       }
       try {
-        resolve16(JSON.parse(body));
+        resolve17(JSON.parse(body));
       } catch {
         reject(new Error("Invalid JSON"));
       }
@@ -8018,7 +8018,7 @@ import * as path10 from "node:path";
 import { runDeadCodeScan } from "@wrongstack/tools/codebase-index";
 var MAX_BODY_BYTES = 10 * 1024 * 1024;
 function readJsonBody(req) {
-  return new Promise((resolve16, reject) => {
+  return new Promise((resolve17, reject) => {
     const chunks = [];
     let total = 0;
     req.on("data", (chunk) => {
@@ -8030,7 +8030,7 @@ function readJsonBody(req) {
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve16(Buffer.concat(chunks).toString("utf8")));
+    req.on("end", () => resolve17(Buffer.concat(chunks).toString("utf8")));
     req.on("error", (err) => reject(err));
   });
 }
@@ -8476,7 +8476,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
   }
 }
 function readJsonBody2(req) {
-  return new Promise((resolve16, reject) => {
+  return new Promise((resolve17, reject) => {
     const contentType = (req.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase();
     if (contentType !== "application/json") {
       reject(new Error(`Unsupported Content-Type: ${contentType || "(absent)"}`));
@@ -8492,7 +8492,7 @@ function readJsonBody2(req) {
     });
     req.on("end", () => {
       try {
-        resolve16(data ? JSON.parse(data) : {});
+        resolve17(data ? JSON.parse(data) : {});
       } catch (err) {
         reject(err instanceof Error ? err : new Error(String(err)));
       }
@@ -8768,14 +8768,14 @@ async function readJsonBody3(res, req) {
     });
     return null;
   }
-  return new Promise((resolve16) => {
+  return new Promise((resolve17) => {
     let data = "";
     let failed = false;
     const fail2 = (message) => {
       if (failed) return;
       failed = true;
       sendJson2(res, 400, { error: { code: "INVALID_BODY", message } });
-      resolve16(null);
+      resolve17(null);
     };
     req.on("data", (chunk) => {
       if (failed) return;
@@ -8788,7 +8788,7 @@ async function readJsonBody3(res, req) {
     req.on("end", () => {
       if (failed) return;
       try {
-        resolve16(data.trim().length === 0 ? {} : JSON.parse(data));
+        resolve17(data.trim().length === 0 ? {} : JSON.parse(data));
       } catch {
         fail2("Request body is not valid JSON");
       }
@@ -9627,7 +9627,7 @@ function strictDecodeParam(segment, res) {
 function createHttpServer(opts) {
   const port = opts.port ?? Number.parseInt(process.env["PORT"] ?? "3456", 10);
   const distDir = path13.resolve(opts.distDir);
-  const requireAccessToken = true;
+  const requireAccessToken = Boolean(opts.requireToken) || !isLoopbackBind(opts.host);
   const secureCookies = opts.secureCookies ?? (opts.publicWsUrl?.trim().toLowerCase().startsWith("wss:") ?? false);
   const trustedHostnames = (() => {
     const names = [...opts.allowedHostnames ?? []];
@@ -10173,10 +10173,78 @@ function createHttpServer(opts) {
 }
 
 // src/server/instance-registry.ts
+import * as fs11 from "node:fs/promises";
 import * as os from "node:os";
 import * as path14 from "node:path";
-import * as fs11 from "node:fs/promises";
 import { atomicWrite as atomicWrite4 } from "@wrongstack/core/utils";
+function normalizeRoot(root) {
+  const resolved = path14.resolve(root);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+function isLiveSessionStatus(status) {
+  return status === "active" || status === "idle";
+}
+function instanceRole(instance) {
+  return instance.role ?? "standalone";
+}
+function resolveAttachability(input) {
+  const { session, instance } = input;
+  if (!isLiveSessionStatus(session.status)) {
+    return { attachable: false, degradedReason: "session-not-live" };
+  }
+  if (!instance) {
+    return { attachable: false, degradedReason: "live-session-no-webui-endpoint" };
+  }
+  if (instance.pid !== session.pid) {
+    return { attachable: false, degradedReason: "endpoint-owner-mismatch" };
+  }
+  if (!instance.sessionId) {
+    return { attachable: false, instance, degradedReason: "endpoint-missing-session-id" };
+  }
+  if (instance.sessionId !== session.sessionId) {
+    return { attachable: false, instance, degradedReason: "endpoint-session-mismatch" };
+  }
+  if (instanceRole(instance) !== "session-child") {
+    return { attachable: false, instance, degradedReason: "endpoint-not-session-child" };
+  }
+  if (instance.attachable === false) {
+    return { attachable: false, instance, degradedReason: "endpoint-not-attachable" };
+  }
+  return {
+    attachable: true,
+    endpoint: {
+      host: instance.host,
+      httpPort: instance.httpPort,
+      url: instance.url,
+      ...instance.authToken ? { authToken: instance.authToken } : {}
+    }
+  };
+}
+function joinSessionRegistryWithWebUIInstances(input) {
+  const targetRoot = input.projectRoot ? normalizeRoot(input.projectRoot) : void 0;
+  const sessions = input.sessions.filter((session) => {
+    if (input.projectSlug && session.projectSlug !== input.projectSlug) return false;
+    if (targetRoot && normalizeRoot(session.projectRoot) !== targetRoot) return false;
+    return true;
+  });
+  return sessions.map((session) => {
+    const instance = input.instances.find((candidate) => candidate.sessionId === session.sessionId) ?? input.instances.find(
+      (candidate) => candidate.pid === session.pid && normalizeRoot(candidate.projectRoot) === normalizeRoot(session.projectRoot)
+    );
+    const resolved = resolveAttachability({ session, instance });
+    return {
+      sessionId: session.sessionId,
+      projectRoot: session.projectRoot,
+      workingDir: session.workingDir,
+      sessionPid: session.pid,
+      status: session.status,
+      ...instance ? { instance } : {},
+      ...resolved.endpoint ? { endpoint: resolved.endpoint } : {},
+      attachable: resolved.attachable,
+      ...resolved.degradedReason ? { degradedReason: resolved.degradedReason } : {}
+    };
+  });
+}
 function defaultBaseDir() {
   return path14.join(os.homedir(), ".wrongstack");
 }
@@ -13723,16 +13791,16 @@ function getSurfaceDefaultPorts(surface) {
   return { http: SURFACE_DEFAULT_PORTS[surface].http };
 }
 function isPortFree(host, port) {
-  return new Promise((resolve16) => {
+  return new Promise((resolve17) => {
     const srv = net2.createServer();
-    srv.once("error", () => resolve16(false));
+    srv.once("error", () => resolve17(false));
     srv.once("listening", () => {
-      srv.close(() => resolve16(true));
+      srv.close(() => resolve17(true));
     });
     try {
       srv.listen(port, host);
     } catch {
-      resolve16(false);
+      resolve17(false);
     }
   });
 }
@@ -13888,7 +13956,7 @@ async function startStaticServe(opts, deps2 = {}) {
   return { server, port: opts.httpPort };
 }
 function runPnpmBuild(cwd, workspace, timeoutMs) {
-  return new Promise((resolve16, reject) => {
+  return new Promise((resolve17, reject) => {
     const child = spawn2("pnpm", ["--filter", workspace, "build"], {
       cwd,
       shell: process.platform === "win32",
@@ -13906,7 +13974,7 @@ function runPnpmBuild(cwd, workspace, timeoutMs) {
     });
     child.once("close", (code) => {
       clearTimeout(timer);
-      if (code === 0) resolve16();
+      if (code === 0) resolve17();
       else reject(new Error(`pnpm build exited with code ${String(code)}`));
     });
   });
@@ -13970,27 +14038,41 @@ function formatExternalAccessUrls(opts) {
 }
 
 // src/server/embedded-lifecycle.ts
-function registerWebuiInstance(p, deps2 = {}) {
+async function registerWebuiInstance(p, deps2 = {}) {
   const register = deps2.registerFn ?? registerInstance;
-  void register(
-    {
-      pid: p.pid,
-      surface: p.surface,
-      httpPort: p.httpPort,
-      host: p.host,
-      projectRoot: p.projectRoot,
-      projectName: path16.basename(p.projectRoot) || p.projectRoot,
-      startedAt: p.startedAt,
-      url: buildWebUIAccessUrl({
+  try {
+    await register(
+      {
+        pid: p.pid,
+        surface: p.surface,
+        httpPort: p.httpPort,
         host: p.host,
-        port: p.httpPort,
-        publicUrl: p.publicUrl
-      }),
-      ...p.authToken ? { authToken: p.authToken } : {}
-    },
-    p.registryBaseDir
-  ).catch(() => {
-  });
+        projectRoot: p.projectRoot,
+        projectName: path16.basename(p.projectRoot) || p.projectRoot,
+        startedAt: p.startedAt,
+        url: buildWebUIAccessUrl({
+          host: p.host,
+          port: p.httpPort,
+          publicUrl: p.publicUrl
+        }),
+        ...p.authToken ? { authToken: p.authToken } : {},
+        ...p.role ? { role: p.role } : {},
+        ...p.sessionId ? { sessionId: p.sessionId } : {},
+        ...p.parentPid !== void 0 ? { parentPid: p.parentPid } : {},
+        ...p.parentShellId ? { parentShellId: p.parentShellId } : {},
+        ...p.runtimeId ? { runtimeId: p.runtimeId } : {},
+        ...p.attachable !== void 0 ? { attachable: p.attachable } : {},
+        ...p.authToken ? { auth: { scheme: "registry-token", tokenPresent: true } } : {},
+        ...p.lastReadyAt ? { lastReadyAt: p.lastReadyAt } : {},
+        ...p.protocolVersion !== void 0 ? { protocolVersion: p.protocolVersion } : {},
+        ...p.capabilities ? { capabilities: p.capabilities } : {}
+      },
+      p.registryBaseDir
+    );
+    return true;
+  } catch {
+    return false;
+  }
 }
 function announceWebuiReady(p) {
   const log = p.log ?? ((m) => console.log(m));
@@ -14028,10 +14110,10 @@ async function runBounded(work, timeoutMs, label, debug) {
       Promise.resolve().then(() => work()).catch((err) => {
         debug(`[webui-server] ${label} failed: ${err}`);
       }),
-      new Promise((resolve16) => {
+      new Promise((resolve17) => {
         timer = setTimeout(() => {
           debug(`[webui-server] ${label} timed out after ${timeoutMs}ms`);
-          resolve16();
+          resolve17();
         }, timeoutMs);
         timer.unref?.();
       })
@@ -14064,8 +14146,8 @@ function createWebuiShutdown(res) {
       const unregistered = unregister(res.pid, res.registryBaseDir).catch(
         (err) => debug(`[webui-server] unregister failed: ${err}`)
       );
-      await new Promise((resolve16) => {
-        res.wss.close(() => resolve16());
+      await new Promise((resolve17) => {
+        res.wss.close(() => resolve17());
       });
       await unregistered;
       log("[WebUI] Server stopped");
@@ -20458,8 +20540,8 @@ function createConfigWriteLock() {
     acquire() {
       const prev = lock;
       let release = () => void 0;
-      lock = new Promise((resolve16) => {
-        release = resolve16;
+      lock = new Promise((resolve17) => {
+        release = resolve17;
       });
       return { prev, release };
     }
@@ -23045,7 +23127,7 @@ function findWorkspaceCliEntry(projectRoot) {
   return null;
 }
 function sleep(ms) {
-  return new Promise((resolve16) => setTimeout(resolve16, ms));
+  return new Promise((resolve17) => setTimeout(resolve17, ms));
 }
 
 // src/server/terminal-ws-handler.ts
@@ -23288,7 +23370,7 @@ function clampDim(value, fallback) {
 }
 
 // src/server/worktree-ws-handler.ts
-import { join as join14, resolve as resolve13, sep as sep5 } from "node:path";
+import { join as join14, resolve as resolve14, sep as sep5 } from "node:path";
 import { toErrorMessage as toErrorMessage9 } from "@wrongstack/core/utils";
 import { WorktreeManager as WorktreeManager3 } from "@wrongstack/core/worktree";
 import { cleanupStaleSddWorktrees as cleanupStaleSddWorktrees2 } from "@wrongstack/sdd";
@@ -23373,11 +23455,11 @@ var WorktreeWebSocketHandler = class {
   // ── orphan management ─────────────────────────────────────────────────────
   /** Absolute managed-worktrees root for this project. */
   worktreesRoot() {
-    return resolve13(join14(this.management.projectRoot, ".wrongstack", "worktrees"));
+    return resolve14(join14(this.management.projectRoot, ".wrongstack", "worktrees"));
   }
   /** True iff `dir` resolves strictly inside the managed worktrees root. */
   underRoot(dir) {
-    const abs = resolve13(dir);
+    const abs = resolve14(dir);
     const root = this.worktreesRoot();
     return abs !== root && abs.startsWith(root + sep5);
   }
@@ -23601,7 +23683,7 @@ var WorktreeWebSocketHandler = class {
     }
     const base = baseBranch && MANAGED_BRANCH_RE.test(baseBranch) ? baseBranch : void 0;
     const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
-    const summary = await wt.diffSummary(resolve13(dir), base);
+    const summary = await wt.diffSummary(resolve14(dir), base);
     this.broadcast({ type: "worktree.diff_result", payload: { dir, summary } });
   }
   // ── internals ───────────────────────────────────────────────────────────
@@ -26231,7 +26313,7 @@ async function startWebUI(opts = {}) {
         if (events.listenerCount("tool.confirm_needed") === 0) {
           throw new Error("No permission confirmation surface is connected");
         }
-        const decision = await new Promise((resolve16) => {
+        const decision = await new Promise((resolve17) => {
           events.emit("tool.confirm_needed", {
             sessionId: context.session.id,
             tool: confirmTool,
@@ -26241,7 +26323,7 @@ async function startWebUI(opts = {}) {
             decisionSource: pending.decisionSource,
             riskTier: pending.riskTier,
             boundaryReason: pending.boundaryReason,
-            resolve: resolve16
+            resolve: resolve17
           });
         });
         const rule = { tool: "language_package", pattern: pending.suggestedPattern };
@@ -26883,6 +26965,7 @@ export {
   isPortFree,
   isRegisteredMessageType,
   isWildcardBind,
+  joinSessionRegistryWithWebUIInstances,
   listInstances,
   loadManifest,
   loadSavedProviders,

package/dist/server/embedded-lifecycle.d.ts

@@ -1,4 +1,4 @@
-import { type WebUIInstanceRecord } from './instance-registry.js';
+import { type WebUIInstanceRecord, type WebUIInstanceRole } from './instance-registry.js';
 import type { SurfaceKind } from './port-utils.js';
 /**
  * PR 7 of Issue #30 (webui-server 8-PR refactor): process lifecycle.
@@ -38,6 +38,21 @@ export interface RegisterWebuiInstanceParams {
      * authenticate `POST /api/fleet/ping` (H3). See `WebUIInstanceRecord`.
      */
     authToken?: string | undefined;
+    /** Runtime role. Missing means the legacy standalone WebUI/SimpleUI role. */
+    role?: WebUIInstanceRole | undefined;
+    /** Live session owned by this endpoint when `role === 'session-child'`. */
+    sessionId?: string | undefined;
+    /** Parent shell process identity, when this endpoint was spawned by a parent. */
+    parentPid?: number | undefined;
+    parentShellId?: string | undefined;
+    /** Stable child runtime id, distinct from the session id. */
+    runtimeId?: string | undefined;
+    /** Whether a parent shell should treat this endpoint as attachable. */
+    attachable?: boolean | undefined;
+    /** Health/protocol hints for future parent shells. */
+    lastReadyAt?: string | undefined;
+    protocolVersion?: number | undefined;
+    capabilities?: string[] | undefined;
 }
 export interface RegisterWebuiInstanceDeps {
     registerFn?: (record: WebUIInstanceRecord, baseDir?: string) => Promise<void>;
@@ -48,7 +63,7 @@ export interface RegisterWebuiInstanceDeps {
  * is swallowed (the registry is a convenience index, not a source of
  * truth). Caller guards on `projectRoot` being known.
  */
-export declare function registerWebuiInstance(p: RegisterWebuiInstanceParams, deps?: RegisterWebuiInstanceDeps): void;
+export declare function registerWebuiInstance(p: RegisterWebuiInstanceParams, deps?: RegisterWebuiInstanceDeps): Promise<boolean>;
 export interface AnnounceWebuiReadyParams {
     /** Surface kind — 'webui' or 'simpleui'. */
     surface: SurfaceKind;

package/dist/server/entry.js

@@ -6377,28 +6377,28 @@ async function restartMailboxServer(projectRoot) {
 var RESTART_POLL_INTERVAL_MS = 250;
 var RESTART_DEADLINE_MS = 3e3;
 function isEndpointAlive(endpoint) {
-  return new Promise((resolve15) => {
+  return new Promise((resolve16) => {
     const sock = net.createConnection(endpoint);
     const timer = setTimeout(() => {
       sock.destroy();
-      resolve15(false);
+      resolve16(false);
     }, 500);
     timer.unref?.();
     sock.once("connect", () => {
       clearTimeout(timer);
       sock.destroy();
-      resolve15(true);
+      resolve16(true);
     });
     sock.once("error", () => {
       clearTimeout(timer);
       sock.destroy();
-      resolve15(false);
+      resolve16(false);
     });
   });
 }
 async function waitForShutdown(probe) {
   if (!probe) {
-    await new Promise((resolve15) => setTimeout(resolve15, RESTART_POLL_INTERVAL_MS));
+    await new Promise((resolve16) => setTimeout(resolve16, RESTART_POLL_INTERVAL_MS));
     return;
   }
   const deadline = Date.now() + RESTART_DEADLINE_MS;
@@ -6409,7 +6409,7 @@ async function waitForShutdown(probe) {
     } catch {
       return;
     }
-    await new Promise((resolve15) => setTimeout(resolve15, RESTART_POLL_INTERVAL_MS));
+    await new Promise((resolve16) => setTimeout(resolve16, RESTART_POLL_INTERVAL_MS));
   }
 }
 function failureService(id, label, required, mode, error2, latencyMs) {
@@ -6572,9 +6572,9 @@ async function handleGitInfo(ws, projectRoot) {
   const cwd = projectRoot || void 0;
   try {
     const { execFile: ef } = await import("node:child_process");
-    const git = (args) => new Promise((resolve15) => {
+    const git = (args) => new Promise((resolve16) => {
       ef("git", args, { cwd, timeout: 3e3 }, (err, stdout) => {
-        resolve15(err ? "" : stdout.trim());
+        resolve16(err ? "" : stdout.trim());
       });
     });
     const [branchRaw, diffRaw, statusRaw, upstreamRaw] = await Promise.all([
@@ -6600,12 +6600,12 @@ async function handleGitInfo(ws, projectRoot) {
 function makeGit(cwd) {
   return async (args) => {
     const { execFile: ef } = await import("node:child_process");
-    return new Promise((resolve15) => {
+    return new Promise((resolve16) => {
       ef(
         "git",
         args,
         { cwd, timeout: 5e3, maxBuffer: 1024 * 1024 * 16 },
-        (err, stdout) => resolve15(err ? "" : stdout)
+        (err, stdout) => resolve16(err ? "" : stdout)
       );
     });
   };
@@ -6770,7 +6770,7 @@ import { execFile } from "node:child_process";
 var GIT_TIMEOUT_MS = 1e4;
 var GIT_MAX_OUTPUT_BYTES = 1024 * 1024;
 function gitStdout(cwd, args) {
-  return new Promise((resolve15) => {
+  return new Promise((resolve16) => {
     execFile(
       "git",
       [...args],
@@ -6781,7 +6781,7 @@ function gitStdout(cwd, args) {
         timeout: GIT_TIMEOUT_MS,
         maxBuffer: GIT_MAX_OUTPUT_BYTES
       },
-      (error2, stdout) => resolve15(error2 ? null : stdout)
+      (error2, stdout) => resolve16(error2 ? null : stdout)
     );
   });
 }
@@ -7072,14 +7072,14 @@ var GoalWebSocketHandler = class {
         const cwd = env?.cwd ?? this.projectRoot;
         try {
           const { execFile: execFile2 } = await import("node:child_process");
-          const result = await new Promise((resolve15) => {
+          const result = await new Promise((resolve16) => {
             const npxCommand = process.platform === "win32" ? "npx.cmd" : "npx";
             execFile2(npxCommand, ["tsc", "--noEmit"], { cwd, timeout: 6e4 }, (err, stdout, stderr) => {
               if (err && err.code === "ENOENT") {
-                resolve15("[verify] tsc not found \u2014 skipping");
+                resolve16("[verify] tsc not found \u2014 skipping");
                 return;
               }
-              resolve15(stdout + stderr);
+              resolve16(stdout + stderr);
             });
           });
           if (result.includes("[verify]") || result.trim().length === 0) {
@@ -7817,7 +7817,7 @@ function pushEvent(event) {
   }
 }
 function parseBody(req) {
-  return new Promise((resolve15, reject) => {
+  return new Promise((resolve16, reject) => {
     let body = "";
     let bodyBytes = 0;
     let tooLarge = false;
@@ -7837,7 +7837,7 @@ function parseBody(req) {
         return;
       }
       try {
-        resolve15(JSON.parse(body));
+        resolve16(JSON.parse(body));
       } catch {
         reject(new Error("Invalid JSON"));
       }
@@ -7924,7 +7924,7 @@ import * as path10 from "node:path";
 import { runDeadCodeScan } from "@wrongstack/tools/codebase-index";
 var MAX_BODY_BYTES = 10 * 1024 * 1024;
 function readJsonBody(req) {
-  return new Promise((resolve15, reject) => {
+  return new Promise((resolve16, reject) => {
     const chunks = [];
     let total = 0;
     req.on("data", (chunk) => {
@@ -7936,7 +7936,7 @@ function readJsonBody(req) {
       }
       chunks.push(chunk);
     });
-    req.on("end", () => resolve15(Buffer.concat(chunks).toString("utf8")));
+    req.on("end", () => resolve16(Buffer.concat(chunks).toString("utf8")));
     req.on("error", (err) => reject(err));
   });
 }
@@ -8382,7 +8382,7 @@ async function handleApiSessionEvents(res, globalRoot, sessionId, limit) {
   }
 }
 function readJsonBody2(req) {
-  return new Promise((resolve15, reject) => {
+  return new Promise((resolve16, reject) => {
     const contentType = (req.headers["content-type"] ?? "").split(";")[0]?.trim().toLowerCase();
     if (contentType !== "application/json") {
       reject(new Error(`Unsupported Content-Type: ${contentType || "(absent)"}`));
@@ -8398,7 +8398,7 @@ function readJsonBody2(req) {
     });
     req.on("end", () => {
       try {
-        resolve15(data ? JSON.parse(data) : {});
+        resolve16(data ? JSON.parse(data) : {});
       } catch (err) {
         reject(err instanceof Error ? err : new Error(String(err)));
       }
@@ -8674,14 +8674,14 @@ async function readJsonBody3(res, req) {
     });
     return null;
   }
-  return new Promise((resolve15) => {
+  return new Promise((resolve16) => {
     let data = "";
     let failed = false;
     const fail2 = (message) => {
       if (failed) return;
       failed = true;
       sendJson2(res, 400, { error: { code: "INVALID_BODY", message } });
-      resolve15(null);
+      resolve16(null);
     };
     req.on("data", (chunk) => {
       if (failed) return;
@@ -8694,7 +8694,7 @@ async function readJsonBody3(res, req) {
     req.on("end", () => {
       if (failed) return;
       try {
-        resolve15(data.trim().length === 0 ? {} : JSON.parse(data));
+        resolve16(data.trim().length === 0 ? {} : JSON.parse(data));
       } catch {
         fail2("Request body is not valid JSON");
       }
@@ -9533,7 +9533,7 @@ function strictDecodeParam(segment, res) {
 function createHttpServer(opts) {
   const port = opts.port ?? Number.parseInt(process.env["PORT"] ?? "3456", 10);
   const distDir = path13.resolve(opts.distDir);
-  const requireAccessToken = true;
+  const requireAccessToken = Boolean(opts.requireToken) || !isLoopbackBind(opts.host);
   const secureCookies = opts.secureCookies ?? (opts.publicWsUrl?.trim().toLowerCase().startsWith("wss:") ?? false);
   const trustedHostnames = (() => {
     const names = [...opts.allowedHostnames ?? []];
@@ -10079,9 +10079,9 @@ function createHttpServer(opts) {
 }
 
 // src/server/instance-registry.ts
+import * as fs11 from "node:fs/promises";
 import * as os from "node:os";
 import * as path14 from "node:path";
-import * as fs11 from "node:fs/promises";
 import { atomicWrite as atomicWrite4 } from "@wrongstack/core/utils";
 function defaultBaseDir() {
   return path14.join(os.homedir(), ".wrongstack");
@@ -13503,16 +13503,16 @@ function createModelOperations(context) {
 import * as net2 from "node:net";
 import { ToolValidationError as ToolValidationError4 } from "@wrongstack/core/types";
 function isPortFree(host, port) {
-  return new Promise((resolve15) => {
+  return new Promise((resolve16) => {
     const srv = net2.createServer();
-    srv.once("error", () => resolve15(false));
+    srv.once("error", () => resolve16(false));
     srv.once("listening", () => {
-      srv.close(() => resolve15(true));
+      srv.close(() => resolve16(true));
     });
     try {
       srv.listen(port, host);
     } catch {
-      resolve15(false);
+      resolve16(false);
     }
   });
 }
@@ -20724,7 +20724,7 @@ function findWorkspaceCliEntry(projectRoot) {
   return null;
 }
 function sleep(ms) {
-  return new Promise((resolve15) => setTimeout(resolve15, ms));
+  return new Promise((resolve16) => setTimeout(resolve16, ms));
 }
 
 // src/server/terminal-ws-handler.ts
@@ -20967,7 +20967,7 @@ function clampDim(value, fallback) {
 }
 
 // src/server/worktree-ws-handler.ts
-import { join as join11, resolve as resolve12, sep as sep5 } from "node:path";
+import { join as join11, resolve as resolve13, sep as sep5 } from "node:path";
 import { toErrorMessage as toErrorMessage8 } from "@wrongstack/core/utils";
 import { WorktreeManager as WorktreeManager3 } from "@wrongstack/core/worktree";
 import { cleanupStaleSddWorktrees as cleanupStaleSddWorktrees2 } from "@wrongstack/sdd";
@@ -21052,11 +21052,11 @@ var WorktreeWebSocketHandler = class {
   // ── orphan management ─────────────────────────────────────────────────────
   /** Absolute managed-worktrees root for this project. */
   worktreesRoot() {
-    return resolve12(join11(this.management.projectRoot, ".wrongstack", "worktrees"));
+    return resolve13(join11(this.management.projectRoot, ".wrongstack", "worktrees"));
   }
   /** True iff `dir` resolves strictly inside the managed worktrees root. */
   underRoot(dir) {
-    const abs = resolve12(dir);
+    const abs = resolve13(dir);
     const root = this.worktreesRoot();
     return abs !== root && abs.startsWith(root + sep5);
   }
@@ -21280,7 +21280,7 @@ var WorktreeWebSocketHandler = class {
     }
     const base = baseBranch && MANAGED_BRANCH_RE.test(baseBranch) ? baseBranch : void 0;
     const wt = new WorktreeManager3({ projectRoot: this.management.projectRoot });
-    const summary = await wt.diffSummary(resolve12(dir), base);
+    const summary = await wt.diffSummary(resolve13(dir), base);
     this.broadcast({ type: "worktree.diff_result", payload: { dir, summary } });
   }
   // ── internals ───────────────────────────────────────────────────────────
@@ -23910,7 +23910,7 @@ async function startWebUI(opts = {}) {
         if (events.listenerCount("tool.confirm_needed") === 0) {
           throw new Error("No permission confirmation surface is connected");
         }
-        const decision = await new Promise((resolve15) => {
+        const decision = await new Promise((resolve16) => {
           events.emit("tool.confirm_needed", {
             sessionId: context.session.id,
             tool: confirmTool,
@@ -23920,7 +23920,7 @@ async function startWebUI(opts = {}) {
             decisionSource: pending.decisionSource,
             riskTier: pending.riskTier,
             boundaryReason: pending.boundaryReason,
-            resolve: resolve15
+            resolve: resolve16
           });
         });
         const rule = { tool: "language_package", pattern: pending.suggestedPattern };

package/dist/server/index.d.ts

@@ -42,7 +42,7 @@ export { type HostRouteHandlers, handleHostRoute } from './host-routes.js';
 export { clearAnalyticsBuffer, getAnalyticsBuffer, handleApiAnalyticsGet, handleApiAnalyticsPost, handleApiAnalyticsSummary, } from './http-server/analytics-handler.js';
 export type { CreateHttpServerOptions } from './http-server.js';
 export { buildCspHeader, createHttpServer, decodeSessionId, injectWsConfig, isInsideDist, } from './http-server.js';
-export { defaultBaseDir, formatInstances, isPidAlive, listInstances, registerInstance, registryPath, unregisterInstance, type WebUIInstanceRecord, } from './instance-registry.js';
+export { defaultBaseDir, formatInstances, isPidAlive, joinSessionRegistryWithWebUIInstances, listInstances, registerInstance, registryPath, unregisterInstance, type WebUIInstanceAuthInfo, type WebUIInstanceRecord, type WebUIInstanceRole, type WebUISessionAttachCandidate, type WebUISessionAttachDegradedReason, type WebUISessionAttachEndpoint, } from './instance-registry.js';
 export { handleIntrospectionRoute, type IntrospectionRouteContext, } from './introspection-routes.js';
 export { handleKanbanTaskDispatch, type KanbanDispatchContext, type KanbanDispatchResult, type KanbanTaskDispatcher, parseResolvedDispatchRoute, type ResolvedDispatchRoute, } from './kanban-dispatch.js';
 export { handleKanbanHostRoute, type KanbanHostRouteHandlers } from './kanban-host-routes.js';

package/dist/server/instance-registry.d.ts

@@ -18,12 +18,20 @@
  * - **Best-effort**: a failure to read/write the registry must NEVER take the
  *   server down. Callers wrap these in `.catch()`.
  */
+import type { SessionRegistryEntry, SessionLiveStatus } from '@wrongstack/core/storage';
+export type WebUIInstanceRole = 'standalone' | 'parent-shell' | 'session-child';
+export interface WebUIInstanceAuthInfo {
+    /** How a same-user parent/sibling process can authenticate to this endpoint. */
+    scheme: 'registry-token' | 'cookie-bootstrap' | 'none';
+    /** Whether the record has a usable token in `authToken`. */
+    tokenPresent: boolean;
+}
 /** One running WebUI / SimpleUI process. */
 export interface WebUIInstanceRecord {
     /** OS process id — also the liveness key. */
     pid: number;
-    /** Surface kind — 'webui' or 'simpleui'. */
-    surface: 'webui' | 'simpleui';
+    /** Surface kind — 'webui' or 'simpleui'. Additional strings are tolerated for new surfaces. */
+    surface: 'webui' | 'simpleui' | string;
     /** Port serving both HTTP and WebSocket. */
     httpPort: number;
     /** Bind host (e.g. 127.0.0.1 or 0.0.0.0). */
@@ -57,7 +65,48 @@ export interface WebUIInstanceRecord {
      * Optional so an older record (or a surface that has no token) still parses.
      */
     authToken?: string | undefined;
+    /** Runtime role. Missing means the legacy standalone WebUI/SimpleUI role. */
+    role?: WebUIInstanceRole | undefined;
+    /** Live session owned by this endpoint when `role === 'session-child'`. */
+    sessionId?: string | undefined;
+    /** Parent shell process identity, when this endpoint was spawned by a parent. */
+    parentPid?: number | undefined;
+    parentShellId?: string | undefined;
+    /** Stable child runtime id, distinct from the session id. */
+    runtimeId?: string | undefined;
+    /** Whether a parent shell should treat this endpoint as attachable. */
+    attachable?: boolean | undefined;
+    /** Descriptive auth metadata; the same-user token remains in `authToken`. */
+    auth?: WebUIInstanceAuthInfo | undefined;
+    /** Health/protocol hints for future parent shells. */
+    lastReadyAt?: string | undefined;
+    protocolVersion?: number | undefined;
+    capabilities?: string[] | undefined;
+}
+export interface WebUISessionAttachEndpoint {
+    host: string;
+    httpPort: number;
+    url: string;
+    authToken?: string | undefined;
+}
+export type WebUISessionAttachDegradedReason = 'live-session-no-webui-endpoint' | 'endpoint-owner-mismatch' | 'endpoint-missing-session-id' | 'endpoint-session-mismatch' | 'endpoint-not-session-child' | 'endpoint-not-attachable' | 'session-not-live';
+export interface WebUISessionAttachCandidate {
+    sessionId: string;
+    projectRoot: string;
+    workingDir: string;
+    sessionPid: number;
+    status: SessionLiveStatus;
+    instance?: WebUIInstanceRecord | undefined;
+    endpoint?: WebUISessionAttachEndpoint | undefined;
+    attachable: boolean;
+    degradedReason?: WebUISessionAttachDegradedReason | undefined;
 }
+export declare function joinSessionRegistryWithWebUIInstances(input: {
+    sessions: SessionRegistryEntry[];
+    instances: WebUIInstanceRecord[];
+    projectRoot?: string | undefined;
+    projectSlug?: string | undefined;
+}): WebUISessionAttachCandidate[];
 /** Default wstack home dir (`~/.wrongstack`). Callers may override the base. */
 export declare function defaultBaseDir(): string;
 /** Resolve the registry file path for a given base dir. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/webui-server",
-  "version": "0.301.0",
+  "version": "0.302.0",
   "license": "MIT",
   "description": "WrongStack WebUI HTTP/WebSocket server module — extracted from @wrongstack/webui in PR #243/244 to remove the CLI -> @wrongstack/webui/server cross-package edge (audit §3.1.1). Pure backend: HTTP routes, WebSocket handlers, MCP tool wrappers, HTML serving. The web frontend lives in @wrongstack/webui; this package is the standalone server it can run on.",
   "keywords": [
@@ -40,16 +40,16 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@wrongstack/core": "0.301.0",
-    "@wrongstack/kanban": "0.301.0",
-    "@wrongstack/mcp": "0.301.0",
-    "@wrongstack/requirement-intake": "0.301.0",
-    "@wrongstack/techstack": "0.301.0",
-    "@wrongstack/sage": "0.301.0",
-    "@wrongstack/providers": "0.301.0",
-    "@wrongstack/runtime": "0.301.0",
-    "@wrongstack/sdd": "0.301.0",
-    "@wrongstack/tools": "0.301.0"
+    "@wrongstack/core": "0.302.0",
+    "@wrongstack/mcp": "0.302.0",
+    "@wrongstack/techstack": "0.302.0",
+    "@wrongstack/kanban": "0.302.0",
+    "@wrongstack/runtime": "0.302.0",
+    "@wrongstack/sage": "0.302.0",
+    "@wrongstack/providers": "0.302.0",
+    "@wrongstack/requirement-intake": "0.302.0",
+    "@wrongstack/tools": "0.302.0",
+    "@wrongstack/sdd": "0.302.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",