@wrongstack/cli 0.301.0 → 0.302.0

package/dist/{auth-JASC4K3F.js → auth-PJD3JRH2.js}

@@ -13,10 +13,10 @@ import {
   runOAuthLoginKind,
   runOAuthLoginMenu,
   validateFamily
-} from "./chunk-O7XNGCRT.js";
+} from "./chunk-3MOUBRKZ.js";
 import {
   parseAuthFlags
-} from "./chunk-MHF2IJDE.js";
+} from "./chunk-MT6FGXO3.js";
 import "./chunk-ETOEGL3V.js";
 import "./chunk-PYTFS4MC.js";
 import {
@@ -614,4 +614,4 @@ async function runAuthRemove(deps, providerId) {
 export {
   authCmd
 };
-//# sourceMappingURL=auth-JASC4K3F.js.map
+//# sourceMappingURL=auth-PJD3JRH2.js.map

package/dist/boot/dispatch-webui.d.ts

@@ -1,19 +1,4 @@
-/**
- * WebUI dispatch — extracted from the tail of `execute()`.
- *
- * PR 6 of Issue #29 (partial). The TUI-vs-REPL-vs-WebUI fork at the
- * end of `execute()` is a ~1,600-line `if/else if/else if/else`
- * chain. The WebUI branch is the most self-contained of the four: it
- * constructs a `runWebUI` options object from already-available deps,
- * wires SIGINT handling, and returns an exit code. Extracting it
- * first lets `execute()` shrink by ~100 lines and isolates the
- * WebUI-specific wiring (port resolution, browser banner and autonomy
- * forwarding) in a single named module.
- *
- * The TUI branch (~1,388 lines) and the single-shot branch are left
- * inline — they are too deeply coupled to local mutable state for a
- * single-PR extraction.
- */
+import { type WebuiSessionChildOptions } from './webui-session-child.js';
 import type { Agent } from '@wrongstack/core/agent';
 import type { BrainArbiter } from '@wrongstack/core/coordination';
 import type { JournalEntry } from '@wrongstack/core/goal';
@@ -99,6 +84,8 @@ export interface WebUIDispatchContext {
     }) => Promise<string>) | undefined;
     /** Live fleet budget for WebUI concurrency/spawn gauges (issue #323). */
     getFleetBudget?: CliWebUIOptions['getFleetBudget'];
+    /** Internal one-session child launch metadata, when --webui-session-child is active. */
+    webuiSessionChild?: WebuiSessionChildOptions | undefined;
 }
 /**
  * Run the WebUI server and block until it shuts down.

package/dist/boot/webui-session-child.d.ts

@@ -0,0 +1,91 @@
+export declare const WEBUI_SESSION_CHILD_PROTOCOL_VERSION = 1;
+export declare const WEBUI_SESSION_CHILD_CAPABILITIES: readonly ['multi-session-child', 'single-port-http-ws', 'session-affinity', 'graceful-shutdown'];
+export type WebuiSessionChildPhase = 'validate_args' | 'boot_config' | 'claim_session' | 'create_session' | 'resume_session' | 'bind_port' | 'register_instance' | 'register_session' | 'start_server' | 'unknown';
+export interface WebuiSessionChildOptions {
+    enabled: boolean;
+    projectRoot: string;
+    workingDir: string;
+    sessionId?: string | undefined;
+    resume: boolean;
+    host?: string | undefined;
+    port?: number | undefined;
+    token?: string | undefined;
+    publicUrl?: string | undefined;
+    publicWsUrl?: string | undefined;
+    requireToken?: boolean | undefined;
+    strictPort: boolean;
+    parentPid: number;
+    parentShellId: string;
+    runtimeId: string;
+    readyFile: string;
+    attachable: boolean;
+    protocolVersion: number;
+}
+export interface WebuiSessionChildReadyPayload {
+    type: 'webui.session_child.ready';
+    protocolVersion: number;
+    runtime: {
+        role: 'session-child';
+        runtimeId: string;
+        pid: number;
+        parentPid: number;
+        parentShellId: string;
+        startedAt: string;
+    };
+    project: {
+        projectRoot: string;
+        workingDir: string;
+        projectSlug: string;
+        projectName: string;
+    };
+    session: {
+        sessionId: string;
+        created: boolean;
+        resumed: boolean;
+        title?: string | undefined;
+        provider?: string | undefined;
+        model?: string | undefined;
+    };
+    endpoint: {
+        surface: 'webui';
+        host: string;
+        httpPort: number;
+        url: string;
+        publicUrl?: string | undefined;
+        publicWsUrl?: string | undefined;
+        requireToken: boolean;
+        auth: {
+            scheme: 'registry-token' | 'cookie-bootstrap' | 'none';
+            tokenPresent: boolean;
+            token?: string | undefined;
+        };
+    };
+    registry: {
+        webuiInstanceRegistered: boolean;
+        sessionRegistered: boolean;
+    };
+    capabilities: string[];
+}
+export interface WebuiSessionChildErrorPayload {
+    type: 'webui.session_child.error';
+    protocolVersion: number;
+    runtimeId?: string | undefined;
+    parentShellId?: string | undefined;
+    pid: number;
+    phase: WebuiSessionChildPhase;
+    recoverable: boolean;
+    message: string;
+    details?: Record<string, unknown> | undefined;
+}
+export declare function parseWebuiSessionChildOptions(flags: Record<string, string | boolean>): WebuiSessionChildOptions | null;
+export declare function writeWebuiSessionChildReady(readyFile: string, payload: WebuiSessionChildReadyPayload): Promise<void>;
+export declare function writeWebuiSessionChildError(readyFile: string, input: {
+    protocolVersion?: number | undefined;
+    runtimeId?: string | undefined;
+    parentShellId?: string | undefined;
+    phase: WebuiSessionChildPhase;
+    recoverable: boolean;
+    error: unknown;
+    details?: Record<string, unknown> | undefined;
+}): Promise<void>;
+//# sourceMappingURL=webui-session-child.d.ts.map

package/dist/{chunk-O7XNGCRT.js → chunk-3MOUBRKZ.js}

@@ -1,7 +1,7 @@
 import {
   LOCAL_LLM_PRESETS,
   runLiveProviderPicker
-} from "./chunk-MHF2IJDE.js";
+} from "./chunk-MT6FGXO3.js";
 import {
   openBrowser,
   runCodexOAuthLogin,
@@ -1335,4 +1335,4 @@ export {
   addKeyForProvider,
   runAuthLocal
 };
-//# sourceMappingURL=chunk-O7XNGCRT.js.map
+//# sourceMappingURL=chunk-3MOUBRKZ.js.map

package/dist/{chunk-MHF2IJDE.js → chunk-MT6FGXO3.js}

@@ -33,6 +33,7 @@ var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
   "prompt",
   "metrics",
   "webui",
+  "webui-session-child",
   "simpleui",
   "full-auto",
   "desktop",
@@ -137,6 +138,7 @@ function parseArgs(argv) {
 }
 function normalizeSurfaceAliases(flags, positional) {
   if (flags["simpleui"]) flags["webui"] = true;
+  if (flags["webui-session-child"]) flags["webui"] = true;
   const first = positional[0];
   if (first === "simpleui") {
     flags["simpleui"] = true;
@@ -1037,4 +1039,4 @@ export {
   runLiveProviderPicker,
   runPicker
 };
-//# sourceMappingURL=chunk-MHF2IJDE.js.map
+//# sourceMappingURL=chunk-MT6FGXO3.js.map

package/dist/chunk-PFVVUH5B.js

@@ -0,0 +1,127 @@
+
+// src/boot/webui-session-child.ts
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { atomicWrite, toErrorMessage } from "@wrongstack/core/utils";
+var WEBUI_SESSION_CHILD_PROTOCOL_VERSION = 1;
+var WEBUI_SESSION_CHILD_CAPABILITIES = [
+  "multi-session-child",
+  "single-port-http-ws",
+  "session-affinity",
+  "graceful-shutdown"
+];
+function flagValue(flags, names) {
+  for (const name of names) {
+    if (!Object.hasOwn(flags, name)) continue;
+    const value = flags[name];
+    if (typeof value === "string" && value.trim() !== "") return value.trim();
+    throw new Error(`--${name} requires a value`);
+  }
+  return void 0;
+}
+function boolFlag(flags, names) {
+  for (const name of names) {
+    if (!Object.hasOwn(flags, name)) continue;
+    const value = flags[name];
+    if (typeof value === "boolean") return value;
+    const normalized = String(value).trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized)) return true;
+    if (["0", "false", "no", "off"].includes(normalized)) return false;
+    throw new Error(`--${name} must be a boolean value`);
+  }
+  return void 0;
+}
+function parsePositiveInteger(value, label) {
+  if (value === void 0) throw new Error(`${label} is required`);
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`${label} must be a positive integer`);
+  return parsed;
+}
+function parsePort(value) {
+  if (value === void 0) return void 0;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new Error("--port must be a port between 1 and 65535");
+  }
+  return parsed;
+}
+function requiredString(value, label) {
+  if (!value || value.trim() === "") throw new Error(`${label} is required`);
+  return value.trim();
+}
+function requireAbsolutePath(value, label) {
+  const resolved = requiredString(value, label);
+  if (!path.isAbsolute(resolved)) throw new Error(`${label} must be an absolute path`);
+  return path.resolve(resolved);
+}
+function parseWebuiSessionChildOptions(flags) {
+  if (flags["webui-session-child"] !== true) return null;
+  const projectRoot = requireAbsolutePath(flagValue(flags, ["project-root"]), "--project-root");
+  const workingDir = requireAbsolutePath(flagValue(flags, ["working-dir"]), "--working-dir");
+  const relativeWorkingDir = path.relative(projectRoot, workingDir);
+  if (relativeWorkingDir.startsWith("..") || path.isAbsolute(relativeWorkingDir)) {
+    throw new Error("--working-dir must be inside --project-root");
+  }
+  const sessionId = flagValue(flags, ["session-id"]);
+  const resume = boolFlag(flags, ["resume"]) ?? false;
+  if (sessionId && !resume) throw new Error("--session-id requires --resume");
+  if (resume && !sessionId) throw new Error("--resume requires --session-id in child mode");
+  const host = flagValue(flags, ["webui-host", "host"]);
+  const port = parsePort(flagValue(flags, ["webui-port", "http-port", "port", "ws-port"]));
+  const token = flagValue(flags, ["webui-token", "token"]);
+  const publicUrl = flagValue(flags, ["webui-public-url", "public-url"]);
+  const publicWsUrl = flagValue(flags, ["webui-public-ws-url", "public-ws-url"]);
+  const requireToken = boolFlag(flags, ["webui-require-token", "require-token"]);
+  return {
+    enabled: true,
+    projectRoot,
+    workingDir,
+    ...sessionId ? { sessionId } : {},
+    resume,
+    ...host ? { host } : {},
+    ...port !== void 0 ? { port } : {},
+    ...token ? { token } : {},
+    ...publicUrl ? { publicUrl } : {},
+    ...publicWsUrl ? { publicWsUrl } : {},
+    ...requireToken !== void 0 ? { requireToken } : {},
+    strictPort: boolFlag(flags, ["strict-port"]) ?? false,
+    parentPid: parsePositiveInteger(flagValue(flags, ["parent-pid"]), "--parent-pid"),
+    parentShellId: requiredString(flagValue(flags, ["parent-shell-id"]), "--parent-shell-id"),
+    runtimeId: requiredString(flagValue(flags, ["runtime-id"]), "--runtime-id"),
+    readyFile: requireAbsolutePath(flagValue(flags, ["ready-file"]), "--ready-file"),
+    attachable: boolFlag(flags, ["attachable"]) ?? true,
+    protocolVersion: parsePositiveInteger(
+      flagValue(flags, ["protocol-version"]) ?? String(WEBUI_SESSION_CHILD_PROTOCOL_VERSION),
+      "--protocol-version"
+    )
+  };
+}
+async function writeWebuiSessionChildReady(readyFile, payload) {
+  await fs.mkdir(path.dirname(readyFile), { recursive: true });
+  await atomicWrite(readyFile, `${JSON.stringify(payload, null, 2)}
+`, { mode: 384 });
+}
+async function writeWebuiSessionChildError(readyFile, input) {
+  const payload = {
+    type: "webui.session_child.error",
+    protocolVersion: input.protocolVersion ?? WEBUI_SESSION_CHILD_PROTOCOL_VERSION,
+    ...input.runtimeId ? { runtimeId: input.runtimeId } : {},
+    ...input.parentShellId ? { parentShellId: input.parentShellId } : {},
+    pid: process.pid,
+    phase: input.phase,
+    recoverable: input.recoverable,
+    message: toErrorMessage(input.error),
+    ...input.details ? { details: input.details } : {}
+  };
+  await fs.mkdir(path.dirname(readyFile), { recursive: true });
+  await atomicWrite(readyFile, `${JSON.stringify(payload, null, 2)}
+`, { mode: 384 });
+}
+
+export {
+  WEBUI_SESSION_CHILD_CAPABILITIES,
+  parseWebuiSessionChildOptions,
+  writeWebuiSessionChildReady,
+  writeWebuiSessionChildError
+};
+//# sourceMappingURL=chunk-PFVVUH5B.js.map

package/dist/cli-context.d.ts

@@ -13,6 +13,7 @@
  * Returns a `CliContext` object with all the dependencies the rest of
  * main() needs, or a numeric exit code when a short-circuit fires.
  */
+import { type WebuiSessionChildOptions } from './boot/webui-session-child.js';
 import { wireContainer } from './boot/container-wiring.js';
 import type { EventBus } from '@wrongstack/core/kernel';
 import type { ConfigStore } from '@wrongstack/core/types';
@@ -22,6 +23,7 @@ export interface CliContext extends BootContext {
     events: EventBus;
     container: ReturnType<typeof wireContainer>['container'];
     configStore: ConfigStore;
+    webuiSessionChild?: WebuiSessionChildOptions | undefined;
 }
 /**
  * Run all pre-boot and boot-phase setup. Returns a `CliContext` on success,

package/dist/{cli-main-XWC57MGE.js → cli-main-EOJ74CI4.js}

@@ -80,11 +80,11 @@ import {
   runClaudeOAuthLogin,
   runCopilotOAuthLogin,
   validateFamily
-} from "./chunk-O7XNGCRT.js";
+} from "./chunk-3MOUBRKZ.js";
 import {
   LOCAL_LLM_PRESETS,
   parseSpawnFlags
-} from "./chunk-MHF2IJDE.js";
+} from "./chunk-MT6FGXO3.js";
 import {
   buildPickableProviders,
   visibleModelIds
@@ -30335,7 +30335,8 @@ async function runInteractive(cliCtx) {
     events,
     container,
     configStore,
-    updateInfo
+    updateInfo,
+    webuiSessionChild
   } = cliCtx;
   const profileConfigPath = activeProfileConfigPath(wpaths, config);
   const modeStore = container.resolve(TOKENS9.ModeStore);
@@ -31011,7 +31012,7 @@ async function runInteractive(cliCtx) {
     onEvent: evOn
   });
   const savedProviderCfg = config.providers?.[config.provider];
-  const { execute } = await import("./execution-LHMSMDHB.js");
+  const { execute } = await import("./execution-CQ772VPS.js");
   const stopHeapWatchdog = startSharedHeapWatchdog({
     collectStats: () => {
       const hqQueue = hqPublisherRef.current?.getQueueStats();
@@ -31069,6 +31070,7 @@ async function runInteractive(cliCtx) {
         projectRoot,
         flags,
         positional,
+        webuiSessionChild,
         // Forward preflight's update-info so the TUI banner can render
         // the "(update available: v…)" indicator next to the version
         // chip. May be undefined (e.g. when the registry check was
@@ -31243,4 +31245,4 @@ export {
   CLI_VERSION,
   runInteractive
 };
-//# sourceMappingURL=cli-main-XWC57MGE.js.map
+//# sourceMappingURL=cli-main-EOJ74CI4.js.map

package/dist/execute-deps.d.ts

@@ -15,6 +15,7 @@ import type { JournalEntry } from '@wrongstack/core/goal';
 import type { EventBus } from '@wrongstack/core/kernel';
 import type { SlashCommandRegistry } from '@wrongstack/core/registry';
 import type { QueueStore } from '@wrongstack/core/storage';
+import type { WebuiSessionChildOptions } from './boot/webui-session-child.js';
 import type { AttachmentStore, AutonomyStage, Config, ConfigStore, MemoryPort, Message, ModelsRegistry, ModeStore, PromptLoader, ProviderConfig, ResolvedProvider, SessionEvent, SessionStore, SessionWriter, SkillLoader, TokenCounter } from '@wrongstack/core/types';
 import type { WstackPaths } from '@wrongstack/core/utils';
 import type { MCPRegistry } from '@wrongstack/mcp';
@@ -98,6 +99,8 @@ export interface CoreDeps {
      * is consumed; the TUI reuses the result without making a second request.
      */
     updateInfo?: UpdateInfo | undefined;
+    /** Internal one-session WebUI child launch metadata, when --webui-session-child is active. */
+    webuiSessionChild?: WebuiSessionChildOptions | undefined;
 }
 /** Session + state stores. */
 export interface SessionDeps {

package/dist/{execution-LHMSMDHB.js → execution-CQ772VPS.js}

@@ -25,6 +25,11 @@ import {
   trySaveSpecFromAIOutput,
   trySaveTasksFromAIOutput
 } from "./chunk-XTIXVJXP.js";
+import {
+  WEBUI_SESSION_CHILD_CAPABILITIES,
+  writeWebuiSessionChildError,
+  writeWebuiSessionChildReady
+} from "./chunk-PFVVUH5B.js";
 import {
   theme
 } from "./chunk-QD544J2B.js";
@@ -47,7 +52,7 @@ import {
 import "./chunk-7OCVIDC7.js";
 
 // src/execution.ts
-import * as path11 from "node:path";
+import * as path12 from "node:path";
 import { effectiveFallbackChain as effectiveFallbackChain2, setQueuedMessagesSnapshot as setQueuedMessagesSnapshot2 } from "@wrongstack/core/agent";
 import { attachTodosCheckpoint as attachTodosCheckpoint2 } from "@wrongstack/core/storage";
 import { normalizeTokenSavingTier as normalizeTokenSavingTier2 } from "@wrongstack/core/types";
@@ -155,6 +160,7 @@ async function runTuiDispatch(options) {
 }
 
 // src/boot/dispatch-webui.ts
+import * as path from "node:path";
 import { color as color2 } from "@wrongstack/core/utils";
 async function runWebUIDispatch(ctx) {
   const {
@@ -190,12 +196,14 @@ async function runWebUIDispatch(ctx) {
     agentTranscripts,
     sddSubagentFactory,
     onKanbanDispatch,
-    getFleetBudget
+    getFleetBudget,
+    webuiSessionChild
   } = ctx;
-  const isSimpleUi = flags["simpleui"] === true;
+  const isSessionChild = Boolean(webuiSessionChild);
+  const isSimpleUi = !isSessionChild && flags["simpleui"] === true;
   agent.disableInteractiveConfirmation();
   renderer.setSilent(true);
-  const { runWebUI } = await import("./webui-server-DD35QFNO.js");
+  const { runWebUI } = await import("./webui-server-NFNRGNNT.js");
   const flagValue = (names) => {
     for (const name of names) {
       if (!Object.hasOwn(flags, name)) continue;
@@ -238,22 +246,32 @@ async function runWebUIDispatch(ctx) {
   let webuiRequireToken;
   let frontendDistDir;
   try {
-    webuiHost = flagValue(["webui-host", "host"]) ?? process.env["WEBUI_HOST"] ?? process.env["WS_HOST"] ?? "127.0.0.1";
+    webuiHost = webuiSessionChild?.host ?? flagValue(["webui-host", "host"]) ?? process.env["WEBUI_HOST"] ?? process.env["WS_HOST"] ?? "127.0.0.1";
     const defaultPort = isSimpleUi ? 3466 : 3456;
-    webuiPort = parsePort(
+    webuiPort = webuiSessionChild?.port ?? parsePort(
       flagValue(["webui-port", "http-port", "port", "ws-port"]) ?? process.env["WEBUI_PORT"] ?? process.env["PORT"] ?? process.env["WS_PORT"],
       defaultPort,
       "--port"
     );
-    webuiAccessToken = flagValue(["webui-token"]) ?? process.env["WEBUI_TOKEN"] ?? process.env["WEBUI_AUTH_TOKEN"];
-    webuiPublicUrl = flagValue(["webui-public-url", "public-url"]) ?? process.env["WEBUI_PUBLIC_URL"];
-    webuiPublicWsUrl = flagValue(["webui-public-ws-url", "public-ws-url"]) ?? process.env["WEBUI_PUBLIC_WS_URL"];
-    webuiRequireToken = flagBoolean(["webui-require-token", "require-token"]) ?? envFlag("WEBUI_REQUIRE_TOKEN");
+    webuiAccessToken = webuiSessionChild?.token ?? flagValue(["webui-token"]) ?? process.env["WEBUI_TOKEN"] ?? process.env["WEBUI_AUTH_TOKEN"];
+    webuiPublicUrl = webuiSessionChild?.publicUrl ?? flagValue(["webui-public-url", "public-url"]) ?? process.env["WEBUI_PUBLIC_URL"];
+    webuiPublicWsUrl = webuiSessionChild?.publicWsUrl ?? flagValue(["webui-public-ws-url", "public-ws-url"]) ?? process.env["WEBUI_PUBLIC_WS_URL"];
+    webuiRequireToken = webuiSessionChild?.requireToken ?? flagBoolean(["webui-require-token", "require-token"]) ?? envFlag("WEBUI_REQUIRE_TOKEN");
     if (isSimpleUi) {
       const { ensureSimpleUiDistDir } = await import("./simpleui-dist-JIFGUJO7.js");
       frontendDistDir = await ensureSimpleUiDistDir();
     }
   } catch (err) {
+    if (webuiSessionChild) {
+      await writeWebuiSessionChildError(webuiSessionChild.readyFile, {
+        protocolVersion: webuiSessionChild.protocolVersion,
+        runtimeId: webuiSessionChild.runtimeId,
+        parentShellId: webuiSessionChild.parentShellId,
+        phase: "validate_args",
+        recoverable: false,
+        error: err
+      }).catch(() => void 0);
+    }
     renderer.setSilent(false);
     renderer.writeInfo(color2.red(`  ${err instanceof Error ? err.message : String(err)}`));
     return 1;
@@ -271,9 +289,11 @@ async function runWebUIDispatch(ctx) {
     publicUrl: webuiPublicUrl,
     publicWsUrl: webuiPublicWsUrl,
     requireToken: webuiRequireToken,
+    strictPort: webuiSessionChild?.strictPort,
     projectRoot,
     appConfig: config,
-    open: !!flags.open,
+    open: webuiSessionChild ? false : !!flags.open,
+    webuiSessionChild,
     agentTranscripts,
     hqAllowExec: flagBoolean(["hq-allow-exec"]) ?? false,
     modelsRegistry,
@@ -316,7 +336,50 @@ async function runWebUIDispatch(ctx) {
     // listening, using the RESOLVED port. Requested ports auto-advance past
     // busy ports inside runWebUI, so a banner printed up-front lies whenever
     // the default when it is taken (a second instance, leftover socket).
-    onListening: ({ url }) => {
+    onListening: ({ httpPort, host, url, authToken }) => {
+      if (webuiSessionChild) {
+        void writeWebuiSessionChildReady(webuiSessionChild.readyFile, {
+          type: "webui.session_child.ready",
+          protocolVersion: webuiSessionChild.protocolVersion,
+          runtime: {
+            role: "session-child",
+            runtimeId: webuiSessionChild.runtimeId,
+            pid: process.pid,
+            parentPid: webuiSessionChild.parentPid,
+            parentShellId: webuiSessionChild.parentShellId,
+            startedAt: (/* @__PURE__ */ new Date()).toISOString()
+          },
+          project: {
+            projectRoot,
+            workingDir: webuiSessionChild.workingDir,
+            projectSlug: path.basename(projectRoot) || projectRoot,
+            projectName: path.basename(projectRoot) || projectRoot
+          },
+          session: {
+            sessionId: session.id,
+            created: !webuiSessionChild.resume,
+            resumed: webuiSessionChild.resume,
+            provider: config.provider,
+            model: config.model
+          },
+          endpoint: {
+            surface: "webui",
+            host,
+            httpPort,
+            url,
+            ...webuiPublicUrl ? { publicUrl: webuiPublicUrl } : {},
+            ...webuiPublicWsUrl ? { publicWsUrl: webuiPublicWsUrl } : {},
+            requireToken: webuiRequireToken,
+            auth: authToken ? { scheme: "registry-token", tokenPresent: true, token: authToken } : { scheme: "none", tokenPresent: false }
+          },
+          registry: {
+            webuiInstanceRegistered: true,
+            sessionRegistered: true
+          },
+          capabilities: [...WEBUI_SESSION_CHILD_CAPABILITIES]
+        }).catch(() => void 0);
+        return;
+      }
       const surface = isSimpleUi ? "SimpleUI" : "WebUI";
       renderer.writeInfo(
         `  \u2726 ${terminalText(surface, "success", { bold: true })} ${terminalText("running \u2192", "muted")} ${terminalLink(url)}`
@@ -346,6 +409,16 @@ async function runWebUIDispatch(ctx) {
       );
       resolve3(0);
     }).catch((err) => {
+      if (webuiSessionChild) {
+        void writeWebuiSessionChildError(webuiSessionChild.readyFile, {
+          protocolVersion: webuiSessionChild.protocolVersion,
+          runtimeId: webuiSessionChild.runtimeId,
+          parentShellId: webuiSessionChild.parentShellId,
+          phase: "start_server",
+          recoverable: false,
+          error: err
+        }).catch(() => void 0);
+      }
       renderer.setSilent(false);
       renderer.writeInfo(
         color2.red(
@@ -362,8 +435,8 @@ async function runWebUIDispatch(ctx) {
 function resolveExecutionMode(positional, flags) {
   const prompt = typeof flags["prompt"] === "string" ? flags["prompt"] : "";
   if (positional.length > 0 || prompt.length > 0) return "single-shot";
-  if (flags.tui && flags["no-tui"] !== true && !flags.webui) return "tui";
-  if (flags.webui) return "webui";
+  if (flags.tui && flags["no-tui"] !== true && !flags.webui && !flags["webui-session-child"]) return "tui";
+  if (flags.webui || flags["webui-session-child"]) return "webui";
   return "repl";
 }
 
@@ -503,7 +576,7 @@ function createTuiCoordinatorCallbacks({
 }
 
 // src/boot/tui-coordinator-setup.ts
-import * as path from "node:path";
+import * as path2 from "node:path";
 import { AutonomousCoordinator } from "@wrongstack/core/coordination";
 function setupAutonomousCoordinator(ctx) {
   const { state, events, context, wpaths, mailbox, director, getDirector, coordinatorController, onCoordinatorStopSetter } = ctx;
@@ -512,7 +585,7 @@ function setupAutonomousCoordinator(ctx) {
     const currentDirector = getDirector?.() ?? director;
     if (!currentDirector) return null;
     const transcript = context.session.transcriptPath;
-    const sessionDir = transcript ? path.dirname(transcript) : wpaths.projectDir;
+    const sessionDir = transcript ? path2.dirname(transcript) : wpaths.projectDir;
     const llmProvider = {
       decide: async (prompt) => {
         const sysPrompt = [
@@ -723,10 +796,10 @@ function wireGoal(events) {
 }
 
 // src/boot/tui-live-sessions.ts
-import * as path2 from "node:path";
+import * as path3 from "node:path";
 async function getLiveSessions(ctx) {
   const { SessionRegistry } = await import("@wrongstack/core/storage");
-  const globalRoot = path2.dirname(ctx.state.wpaths.globalConfig);
+  const globalRoot = path3.dirname(ctx.state.wpaths.globalConfig);
   const registry = new SessionRegistry(globalRoot);
   const sessions = await registry.list();
   return sessions.filter((s) => s.status !== "stale").map((s) => ({
@@ -756,7 +829,7 @@ function onSwitchToSession(ctx, _sessionId, targetRoot, projectName) {
 }
 
 // src/boot/tui-project-picker-callback.ts
-import * as path3 from "node:path";
+import * as path4 from "node:path";
 import { color as color3 } from "@wrongstack/core/utils";
 async function getProjectPickerItems(ctx) {
   const { buildPickerItems } = await import("./project-picker-BOCWHBXP.js");
@@ -770,7 +843,7 @@ async function onProjectSelect(ctx, slug, kind) {
   try {
     if (kind === "action") {
       if (slug === "new-session") {
-        const name = path3.basename(state.projectRoot) || state.projectRoot;
+        const name = path4.basename(state.projectRoot) || state.projectRoot;
         const err2 = await switchProjectInPlace2(state.projectRoot, name);
         if (err2) renderer.write(color3.red(`Project switch failed: ${err2}
 `));
@@ -781,8 +854,8 @@ async function onProjectSelect(ctx, slug, kind) {
     const manifest = await loadManifest(state.wpaths.globalConfig);
     const project = manifest.projects.find((p) => p.slug === slug);
     if (!project) return;
-    const targetRoot = path3.resolve(project.root);
-    if (path3.resolve(state.projectRoot) === targetRoot) return;
+    const targetRoot = path4.resolve(project.root);
+    if (path4.resolve(state.projectRoot) === targetRoot) return;
     const fleetStatus = director?.status();
     const fleetRunning = fleetStatus?.subagents.filter((a) => a.status === "running").length ?? 0;
     const eternalActive = getEternalEngine?.()?.currentState === "running";
@@ -820,7 +893,7 @@ ${parts.join("\n")}
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
 import * as fs from "node:fs/promises";
-import * as path4 from "node:path";
+import * as path5 from "node:path";
 import { color as color4 } from "@wrongstack/core/utils";
 async function handleProjectSwitchSpawn(opts) {
   const PROJECT_SWITCH_EXIT_CODE = 42;
@@ -833,8 +906,8 @@ async function handleProjectSwitchSpawn(opts) {
   try {
     const req = createRequire(import.meta.url);
     const pkgPath = req.resolve("@wrongstack/cli/package.json");
-    const pkgDir = path4.dirname(pkgPath);
-    cliPath = path4.join(pkgDir, "dist", "index.js");
+    const pkgDir = path5.dirname(pkgPath);
+    cliPath = path5.join(pkgDir, "dist", "index.js");
     await fs.access(cliPath);
   } catch {
     cliPath = process.argv[1] ?? "";
@@ -870,7 +943,7 @@ async function handleProjectSwitchSpawn(opts) {
 
 // src/boot/tui-project-switch.ts
 import * as fs2 from "node:fs/promises";
-import * as path5 from "node:path";
+import * as path6 from "node:path";
 import {
   DefaultSystemPromptBuilder,
   setQueuedMessagesSnapshot
@@ -891,7 +964,7 @@ async function switchProjectInPlace(ctx, targetRoot, displayName) {
     skillLoader,
     attachTodosCheckpoint: attachTodosCheckpoint3
   } = ctx;
-  const resolved = path5.resolve(targetRoot);
+  const resolved = path6.resolve(targetRoot);
   const stat2 = await fs2.stat(resolved).catch(() => null);
   if (!stat2?.isDirectory()) return `Cannot switch: not a directory: ${resolved}`;
   const oldWriter = context.session;
@@ -930,7 +1003,7 @@ async function switchProjectInPlace(ctx, targetRoot, displayName) {
     await state.activateSessionIdentity(nextWriter.id, {
       projectSlug: nextWpaths.projectSlug,
       projectRoot: resolved,
-      projectName: displayName || path5.basename(resolved),
+      projectName: displayName || path6.basename(resolved),
       workingDir: resolved
     });
   } catch (err) {
@@ -1067,7 +1140,7 @@ async function onSDDOutput(output) {
 }
 
 // src/boot/tui-session-resume.ts
-import * as path6 from "node:path";
+import * as path7 from "node:path";
 import { attachTodosCheckpoint, loadTodosCheckpoint } from "@wrongstack/core/storage";
 import { sessionScopedPath as sessionScopedPath2 } from "@wrongstack/core/utils";
 async function resumeSession(ctx, sessionId) {
@@ -1093,7 +1166,7 @@ async function resumeSession(ctx, sessionId) {
   }
   try {
     const { SessionRegistry } = await import("@wrongstack/core/storage");
-    const registry = new SessionRegistry(path6.dirname(state.wpaths.globalConfig));
+    const registry = new SessionRegistry(path7.dirname(state.wpaths.globalConfig));
     const live = (await registry.list()).find(
       (s) => s.sessionId === canonicalSessionId && s.status !== "stale" && s.pid !== process.pid
     );
@@ -1304,7 +1377,7 @@ async function resumeSession(ctx, sessionId) {
 
 // src/boot/tui-settings-adapter.ts
 import * as fs3 from "node:fs/promises";
-import * as path7 from "node:path";
+import * as path8 from "node:path";
 import { decryptConfigSecrets, encryptConfigSecrets, noOpVault } from "@wrongstack/core/security";
 import { normalizeTokenSavingTier, resolveFleetChatVerbosity } from "@wrongstack/core/types";
 import { atomicWrite, deepMerge } from "@wrongstack/core/utils";
@@ -1595,7 +1668,7 @@ function createSettingsAdapter(ctx) {
         const isProjectTarget = actualTarget === wpaths.inProjectConfig;
         const toWrite = isProjectTarget ? filterSafeForProject(mergedToWrite) : mergedToWrite;
         const encrypted = encryptConfigSecrets(toWrite, noOpVault);
-        await fs3.mkdir(path7.dirname(actualTarget), { recursive: true });
+        await fs3.mkdir(path8.dirname(actualTarget), { recursive: true });
         await atomicWrite(actualTarget, JSON.stringify(encrypted, null, 2), { mode: 384 });
         const currentConfig = configStore.get();
         const nextModelRuntime = {
@@ -2520,7 +2593,7 @@ function createChimeraWorkRegistry() {
 
 // src/execution-chimera-cascade.ts
 import * as fsp from "node:fs/promises";
-import * as path8 from "node:path";
+import * as path9 from "node:path";
 import { emitReviewIfChanged } from "@wrongstack/core/plugin";
 
 // src/chimera-review-task.ts
@@ -2883,7 +2956,7 @@ async function maybeReReviewCascade({
       const reReadFiles = [];
       for (const f of bundle.files) {
         try {
-          const absPath = path8.join(bundle.cwd, f.path);
+          const absPath = path9.join(bundle.cwd, f.path);
           const content = await fsp.readFile(absPath, "utf8");
           reReadFiles.push({ path: f.path, status: "modified", content });
         } catch {
@@ -2952,7 +3025,7 @@ async function maybeReReviewCascade({
 
 // src/execution-chimera-review.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import path9 from "node:path";
+import path10 from "node:path";
 import { effectiveFallbackChain } from "@wrongstack/core/agent";
 import {
   CHIMERA_REVIEW_PROMPT,
@@ -2965,7 +3038,7 @@ import {
 function normalizeFileKeyForCitation(raw, cwd) {
   const forward = raw.replace(/\\/g, "/").replace(/^\.\//, "");
   const isAbsolute = forward.startsWith("/") || /^[a-zA-Z]:\//.test(forward);
-  const pathMod = process.platform === "win32" ? path9.win32 : path9;
+  const pathMod = process.platform === "win32" ? path10.win32 : path10;
   const relative = isAbsolute ? pathMod.relative(cwd, forward).replace(/\\/g, "/").replace(/^\.\//, "") : forward;
   return process.platform === "win32" ? relative.toLowerCase() : relative;
 }
@@ -3163,16 +3236,16 @@ function installChimeraReviewHandler({
             const changedBasenameIndex = /* @__PURE__ */ new Map();
             for (const file of p.files) {
               const normalized = normalizeFileKeyForCitation(file.path, p.cwd);
-              const basename5 = path9.basename(file.path).toLowerCase();
-              const bucket = changedBasenameIndex.get(basename5);
+              const basename6 = path10.basename(file.path).toLowerCase();
+              const bucket = changedBasenameIndex.get(basename6);
               if (bucket) bucket.push(normalized);
-              else changedBasenameIndex.set(basename5, [normalized]);
+              else changedBasenameIndex.set(basename6, [normalized]);
             }
             const droppedCitations = citedFindings.filter((finding) => {
               const citedKey = normalizeFileKeyForCitation(finding.location.file, p.cwd);
               if (citedPaths.has(citedKey)) return false;
-              const basename5 = path9.basename(finding.location.file).toLowerCase();
-              const bucket = changedBasenameIndex.get(basename5);
+              const basename6 = path10.basename(finding.location.file).toLowerCase();
+              const bucket = changedBasenameIndex.get(basename6);
               return !(bucket && bucket.length === 1);
             });
             const effectiveHasFindings = reviewHasFindings && (parsedReview.findings.length === 0 || parsedReview.findings.length > droppedCitations.length);
@@ -3694,7 +3767,7 @@ function printBanner(renderer, projectName) {
 
 // src/repl-client-registration.ts
 import * as crypto from "node:crypto";
-import * as path10 from "node:path";
+import * as path11 from "node:path";
 import {
   getSharedProjectMailbox,
   resolveProjectDir
@@ -3707,7 +3780,7 @@ function registerReplClient(opts) {
   const hqConnection = startCliHqConnection({
     clientKind: "repl",
     projectRoot: replProjectRoot,
-    projectName: path10.basename(replProjectRoot),
+    projectName: path11.basename(replProjectRoot),
     appConfig: opts.appConfig,
     capabilities: ["telemetry.publish", "mailbox.summary"]
   });
@@ -3721,7 +3794,7 @@ function registerReplClient(opts) {
   clientMailbox.registerClient({
     clientId,
     sessionId: opts.getSessionId?.() ?? replProjectRoot,
-    name: `REPL [${path10.basename(replProjectRoot)}]`,
+    name: `REPL [${path11.basename(replProjectRoot)}]`,
     source: "repl",
     pid: process.pid
   }).then(() => {
@@ -4515,7 +4588,8 @@ async function execute(deps) {
       slashRegistry,
       tokenCounter,
       activateSessionIdentity,
-      updateInfo: initialUpdateInfo
+      updateInfo: initialUpdateInfo,
+      webuiSessionChild
     },
     session: {
       session,
@@ -4983,6 +5057,7 @@ async function execute(deps) {
         sddSubagentFactory,
         statusTracker,
         updateInfo: bootUpdateInfo,
+        webuiSessionChild,
         getFleetBudget: () => {
           const d = getDirector?.() ?? null;
           if (!d) return null;
@@ -5025,7 +5100,7 @@ async function execute(deps) {
           attachments,
           effectiveMaxContext,
           getEffectiveMaxContext,
-          projectName: path11.basename(projectRoot) || void 0,
+          projectName: path12.basename(projectRoot) || void 0,
           projectRoot,
           appConfig: config,
           getSessionId: () => agent.ctx.session?.id ?? session.id,
@@ -5084,4 +5159,4 @@ export {
   execute,
   resolveReviewerFallbackModels
 };
-//# sourceMappingURL=execution-LHMSMDHB.js.map
+//# sourceMappingURL=execution-CQ772VPS.js.map

package/dist/index.js

@@ -1,4 +1,8 @@
 #!/usr/bin/env node
+import {
+  parseWebuiSessionChildOptions,
+  writeWebuiSessionChildError
+} from "./chunk-PFVVUH5B.js";
 import {
   applySimpleUiFullAutoProfile,
   detectProjectFacts,
@@ -37,7 +41,7 @@ import {
   parseArgs,
   runPicker,
   saveToGlobalConfig
-} from "./chunk-MHF2IJDE.js";
+} from "./chunk-MT6FGXO3.js";
 import {
   isKeylessLocalProvider,
   visibleModelIds
@@ -1499,7 +1503,7 @@ function compactSingleLine(text) {
 var loaders = {
   acp: async () => (await import("./acp-DATHHPNT.js")).acpCmd,
   init: async () => (await import("./init-E2NDDOHI.js")).initCmd,
-  auth: async () => (await import("./auth-JASC4K3F.js")).authCmd,
+  auth: async () => (await import("./auth-PJD3JRH2.js")).authCmd,
   update: async () => (await import("./update-MV6TUACD.js")).updateCmd,
   sessions: async () => (await import("./sessions-config-XXN7267N.js")).sessionsCmd,
   config: async () => (await import("./sessions-config-XXN7267N.js")).configCmd,
@@ -2477,6 +2481,7 @@ var PORT_TIMEOUT_MS = 8e3;
 function shouldSkipMenu(argv, flags, positional) {
   if (flags["no-menu"] === true) return true;
   if (flags["webui"] === true) return true;
+  if (flags["webui-session-child"] === true) return true;
   if (flags["simpleui"] === true) return true;
   if (flags["hq"] === true) return true;
   if (flags["desktop"] === true) return true;
@@ -2992,6 +2997,7 @@ function bindReplayToContainer(opts) {
 // src/cli-context.ts
 import { setOAuthTokenPersister } from "@wrongstack/providers";
 import { TOKENS as TOKENS4 } from "@wrongstack/core/kernel";
+import { writeErr as writeErr4 } from "@wrongstack/core/utils";
 async function initializeCli(argv) {
   applyNodeEnvDefault();
   applySessionShellDefault();
@@ -3001,6 +3007,28 @@ async function initializeCli(argv) {
   const desktopExit = await handleDesktopShortCircuit(earlyFlags, argv);
   if (desktopExit !== null) return desktopExit;
   const { flags: _earlyForMenu, positional: _positionalForMenu } = parseArgs(argv);
+  let webuiSessionChild;
+  if (_earlyForMenu["webui-session-child"] === true) {
+    try {
+      webuiSessionChild = parseWebuiSessionChildOptions(_earlyForMenu) ?? void 0;
+    } catch (err) {
+      const readyFile = typeof _earlyForMenu["ready-file"] === "string" ? _earlyForMenu["ready-file"] : void 0;
+      if (readyFile) {
+        await writeWebuiSessionChildError(readyFile, {
+          runtimeId: typeof _earlyForMenu["runtime-id"] === "string" ? _earlyForMenu["runtime-id"] : void 0,
+          parentShellId: typeof _earlyForMenu["parent-shell-id"] === "string" ? _earlyForMenu["parent-shell-id"] : void 0,
+          phase: "validate_args",
+          recoverable: false,
+          error: err
+        }).catch(() => void 0);
+      }
+      writeErr4(
+        `WebUI session child argument error: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return 2;
+    }
+  }
   const launchMenuReader = new ReadlineInputReader();
   let menuResult;
   try {
@@ -3034,7 +3062,55 @@ async function initializeCli(argv) {
       if (hqAfterMenu !== null) return hqAfterMenu;
     }
   }
-  const hqExit = await handleHqShortCircuit(parseArgs(effectiveArgv).flags);
+  const effectiveFlags = parseArgs(effectiveArgv).flags;
+  try {
+    webuiSessionChild = webuiSessionChild ?? parseWebuiSessionChildOptions(effectiveFlags) ?? void 0;
+  } catch (err) {
+    const readyFile = typeof effectiveFlags["ready-file"] === "string" ? effectiveFlags["ready-file"] : void 0;
+    if (readyFile) {
+      await writeWebuiSessionChildError(readyFile, {
+        runtimeId: typeof effectiveFlags["runtime-id"] === "string" ? effectiveFlags["runtime-id"] : void 0,
+        parentShellId: typeof effectiveFlags["parent-shell-id"] === "string" ? effectiveFlags["parent-shell-id"] : void 0,
+        phase: "validate_args",
+        recoverable: false,
+        error: err
+      }).catch(() => void 0);
+    }
+    writeErr4(`WebUI session child argument error: ${err instanceof Error ? err.message : String(err)}
+`);
+    return 2;
+  }
+  if (webuiSessionChild) {
+    try {
+      process.chdir(webuiSessionChild.workingDir);
+      if (webuiSessionChild.resume && webuiSessionChild.sessionId) {
+        const currentResume = effectiveFlags["resume"];
+        if (typeof currentResume === "string" && currentResume !== webuiSessionChild.sessionId) {
+          throw new Error(
+            `--resume ${currentResume} conflicts with --session-id ${webuiSessionChild.sessionId}`
+          );
+        }
+        if (currentResume !== webuiSessionChild.sessionId) {
+          effectiveArgv = [...effectiveArgv, "--resume", webuiSessionChild.sessionId];
+        }
+      }
+    } catch (err) {
+      await writeWebuiSessionChildError(webuiSessionChild.readyFile, {
+        protocolVersion: webuiSessionChild.protocolVersion,
+        runtimeId: webuiSessionChild.runtimeId,
+        parentShellId: webuiSessionChild.parentShellId,
+        phase: "validate_args",
+        recoverable: false,
+        error: err
+      }).catch(() => void 0);
+      writeErr4(
+        `WebUI session child argument error: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      return 2;
+    }
+  }
+  const hqExit = await handleHqShortCircuit(effectiveFlags);
   if (hqExit !== null) return hqExit;
   const ctx = await boot(effectiveArgv);
   if (typeof ctx === "number") return ctx;
@@ -3106,7 +3182,8 @@ async function initializeCli(argv) {
     updateInfo: refreshedUpdateInfo,
     events,
     container,
-    configStore
+    configStore,
+    webuiSessionChild
   };
 }
 
@@ -3114,7 +3191,7 @@ async function initializeCli(argv) {
 async function main(argv) {
   const cliCtx = await initializeCli(argv);
   if (typeof cliCtx === "number") return cliCtx;
-  const { runInteractive } = await import("./cli-main-XWC57MGE.js");
+  const { runInteractive } = await import("./cli-main-EOJ74CI4.js");
   return runInteractive(cliCtx);
 }
 

package/dist/{webui-server-DD35QFNO.js → webui-server-NFNRGNNT.js}

@@ -7,6 +7,9 @@ import {
 import {
   startCliHqConnection
 } from "./chunk-JW75HY4F.js";
+import {
+  WEBUI_SESSION_CHILD_CAPABILITIES
+} from "./chunk-PFVVUH5B.js";
 import {
   loadConfigProviders,
   mutateConfigProviders
@@ -872,7 +875,7 @@ async function runWebUI(opts) {
   const surface = opts.surface ?? "webui";
   const surfaceDefaults = surface === "simpleui" ? { http: 3466 } : { http: 3456 };
   const requestedHttpPort = opts.httpPort ?? opts.port ?? surfaceDefaults.http;
-  const strictPort = process.env["WEBUI_STRICT_PORT"] === "1" || process.env["WEBUI_STRICT_PORT"] === "true";
+  const strictPort = opts.strictPort ?? (process.env["WEBUI_STRICT_PORT"] === "1" || process.env["WEBUI_STRICT_PORT"] === "true");
   let httpPort = requestedHttpPort;
   if (!strictPort) {
     httpPort = await findFreePort(host, requestedHttpPort);
@@ -1089,24 +1092,47 @@ async function runWebUI(opts) {
       `[WebUI] Frontend not served (run \`pnpm --filter @wrongstack/webui build\`). WS bridge still active on ws://${host}:${httpPort}.`
     );
   }
+  const currentSessionId = () => opts.agent.ctx.session?.id ?? opts.session.id;
   const registryBaseDir = globalRoot;
+  let webuiInstanceRegistered = false;
   if (opts.projectRoot) {
-    registerWebuiInstance({
-      pid: process.pid,
-      surface,
-      host,
-      httpPort,
-      publicUrl,
-      projectRoot: opts.projectRoot,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      registryBaseDir,
-      // Lets a same-project TUI/REPL authenticate `POST /api/fleet/ping` now
-      // that the API requires a token on every bind (H3).
-      authToken: wsToken
-    });
+    const registration = Promise.resolve(
+      registerWebuiInstance({
+        pid: process.pid,
+        surface,
+        host,
+        httpPort,
+        publicUrl,
+        projectRoot: opts.projectRoot,
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        registryBaseDir,
+        // Lets a same-project TUI/REPL authenticate `POST /api/fleet/ping` now
+        // that the API requires a token on every bind (H3).
+        authToken: wsToken,
+        ...opts.webuiSessionChild ? {
+          role: "session-child",
+          sessionId: currentSessionId(),
+          parentPid: opts.webuiSessionChild.parentPid,
+          parentShellId: opts.webuiSessionChild.parentShellId,
+          runtimeId: opts.webuiSessionChild.runtimeId,
+          attachable: opts.webuiSessionChild.attachable,
+          lastReadyAt: (/* @__PURE__ */ new Date()).toISOString(),
+          protocolVersion: opts.webuiSessionChild.protocolVersion,
+          capabilities: [...WEBUI_SESSION_CHILD_CAPABILITIES]
+        } : {}
+      })
+    ).then(
+      (value) => value !== false,
+      () => false
+    );
+    if (opts.webuiSessionChild) {
+      webuiInstanceRegistered = await registration;
+    } else {
+      void registration;
+      webuiInstanceRegistered = true;
+    }
   }
   const eventUnsubscribers = [];
-  const currentSessionId = () => opts.agent.ctx.session?.id ?? opts.session.id;
   const sessionPayload = (payload) => {
     const provided = payload["sessionId"];
     const sessionId = typeof provided === "string" && provided.length > 0 ? provided : currentSessionId();
@@ -1406,7 +1432,14 @@ async function runWebUI(opts) {
       console.log(`[WebUI] WebSocket server running on ws://${host}:${httpPort}`);
       try {
         setupEvents();
-        opts.onListening?.({ httpPort, wsPort, host, url: accessUrl });
+        opts.onListening?.({
+          httpPort,
+          wsPort,
+          host,
+          url: accessUrl,
+          authToken: wsToken,
+          webuiInstanceRegistered
+        });
       } catch (err) {
         consoleLogger.error("setup_events_failed", { message: toErrorMessage(err) });
       }
@@ -1550,4 +1583,4 @@ async function runWebUI(opts) {
 export {
   runWebUI
 };
-//# sourceMappingURL=webui-server-DD35QFNO.js.map
+//# sourceMappingURL=webui-server-NFNRGNNT.js.map

package/dist/webui-server-options.d.ts

@@ -1,5 +1,6 @@
 import type { Agent } from '@wrongstack/core/agent';
 import type { BrainArbiter } from '@wrongstack/core/coordination';
+import type { WebuiSessionChildOptions } from './boot/webui-session-child.js';
 import type { BrainAutoRisk } from '@wrongstack/core/execution';
 import type { EventBus } from '@wrongstack/core/kernel';
 import type { TrustBoundary } from '@wrongstack/core/security';
@@ -36,6 +37,10 @@ export interface CliWebUIOptions {
     surface?: 'webui' | 'simpleui' | undefined;
     /** Fixed access token/password. Defaults to WEBUI_TOKEN or random per process. */
     accessToken?: string | undefined;
+    /** Fail instead of auto-advancing when the requested HTTP/WS port is busy. */
+    strictPort?: boolean | undefined;
+    /** Internal one-session child launch metadata for the multi-session parent shell. */
+    webuiSessionChild?: WebuiSessionChildOptions | undefined;
     /**
      * Live fleet concurrency + lifetime spawn budget for WebUI (issue #323).
      * Merged into `fleet.concurrency_update` broadcasts.
@@ -81,6 +86,8 @@ export interface CliWebUIOptions {
         wsPort: number;
         host: string;
         url: string;
+        authToken: string;
+        webuiInstanceRegistered: boolean;
     }) => void;
     modelsRegistry?: ModelsRegistry | undefined;
     globalConfigPath?: string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wrongstack/cli",
-  "version": "0.301.0",
+  "version": "0.302.0",
   "license": "MIT",
   "description": "WrongStack CLI — terminal AI coding agent with provider catalog from models.dev. Provides `wrongstack` and `wstack` binaries.",
   "keywords": [
@@ -42,30 +42,30 @@
   ],
   "dependencies": {
     "ws": "^8.21.1",
-    "@wrongstack/acp": "0.301.0",
-    "@wrongstack/mcp": "0.301.0",
-    "@wrongstack/bench": "0.301.0",
-    "@wrongstack/plug-lsp": "0.301.0",
-    "@wrongstack/kanban": "0.301.0",
-    "@wrongstack/providers": "0.301.0",
-    "@wrongstack/plugins": "0.301.0",
-    "@wrongstack/sdd": "0.301.0",
-    "@wrongstack/requirement-intake": "0.301.0",
-    "@wrongstack/runtime": "0.301.0",
-    "@wrongstack/security-scanner": "0.301.0",
-    "@wrongstack/core": "0.301.0",
-    "@wrongstack/simpleui": "0.301.0",
-    "@wrongstack/techstack": "0.301.0",
-    "@wrongstack/sage": "0.301.0",
-    "@wrongstack/telegram": "0.301.0",
-    "@wrongstack/tui": "0.301.0",
-    "@wrongstack/tools": "0.301.0",
-    "@wrongstack/webui": "0.301.0",
-    "@wrongstack/webui-hq": "0.301.0",
-    "@wrongstack/webui-server": "0.301.0"
+    "@wrongstack/plug-lsp": "0.302.0",
+    "@wrongstack/acp": "0.302.0",
+    "@wrongstack/bench": "0.302.0",
+    "@wrongstack/core": "0.302.0",
+    "@wrongstack/runtime": "0.302.0",
+    "@wrongstack/plugins": "0.302.0",
+    "@wrongstack/providers": "0.302.0",
+    "@wrongstack/mcp": "0.302.0",
+    "@wrongstack/sdd": "0.302.0",
+    "@wrongstack/kanban": "0.302.0",
+    "@wrongstack/security-scanner": "0.302.0",
+    "@wrongstack/sage": "0.302.0",
+    "@wrongstack/requirement-intake": "0.302.0",
+    "@wrongstack/techstack": "0.302.0",
+    "@wrongstack/telegram": "0.302.0",
+    "@wrongstack/webui": "0.302.0",
+    "@wrongstack/simpleui": "0.302.0",
+    "@wrongstack/tools": "0.302.0",
+    "@wrongstack/tui": "0.302.0",
+    "@wrongstack/webui-hq": "0.302.0",
+    "@wrongstack/webui-server": "0.302.0"
   },
   "optionalDependencies": {
-    "@wrongstack/desktop": "0.301.0"
+    "@wrongstack/desktop": "0.302.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",