From 503afccbe728448f124db3663515728fa7a7505c Mon Sep 17 00:00:00 2001
From: Hermes SysOp <sysop@webx11.duckdns.org>
Date: Thu, 12 Nov 2026 17:11:57 +0100
Subject: feat(newos4): re-enable the six UI modes behind an opt-in gate
 (v4.6.162)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The six interface modes (v4.6.152–156) were removed from the startup path outright in
v4.6.157 after crash reports. The crash was never reproduced: F2 in the rollback plan
(2026-11-09_224409) drove all six modes on one page in headless Chromium at 390×844 and
recorded crashes: [], pageerrors: [], heap flat at 10 MB over a 25 s idle. The two
defects the investigation DID find were fixed instead — F3 (nginx 413 on a >1 MB agent
context) and F4 (36 tool handlers where a model-supplied non-string reached
.trim/.split/.replace). v4.6.159–161 also removed the last navigator.onLine verdicts,
which is what made "it died mid-session" look like a UI crash.

So the modes come back, but only for a visitor who asks for them.

1. The gate (modules/core/terminal.js, plan Task 9)
   - Registration is now conditional:
         const _uiExp = ... URLSearchParams(location.search).get('ui') === '1'
                        || localStorage.getItem('webx11_ui_experimental') === '1';
         if (_uiExp) this._safeRegister('UIShellModule', 'UI shell');
   - Without the flag nothing changes: the shell is not registered, no mode can mount (the
     ui-*.js files all begin `if (!terminal.uiShell) return;`), no first-run picker
     appears, `data-ui-mode` is absent and `webx11.uiShell` is undefined.
   - The gate is in the bundle, so it cannot be bypassed by a stale cached ext file.

2. What was verified on the served page (v4.6.162, live Chromium)
   - Classic, no flag: NEWOS4_VERSION v4.6.162, 48 modules, uiShell undefined, 0 #ui-root,
     no #wx11-ui-picker, no data-ui-mode, terminal visible, `help` renders 18,124 chars,
     0 console warnings, 0 JS errors, 55 console messages.
   - Opt-in `?ui=1`: uiShell object, #ui-root + #ui-foot, data-ui-mode="classic",
     49 modules, picker present (opt-in only), 0 warnings, 0 JS errors.
   - All six modes driven through uiShell.apply() with a 1.2 s settle each, and back to
     classic: chat (body wx11-ui-chat, 6 mode nodes), cockpit (3), easy (4), commander (4),
     studio (3), workspace (5), classic (0). #terminal-container survived every switch,
     zero throws, heap 6.3 MB against 3.3 MB classic.
   - Served bytes identical to disk for core-bundle.js; `_uiExp` appears twice in the
     served bundle and the registration line is the guarded one (core-bundle.js:4111).

3. Not done, deliberately (plan Task 9 step 4)
   - `webx11_ui_experimental` is NOT defaulted on for new visitors. The plan asks for one
     week of clean use first, with the crash matrix re-run on the then-current bundle.

Guard for this gate: admin/scripts/verify-newos4-ui-gate.py, wired above `exit $FAIL` in
smoke-auth.sh — a bare (unconditional) registration is the failure it exists to catch.
---
 main.html                     |  6 +++---
 modules/core/core-bundle.js   | 25 ++++++++++++++++---------
 modules/core/module-loader.js |  2 +-
 modules/core/terminal.js      | 25 ++++++++++++++++---------
 4 files changed, 36 insertions(+), 22 deletions(-)

diff --git a/main.html b/main.html
index 71e1804..afde783 100644
--- a/main.html
+++ b/main.html
@@ -1350,13 +1350,13 @@
     </script>
 
     <!-- v4.5.63: A2A scratchpad fixes + agent-register arg fix -->
-<script src="modules/core/core-bundle.js?v=v4.6.161"></script>
+<script src="modules/core/core-bundle.js?v=v4.6.162"></script>
 
     <!-- Async dependency-ordered module loader now only initializes terminal and loads optional ext modules -->
-<script src="modules/core/module-loader.js?v=v4.6.161"></script>
+<script src="modules/core/module-loader.js?v=v4.6.162"></script>
 
     <!-- Critical ext bundle loads AFTER webx11 exists so registerModule calls work -->
-<script src="modules/ext/critical-ext-bundle.js?v=v4.6.161"></script>
+<script src="modules/ext/critical-ext-bundle.js?v=v4.6.162"></script>
 
 <script>
 // ═══ ONE TRUE VERSION SOURCE ═══
diff --git a/modules/core/core-bundle.js b/modules/core/core-bundle.js
index fe86c8f..d52764d 100644
--- a/modules/core/core-bundle.js
+++ b/modules/core/core-bundle.js
@@ -4093,15 +4093,22 @@ Only output XML function calls for tool tasks. If no tool is needed, answer norm
                 this._safeRegister('SmartContextModule', 'smart context');
                 this._safeRegister('SimpleGUIModule', 'simple GUI builder');
                 this._safeRegister('DebugSupervisorModule', 'debug supervisor');
-                // 2026-11-09 — UI shell DISABLED from startup (operator order after crash reports).
-                // The six interface modes (v4.6.152–156) are not in extKeys, so with the shell
-                // unregistered no mode can mount, no first-run picker appears, and `ui` does not
-                // exist: newOS4 boots to classic only. The ext ui-*.js files all begin with
-                // `if (!terminal.uiShell) return;`, so an accidental load is a no-op.
-                // Re-enable = restore this line, rebuild the bundle (scripts/rebuild-bundles.py),
-                // bump LATEST_VER + main.html ?v=, re-run admin/scripts/probe-ui-modes.py.
-                // Tracked in .hermes/plans/2026-11-09_*-newos4-ui-rollback.md
-                // this._safeRegister('UIShellModule', 'UI shell');
+                // 2026-11-12 — UI shell re-enabled BEHIND AN OPT-IN FLAG (plan Task 9, v4.6.162).
+                // v4.6.157 had disabled it outright after crash reports; the crash itself was never
+                // reproduced (F2) and the two defects the investigation did find (F3 413, F4 arg
+                // coercion) were fixed instead. So the six modes come back, but only for a visitor
+                // who asks for them: `?ui=1` on the URL or localStorage['webx11_ui_experimental']=1.
+                // Without the flag nothing changes: the shell is not registered, no mode can mount
+                // (the ui-*.js files begin with `if (!terminal.uiShell) return;`), no first-run
+                // picker appears, and `ui` does not exist. Guard: admin/scripts/verify-newos4-ui-gate.py
+                // (cron ui-gate-guard) fails if the gate is lost or the bare call returns.
+                const _uiExp = (function () {
+                    try {
+                        if (new URLSearchParams(location.search).get('ui') === '1') return true;
+                        return localStorage.getItem('webx11_ui_experimental') === '1';
+                    } catch (e) { return false; }
+                })();
+                if (_uiExp) this._safeRegister('UIShellModule', 'UI shell');
                 // v4.5.47 used to _safeRegister() seven critical ext classes here (EditorModule,
                 // ShellModule, AliasModule, FinderModule, FileManagerModule, DiffModule,
                 // BusyBoxModule). They are declared in modules/ext/critical-ext-bundle.js, which is
diff --git a/modules/core/module-loader.js b/modules/core/module-loader.js
index ce42652..06a809f 100644
--- a/modules/core/module-loader.js
+++ b/modules/core/module-loader.js
@@ -4,7 +4,7 @@
     // Core module bundle loaded synchronously in main.html.
     // This loader only handles version cache-busting, splash, terminal init, and optional ext modules.
 
-    const LATEST_VER = 'v4.6.161';
+    const LATEST_VER = 'v4.6.162';
     const CACHE = '?v=' + LATEST_VER;
     // Exposed so ext modules can register their own URL with the same cache-busting version
     // instead of an unversioned path the browser may already have cached (shell.js did).
diff --git a/modules/core/terminal.js b/modules/core/terminal.js
index 9750c24..cd7f5ae 100644
--- a/modules/core/terminal.js
+++ b/modules/core/terminal.js
@@ -1387,15 +1387,22 @@
                 this._safeRegister('SmartContextModule', 'smart context');
                 this._safeRegister('SimpleGUIModule', 'simple GUI builder');
                 this._safeRegister('DebugSupervisorModule', 'debug supervisor');
-                // 2026-11-09 — UI shell DISABLED from startup (operator order after crash reports).
-                // The six interface modes (v4.6.152–156) are not in extKeys, so with the shell
-                // unregistered no mode can mount, no first-run picker appears, and `ui` does not
-                // exist: newOS4 boots to classic only. The ext ui-*.js files all begin with
-                // `if (!terminal.uiShell) return;`, so an accidental load is a no-op.
-                // Re-enable = restore this line, rebuild the bundle (scripts/rebuild-bundles.py),
-                // bump LATEST_VER + main.html ?v=, re-run admin/scripts/probe-ui-modes.py.
-                // Tracked in .hermes/plans/2026-11-09_*-newos4-ui-rollback.md
-                // this._safeRegister('UIShellModule', 'UI shell');
+                // 2026-11-12 — UI shell re-enabled BEHIND AN OPT-IN FLAG (plan Task 9, v4.6.162).
+                // v4.6.157 had disabled it outright after crash reports; the crash itself was never
+                // reproduced (F2) and the two defects the investigation did find (F3 413, F4 arg
+                // coercion) were fixed instead. So the six modes come back, but only for a visitor
+                // who asks for them: `?ui=1` on the URL or localStorage['webx11_ui_experimental']=1.
+                // Without the flag nothing changes: the shell is not registered, no mode can mount
+                // (the ui-*.js files begin with `if (!terminal.uiShell) return;`), no first-run
+                // picker appears, and `ui` does not exist. Guard: admin/scripts/verify-newos4-ui-gate.py
+                // (cron ui-gate-guard) fails if the gate is lost or the bare call returns.
+                const _uiExp = (function () {
+                    try {
+                        if (new URLSearchParams(location.search).get('ui') === '1') return true;
+                        return localStorage.getItem('webx11_ui_experimental') === '1';
+                    } catch (e) { return false; }
+                })();
+                if (_uiExp) this._safeRegister('UIShellModule', 'UI shell');
                 // v4.5.47 used to _safeRegister() seven critical ext classes here (EditorModule,
                 // ShellModule, AliasModule, FinderModule, FileManagerModule, DiffModule,
                 // BusyBoxModule). They are declared in modules/ext/critical-ext-bundle.js, which is
-- 
cgit v1.2.3