merge: reconcile PR 40 with current lab

Integrate lab fff55a78 into PR #40 (cc25d5ba). Lab's modular email
backend/frontend, modular settings, split stylesheets (static/style.css
stays deleted), procfs compatibility, and request-scoped TurnContract
authority win; PR #40's routing classifiers, editor/email/task features,
and style.css changes are ported into lab's module and stylesheet homes.

Integration fixes:
- settings/api.js imports ui.js under its canonical versioned URL
- browser observations keep legacy CAPTCHA/access-block evidence
- artifact turns do not re-trigger broad-web research recovery
- env reference documents PR test-tool variables; page regenerated

PR #40 defects surfaced by lab gates and fixed here:
- web_fetch generic schema drops top-level anyOf (OpenAI contract);
  the compact preview contract still requires url or urls
- get_weather registered as a brokered network read
- new lazy editor modules precached for offline use
- SearXNG pin mirrored into GPU standalone compose files
- image model picker again skips offline endpoints

Tests updated where PR #40 changed behaviour on purpose, and PR tests
moved onto lab's document_source helpers.

tests/helpers/document_source.mjs

@@ -0,0 +1,32 @@
+// JS twin of tests/helpers/document_source.py: the document editor's whole
+// implementation set, so tests keep finding code as it moves out of the
+// static/js/document.js entry into static/js/document/.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const JS = join(HERE, '..', '..', 'static', 'js');
+const ENTRY = join(JS, 'document.js');
+const IMPL_DIR = join(JS, 'document');
+
+function walk(dir) {
+  return readdirSync(dir).sort().flatMap(name => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return walk(path);
+    return name.endsWith('.js') ? [path] : [];
+  });
+}
+
+/** Every file holding document-editor implementation, entry first. */
+export function documentSourcePaths() {
+  if (!existsSync(ENTRY)) {
+    throw new Error(`document editor entry point is missing: ${ENTRY}`);
+  }
+  return [ENTRY, ...(existsSync(IMPL_DIR) ? walk(IMPL_DIR).sort() : [])];
+}
+
+/** The whole implementation set as one string, entry first. */
+export function documentSource() {
+  return documentSourcePaths().map(path => readFileSync(path, 'utf8')).join('\n');
+}

tests/helpers/document_source.py

@@ -0,0 +1,288 @@
+"""Read the document editor's JavaScript the way the browser loads it.
+
+``static/js/document.js`` is being decomposed. It stays the entry point the
+browser requests -- ``static/index.html`` names it, ``static/sw.js`` precaches
+it, and five modules import it -- but the implementation moves into modules
+under ``static/js/document/``. The implementation set is the entry plus that
+directory.
+
+Two habits in the existing tests do not survive that move, and this module
+exists to replace both.
+
+**Reading the entry file alone.** A membership assertion against
+``document.js`` silently covers less the moment the behaviour it names moves
+out. Use :func:`document_source` for those: it is the whole implementation set,
+so a test keeps finding what it asserts on wherever the code lands.
+
+**Slicing between two adjacent functions.** ``function_body("a")`` means "the region between a and b", which is only
+the body of ``a`` while ``a`` and ``b`` happen to be neighbours in one file.
+After a split they may sit in different modules, and then the slice runs to the
+end of the concatenation and quietly grows: an ``assert "x" in region`` passes
+against code it was never meant to see. Several of these also hard-code the
+entry file's two-space indentation (``"\\n  function showDocTabMenu"``), which
+no extracted module reproduces. Use :func:`function_body` or
+:func:`declaration` instead -- they find the construct by name, in whichever
+module defines it, and end at its real closing brace.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_STATIC = Path(__file__).resolve().parents[2] / "static"
+_ENTRY = _STATIC / "js" / "document.js"
+
+# Extracted implementation modules get one home, so the set is discoverable
+# without a manifest anyone has to remember to update.
+_IMPL_DIR = _STATIC / "js" / "document"
+
+
+def document_source_paths() -> list[Path]:
+    """Every file holding document-editor implementation, entry first.
+
+    The entry comes first so a concatenation reads in the order the browser
+    evaluates the graph's root; the rest are sorted for determinism.
+    """
+    if not _ENTRY.is_file():
+        raise AssertionError(f"document editor entry point is missing: {_ENTRY}")
+    extracted = sorted(_IMPL_DIR.rglob("*.js")) if _IMPL_DIR.is_dir() else []
+    return [_ENTRY, *extracted]
+
+
+def document_source() -> str:
+    """The whole implementation set as one string, entry first.
+
+    For membership assertions (``assert "..." in document_source()``). For
+    anything positional use :func:`function_body` or :func:`declaration`.
+    """
+    return "\n".join(p.read_text(encoding="utf-8") for p in document_source_paths())
+
+
+# --- Locating a construct by name, not by what follows it ------------------
+
+def _defining_source(pattern: re.Pattern[str], what: str) -> tuple[str, int]:
+    """The source text that defines ``what``, and the offset of the match."""
+    hits = []
+    for path in document_source_paths():
+        src = path.read_text(encoding="utf-8")
+        for m in pattern.finditer(src):
+            hits.append((path, src, m.start()))
+    if not hits:
+        raise AssertionError(f"{what} is not defined anywhere in {_describe_set()}")
+    if len(hits) > 1:
+        where = ", ".join(
+            f"{p.relative_to(_STATIC.parent)}:{s.count(chr(10), 0, o) + 1}"
+            for p, s, o in hits
+        )
+        raise AssertionError(f"{what} is defined more than once ({where})")
+    _path, src, offset = hits[0]
+    return src, offset
+
+
+def _describe_set() -> str:
+    return ", ".join(str(p.relative_to(_STATIC.parent)) for p in document_source_paths())
+
+
+def function_body(name: str) -> str:
+    """The full text of function ``name``, signature through closing brace.
+
+    Matches ``function name``, optionally prefixed by ``export`` and/or
+    ``async``, at any indentation, in whichever module of the implementation
+    set defines it. The end is found by matching braces rather than by naming
+    whatever declaration follows, so moving the function -- or the one after
+    it -- does not change the region a test sees.
+    """
+    pattern = re.compile(
+        r"^[ \t]*(?:export\s+)?(?:async\s+)?function\s+" + re.escape(name) + r"\s*\(",
+        re.M,
+    )
+    src, offset = _defining_source(pattern, f"function {name}")
+    # Skip the parameter list before looking for the body. A destructured
+    # parameter -- `function f(table, { headerRow, headerColumn })` -- opens a
+    # brace that is not the body, and matching it would return the signature
+    # alone.
+    body_start = _end_of_params(src, src.index("(", offset))
+    return src[offset : _end_of_block(src, body_start)]
+
+
+def declaration(name: str) -> str:
+    """The full text of a top-level ``const``/``let``/``var`` named ``name``.
+
+    For the array and object tables the tests assert on (toolbar groups, slash
+    commands, input rules). Ends at the declaration's closing bracket or brace,
+    or at the end of the statement for a simple initialiser.
+    """
+    pattern = re.compile(
+        r"^[ \t]*(?:export\s+)?(?:const|let|var)\s+" + re.escape(name) + r"\b",
+        re.M,
+    )
+    src, offset = _defining_source(pattern, f"declaration {name}")
+    return src[offset : _end_of_statement(src, offset)]
+
+
+# --- A brace matcher that is not fooled by braces inside literals ----------
+#
+# `document.js` is full of template literals building DOM, regexes containing
+# braces, and apostrophes inside comments. Counting raw `{`/`}` mis-slices on
+# all three, so the scan tracks what kind of text it is inside.
+
+# After one of these, `/` starts a regex literal; after a value it is division.
+_REGEX_OK_BEFORE = re.compile(r"[({\[,;:=!&|?+\-*~^%<>]\s*$|\b(?:return|typeof|case|in|of|new|delete|void|do|else|yield|await)\s*$")
+
+
+def _scan(src: str, start: int, stop):
+    """Walk ``src`` from ``start``, skipping literals and comments.
+
+    Calls ``stop(index, depth_delta_applied)``-free: instead it yields
+    ``(index, char)`` for code positions only, so callers can track nesting.
+    """
+    i, n = start, len(src)
+    # Stack of template-literal depths: entering `${` pushes brace depth.
+    template_stack: list[int] = []
+    while i < n:
+        c = src[i]
+        two = src[i : i + 2]
+        if two == "//":
+            j = src.find("\n", i)
+            i = n if j == -1 else j + 1
+            continue
+        if two == "/*":
+            j = src.find("*/", i + 2)
+            i = n if j == -1 else j + 2
+            continue
+        if c in "'\"":
+            i = _skip_quoted(src, i, c)
+            continue
+        if c == "`":
+            i += 1
+            i, entered = _skip_template(src, i)
+            if entered:
+                template_stack.append(0)
+            continue
+        if c == "/" and _REGEX_OK_BEFORE.search(src[max(0, i - 24) : i]):
+            j = _skip_regex(src, i)
+            if j is not None:
+                i = j
+                continue
+        if template_stack:
+            # Inside `${ ... }`: a `}` that closes it returns to template text.
+            if c == "{":
+                template_stack[-1] += 1
+            elif c == "}":
+                if template_stack[-1] == 0:
+                    template_stack.pop()
+                    i += 1
+                    i, entered = _skip_template(src, i)
+                    if entered:
+                        template_stack.append(0)
+                    continue
+                template_stack[-1] -= 1
+        yield i, c
+        i += 1
+
+
+def _skip_quoted(src: str, i: int, quote: str) -> int:
+    i += 1
+    n = len(src)
+    while i < n:
+        if src[i] == "\\":
+            i += 2
+            continue
+        if src[i] == quote:
+            return i + 1
+        if src[i] == "\n":  # unterminated; do not run away
+            return i
+        i += 1
+    return n
+
+
+def _skip_template(src: str, i: int) -> tuple[int, bool]:
+    """From inside template text, advance to the backtick end or a ``${``.
+
+    Returns the new index and whether an interpolation was entered.
+    """
+    n = len(src)
+    while i < n:
+        if src[i] == "\\":
+            i += 2
+            continue
+        if src[i] == "`":
+            return i + 1, False
+        if src[i : i + 2] == "${":
+            return i + 2, True
+        i += 1
+    return n, False
+
+
+def _skip_regex(src: str, i: int) -> int | None:
+    """Past a regex literal starting at ``i``, or None if it is not one."""
+    i += 1
+    n = len(src)
+    in_class = False
+    while i < n:
+        c = src[i]
+        if c == "\\":
+            i += 2
+            continue
+        if c == "\n":
+            return None
+        if in_class:
+            if c == "]":
+                in_class = False
+        elif c == "[":
+            in_class = True
+        elif c == "/":
+            i += 1
+            while i < n and src[i].isalpha():  # flags
+                i += 1
+            return i
+        i += 1
+    return None
+
+
+def _end_of_block(src: str, start: int) -> int:
+    """Index just past the ``}`` closing the first ``{`` at or after ``start``."""
+    depth = 0
+    seen = False
+    for i, c in _scan(src, start, None):
+        if c == "{":
+            depth += 1
+            seen = True
+        elif c == "}":
+            depth -= 1
+            if seen and depth == 0:
+                return i + 1
+    raise AssertionError(f"unbalanced braces from offset {start}")
+
+
+def _end_of_statement(src: str, start: int) -> int:
+    """Index just past the end of the declaration statement at ``start``.
+
+    Ends on the ``;`` or newline that closes it at nesting depth zero, so an
+    array or object initialiser is returned whole.
+    """
+    depth = 0
+    for i, c in _scan(src, start, None):
+        if c in "{[(":
+            depth += 1
+        elif c in "}])":
+            depth -= 1
+        elif depth == 0 and c == ";":
+            return i + 1
+        elif depth == 0 and c == "\n" and i > start:
+            return i
+    return len(src)
+
+
+def _end_of_params(src: str, open_paren: int) -> int:
+    """Index just past the ``)`` closing the parameter list at ``open_paren``."""
+    depth = 0
+    for i, c in _scan(src, open_paren, None):
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+            if depth == 0:
+                return i + 1
+    raise AssertionError(f"unbalanced parameter list at offset {open_paren}")

tests/helpers/import_state.py

@@ -31,6 +31,7 @@ safe for callers that pass both a parent package and a child module.
 """
 
 import sys
+import types
 from contextlib import contextmanager
 
 _ABSENT = object()
@@ -167,3 +168,33 @@ def preserve_import_state(*module_names):
         # Phase 2: restore all parent-package attributes.
         for name, (_, saved_attr) in saved.items():
             _restore_parent_attr(name, saved_attr)
+
+
+# Names under these prefixes are the ones a leaked stub actually breaks: a
+# later test doing ``import src.x`` or ``import core.x`` silently gets the
+# empty stub instead of the real module.
+_GUARDED_PREFIXES = ("src.", "core.")
+
+
+def bare_module_stubs():
+    """Return the ``src.*``/``core.*`` names currently bound to a bare stub.
+
+    A bare stub is a plain :class:`types.ModuleType` with no on-disk
+    ``__file__`` — the object ``types.ModuleType(name)`` produces. That is the
+    same "is this a fake?" test the ``clear_fake_*`` helpers above use, so a
+    module imported from disk is never reported.
+
+    ``MagicMock`` stand-ins are deliberately out of scope: they answer every
+    attribute, so they fail loudly at use rather than silently, and several
+    test modules install them on purpose.
+    """
+    found = set()
+    for name, mod in list(sys.modules.items()):
+        if not name.startswith(_GUARDED_PREFIXES):
+            continue
+        if type(mod) is not types.ModuleType:
+            continue
+        if getattr(mod, "__file__", None):
+            continue
+        found.add(name)
+    return found

tests/helpers/js_modules.py

@@ -0,0 +1,83 @@
+"""Read a split JS subpackage the way the module graph does.
+
+``static/js/emailLibrary.js`` is a re-export wrapper; the implementation lives
+in ``static/js/emailLibrary/``. A test that asserts on email-library behaviour
+has to look at every module in that package, because reading one file ties the
+test to whichever module a function happens to sit in today — it goes red the
+next time something moves without any behaviour changing.
+
+That is the mistake the stylesheet split made, which is why
+``tests/helpers/stylesheets.py`` exists. This is the same helper for JS.
+
+Order is deterministic: the entry module first, then the rest alphabetically.
+Tests that assert "A appears before B" are asserting about one module's source,
+not about the package, so the concatenation order only has to be stable.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_STATIC_JS = Path(__file__).resolve().parents[2] / "static" / "js"
+
+EMAIL_LIBRARY_WRAPPER = _STATIC_JS / "emailLibrary.js"
+EMAIL_LIBRARY_PACKAGE = _STATIC_JS / "emailLibrary"
+EMAIL_LIBRARY_ENTRY = EMAIL_LIBRARY_PACKAGE / "index.js"
+
+
+def _package_paths(package: Path, entry: Path) -> list[Path]:
+    if not entry.is_file():
+        raise AssertionError(f"missing package entry module: {entry}")
+    rest = sorted(p for p in package.glob("*.js") if p != entry)
+    return [entry, *rest]
+
+
+def email_library_paths(include_wrapper: bool = False) -> list[Path]:
+    """Every module of the email-library package, entry module first.
+
+    ``include_wrapper`` adds the compatibility file at the old top-level path.
+    Leave it off for assertions about implementation code: the wrapper holds
+    only an ``export … from`` list.
+    """
+    paths = _package_paths(EMAIL_LIBRARY_PACKAGE, EMAIL_LIBRARY_ENTRY)
+    return [EMAIL_LIBRARY_WRAPPER, *paths] if include_wrapper else paths
+
+
+def email_library_source(include_wrapper: bool = False) -> str:
+    """The whole email-library package as one string."""
+    return "\n".join(
+        p.read_text(encoding="utf-8") for p in email_library_paths(include_wrapper)
+    )
+
+
+def js_function_source(name: str, source: str | None = None) -> str:
+    """One top-level JS function, from its signature to its closing brace.
+
+    Two things this does not do, on purpose.
+
+    It does not slice between a signature and a marker further down ("from
+    ``_toggleCardPreview`` to the ``Wrap a probable signature`` comment"). That
+    is what a split breaks: the marker ends up in another module, the slice runs
+    past the end of the function without failing, and the assertions keep
+    passing against the wrong text.
+
+    It does not balance braces by walking characters either. The obvious version
+    of that walker treats the apostrophe in a ``// that's a scroll`` comment as
+    an open quote and swallows every brace until the next one, which ends the
+    function early — silently, again.
+
+    Instead it uses the invariant the file actually holds: a top-level
+    declaration starts at column 0, so its closing brace is the next lone ``}``
+    at column 0.
+    """
+    text = email_library_source() if source is None else source
+    signature = re.compile(
+        r"^(?:export\s+)?(?:async\s+)?function\s+" + re.escape(name) + r"\s*\(",
+        re.M,
+    )
+    match = signature.search(text)
+    assert match, f"no top-level declaration of {name}"
+    closing = re.compile(r"^\}", re.M).search(text, match.end())
+    assert closing, f"unterminated function {name}"
+    return text[match.start():closing.end()]

tests/helpers/stylesheets.mjs

@@ -0,0 +1,67 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const STATIC = join(HERE, '..', '..', 'static');
+const INDEX = join(STATIC, 'index.html');
+
+const LINK = /<link\b[^>]*\brel\s*=\s*["']stylesheet["'][^>]*\bhref\s*=\s*["']\/static\/([^"'?]+)([^"']*)["']/gi;
+
+async function entries() {
+  const html = await readFile(INDEX, 'utf8');
+  const out = [];
+
+  for (const match of html.matchAll(LINK)) {
+    const rel = match[1];
+    const query = match[2];
+
+    if (rel.startsWith('lib/')) continue;
+
+    out.push({
+      path: join(STATIC, rel),
+      url: `/static/${rel}${query}`,
+    });
+  }
+
+  if (!out.length) {
+    throw new Error(`no app stylesheet <link> tags found in ${INDEX}`);
+  }
+
+  for (const entry of out) {
+    try {
+      await readFile(entry.path);
+    } catch {
+      throw new Error(
+        `index.html links a stylesheet that does not exist: ${entry.path}`,
+      );
+    }
+  }
+
+  return out;
+}
+
+export async function stylesheetPaths() {
+  return (await entries()).map(entry => entry.path);
+}
+
+export async function stylesheetUrls() {
+  return (await entries()).map(entry => entry.url);
+}
+
+export async function stylesheetLinkTags() {
+  return (await stylesheetUrls())
+    .map(url => `<link rel="stylesheet" href="${url}">`)
+    .join('');
+}
+
+export async function appCss() {
+  const paths = await stylesheetPaths();
+  const parts = [];
+
+  for (const path of paths) {
+    parts.push(await readFile(path, 'utf8'));
+  }
+
+  return parts.join('\n');
+}

tests/helpers/stylesheets.py

@@ -0,0 +1,84 @@
+"""Read the app's CSS the way the browser does.
+
+The former ``static/style.css`` is now an ordered set of numbered fragments,
+followed by the existing panel stylesheets. ``static/index.html`` loads the
+complete cascade eagerly in the order the browser must apply it.
+
+A test that asserts on a rule must therefore look at the complete cascade.
+Reading one fragment alone ties the test to whichever file a rule happens to
+sit in today, so it goes red the next time a rule moves without anything about
+the rendered page having changed.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+_STATIC = Path(__file__).resolve().parents[2] / "static"
+_INDEX = _STATIC / "index.html"
+
+# Only same-origin app stylesheets. Vendored <link>s under static/lib are not
+# part of the cascade these tests reason about.
+_LINK = re.compile(
+    r"""<link\b[^>]*\brel\s*=\s*["']stylesheet["'][^>]*\bhref\s*=\s*["']/static/([^"'?]+)([^"']*)["']""",
+    re.I,
+)
+
+
+def _entries() -> list[tuple[Path, str]]:
+    html = _INDEX.read_text(encoding="utf-8")
+    out = []
+    for m in _LINK.finditer(html):
+        rel, query = m.group(1), m.group(2)
+        if rel.startswith("lib/"):
+            continue
+        out.append((_STATIC / rel, "/static/" + rel + query))
+    if not out:
+        raise AssertionError(f"no app stylesheet <link> tags found in {_INDEX}")
+    missing = [p for p, _u in out if not p.is_file()]
+    if missing:
+        raise AssertionError(f"index.html links stylesheets that do not exist: {missing}")
+    return out
+
+
+def stylesheet_paths() -> list[Path]:
+    """Every app stylesheet on disk, in the order index.html loads it."""
+    return [p for p, _u in _entries()]
+
+
+def stylesheet_urls() -> list[str]:
+    """The same stylesheets as request URLs, query string included."""
+    return [u for _p, u in _entries()]
+
+
+def stylesheet_link_tags() -> str:
+    """The <link> tags for a synthetic page that needs the whole cascade."""
+    return "".join(f'<link rel="stylesheet" href="{u}">' for u in stylesheet_urls())
+
+
+def app_css() -> str:
+    """The whole cascade as one string, in load order."""
+    return "\n".join(p.read_text(encoding="utf-8") for p in stylesheet_paths())
+
+
+def stylesheet_cache_version() -> str:
+    """The single ``?v=`` token every app stylesheet link carries.
+
+    The stylesheet is split across several files that must be busted together:
+    shipping one fragment under a stale token serves a browser half of an old
+    cascade and half of a new one. Tests ask for the shared version here instead of deriving it from one
+    stylesheet filename, so they keep checking the invariant
+    rather than a filename.
+    """
+    versions = set()
+    for url in stylesheet_urls():
+        m = re.search(r"\?v=([^&]+)$", url)
+        if not m:
+            raise AssertionError(f"app stylesheet has no cache-bust token: {url}")
+        versions.add(m.group(1))
+    if len(versions) != 1:
+        raise AssertionError(
+            f"app stylesheets disagree on their cache-bust token: {sorted(versions)}"
+        )
+    return versions.pop()

tests/helpers/test_settings_shell_coordinator.mjs

@@ -20,6 +20,14 @@ const REAL_MODULES = new Set([
   path.join(JS, 'settings/sidebar.js'),
   path.join(JS, 'settings/navigation.js'),
   path.join(JS, 'settings/lifecycle.js'),
+  path.join(JS, 'settings/api.js'),
+  path.join(JS, 'settings/speech.js'),
+  path.join(JS, 'settings/writingStyle.js'),
+  path.join(JS, 'settings/imageModels.js'),
+  path.join(JS, 'settings/agent.js'),
+  path.join(JS, 'settings/shell.js'),
+  path.join(JS, 'settings/peek.js'),
+  path.join(JS, 'settings/oauthReturn.js'),
   path.join(JS, 'searchProviderIcons.js'),
 ]);
 
@@ -497,6 +505,11 @@ function buildFixture(document) {
   header.className = 'modal-header';
   modal.appendChild(header);
 
+  const peekToggle = document.createElement('button');
+  peekToggle.id = 'settings-opacity-wrap';
+  peekToggle.className = 'theme-opacity-wrap theme-opacity-toggle hidden';
+  header.appendChild(peekToggle);
+
   const close = document.createElement('button');
   close.className = 'close-btn';
   header.appendChild(close);
@@ -539,6 +552,14 @@ function buildFixture(document) {
   panels.className = 'settings-panels';
   content.appendChild(panels);
 
+  const adminCard = document.createElement('div');
+  adminCard.className = 'admin-card';
+  panels.appendChild(adminCard);
+
+  const adminOnly = document.createElement('div');
+  adminOnly.className = 'admin-only';
+  adminCard.appendChild(adminOnly);
+
   const panelIds = [
     'services',
     'added-models',
@@ -590,6 +611,9 @@ function buildFixture(document) {
     sidebarHandle,
     searchInput,
     searchResults,
+    peekToggle,
+    adminCard,
+    adminOnly,
     services: settingsPanels.services,
     appearance: settingsPanels.appearance,
     ai: settingsPanels.ai,
@@ -796,6 +820,14 @@ const STUBS = new Map([
       },
     },
   ],
+  [
+    path.join(JS, 'editor/ai-models.js'),
+    {
+      modelCaps() {
+        return {};
+      },
+    },
+  ],
   [
     path.join(JS, 'providers.js'),
     {
@@ -847,9 +879,10 @@ function resolveImport(specifier, parent) {
     throw new Error(`Unexpected non-relative import: ${specifier}`);
   }
 
+  const cleanSpecifier = specifier.split('?')[0].split('#')[0];
   return path.resolve(
     path.dirname(parent),
-    specifier,
+    cleanSpecifier,
   );
 }
 
@@ -993,6 +1026,14 @@ assert(
 );
 
 
+// shell.js owns admin-only visibility. A non-admin must not merely see an
+// unpopulated admin control — the element has to be hidden on every open().
+assert(
+  fixture.adminOnly.style.display === 'none',
+  'open() did not hide .admin-only for a non-admin',
+);
+
+
 // #6040 coordinator integration: initAll() must bind the real finder and
 // sidebar controllers, not merely make their modules link successfully.
 assert(
@@ -1049,6 +1090,28 @@ assert(
   'navigation callback did not apply Appearance coordinator state',
 );
 
+assert(
+  !fixture.peekToggle.classList.contains('hidden'),
+  'Appearance activation did not reveal the Peek toggle',
+);
+
+
+// peek.js fades the window background via color-mix, never element opacity, so
+// the controls stay readable while the user previews the page behind Settings.
+fixture.peekToggle.click();
+
+assert(
+  fixture.content.style.values.background
+    === 'color-mix(in srgb, var(--bg) 55%, transparent)',
+  'Peek toggle did not fade the Settings window background',
+);
+
+assert(
+  fixture.adminCard.style.values.background
+    === 'color-mix(in srgb, var(--panel) 55%, transparent)',
+  'Peek toggle did not fade the Settings cards',
+);
+
 
 // Direct public open() after initialization must still coordinate activation.
 settings.open('ai');
@@ -1068,6 +1131,19 @@ assert(
   'direct open("ai") did not clear Appearance coordinator state',
 );
 
+// Leaving Appearance with Peek still toggled on must not leave the rest of
+// Settings faded — this is the bug the sync exists to prevent.
+assert(
+  fixture.content.style.values.background === undefined
+    && fixture.adminCard.style.values.background === undefined,
+  'leaving Appearance left the Peek fade applied',
+);
+
+assert(
+  fixture.peekToggle.classList.contains('hidden'),
+  'leaving Appearance left the Peek toggle visible',
+);
+
 
 // Public close() must route through the real lifecycle module.
 settings.close();
@@ -1083,6 +1159,44 @@ assert(
 );
 
 
+// shell.js hands an admin-managed tab to admin.js and must not then perform a
+// second local activation. Nothing before this point installs an admin module,
+// so the earlier assertions covered the no-admin-module fallback.
+const adminCalls = [];
+
+sandbox.adminModule = {
+  open(tab) {
+    adminCalls.push(tab);
+    return true;
+  },
+  _initData() {
+    adminCalls.push('_initData');
+  },
+};
+
+fixture.settingsPanels.users.button.click();
+
+assert(
+  adminCalls.length === 1 && adminCalls[0] === 'users',
+  `admin tab click did not hand "users" to the admin module: ${adminCalls}`,
+);
+
+assert(
+  !fixture.settingsPanels.users.button.classList.contains('active'),
+  'shell activated an admin tab locally after the admin module claimed it',
+);
+
+
+// Admin status is read per open(), not cached at initialization.
+sandbox._isAdmin = true;
+settings.open('services');
+
+assert(
+  fixture.adminOnly.style.display === '',
+  'open() did not reveal .admin-only for an admin',
+);
+
+
 // initAll() starts some existing async panel initializers without awaiting
 // them. Give already-ready continuations a chance to run before declaring the
 // smoke successful, so late coordinator/setup exceptions still fail the test.
@@ -1097,4 +1211,7 @@ console.log(JSON.stringify({
   navigationCallback: true,
   directOpen: true,
   directClose: true,
+  peekChrome: true,
+  adminVisibility: true,
+  adminTabHandoff: true,
 }));

tests/helpers/unix_sockets.py

@@ -0,0 +1,46 @@
+"""Bind an AF_UNIX socket at a path the kernel will actually accept.
+
+``sun_path`` is 104 bytes on macOS, terminator included, so a bind path longer
+than 103 characters fails with ``OSError: AF_UNIX path too long``. pytest's
+``tmp_path`` is rooted at ``$TMPDIR``, which on stock macOS is a 49-character
+``/var/folders/<2>/<30>/T/`` path; adding ``pytest-of-<user>/pytest-<n>/`` and
+the test's own (truncated) name spends the rest of the budget before the
+filename is appended.
+
+That is why this reads as flaky rather than broken. Linux allows 108 bytes and
+roots ``$TMPDIR`` at ``/tmp``, so it never bites there; on macOS whether it
+bites depends on the length of ``$TMPDIR``, the test's name, and how many
+digits pytest's run counter is currently using. A run under a shortened
+``$TMPDIR`` passes, the same checkout under the default one does not.
+
+The path is resolved before it is handed back, for the same reason the rest of
+this change resolves temp paths: on macOS ``/tmp`` is a symlink to
+``/private/tmp``, and a test that binds one spelling and asserts on the other
+is comparing two names for the same socket.
+"""
+
+import os
+import shutil
+import socket
+import tempfile
+from contextlib import contextmanager
+
+# Short enough to leave room for the socket's own name under every platform's
+# sun_path budget. A relative root would depend on the working directory.
+_SHORT_ROOT = os.path.realpath(tempfile.gettempdir() if os.name == "nt" else "/tmp")
+
+
+@contextmanager
+def bound_unix_socket(name="docker.sock"):
+    """Yield the path of a listening AF_UNIX socket, cleaned up on exit."""
+    directory = os.path.realpath(tempfile.mkdtemp(prefix="odysseus-sock-", dir=_SHORT_ROOT))
+    path = os.path.join(directory, name)
+    if len(path) > 103:  # pragma: no cover - guards the guard
+        raise AssertionError(f"socket path is {len(path)} bytes, over the limit: {path}")
+    sock = socket.socket(socket.AF_UNIX)
+    try:
+        sock.bind(path)
+        yield path
+    finally:
+        sock.close()
+        shutil.rmtree(directory, ignore_errors=True)