# MyFlames Developer Reference This is the detailed contract per feature; [AGENTS.md](https://github.com/vgrippa/myflames/blob/master/AGENTS.md) has the rules. Read the relevant section before changing behavior, output formats, UI integration, or feature-specific tests. ## Table of contents - [Commands Reference](https://myflames.io/docs/ref-developer-reference.md#commands-reference) - [Local UI](https://myflames.io/docs/ref-developer-reference.md#local-ui) - [Release sync](https://myflames.io/docs/ref-developer-reference.md#release-sync) - [Release notes](https://myflames.io/docs/ref-developer-reference.md#release-notes) - [Shared view presentation](https://myflames.io/docs/ref-developer-reference.md#shared-view-presentation) - [Chart runtime](https://myflames.io/docs/ref-developer-reference.md#chart-runtime) - [Bundle and lazy loading](https://myflames.io/docs/ref-developer-reference.md#bundle-and-lazy-loading) - [Local authentication and request limits](https://myflames.io/docs/ref-developer-reference.md#local-authentication-and-request-limits) - [Client and local-storage boundaries](https://myflames.io/docs/ref-developer-reference.md#client-and-local-storage-boundaries) - [Reviewed actions and session ownership](https://myflames.io/docs/ref-developer-reference.md#reviewed-actions-and-session-ownership) - [Shared CLI confirmation](https://myflames.io/docs/ref-developer-reference.md#shared-cli-confirmation) - [Profiles](https://myflames.io/docs/ref-developer-reference.md#profiles) - [Write safety and audit](https://myflames.io/docs/ref-developer-reference.md#write-safety-and-audit) - [SQL CLI](https://myflames.io/docs/ref-developer-reference.md#sql-cli) - [Query editor sessions](https://myflames.io/docs/ref-developer-reference.md#query-editor-sessions) - [Run](https://myflames.io/docs/ref-developer-reference.md#run) - [Plan Stats and shared-plan literal hiding](https://myflames.io/docs/ref-developer-reference.md#plan-stats-and-shared-plan-literal-hiding) - [Digest](https://myflames.io/docs/ref-developer-reference.md#digest) - [Plan diff](https://myflames.io/docs/ref-developer-reference.md#plan-diff) - [CI gate](https://myflames.io/docs/ref-developer-reference.md#ci-gate) - [Advise](https://myflames.io/docs/ref-developer-reference.md#advise) - [Rule controls](https://myflames.io/docs/ref-developer-reference.md#rule-controls) - [Advisor evidence rules](https://myflames.io/docs/ref-developer-reference.md#advisor-evidence-rules) - [Find slow queries](https://myflames.io/docs/ref-developer-reference.md#find-slow-queries) - [Locks](https://myflames.io/docs/ref-developer-reference.md#locks) - [Sessions](https://myflames.io/docs/ref-developer-reference.md#sessions) - [InnoDB](https://myflames.io/docs/ref-developer-reference.md#innodb) - [Error log](https://myflames.io/docs/ref-developer-reference.md#error-log) - [Server identity: Percona Server](https://myflames.io/docs/ref-developer-reference.md#server-identity-percona-server) - [Server health](https://myflames.io/docs/ref-developer-reference.md#server-health) - [Baselines: Health and Query digest](https://myflames.io/docs/ref-developer-reference.md#baselines-health-and-query-digest) - [Waits, Indexes, Tables, I/O, Config](https://myflames.io/docs/ref-developer-reference.md#waits-indexes-tables-io-config) - [Memory](https://myflames.io/docs/ref-developer-reference.md#memory) - [Server variables: config set, reset-persist](https://myflames.io/docs/ref-developer-reference.md#server-variables-config-set-reset-persist) - [Instruments](https://myflames.io/docs/ref-developer-reference.md#instruments) - [Full analysis report](https://myflames.io/docs/ref-developer-reference.md#full-analysis-report) - [Database Tuning Advisor](https://myflames.io/docs/ref-developer-reference.md#database-tuning-advisor) - [Server lifecycle: upgrade-check, dump, restore, clone](https://myflames.io/docs/ref-developer-reference.md#server-lifecycle-upgrade-check-dump-restore-clone) - [Replication: status, skip, skip-loop](https://myflames.io/docs/ref-developer-reference.md#replication-status-skip-skip-loop) - [Cluster: Galera, Percona XtraDB Cluster, InnoDB Cluster](https://myflames.io/docs/ref-developer-reference.md#cluster-galera-percona-xtradb-cluster-innodb-cluster) - [Users and roles: privileges, accounts](https://myflames.io/docs/ref-developer-reference.md#users-and-roles-privileges-accounts) - [Privilege catalogs and adding scopes](https://myflames.io/docs/ref-developer-reference.md#privilege-catalogs-and-adding-scopes) - [Database diagram](https://myflames.io/docs/ref-developer-reference.md#database-diagram) - [Schema versions](https://myflames.io/docs/ref-developer-reference.md#schema-versions) - [Compare servers: parameters and accounts](https://myflames.io/docs/ref-developer-reference.md#compare-servers-parameters-and-accounts) - [Parameter version catalogs](https://myflames.io/docs/ref-developer-reference.md#parameter-version-catalogs) - [Engine words for the Query editor](https://myflames.io/docs/ref-developer-reference.md#engine-words-for-the-query-editor) - [MySQL 5.7 support](https://myflames.io/docs/ref-developer-reference.md#mysql-57-support) - [Export as SQL and Table structure](https://myflames.io/docs/ref-developer-reference.md#export-as-sql-and-table-structure) - [Query digest sources and Time range](https://myflames.io/docs/ref-developer-reference.md#query-digest-sources-and-time-range) - [Structure-only dumps](https://myflames.io/docs/ref-developer-reference.md#structure-only-dumps) - [Saved connections and Database diagram Load](https://myflames.io/docs/ref-developer-reference.md#saved-connections-and-database-diagram-load) - [Connection readiness and import](https://myflames.io/docs/ref-developer-reference.md#connection-readiness-and-import) - [Learn guided lessons](https://myflames.io/docs/ref-developer-reference.md#learn-guided-lessons) - [Command line deprecation](https://myflames.io/docs/ref-developer-reference.md#command-line-deprecation) - [MySQL Shell](https://myflames.io/docs/ref-developer-reference.md#mysql-shell) - [File transfer: SSH connections and SFTP](https://myflames.io/docs/ref-developer-reference.md#file-transfer-ssh-connections-and-sftp) - [--quiet / -q](https://myflames.io/docs/ref-developer-reference.md#--quiet---q) - [MCP server](https://myflames.io/docs/ref-developer-reference.md#mcp-server) - [MySQL Fixtures](https://myflames.io/docs/ref-developer-reference.md#mysql-fixtures) - [MariaDB Fixtures](https://myflames.io/docs/ref-developer-reference.md#mariadb-fixtures) - [Visual Explain (merged Diagram / Workbench)](https://myflames.io/docs/ref-developer-reference.md#visual-explain-merged-diagram--workbench) - [Investigation engine](https://myflames.io/docs/ref-developer-reference.md#investigation-engine) - [Import CSV](https://myflames.io/docs/ref-developer-reference.md#import-csv) - [Workspace navigation and configuration controls](https://myflames.io/docs/ref-developer-reference.md#workspace-navigation-and-configuration-controls) - [Action feedback](https://myflames.io/docs/ref-developer-reference.md#action-feedback) - [Tables and indexes: browse and export](https://myflames.io/docs/ref-developer-reference.md#tables-and-indexes-browse-and-export) ## Commands Reference ### Local UI The workspace and favicon use `docs/brand/myflames-app-logo.png`, derived from the primary flame SVG (`myflames-logo.svg`). The stable built URL remains `/assets/myflames-logo.png`. Desktop packaging uses the charcoal-slate icon in `docs/brand/`: `myflames-app-icon.icns` on macOS and the 1024 px PNG master on Windows. The optional Electron development host is in `apps/desktop`. It starts its own Python server and loads the one-use launch URL into a sandboxed window. It uses separate app data and retains the same API authentication and write contracts. The Apple Silicon package bundles its Python backend and opens through Finder. Build with `package:mac` (unsigned, for local use) or `package:mac:release` (`scripts/package-mac-release.sh`: Developer ID signing under the hardened runtime with only `com.apple.security.cs.allow-jit` from `entitlements.mac.plist`, notarization and stapling of the app and the DMG, Gatekeeper checks, and the 200 MiB update download limit (3.3.3 and older stop their Download at 150 MiB and open the release page instead); it also builds the update zip (`electron-builder --mac dmg zip --arm64`; `mac.artifactName` `myflames-${version}-macos-${arch}.${ext}`), extracts it and checks the app inside (`codesign --verify --deep --strict`, Gatekeeper source Notarized Developer ID, stapler validate), applies the 200 MiB limit to the DMG and the zip, and writes `.sha256` for both; the certificate comes from `MYFLAMES_MAC_IDENTITY` and the notary sign-in from `APPLE_KEYCHAIN_PROFILE`, or from an App Store Connect API key in `APPLE_API_KEY`, `APPLE_API_KEY_ID` and `APPLE_API_ISSUER`). Validate the delivered `.app` using the packaged smoke, which removes system Python from the startup path and checks owned cleanup. Run `node apps/desktop/scripts/editor-settings-smoke.cjs apps/desktop/dist/mac-arm64/myflames.app` (`smoke:editor-settings` in `apps/desktop`) against that same built bundle for the two-launch Query editor settings check. It changes wrapping and multiple cursors through Settings, checks their stored and rendered behavior after restart, then restores the defaults. Beside it, `node apps/desktop/scripts/preferences-smoke.cjs apps/desktop/dist/mac-arm64/myflames.app` (`smoke:preferences`) uses three launches sharing one isolated data folder: System theme, 208 px sidebar and floating Server views; Dracula, a 280 px sidebar, a 160 px Query editor split and docked Server views after restart; then restored defaults, including the 260 px editor split, after another restart. All changes use real UI controls. Before any click on each launch, it reads the root theme at the earliest opportunity after CDP attaches and checks the stored theme in server-rendered HTML from a later GET /. Neither check captures the original navigation response or proves first paint. It also reads `/api/settings/ui` and the autosaved session, checks the rendered sizes and docking state, and waits for the expected stored layout, current place and All changes saved before normal SIGTERM quit. Both checks use the bundled backend, temporary HOME/USERPROFILE, the vault backend and a minimal PATH, need no database connection or SQL execution, report numbered `PASS` lines, and remove their isolated data and owned processes on success or failure. They never restart an existing server. Releases ship `myflames--macos-arm64.dmg` and `myflames--macos-arm64.zip` from `package:mac:release` (`apps/desktop/scripts/package-mac-release.sh`), with a `.sha256` for each; attach the DMG, the zip and both `.sha256` files, uploading the DMG before the zip because 3.3.3 and older pick the first matching `.zip` or `.dmg` in the release's asset order for Download. The first release with in-place updates must be installed by hand once. Packaging tests keep the desktop `package.json` version equal to `myflames.__version__` and `pyproject.toml`. Local builds (`package:mac`) keep Developer ID signing and notarization explicitly disabled; the certificate and the notary sign-in come from the environment, never the repository. Verify the delivered app with a minimal PATH and an unavailable system Python; normal Finder launches must not require a terminal. Keep the standard client-discovery paths fixed; discovery order breaks ties after the per-server ranking below. Keep the renderer sandboxed and isolated, with no Node integration or broad IPC bridge; the one bridge is the updater's (`preload.cjs` exposes `window.myflamesDesktop.update` with `support()`, `prepare()` and `restart()`, over the IPC channels `myflames:update-support`, `myflames:update-prepare` and `myflames:update-restart`, with no arguments; the main process answers only the workspace origin's top frame and refuses anything else). Its session refuses every permission request except the Fullscreen API for the workspace origin (Learn's Full screen). Quitting sends SIGINT to the backend's process group and waits 5 s; `backend.cjs` then kills the dump, restore and clone tool groups the backend listed in its `runtime/tool-groups-.json` file, kills the backend's group and stops any group in its last list, never signalling an id it already saw gone. The file is opened without following links or blocking, and a missing, oversized or malformed list counts as unconfirmed. `stop()` resolves only when all are gone (7 s in total) and otherwise rejects, which shows the shutdown-incomplete dialog. SSH tunnels (`myflames/ssh_tunnel.py`) are listed in the same file as service groups (`ToolGroups.add/start(..., service=True)`): `ToolGroups.terminate(services=False)` stops only the lifecycle tools, so a job's KILL QUERY can still go through its tunnel, and `backend.cjs` kills the service groups with the tools when it must kill the backend (it accepts at most `MAX_TOOL_GROUPS`, 16, listed groups, the same number as `lifecycle.ToolGroups.MAX_GROUPS`, which refuses a 17th tool or tunnel before spawning it; tunnels alone are capped at 8). A group that holds only zombies counts as gone (`lifecycle._group_alive`: macOS answers EPERM for it, and on Linux the group runs only while `/proc/PID/stat` shows a member in a state other than Z or X, or a Z member whose num_threads is above 1: the state is the main thread's, which shows Z while other threads still run and the process cannot be reaped), so dump, restore, clone and tunnel cleanup never waits on one. When the desktop dies and the backend's own shutdown hangs for 5 s, `backend-entry.py` SIGKILLs the groups the backend owns before its own group (see [SSH tunnels](https://myflames.io/docs/ref-developer-reference.md#ssh-tunnels)). `backendEnvironment` sets `MYFLAMES_SSH_HOME` (the inherited real home) and, on POSIX, `MYFLAMES_SSH_AUTH_SOCK` (the inherited agent socket); `main.cjs` sets `MYFLAMES_SSH_HOME` from `os.homedir()`. The backend's own HOME stays isolated, and database clients never see either variable. Development and tests use separate app data, never the real CLI workspace. Client discovery (`backendEnvironment` in `backend.cjs`) builds the backend PATH without shell startup scripts, in this order. macOS: the inherited PATH (Finder's default `/usr/bin:/bin:/usr/sbin:/sbin` when none), then `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/local/mysql/bin`, the Homebrew `opt` folders of `mysql-client`, `mysql-shell` and `mariadb`, `/opt/local/bin`, keg-only versioned formulae (`mysql-client@*`, `mysql@*`, `mariadb@*` under `/opt/homebrew/opt` then `/usr/local/opt`, newest first), Laravel Herd's `~/Library/Application Support/Herd/bin` and `/Applications/MySQLWorkbench.app/Contents/MacOS`. Windows: the inherited PATH, then the installers' versioned folders under each Program Files folder, which the installers do not add to PATH (`MySQL\MySQL Server *\bin`, `MariaDB *\bin`, `MySQL\MySQL Shell *\bin`, then `MySQL\MySQL Workbench *` when it holds `mysql.exe`; newest version first, `windowsClientDirectories`), compared without case. **Bundled client.** The packaged app ships the official MySQL client in `/mysql-client` (`Contents/Resources/mysql-client` in the `.app`, `resources\mysql-client` beside `myflames.exe` on Windows): `bin/mysql` and `bin/mysqldump` from the MySQL 8.4 LTS release pinned in `apps/desktop/mysql-client.lock.json`, with exactly the libraries they load (macOS: OpenSSL in `lib/`, found through `@loader_path/../lib`; Windows: the OpenSSL DLLs and the Visual C++ runtime DLLs `msvcp140.dll`, `vcruntime140.dll` and `vcruntime140_1.dll` beside the programs), the archive's `LICENSE` and `README`, and a `manifest.json` that lists every file with its size, SHA-256 and origin. `main.cjs` passes `process.resourcesPath` to `backendEnvironment` only when `app.isPackaged` (development builds add nothing); `backendEnvironment` appends `/mysql-client/bin` as the very last PATH entry on macOS and Windows, after everything above (moving it there if the inherited PATH already holds it, and leaving it off PATH when the folder name holds the PATH separator), and sets `MYFLAMES_BUNDLED_CLIENT_DIR` to it. Discovery includes that folder alongside installed tools; selection ranks each role against the server's engine and major.minor series, so the bundled copy can beat an older or newer installed series. Installed tools win only after series, authentication plugins and patch version tie. The bundled `mysqldump` is offered for MySQL servers only. The bundled client cannot sign in to MariaDB accounts that use `ed25519` or `parsec` (`ERROR 2059: Authentication plugin 'client_ed25519' cannot be loaded`); those need an installed MariaDB client. It carries no client plugins (`lib/plugin`), so Kerberos, LDAP SASL, OCI and WebAuthn authentication also need an installed client. `apps/desktop/scripts/fetch-mysql-client.py` (stdlib) downloads the archive into `apps/desktop/build/mysql-client-cache` (or `MYFLAMES_MYSQL_CLIENT_CACHE`), refuses any size or SHA-256 mismatch with the lock (HTTPS only, the download capped at the pinned size; the cached file is opened once, without following links or blocking, owned by the user and not writable by others, and the handle that was hashed is the one extracted), reads the dependencies from the Mach-O load commands or the PE import and delay-import tables and refuses anything outside the archive, the operating system and, on Windows, the Visual C++ runtime folder (DLL names must be plain file names; output paths never come from the archive and must stay inside the output folder; the runtime is found with `vswhere` in `VC\Redist\MSVC\\x64\Microsoft.VC*.CRT`, or `--vc-runtime`), and writes `apps/desktop/build/mysql-client`. `package:mac`, `package-mac-release.sh` and the Windows workflow (archive cached by its SHA-256) run it before electron-builder; electron-builder copies the folder to `mysql-client` and its `LICENSE` to `licenses/MySQL-Client-LICENSE`. The release build re-signs the client and its libraries with the app's Developer ID under the hardened runtime and checks that `mysql --version` and `mysqldump --version` still run; the packaged smoke runs the bundled `mysql --version` with only the system folders on PATH and checks that the backend found a usable `mysql` (`/api/lifecycle/tools`). Moving to another MySQL release repeats the checks recorded in the lock's `comment` (Oracle's MD5 file and `.asc` signature, then the SHA-256) and updates NOTICE. Tests: `apps/desktop/test` (PATH order, extraResources, lock) and `test/test_fetch_mysql_client.py`, `test_connector.TestBundledClientResolution` and `test_connector.TestVersionAwareClients`. Packaged app data is separate from development and CLI data. **Client tool discovery and selection.** `myflames/client_tools.py` is shared by query connections and Maintenance. `snapshot` only stats executable regular files: every copy of `mysql`, `mariadb`, `mysqldump`, `mariadb-dump`, `mariadb-backup`, `mariadb-upgrade`, `mysqlpump` and `mysqlsh` in nonempty PATH entries, then `lifecycle.COMMON_BIN_DIRS` on POSIX, then the bundled folder. Aliases are deduplicated by realpath, with MariaDB names preferred for compatibility links; there is no implicit current-directory or PATHEXT lookup. Installations are keyed by `:`; `folder` is resolved, `found_in` retains the discovery folder. Each program keeps its path, realpath and distribution version. Origin codes and labels are `bundled` (Bundled with myflames), `homebrew` (Homebrew ), `macports` (MacPorts), `mysql-installer` (MySQL installer), `workbench` (MySQL Workbench), `mariadb-installer` (MariaDB), `system` (System package, Linux /usr/bin and /usr/sbin), `path` (On PATH), and `folder` (Chosen folder for otherwise unclassified Settings folders outside the search). `has_auth_plugins` means a recognized plugin file exists in `../lib/plugin`, `../lib/mysql/plugin` or `../lib64/mysql/plugin`: LDAP SASL, Kerberos, OCI, WebAuthn, ed25519, GSSAPI or parsec. It is a selection hint, not proof that an account can authenticate. `discover` requests at most 32 version probes per call, including cache hits; `discover_choices` and lifecycle discovery can make extra discovery calls for chosen folders. `probe` runs `--version` with an isolated HOME and allowlisted environment, no stdin and an 8 s timeout; banners retain at most 4,096 characters. Successful recognized versions use a 64-entry LRU keyed by program name, realpath, device, inode, size, mtime_ns and ctime_ns, without a time limit. Failures and timeouts are not retained, and a file changed during a probe is not cached. Concurrent probes of one identity share a flight, including its failure; child processes run outside the cache lock. `refresh=True` bypasses cached results. Workspace startup warms discovery on a daemon thread without blocking the window. `mysqlpump` is presence-only, with null version and version tuple; it is deprecated, never probed, selected or marked used. Shell copies are listed separately, newest first. `select` is pure. For each supported role it considers the server's own engine, using that program's version even in a mixed-version folder. Automatic ranks its own major.minor series first, then the nearest newer series, then the newest older series. Within the selected series, installations with authentication plugins win, then the newest patch, then installed before bundled, then discovery order and stable keys/paths. An older automatic dump or load program carries ` is older than this server ( ).`; dumps add `Install client tools for a complete dump.` A Settings choice wins for that engine's roles, and missing programs never come from another installation to repair that choice. Chosen tools use reason `chosen`, without an automatic older-version warning. Roles are `client` (queries), `dump`, `load` (SQL restores and CLONE), `backup` (MariaDB physical backup) and `shell`. MariaDB prefers `mariadb` and `mariadb-dump`, accepting its own `mysql` and `mysqldump` compatibility names. Load uses the client in the selected dump installation; if it has no client, load is missing. Without a selected dump, an own-engine query client can supply load. MySQL Shell uses the newest discovered Shell independently of the Settings choice and is selected only for a known MySQL server. Auxiliary programs such as `mariadb-upgrade` use the same series ranking through `select_program`. An unknown or unrecognized server gets only a query client: installed before bundled, then mysql before mariadb, then discovery order. If a known server has no tools of its own engine, only queries may use the other engine; dump, load and backup stay missing. That `other_engine` query client prefers authentication plugins, then the newest client version, then installed before bundled, then discovery order and installation key. The `unknown_server` first-contact order stays unchanged. For MariaDB this adds a note that dumps and restores need MariaDB tools. Reason codes are `chosen`, `series`, `newer`, `older`, `unknown_server`, `other_engine` and `newest` (Shell). **Choices and trust.** **Settings > Client tools…** stores independent `client_choice_mysql` and `client_choice_mariadb` settings. The value is the absolute client path or folder as chosen (preserving stable symlink spelling), `bundled`, or no key for **Automatic (best match for each server)**. Validation requires an absolute path of at most 4,096 characters without NUL or line breaks, a client named mysql or mariadb (with .exe on Windows), a regular executable file, and a recognized mysql/mariadb banner of the requested engine. The chooser runs `--no-defaults --version` in `client_environment()` with a 5 s deadline and 16 KiB per stream, in a process group killed with its children at the deadline. A rejected choice leaves the stored and active choices intact. A stored choice that moved, stopped working or became untrusted remains stored with its error; resolution raises `ClientMissingError` rather than silently falling back. At startup `migrate_client_choices` moves `client_binary` once: a successful trusted probe decides the engine, otherwise a mariadb filename means MariaDB and any other name means MySQL; broken paths are preserved. Bundled paths become `bundled`, existing per-engine choices win, and the legacy key is deleted. Choices are published with `connector.set_client_choices` at startup and after changes; existing connection objects follow the generation on their next resolution. Every discovered or chosen non-bundled copy must pass `connector.checked_program` before probing or receiving credentials. On POSIX, the file and every ancestor of both the chosen spelling and its realpath must be owned by the user or root, with no group/other write; symlink modes do not control replacement. Exceptions are root-owned sticky directories and, only on macOS, group write by the admin group (gid 80) without other write. Windows accepts only local mysql.exe, mariadb.exe, mysqldump.exe, mariadb-dump.exe, mariadb-backup.exe or mysqlsh.exe under ProgramFiles, ProgramFiles(x86), ProgramW6432, LOCALAPPDATA or the user profile (MYFLAMES_USER_PROFILE or USERPROFILE); UNC and device paths are refused before resolution. This is a location restriction, not a Windows ACL check. Only the actual bundled folder is exempt, never an arbitrary extra search folder. Refused copies remain in `skipped` with their reason. Each use rechecks the path and pinned resolved target, refuses a changed target, and executes the resolved file. Lifecycle rechecks immediately before launching; editor helpers recheck the tab's pinned client. The single-client shortcut also checks trust. An explicit connector `binary=` override bypasses automatic selection and its trust checks; it is not a workspace setting or accepted connection field. **Connector resolution and first contact.** Resolution is a per-connection `binary=` override, then the Settings choice for the known engine, otherwise automatic selection for that server. With no choices and at most one stat candidate, resolution uses the checked candidate without an inventory probe or preliminary server read; option-file construction still probes its engine. With multiple distinct clients and no cached facts, `_first_contact` runs `SELECT @@version, @@version_comment` once per endpoint flight using that connection's credentials, socket/TCP, TLS and SSH tunnel. A MySQL choice is used first, then a MariaDB choice; without choices it uses the unknown-server query fallback. Unrelated automatic clients are not probed while a chosen installation supplies the connection. If the read discovers an engine with no choice, full discovery then supplies that engine's automatic pick. Concurrent callers share first-contact success or failure. Only a missing authentication plugin permits one retry with the other engine's best client; login and transport failures propagate without a second connection. A server SQL error with `at line N` and a non-2xxx error number leaves the version unknown; so do unparseable or unsupported versions such as ProxySQL 2.x. Unknown and failed reads are not cached and a later request may retry. `client_tools` keeps valid `{engine, version}` facts in a thread-safe 256-entry LRU without a time limit. The key is host, port, socket, ssh_host, ssh_user and ssh_port (defaults localhost/3306/22); localhost and 127.0.0.1 are distinct, and database user, password and TLS are not part of the key. Connector version reads, editor handshakes and the client-tools API also remember valid facts. `ClientMissingError` (`ConnectorError`, code `client-missing`) reports no usable client or a broken choice. `ClientAuthPluginError` subclasses it with code `client-auth-plugin`. Only the first ERROR line of a client connection failure matching `ERROR 2059 (HY000): Authentication plugin '' cannot be loaded` (end of line, colon or period after `loaded`, plugin name letters/digits/underscores) gets that type. Statement errors (`at line N`) and subsequent ERROR lines do not. Its text names the program, version, origin and plugin, and directs the user to Settings. `client_missing_error` follows causes and only myflames' own ConnectorError/ValueError wrapper contexts; unexpected exception contexts still produce generic 500 errors. Typed client failures answer HTTP 400 with `error` and the error's `code`. `ClientMissingNotice` offers **Choose client tools…** and **Try again** in Server views, Test connection and the Query editor; plugin failures show their specific text. Maintenance can retain its inventory and download links when the server cannot be read. Option files follow the probed client engine, including a mysql compatibility link to MariaDB, and remain paired with that invocation's binary. `client_tls_options` serves reads, writes, editor/CSV sessions and lifecycle programs. MySQL gets `ssl-mode` and, for connector sessions unless TLS is DISABLED, `get-server-public-key=ON`. MariaDB maps DISABLED to `skip-ssl`, REQUIRED to `ssl`, VERIFY_CA and VERIFY_IDENTITY to `ssl` plus `ssl-verify-server-cert`, and PREFERRED to no mode option. It receives neither `ssl-mode` nor `get-server-public-key`. Both keep CA, certificate, key and cipher options. This mapping uses the client engine, not the server engine. **Client tools API.** Authenticated `POST /api/client/tools` accepts `{}` for inventory only, optional `refresh: true` to re-probe, and optional `connection` to read that server and select roles. `POST /api/client/tools/choose` requires `engine` (mysql or mariadb), `path` (absolute program/folder, `bundled`, or null for Automatic), and optionally `connection`; unexpected fields are refused. Only choose mutates settings. Missing API authentication answers 403; invalid fields, paths or engine choices answer 400 with a plain `{error}` and no code, leaving the active choice intact. Both return `client-tools-1.0`: - `installations[]`: `key`, `engine`, `version`, `series`, `folder`, `found_in`, `origin`, `origin_label`, `bundled`, `has_auth_plugins`, `programs` keyed by name with `{path, realpath, version}` (no mysqlpump), and `chosen_for[]`. Order is engine, descending version, then discovery order/key. - `shells[]`: `{path, realpath, version, origin, origin_label}`, newest first; `skipped[]`: `{path, reason}`; `choice`: mysql and mariadb objects with `{path, installation, error}` (null where absent). - With a connection only: `server` `{engine, version, product}` or null, `server_error` `{code, error}` or null, and `used` with nullable `client`, `dump`, `load`, `backup`, `shell`, plus `missing[]` `{role, program, text}` and `notes[]`. Each use has `role`, `program`, `path`, `version`, `engine`, `installation` (null for Shell), `origin`, `origin_label`, `bundled`, `reason`, `warning`; internal realpath/version_tuple/order are omitted. A server-read error uses `client-missing`, `client-auth-plugin` or `server-read`; typed client failures clear `used.client`. `/api/client/settings`, `/api/client/detect` and `client-settings-1.0` are removed; the old endpoints return 404. The dialog shows the programs for the connection in use, separate engine choices and **Found on this computer** with **Detect again**. Its install hint appears only when no installation was found. `toolUseLine` renders program, version, origin and selection reason in Maintenance and the review sheet; Maintenance heads this block **Used for this server**. The Dump tool choice names the program, version and origin (or the Shell version for Automatic). The deprecated CLI and `myflames-mcp` use automatic selection only, without the workspace's stored choices; `--mysql-binary` still overrides query connections. Each new command process with several clients pays its own first-contact read because endpoint facts are in memory. No new CLI flag or MCP tool is added. Contract tests: `test/test_client_tools.py` (`DiscoveryTests`: inventory, origins, plugins, trust, probe identity/LRU/single flight/limits; `SelectionTests`: ranking, roles, reasons, missing choices; `EndpointTests`: endpoint normalization and facts LRU). `test/test_connector.py` (`TestVersionAwareClients`: resolution and first contact; `TestClientSelection` and `TestWindowsClientTrust`: validation/trust; `TestClientSecurityFixes`: trust, exact 2059 matching and MariaDB TLS; `TestBundledClientResolution`: bundle paths). `test/test_workspace_store.py` (`TestWorkspaceStore`: independent choices and legacy migration); `test/test_ui.py` (`TestClientToolsAPI`: authentication, validation, wire fields, removed routes and typed errors). `test/test_editor_session.py` (`ProcessTests`, `PinnedClientTrustTests`): pinned helpers and permission changes. UI: `apps/workspace/test/client-tools.mjs` (`npm run test:client-tools`), replacing `database-client.mjs`. **UI preferences.** `POST /api/settings/ui` is in `_SETTINGS_PATHS`, requires the usual local session and CSRF token, and never opens a database server connection or writes an audit record. `{}` returns `ui-preferences-1.0`, with `preferences` and `defaults`. `{"set": {...}}` validates every change before writing `ui.` JSON rows in one transaction; unknown keys, invalid values, unknown outer fields and a non-dict `set` (including null) return 400. A read, including an empty `set`, never creates the workspace database. Stored `ui.` prefixes are case-sensitive. `workspace_store.UI_PREFERENCE_DEFAULTS` defines `theme` (`system`, or exactly one of the single literal `UI_THEME_IDS` list matching TypeScript `THEME_IDS`), `sidebar_width` (integer 208–320, default 208), `server_nav_collapsed` (boolean, default true), `inspector_width` (integer 280–560, default 340), `explain_format` (`table`, `tree` or `json`, default `table`), `files_show_hidden` (boolean, default false), `files_transfers_open` (boolean, default true), and `health_auto_production` / `health_auto_development` (each an integer -1, 0, 10, 30 or 60, default -1; -1 follows the sampling window and 0 disables refresh). Booleans and floats are refused for integer preferences. Unknown or malformed stored rows fall back to defaults. The index reads only the theme through a read-only connection with a 0.5-second lock timeout, without creating or migrating storage. It refuses symlink store paths, omits its theme attribute if preference storage cannot be read and still returns 200. `src/uiPreferences.ts` shares a module value and listeners, displays changes immediately, serializes writes, ignores stale answers and re-reads after the latest write fails. Startup waits up to 1.5 seconds for preferences before mounting the sidebar with the current values; a late answer still updates the theme, sidebar width and subscribed controls. The renderer exposes `window.__myflamesFlushUiPreferences()` to drain the serialized preference queue for up to 1.5 seconds, including writes queued during the drain. Desktop quit, direct window close and Restart to update call it before stopping the backend; a direct close then replays the ordinary window close so its unsaved-work check still applies. The replay guard lasts until the window closes, the renderer refuses unload, or two seconds pass, so asynchronous close events do not flush again and a later close after refusal can drain new preferences. Restart to update still overrides an unload refusal. The main process also bounds an unresponsive renderer to 1.6 seconds. A crashed renderer or timed-out write can still lose its last pending preference. Tests: `test/test_workspace_store.py`, `test/test_ui.py`, `test/ui-preferences-unit.mjs` and `test/shell-layout.mjs`. **Query editor settings and variable names.** `POST /api/settings/editor` (ui.py `_SETTINGS_PATHS`; no connection, no server read, no audit) reads and writes the Query editor's settings in the workspace store's `settings` table (rows `editor.` = `on`/`off`). `{}` returns `editor-settings-1.0` with `settings` (the defaults merged with the stored rows; unknown keys and malformed values fall back to the default) and `defaults`; `{"set": {key: bool}}` writes the given keys in one transaction and returns the same shape. The keys are `multi_cursor`, `completion_auto`, `close_brackets`, `soft_wrap`, `problem_warnings` and `hover_info` (`EDITOR_SETTING_DEFAULTS`; `soft_wrap` defaults off, the rest on). A read never creates the database. An omitted or null `set` reads without writing. A payload with any field besides `set`, a non-null `set` that is not a dict, an unknown key or a non-boolean value is a 400 through the shared `request_error_text` ("Unexpected editor settings field.", "Expected a dict of editor settings.", "Unknown editor setting ...", "The editor setting ... must be true or false."), as is a call without a running workspace. `POST /api/config/versions/names` (`_PARAM_VERSION_PATHS`) answers offline from the generated parameter catalogs: `{engine, version}` returns `param-names-1.0` with `engine`, `requested`, `release` (null when the series is not cataloged or the version predates its first release), `exact` (true when the numeric version extracted from the request is cataloged, including a suffixed build; false when an uncataloged patch resolves to the nearest earlier cataloged release of the same series) and `names` (`name`, `scope` `global`/`session`/`both`, `type`, `dynamic`, `deprecated`; `type` and `dynamic` are null where the catalogs do not record them, never a guessed false). The Query editor's completion reads it for `@@` system-variable suggestions and caches the answer per engine and version in the page. A bad engine or version is a 400 ("Choose engine mysql or mariadb.", "Choose a cataloged version of at most 32 characters."). Tests: `test/test_ui.py` (editor-settings round trip, bad payloads, local routing) and `apps/workspace/test/editor-settings.mjs`. `QueryEditorSettings.tsx` tracks saves and errors per setting, with a request sequence per key that ignores stale completions. Each row keeps an empty `role="alert"` node mounted until an error fills it. `package:win` builds the unsigned Windows x64 NSIS installer (`myflames--windows-x64-setup.exe`, per user). PyInstaller does not cross-compile, so `.github/workflows/windows-desktop.yml` builds the backend on a Windows runner, packages the installer, runs the packaged smoke on `dist/win-unpacked` and uploads the installer with its SHA-256; releases attach that artifact (`myflames--windows-x64-setup.exe` and its `.sha256`, from the workflow run of the release commit) as an unsigned preview until Windows crash supervision and signing land. Windows quits with `taskkill /PID backend /T /F` and is unsigned. Crash supervision is partial there: an SSH tunnel's ssh.exe ends with the backend however the backend ends (its kill-on-close job object; Windows tunnels are not listed in `tool-groups-1.0`), while dump, restore and clone tools still outlive a backend that crashed or was killed. See [Desktop app](https://myflames.io/docs/ref-desktop.md) (`docs/DESKTOP.md`) and the desktop package README for launch and test instructions and for the scope and distribution work still required. Current delivery targets macOS. The shared working UI now uses compact neutral navigation, open-query links, a command palette and full-width Server details. Update checks run only when the workspace asks: **Check for updates** in the window status bar on every screen and in About myflames (`UpdateCheck.tsx`, shared state in `updateStatus.ts`) posts `/api/app/update/check` with `force: true`. The `app-update-1.0` answer carries `checked_at` (UTC, when the release metadata was read; a cached answer keeps its time), and a failed check carries `error` plus a short `reason` (GitHub could not be reached, did not answer in 5 seconds, took longer than 10 seconds to answer, limited requests, answered with a status, sent the check to an unexpected address, unreadable release information, or "a secure connection to GitHub could not be verified" when certificate verification failed, which is not reported as offline); a failed check is never cached and never reported as up to date. From the workspace, the check also stores `last_check` (`checked_at`, `outcome` `up_to_date` | `available` | `failed`, `current_version`, `latest_version`, `reason`; never release notes or URLs) in the workspace store's `settings` table (`app_update_last_check`). `/api/app/update/status` returns `app-update-status-1.0` with that record and never reads the network; a record made by another myflames version is dropped. The footer shows "Checked today at 10:42", "Checked yesterday" or "Checked Oct 18" in local time with the full timestamp in the tooltip ("Tried …" for a failure), "Not checked yet" before the first check, "Last check unknown" when the stored record could not be read (retried when Home or About mounts again), and a result older than 24 hours, or one whose time cannot be read, as "Last result: …". **Check for updates automatically** in Settings (on by default, stored in the workspace store's `settings` table under `app_update_auto` as `'on'`/`'off'`; `POST /api/app/update/settings` with an optional `{"auto_check": bool}` returns `app-update-settings-1.0` `{"auto_check"}`) lets the workspace check 10 seconds after it opens when there is no stored check, the last one is older than 24 hours, or the last one failed more than an hour ago, re-testing that hourly; an automatic check uses the same `/api/app/update/check` as the button, and a failed automatic check shows no badge (the window status bar shows the reason as before). When a current check found a newer version, a round badge appears beside the flame logo and the myflames name at the top of the sidebar (`UpdateBadge.tsx`): available (a download arrow), the download's progress (a ring with the percent in its tooltip), preparing (a spinner) and ready (a green restart arrow); on the 48 px icon rail (651–900 px windows) it is a dot on the logo's corner, and a result older than 24 hours shows no badge. While an update is pending, the Settings page's Updates and news section also lists **Update available…**, **Update progress…** or **Restart to update…**; clicking the badge or the menu item opens the Software update dialog. **Download…** appears for a current newer release (unavailable while a check runs) and opens the update dialog with the result captured at the click; after a reload it checks again first, because the download needs the asset the check found. Download update saves the DMG or EXE in Downloads and never installs it; it prefers the `.dmg` on macOS (then `.zip`, `.tar.gz`) and the `.exe` on Windows regardless of the order GitHub lists assets, and checks the download against the release's `.sha256` when the release has one, a mismatch falling back to the release page like any failed download. Application updates (`myflames/app_update.py`, `/api/app/update/check` and `/api/app/update/download`) build both openers as `tool_updates._fetch` does (`app_update._opener`): `ProxyHandler({})`, so no proxy from the environment or the macOS settings is used, one HTTPS handler with the `tls.https_context()` context, and a redirect handler that checks every target before following it and closes the redirect response without reading its body (urllib's own handler reads it whole, with no size limit; urllib's limits of four visits to one address and ten redirects still apply). The check follows redirects only to HTTPS `api.github.com` at `/repos///releases/latest` or `/repositories//releases/latest` (how GitHub moves a renamed or transferred repository) and checks the final URL too; it reads at most 1 MiB (a longer answer is unreadable), and each socket operation times out after 5 s. The check answers within `CHECK_DEADLINE` (10 s): `app_update._read_release` runs the read in a worker thread and waits for it at most that long, and `tls.Watchdog` shuts the worker's TCP and TLS sockets at the same deadline. What comes before a socket exists is not cut (building the TLS context, which may read the macOS roots with `/usr/bin/security`, the DNS lookup, and the TCP connect, 5 s per address), so a read still running at the deadline ends in the background. A check made while a read runs waits for that read and shares its answer; once the deadline has passed it reports the deadline at once, and no second read starts until the first ends. The check selects an asset only when its operating system and architecture match; macOS also accepts universal builds. An unmatched release has no selected asset. The first download URL must be an HTTPS `github.com/vgrippa/myflames/releases/download//` URL; when an update check has found an asset (the cached `check_for_updates` result), only that `asset_url` is accepted and any other client URL is refused, never substituted. `objects.githubusercontent.com` and `release-assets.githubusercontent.com` serve every repository's release files, so they are accepted only as a redirect target or as the final response URL. Every redirect is checked before following it, and the final response URL is checked before reading the body. Other URLs raise `ValueError`; release-page fallbacks also require the project's official HTTPS release page. Downloads use an exclusively created private temporary file in the destination directory and enforce the 200 MiB limit (`MAX_UPDATE_BYTES`) before publishing. http.client returns an empty read at an early EOF even when Content-Length promised more (TLS ragged EOFs are suppressed too), so after the read loop a remaining declared length, a byte count different from Content-Length, or one different from the checked `asset_size` raises "The download ended early." (or a size mismatch) and the temporary file is removed unpublished. Publication uses an atomic hard link to an unused name, adding ` (1)`, ` (2)`, etc. before the extension on collisions; files and symlinks already present are preserved. The temporary file is removed after success or failure. If the filesystem cannot publish a hard link, the download opens the validated release page (or the official latest-release page) in the browser, never the binary asset URL, and returns that page as `html_url`. The TLS, headers and body read have a 300-second `tls.Watchdog` deadline, checked even after an EOF so an interrupted response cannot be published. DNS, TCP connection establishment and TLS-context construction precede socket registration and cannot be interrupted by this watchdog. The destination is `MYFLAMES_DOWNLOADS_DIR` when it names an absolute existing directory (the desktop app sets it to the user's Downloads folder, because its backend runs with an isolated HOME), else `~/Downloads`, else the temporary directory. The Software update dialog's **Update** button stages the release's update file (`POST /api/app/update/stage`, `app-update-stage-1.0`): the backend first reads the release's `.sha256` (at most 1 KiB, one `<64 hex> ` or `<64 hex> *` line naming exactly that file), then downloads `myflames--macos-arm64.zip` on macOS or `myflames--windows-x64-setup.exe` on Windows with the same HTTPS, redirect, host and 200 MiB rules as Download, within 900 seconds (`STAGE_DEADLINE`), checks size and SHA-256, publishes the file atomically into the desktop app's private updates folder (`MYFLAMES_UPDATES_DIR`, which `main.cjs` sets to the updates folder inside the desktop data folder and makes mode 0700), removes the updater's own older files there (`staged-update.json`, release file names and `.myflames-stage-*.part`; anything else stays) and writes `staged-update.json` (`staged-update-1.0`: `version`, `platform`, `file`, `size`, `sha256`, `staged_at`) atomically. Staging answers at once and runs in a background thread, one at a time; its state is `running` | `done` | `failed`, with `version`, `received`, `total` and `reason`. The update file must be named `myflames--(macos|windows)-(arm64|x64|universal)[-setup].(zip|exe)` and match the platform (zip on macOS, `-setup.exe` on Windows), and its URL must be this release's own `/releases/download//`. The updates folder must be a plain folder, not a link, and on macOS and Linux owned by the user with no access for others (`app_update._updates_directory` and `updater.checkFolder` check the same rule); otherwise staging, the status record and startup cleanup refuse it and touch nothing. `/api/app/update/status` (still never the network) adds `auto_check`, `staging` (that progress), `staged` (the verified record, or null) and `active_operations` (dump, restore and clone jobs queued or running). At startup, after the single-instance lock, the desktop app removes a staged update that is not newer than itself (installed) or whose record cannot be read. In development only (never a frozen backend, and the desktop's environment allowlist drops both variables), when `MYFLAMES_TEST_UPDATE` and `MYFLAMES_TEST_UPDATE_FILE` (an absolute path to a regular file) are set, staging copies that file instead of downloading. The page then calls `window.myflamesDesktop.update.prepare()`. `updater.cjs` reads `staged-update.json` from the fixed folder only (no links followed, at most 4096 bytes, the file name pattern above, this platform, a version newer than the app's) and hashes the file again. On macOS it serves the zip once on 127.0.0.1 (a random port, an unguessable 64-hex path, the JSON feed and the zip, closed after the update is staged or after 2 minutes) to Electron's `autoUpdater` (Squirrel.Mac, `serverType` `json`), which installs it only when its code signature satisfies the installed app's designated requirement (the same Developer ID team and bundle identifier), and `ElectronSquirrelPreventDowngrades` in the app's Info.plist refuses a lower version even from that team; a zip signed by anyone else is refused with "The update is not signed by the developer of this copy of myflames, so it was not installed." macOS updates in place only when the app is in an Applications folder (`app.isInApplicationsFolder()`) and its bundle and that folder are writable; otherwise the dialog names the reason (for example "Move myflames to the Applications folder to update it in place.") and offers **Download update** as before. The loopback feed answers only exact request lines with `Host: 127.0.0.1:` (anything else gets 400, and no request can throw in the main process). **Restart to update** on macOS stops the backend and its dump, restore, clone and tunnel processes first (a second Quit meanwhile is held, as during any quit), then `autoUpdater.quitAndInstall()` replaces the app and opens the new version; **Later** installs the update when you next quit myflames, without reopening. Squirrel.Mac also applies a staged update at that quit when the backend could not be confirmed stopped. On Windows, when the app quits after the backend stopped (never when the stop failed, and never when `MYFLAMES_DESKTOP_DATA` chose the data folder, whose owner cannot be checked there), it runs the installer from the updates folder, in that folder, detached, without a shell: `.exe --updated /S` (silent, keeps the app's data), plus `--force-run` after **Restart to update** so the new version opens. The Windows installer is unsigned: the update is trusted through HTTPS from GitHub's release hosts and the SHA-256 published in the same release, and an Authenticode publisher check is to be added when Windows signing lands. When a dump, restore or clone is running, **Restart to update** first says "A dump is running. Restarting stops it before it finishes." and offers **Restart anyway**; other work in progress (an open editor transaction, an import, a file transfer, a skip loop) stops as it does on any quit. Verified on 2026-11-09 with Developer ID signed (not notarized) test builds 3.3.90 and 3.3.91 under a separate bundle identifier: **Restart to update** installed 3.3.91 and reopened it within about 5 seconds with only the new backend running, **Later** followed by a normal quit installed it without reopening, and an ad hoc signed 3.3.91 zip with a correct checksum was refused by Squirrel.Mac and the app stayed 3.3.90. On the Windows lab PC the CI installer, staged as a newer version, was installed silently after **Restart to update**, which replaced the install folder and reopened the app 13 seconds later. After the security fixes, signed builds 3.3.95 and 3.3.96 repeated the macOS update through the Host-checked feed, and an older signed build staged as 3.3.99 was refused by `ElectronSquirrelPreventDowngrades` ("The update is older than this copy of myflames, so it was not installed."). Every HTTPS read (the release check and download, `tool_updates._fetch`, and Home news) takes its context from `myflames/tls.py` `https_context()`: the standard library's default context, with certificate and host name checks on. The packaged macOS app's bundled OpenSSL looks for certificate authorities only at paths on the build machine (Homebrew's `/opt/homebrew/etc/openssl@3/cert.pem`), so on a Mac without them the default context trusts nothing. When it holds no CA certificate on macOS, `https_context()` also loads the roots macOS trusts, read with `/usr/bin/security` (10 s limit per call, `LC_ALL=C`): the certificates `find-certificate -a -p` exports from `/System/Library/Keychains/SystemRootCertificates.keychain` and `/Library/Keychains/System.keychain`, kept only when their SHA-1 is listed by `trust-settings-export` (system `-s`, admin `-d` or user domain) as a trusted root with no policy, application or host restriction, and no domain denies it for any policy. The exports also hold intermediates (Developer ID, WWDR) and System Identity certificates, which have no trust settings and are left out. When any trust domain cannot be read (the export fails, times out, writes no file or an unreadable plist), nothing is added, so a "Never Trust" choice is never dropped. An admin or user domain without settings counts as empty only in the two forms macOS reports it: an export that succeeds with an empty `trustList` (macOS 27, checked on 27.0.1) or "No Trust Settings were found" on stderr (older macOS). A complete read is kept for the process; a failed or partial one (a keychain export that failed) is read again after `tls.RETRY_AFTER` (60 s), never cached for the process. When `SSL_CERT_FILE` or `SSL_CERT_DIR` is set, even empty, the user chose the trust store: myflames adds no macOS roots (OpenSSL reads an `SSL_CERT_DIR` only on lookup, so its context counts no CA up front). `tls.Watchdog`, `tls.watched_connection_class` and `tls.WatchedHTTPSHandler` give Home news and the release check one deadline per read for everything after the TCP connect (the TLS handshake, headers and body). The DNS lookup, the connect and building the context come before the watchdog holds a socket, so each caller also bounds its own wait (the release check's worker, the news refresh's join). Tests: `test/test_tls.py` (with `test/fixtures/tls/test-root-ca.pem`, a throwaway CA whose key was discarded). Home news (`myflames/news.py`, `/api/news` and `/api/news/settings`, `news-1.0`) reads the two feeds in `news.SOURCES` and nothing else: Planet MySQL (`https://planet.mysql.com/rss20.xml`, keeping only links under `https://blogs.oracle.com/mysql/`, the MySQL team's posts) and the MariaDB Foundation (`https://mariadb.org/feed/`, links on `mariadb.org`). The Oracle MySQL blog feed itself (`blogs.oracle.com/mysql/rss`) answered 403 to every client tried on 2026-10-20, and `mariadb.com/feed/` refuses a User-Agent that starts with Python-urllib, so neither is read. `fetch_feed` sends `User-Agent: Python-urllib/ myflames/` (Planet MySQL's CDN refuses a first product it does not know), `Accept-Encoding: identity`, no cookies and no identifiers, through an opener with only an HTTPS handler and its own redirect handler: at most three redirects, each to an HTTPS feed host without credentials or a port, within the feed's deadline, closing every redirect response without reading its body. It reads at most 1 MiB, each socket operation times out after 5 s, and the feed stops at its 8 s deadline: a watchdog (`tls.Watchdog`) shuts the feed's sockets down at that deadline, the TCP socket and the TLS socket wrapped around it (registered before its handshake, since wrapping detaches the TCP socket, and shut on its descriptor without touching the TLS state the reading thread uses), so the TLS handshake, headers or chunk framing cannot outlast it either. The DNS lookup and the TCP connect (5 s per address) come before the watchdog holds a socket and can; the wait of `/api/news` (below) bounds them. Its tests and the release check's use the local servers in `test/_tls_servers.py`: one that never answers a TLS handshake, and one that sends an optional head at once, then the rest of its answer a byte at a time (so the release check's test stalls inside one body read as well as in the headers). `parse_feed` refuses NUL bytes and declared encodings other than UTF-8, ASCII, ISO-8859-1 and windows-1252 (UTF-16 or EBCDIC would hide a declaration from a byte check), refuses ``; `ReplicationView` reads once when it opens on screen with no report or one from another connection, never while a hidden place stays hidden. The Cluster report is shared the same way (`clusterShared` in `main.tsx`, `cluster`/`onCluster` on `Server`), and the shell derives the sidebar item's state from it (`clusterNav` in `clusterApi.ts`). Badges come only from loaded reports, which `Server.tsx` keeps. Every view uses `ViewLayout` from `kit.tsx`: toolbar, one summary line, a table or one-line rows, and an inspector (pane, or a bottom sheet below 1,040 px; the list of views is pushed below 720 px). Shared components live once in `kit.tsx`/`kit.css` (SourceList, DataTable, GroupedList, Inspector, Popover/NotesButton, StatusPill, CountBadge, NavMarker, Segmented, MetricTile, TileGrid, FactStrip, Fields, Sparkline, ConfirmSheet, PrerequisiteGate); explanations go behind ⓘ or into the inspector, never on the page. Investigations (`Library.tsx`), Learn (`Teach.tsx`; the CLI stays `myflames teach`). Below the places, Open plans; from 651 to 900 px the sidebar becomes a 48 px icon rail, with tooltips, accessible names, compact status markers and an Open plans (N) popover. Its toggle opens the full sidebar as an overlay and Escape returns focus to the toggle. At 650 px and below it keeps the Menu drawer. The footer has one autosave status and the Settings gear, which opens the Settings page (`SettingsPage.tsx`): a page in the main area, not a place in the sidebar's navigation, with a section list on the left (the Server place's `SourceList`): Appearance, Query editor, Workspace (Restore workspace on startup and Start fresh), Updates and news (Check for updates automatically, Show MySQL and MariaDB news on Home, and the update item while one is pending) and Client tools, with Audit log and About myflames as actions at the bottom of the list. It opens from the gear, ⌘, (Ctrl+, on Windows and Linux) or the command palette, and closes with Escape, Back or choosing a place, returning focus to the gear. The two switches carry their explanation in a visible hint tied by `aria-describedby` ("Off clears the saved workspace. Passwords are never saved in it.", or "Off for this launch (--no-restore); the saved workspace is kept."; "Planet MySQL and the MariaDB Foundation, read over HTTPS while Home is open."), with no separate information button; Home's news section keeps its own. Saved connections and the connection picker are in `Connections.tsx`; the UI says "connection", the API/CLI keep `profile`. The connection in use is `query_lab.profile_id` + `query_lab.connection` in the session (its password stays in page memory; `connection.read_only` is the one safety choice of an unsaved connection). `connectionSafety` there is the client twin of `dbops.connection_safety` (a saved connection's type only while host, port, user and TLS settings match, else Production) and `requestConnection` sends its `type` and `read_only`. Profiles are read again on window focus and by `WritePolicyContext.check` right before a Kill is sent (a changed type or read-only flag changes the connection key, so the sheet sends nothing); while they are not loaded or the read failed the policy is unknown: the footer says "Production assumed" and Kill is off (`WritePolicy.blocked`). `SafetyStatus` (`Connections.tsx`) is the first item of the window footer (`WindowStatusBar lead`, `kit.tsx`) on the places that send to the connection in use (Query editor, Server, Workload, Replication, Cluster, Tuning): `data-status="safety"`, `data-safety` production, read-only, development or unknown, a dot plus words, `role="note"` with the full sentence as `aria-label` and tooltip, and Retry after a failed read. Nothing sits under the top bar (`--topbar-height` is the top bar row), and the picker shows `TypeDot` and `SafetyTags` (a short type word in place of the pills where they yield to width; see Home connections below). The Audit log is `Audit.tsx` (session mode `audit`, no place active). Stored session `mode` values keep the earlier names (`inspect`, `compare`, `query`, `library`, `teach`) plus `home`, `server` and `audit`; `placeOf` in `main.tsx` maps them to places. Naming follows `.claude/skills/ui-architecture/references/vocabulary.md`; styles use the tokens on `:root` in `style.css` (web-design skill). Browser test for the shell: `apps/workspace/test/navigation.mjs`; `apps/workspace/test/server-nav.mjs` covers the Server place. The workspace sidebar, Home, About and favicon use the 128 px `myflames-app-logo.png`, derived from `myflames-logo.svg`. Vite emits the stable `/assets/myflames-logo.png` URL. `npm ci && npm run build` there regenerates committed `myflames/ui_assets/` files shipped in the wheel. Python users need no Node.js. The UI API reuses the parser, sidecars, and renderers. Investigations are saved only on request. Investigations and saved connections (profiles) use `~/.myflames/workspace.sqlite3`; remembered connection passwords are stored separately. `/api/investigations/list` returns summaries only (`investigation-list-1.0`: `items`, newest first, and `next_cursor`, null on the last page; request `limit` 1 to 50, default 25, an optional `cursor` and `search`). Each item is an `investigation-summary-1.0` (`id`, `updated_at`, `name`, `notes`, `tags`, `baseline_id`, `plans [{id, name, capture: {mode}}]`), never a plan; `search` keeps the rows whose name, tags or notes contain the text, ignoring case, as Library's own filter does. `/api/investigations/get {id}` returns the complete saved `investigation-1.0` bundle (the shape `list` returned before), which Open, Compare to baseline and Export read on demand. Home asks for 6 rows; Library for pages of 25 with Load more and searches on the server after a 250 ms pause. `WorkspaceStore.list_investigations` pages on `(updated, id)`, so a delete never skips a row. Summaries live in the `investigation_summaries` table, written in the same transaction as each save and delete and checked against `records.updated` before every list: an older myflames using the same file writes records only, so missing or outdated summaries are rebuilt one bundle at a time and a record that is not a readable bundle is left out (no `STORE_VERSION` change or migration). `WorkspaceStore.list("investigation")` keeps its full-bundle result for Python callers. Tests: `test/test_investigation_summaries.py`, `test/test_workspace_api.py`, `navigation.mjs`. `/api/analyze` sends the plan's SQL once (`query`, and the sidecar's `query.raw`): its teach hooks, top level and in `analysis`, carry no `query_sql` (one copy per hook made a 801-operator plan with 70 KB of SQL a 123 MiB response). Export JSON adds `query_sql` back to each hook (`exportedAnalysis` in `api.ts`), so the file equals the CLI sidecar (`browser.mjs` compares them); the CLI sidecar, digest and HTML report keep `query_sql` on every hook. Its `chart_data` is `chart-data-2.0` (`build_chart_data(..., compact=True)`): each analysis message is stored once in `highlight_messages` and nodes carry `highlight_id`, because a grouped warning names every affected table and applies to each of them. HTML reports and `explore` pages still embed `chart-data-1.0`; the bundle reads both (`charts/core/highlights.ts`), and `charts.mjs` checks that both draw the same chart. Tests: `test/test_workspace_payloads.py`, `test/test_chart_data.py`. **Save connection** then **Save with password** stores the secret through `secret_store.py` (macOS Keychain via `security -i` stdin, `secret-tool`, Windows Credential Manager, else the HMAC-SHA256 encrypted vault `~/.myflames/credentials.vault` + `vault.key`; `MYFLAMES_SECRET_BACKEND=keychain|vault|none`). Connection endpoints accept `connection.profile_id`; `WorkspaceStore.connection_with_saved_password` fills the password per request, only for the profile's own host/port/user. The secret's key is `..` (the record's `secret_ref`, never returned by the API): a SHA-256 of host, port, user, TLS mode and CA path, and a new random part on every save. The record and its `secret_ref` are written in one `BEGIN IMMEDIATE` transaction, the replaced secret is deleted after the commit, and the password is released only when the fingerprint in its key matches the profile's endpoint. Passwords saved before `secret_ref` existed stay under the bare profile ID until the next save. Tests must use temporary HOME and USERPROFILE with `MYFLAMES_SECRET_BACKEND=vault`. Live capture jobs reuse `live.py`; `/api/live/status` and `/api/live/cancel` require the owning `connection` (`dbops.identity_endpoint`), refusing other connections. Workspace restore is silent on successful startup. Settings > Start fresh opens a confirmation sheet and preserves the existing backup behavior. Actual restore warnings and save conflicts remain visible. Session restore autosaves the workspace snapshot (plans, query tabs, non-secret connection fields, screen/view/selection) about 1 s after each change to the single `session` row in the same database (`/api/session/load|save|clear|settings`, revision-checked, 64 MiB cap, `password` keys stripped at any depth, file 0600 and directory 0700). Saves, clears and settings changes from one page share its `seq`; a request at or below the stored `writer_seq` of the same page (late or retried) changes nothing and returns `stale: true`, so it never deletes newer state or lowers the sequence. Client logic is in `apps/workspace/src/session.ts`; `--no-restore` skips restore and autosave for one launch without deleting the session. Test with `test/test_session.py` and `npm run test:session`. Its Learn catalog and lesson player use the existing `LESSONS` registry and `CURRICULUM` order. The Learn place uses a view toolbar (Search lessons, Family filter, Start learning), a one-line summary ("23 lessons, 16 in the learning path") and grouped rows by family, ordered by the learning path, each with its summary and "Lesson n of 16" ("Additional topic" off the path; never "Step", which is a beat of a lesson's own step bar). An open lesson has one thin toolbar, one control high (`.teach-toolbar.is-lesson`: All lessons, Previous lesson, Lesson n of 16, Next lesson, Download lesson, Full screen; it stays out of the top bar, which has no room for them at the 720 px minimum) and fills exactly the remaining height; the top bar shows the lesson title. `render_page` orders every lesson through `arrange_lesson(controls_html, stage_html)`: the banner, `section.controls` (parameters), `section.stage` (toolbar, scrubber, step bar, drawing and simplified code), `section.about-example#about-example` ("About this example": the `query_card`, then the `explainer`, side by side when there is room; lessons keep writing both cards in their stage HTML and `arrange_lesson` moves them by the exact markup the two helpers write), then the readout and Learn more; DOM order is the visual order. It also turns each control's `div.hint` into a `span.help-tip` (?) in a `.control-head` beside, never inside, its label, and appends its id to the control's `aria-describedby` (a hint keeps its own id, else `hint-`, never colliding with an id on the page); the tip opens on hover of the (?) or while the control has keyboard focus, and the controls heading gets `a.about-link` to `#about-example`. In-page `#` links are handled by the runtime (`teachFocus`: scrollIntoView, smooth unless reduced motion, focus to the section's h2) because an srcdoc frame resolves them against the workspace's address. Stage drawings fit the frame through the shared fit rule in `_BASE_CSS` (`max-height: max(160px, calc(100vh - var(--stage-chrome, 96px)))`); `teachFocus.fit()` measures `--stage-chrome` from the stage toolbar to the drawing plus captions and 24 px, and also counts what sits above the toolbar (page margin, banner, the one-row parameters) while that is at most a quarter of the window height and costs every stage drawing at most 15% of its scale; otherwise (wrapped parameters, a short window) the drawing fits under its toolbar as before. `test_teach.TestLessonPageOrder` checks the order for all 23 lessons and that the committed `docs/teach` pages equal the renderer. Full screen: `Teach.tsx` requests the browser's full screen on the lesson host (the desktop app grants only this permission, `fullscreenOnly` in `apps/desktop/main.cjs`; a refused request falls back to an overlay over the window, and one that settles after the lesson was left changes nothing) and posts `{type: "myflames-lesson-focus", focus}` to the frame; `teachFocus` in `myflames/teach/_html.py` accepts it only from its parent and switches to `html[data-focus="true"]`, moving the stage toolbar, scrubber, stage, phase label and readout grid into a fixed shell and back to their exact places on exit (lesson code keeps its element references); `main#lesson-main` becomes the Details panel. Escape in the lesson posts `focus: false`, which the workspace accepts only from that frame. A standalone page uses its own `#btn-fullscreen`. Covered by `test/learn-fullscreen.mjs` and `test_teach.TestLessonFitAndFullScreen`. The workspace adds `data-embedded="true"` to the lesson page, which hides its own header and footer. Lesson pages and the standalone catalog (`myflames teach --index`, which includes a lesson filter) use the workspace's light and dark tokens (`prefers-color-scheme`, `data-theme` overrides, and `?theme=` / `?embedded=1` URL parameters), restyled controls, and semantic `--svg-*` drawing colors resolved by `anim.cssVar` and `anim.palette`, so drawings redraw when the appearance changes and keep their meaning (descent path, arrival pulse, PK hop, build vs probe, hit, spill). Lesson titles use a colon ("B+tree lookup: how InnoDB finds a row"). See `docs/LOCAL_UI.md` and `docs/QUERY_WORKSPACE.md`. Test with `test/test_ui.py` and the CLI suite. Lessons use SVG only. The catalog exposes each lesson's key, title, summary and family; the workspace requests a lesson by key. The lesson API accepts an omitted `view` or `"2d"` for older clients and rejects any other value with HTTP 400. Session restore reads the lesson key and ignores obsolete view preferences. The shape and range helpers in `_cost_model.py` remain covered by the independent Python unit tests in `test/test_teach.py`. Keep the import dialog's native file control visually clipped but keyboard accessible; verify open/error states at desktop and narrow, short viewports. Use `docs/UI_TESTING.md` for the interaction matrix. Check contextual Learn links after navigating to a different lesson and returning to the plan. ### Release sync A release is one commit in which the versions, the release notes, the README screenshots and the handbook agree, and one GitHub release whose notes and files come from that commit. AGENTS.md "Release sync" lists the steps; these are the contracts of the tools that check them. - **Versions.** `apps/desktop/package.json` `version`, `myflames/__init__.py` `__version__` and `pyproject.toml` `[project] version` are equal. - **Release notes.** `scripts/release_notes.py X.Y.Z` (or `vX.Y.Z`) prints `docs/release-notes/X.Y.Z.md` (`--notes-dir` reads another folder) without its title line and without leading or trailing blank lines, as UTF-8: the GitHub release shows its name above the notes. It refuses a page that breaks the format in [Release notes](https://myflames.io/docs/ref-developer-reference.md#release-notes) (title, sections, order, no heading deeper than level two, at least one entry, closed code fences, no em dash and no `/api/` path outside code fences) with a message on stderr that says what to fix, and exits 1. The script then ends the notes with the inspiration credit line (`CREDIT`, the README's "Inspired by Brendan Gregg's FlameGraph and Tanel Poder's SQL Plan FlameGraphs"), unless the page already holds it, so no release's notes lose it. - **README screenshots.** `npm run docs:screenshots` in `apps/workspace` (`test/readme-screenshots.mjs`) builds nothing: it opens the built workspace in `myflames/ui_assets` through the perf harness (`open()` with `seed`, `beforeGoto`, `viewport`, `refuse`, `offline` and `launchArgs`), with the real Python server on a throwaway HOME, store and vault, two saved connections (Dev MySQL, Prod MySQL) and every database read answered from fixtures (`health-mysql-8.4-full.json`, `schemas-mysql-8.4.json`, a 24-row editor result, readiness, the editor's privileges preview, offline news). The page clock is frozen at 2026-10-14T16:26:00Z, the time zone is UTC, the locale en-US, the theme light, motion reduced, transitions and the caret hidden, and the window 1440x900 at scale 1. Chromium runs with `--disable-partial-raster` and `--force-color-profile=srgb` (without them a rounded corner's anti-aliasing changed between runs), and each image is written once two captures in a row agree. It writes `docs/screenshots/home.png`, `plan-visual-explain.png` (the sample plan), `query-editor.png` and `server-health.png`, then `manifest.json` (`version` from `apps/desktop/package.json`, `commit` from the checkout's HEAD, `captured_at` in UTC). Every request that is not for the local server is aborted from the first navigation on, and the script fails when one was made or on a page error; `--out DIR` writes elsewhere. Two runs of one build on one machine write identical PNGs (only `manifest.json` changes); fonts differ between systems, so capture on macOS, where the README's app runs. Run it after `npm run build` at the release commit. - **`scripts/check_release_sync.py X.Y.Z`** exits 0 only when the three versions equal X.Y.Z, `docs/release-notes/X.Y.Z.md` passes `release_notes.py`'s format check, `docs/release-notes/index.md` lists it first with the page's date, lists every page in the folder newest first and names only pages that exist, `CHANGELOG.md` `[Unreleased]` holds no entries (they moved into the page), `docs/screenshots/manifest.json` `version` is X.Y.Z with the four README images present, and `docs/handbook/manifest.json` parses with every listed chapter file present; otherwise it lists every problem and exits 1. - **Release files.** A release carries `myflames-X.Y.Z-macos-arm64.dmg` (new installs), `myflames-X.Y.Z-macos-arm64.zip` (the in-app update file) and `myflames-X.Y.Z-windows-x64-setup.exe`, each with its `.sha256`. The DMG is uploaded before the zip (a lower asset id): an installed myflames up to 3.3.3 takes the first macOS asset GitHub lists (`app_update.match_asset_for_platform`), which must stay the DMG. `gh release create` uploads its files in parallel, so the zip and its `.sha256` go up with a separate `gh release upload` after the create ends. `scripts/check_release_assets.py X.Y.Z RELEASE_JSON` (the `gh api repos/vgrippa/myflames/releases/tags/vX.Y.Z` answer, or for a draft, which has no tag yet, `gh release view vX.Y.Z --json assets`, whose node ids it reads the number from `apiUrl` for; `-` reads stdin) checks the names, that every file finished uploading, the id order, and that the first macOS file in GitHub's list, by the 3.3.3 rule (`legacy_macos_choice`), is the DMG. - **`.github/workflows/docs-sync.yml`** (`contents: read`; `contents: write` only in the release job). On a pull request to master (also when its labels change): a change under `apps/workspace/src/`, `apps/desktop/` (not `test/`) or `myflames/` (not `ui_assets/`, `tests/` or `test_*.py`; both sides of a rename count, and names are compared whole, so a name holding a newline cannot pass for `CHANGELOG.md`) without a change to `CHANGELOG.md` or to a `docs/release-notes/*.md` page fails unless the PR has the `no-changelog` label, and a change of the `apps/desktop/package.json` version runs `check_release_sync.py` for the new version. When a release is published, or by hand for a tag (Actions > Docs and release sync > Run workflow), it checks out the tag (the whole value must match `vX.Y.Z`; it is never echoed), replaces the release notes with `release_notes.py`'s text when they differ (ignoring line endings and outer blank lines), fails when the tag has no valid page for the version, and runs `check_release_assets.py`. Release notes of releases published before the tag carried `docs/release-notes` are edited by hand from master: `python3 scripts/release_notes.py X.Y.Z > local/notes.md && gh release edit vX.Y.Z --notes-file local/notes.md`. - **Website.** myflames.io is built from the separate `vgrippa/myflames-website` repository. Its `sync.yml` workflow (every 6 hours and on demand) checks this repository out at its latest release tag (the peeled commit of an annotated tag; never master, so the site describes the released app) beside it, runs `sync_releases.py` (the latest release's DMG and Windows `-setup.exe` with their `.sha256`, never the update zip), `build_docs.py --source` (the handbook, the reference documents and the raster images in `docs/screenshots`; links and SVG files are not copied) and its release notes. Release notes are written after a release, so they come from master's `docs/release-notes` alone (a sparse checkout, read as Markdown, `--release-notes-source`): 3.0.0 and later under a Release notes group, older versions linked on GitHub, and nothing newer than the latest published release. The sync also reruns when that folder changes. Then it runs its QA without the CLI examples (no code from this repository runs in that job, which can push) and commits to its default branch when something changed. The site goes live only when someone clicks Publish in Lovable. ### Release notes The release notes are written for people who use myflames (DBAs, SREs and developers), in the form of Percona Server for MySQL's release notes: an index and one page per version. Engineering detail (endpoints, schemas, functions, tests, the reasons behind a design) belongs in this reference and in commit messages, never in the notes. - **Files.** `docs/release-notes/index.md` lists every version newest first, one line each: `- [myflames X.Y.Z (YYYY-MM-DD)](X.Y.Z.md)`. `docs/release-notes/X.Y.Z.md` is one version's page. `CHANGELOG.md` holds only `## [Unreleased]`: every pull request that changes what users see adds its entry there, already written in the style below and under the heading of the section it will go to (`### New features`, `### Bug fixes`, and so on). The release commit moves those entries into the new page and leaves `[Unreleased]` empty. - **Page layout.** The first line is `# myflames X.Y.Z (YYYY-MM-DD)`. Under it comes one sentence on where the version runs (from 3.3.0: "myflames X.Y.Z is available for macOS on Apple Silicon and, as an unsigned preview, for Windows x64."). Then these `##` sections, in this order, each left out when empty: Release highlights, New features, Improvements, Bug fixes, Security fixes, Deprecations and removals, Known issues, Packaging notes, Additional resources (always present: the download links, the Quickstart and GitHub Issues). No other headings. The page ends with the inspiration credit line. - **Release highlights.** Only for a version with three or more notable changes: two to four bullets of one sentence each, naming what is worth upgrading for. The detail stays in the sections below. - **Entries.** Each is a bullet of one to three sentences, about 15 to 60 words, with no bold title in front. New features start with "Adds", improvements with "Improves" or with the thing and what it does now, bug fixes with "Fixed an issue where" and the symptom the user saw (a second sentence may say what happens now), deprecations with what to use instead. UI labels are bold as they appear (**Settings > Client tools…**); SQL, variables, programs, options and file names are in backticks. - **What stays out.** `/api/` paths, schema tags such as `memory-1.0`, module, function and test names, CI, release tooling, README screenshots, test infrastructure and other contributor-only work, mechanics such as timers, worker threads and time budgets, lists of edge cases, and review notes. Command line and `myflames-mcp` changes appear only as deprecations or when they are the whole point of the entry. - **Writing.** Plain sentences a colleague would say aloud. No em dashes (a period, comma, colon or parentheses instead; en dashes only in number ranges), no chains of semicolons or stacked parentheses, no "not X, but Y" frames unless the contrast is the news, no lists padded to three, no filler such as seamless, robust, comprehensive, leverage, ensure or notably, no emojis, no notes about who wrote or reviewed the change. Every fact comes from the change itself. ### Shared view presentation Appearance is registered in `apps/workspace/src/themes.ts`. `THEME_CHOICES` contains stable ids, display names and a light/dark base. `theme-picker.ts` pairs each choice with credit and picker swatches (background, surface, accent and two syntax colors) as `THEMES`; only the lazy Settings chunk imports it, so picker metadata stays out of the entry chunk. `THEME_IDS` is exported for the backend preferences allowlist comparison. System resolves through the OS media query; `appliedThemeBase()` resolves explicit ids through the registry. The command palette offers `Theme: ` for every choice. The Settings > Appearance picker (`AppearanceSettings` in `SettingsPage.tsx`, inside the lazy Settings chunk, so picker metadata stays out of the entry chunk) shows one card per registry theme, grouped and ordered myflames (System, Light, Dark and the Fire, Digital Rain and Neon Grid originals), then the popular dark themes, then the popular light themes, under small group labels. Each card draws its preview from the registry's inline swatches (background, surface, accent and two syntax colors) plus the credit line, so it keeps the theme's own colors whatever the current theme is. The group is a `role="radiogroup"` named Theme; each card is a `role="radio"` with `aria-checked`, a single tab stop roves to the checked card, arrow keys move and select with wraparound in the visual order, Home and End go to the first and last card, and Space and Enter select the focused card. The selected card pairs an accent border with a check icon. A MutationObserver on the root `data-theme` attribute keeps the checked card in step with palette Theme actions while the page is open. `applyTheme()` and `savedTheme()` use the shared UI preferences store, including Settings > Appearance and palette actions. `ui.py` injects a validated stored `data-theme` on `` for every non-System theme, so desktop launches paint the saved theme before JavaScript runs. System omits the attribute. Vite validates every registry id against `^[a-z]+(-[a-z]+)*$` before substituting the boot list through a literal replacer. Its blocking boot script still accepts only ids generated from `THEME_IDS`; it never removes an injected attribute. Legacy localStorage is a one-time browser development fallback, and the backend answer wins. `UI_THEME_IDS` is the backend's one literal list, checked against the registry by `test/themes.mjs`. `themes.css` loads after `style.css` through `styles.ts`. Every named theme sets `color-scheme` and every color property set by the explicit Dark block, plus all chart surface roles. Light and Dark retain their existing values. Adapted palettes retain official syntax colors when they pass; changes tune HSL lightness only and show `official #xxxxxx` beside each adjusted syntax color. Credits say `Based on (MIT)`; exact upstream copyright notices and license permissions are in NOTICE. Fire, Digital Rain and Neon Grid are myflames originals under Apache-2.0. The contrast contract is ink and muted ink at least 4.5:1 on background, content and muted surfaces, lines and control lines at least 3:1, accent at least 3:1 on background, each syntax role at least 4.5:1 on the editor surface, and status text at least 4.5:1. Selection and current Find fill contrast at least 1.8:1 against a dark editor or 1.5:1 against a light editor; selected ink contrasts at least 4.5:1 against each highlight. Matching words use a subtler fill, at least 0.3 lower in contrast than selection, yet at least 1.3:1 against a dark editor or 1.2:1 against a light one. Opaque hex literals for measured tokens make source-based and computed-style tests comparable. Status hues retain OK green, warning amber, danger red and information blue; Production stays purple and Development teal. The estimate role stays violet. Operator families, including Join and Scan, retain their bands and dark ink. Only chart canvas, cards, panes, ink, lines, focus and selection follow the workspace palette, through `--mfc-*` roles. Injected chart defaults match System, Light or Dark only; a late chart style cannot overwrite a named palette. Sandboxed previews receive the resolved base, accents and allowlisted chart surface colors from `bindFrameAppearance()`. `themeFrame()` uses fixed script text, accepts messages only from its parent, and assigns allowlisted properties with `style.setProperty`. Both color paths accept only strings up to 128 characters: 3/4/6/8-digit hex or rgb/rgba/hsl/hsla/hwb/lab/lch/oklab/oklch/color/color-mix functions with ASCII color characters, followed by `CSS.supports` validation. Backslashes, var/attr/env/if/url/from tokens, empty strings and CSS-wide keywords are refused. Missing host surface overrides are sent as literal values from the shared chart defaults, so returning to Light, Dark or System restores them. Values never enter markup or executable code. The sandbox remains opaque. SchemaDiagram watches both the root `data-theme` attribute and OS appearance through `appliedThemeBase()`; its default Mermaid color template follows appearance while explicit templates stay selectable. To add a theme: add one choice and matching picker details, a complete CSS block, upstream copyright/license attribution and user documentation. Extend the backend allowlist only in its single existing location once preferences are present. Run `theme-contrast-unit.mjs` for every token and selection pair, then build and run `theme-contrast.mjs` for computed styles and `themes.mjs` for registry completeness, palette actions, restore, base resolution and frame isolation. Recheck 1440 and 720 px layouts and light/dark OS preferences. Measured durations and ages use `durationText` (`duration.ts`). Duration table cells and the Processlist inspector, Locks summary facts and Replication lag facts use `Duration` (`PerfShared.tsx`) for exact seconds, including decimal precision, on hover and in the accessible name; optional lag caveats join that same tooltip. Keep sorting numeric and preserve unknown states. Replication's summary, lag tile and topology use the same readable words; the tile and map labels retain exact seconds on hover. The ALTER review transaction age uses words too. Narrative text and other Locks badges need not offer exact seconds; see `docs/LOCAL_UI.md` for the hover locations. Sampling windows, budgets, thresholds, input controls and progress counters keep their existing units. `NavMarker` (`kit.tsx`) keeps a state dot separate from a neutral count. Compact navigation rows put the state in their tooltip and accessible name; a caller that already provides hidden text uses `announce={false}` to avoid reading it twice. Navigation may hide the OK dot. `ViewSwitcher` places the other views' attention count on its chevron and names it there; the current view's title never carries a bare dot for a different view's state. `StatusPill` and `StatusDot` draw both a dot and a word, including quieter OK rows in Health and InnoDB. Summary words are OK, Watch, Problem, Not judged and Unknown. `TileGrid` uses equal-width columns in wide windows. At 900 px and below, `kit.css` turns it into one horizontally scrollable strip of 44 px tiles; `FactStrip` uses the same breakpoint to collapse into Details. `Fields` uses a label column sized to its longest label up to 40% of the available width, with a flexible value column; at 900 px and below each value follows its label on a separate line. `WindowStatusBar` keeps safety words visible while other facts truncate before the version and update actions. Server, Workload, Tuning and Database diagram share the latest version read for the connection in use; other connection places publish their own read version. Unknown fields stay hidden. Visible Esc hints use a keycap. Replication passes `detailBackLabel=""` to `ViewLayout` for a side inspector with the list still visible in wide windows, and a sheet at narrow widths. Parameters details follow the same interaction contract. Parameter Value and Default use the same `valueSpan` formatter. Replication GTID sets use `formatGtidSet` and `code.ops-gtid`, with wrap opportunities after commas. Other views may keep the full-width details pattern. Tuning category cards use an auto-fit grid. A category with at least one measurement and fewer than half its checks measured has `is-low-coverage`: a muted, hatched bar and a score labelled with coverage, such as "100% of 1 check". Run full analysis is the toolbar action on both Tuning tabs; Tuning has no generic Refresh. Database diagram uses its view Refresh for rebuilds. I/O keeps its view controls in the toolbar and its counters in the content, with no repeated action under a section heading. Investigations hides the empty list when nothing is saved and offers Save N open plans as an investigation… when plans are open, otherwise Import plan. Learn's shared 2D lesson wrapper hides Phases when no phase items exist (`myflames/teach/_html.py`); phase navigation remains when marks exist. ### Chart runtime Default flame colors use a cream-to-orange sequential scale of the square root of each frame’s own units divided by the whole graph’s units. Width still includes descendants. Color remains stable while zooming; unmeasured plans use a neutral fill. Python and TypeScript mirror this rule, and explicit alternative palettes remain supported. HTML reports, `explore` pages, and the workspace draw every chart with the TypeScript runtime in `apps/workspace/src/charts/` (built by `npm run build` into the committed `myflames/assets/myflames-charts.js`, inlined by `chart_assets.py`). Python stays the source of every semantic decision: `chart_data.py` emits `chart-data-1.0` for reports and `explore` pages and `chart-data-2.0` for the workspace (`docs/schemas/chart-data-*.json`; 2.0 stores each analysis message once, and the bundle reads both) using the same helpers as the Python renderers, and the TS only lays out and handles interaction. Keep both renderers in step: `apps/workspace/test/parity.mjs` compares them on every fixture, `test_chart_data.py` fails if the committed bundle is older than its sources or over 80 KB. Charts are instance-scoped (no page-wide IDs), set plan text with `textContent` only, and capture Ctrl+F only while focus is inside the chart. Visual Explain's fit never renders text below 11 px: `MIN_TEXT_PX` in `charts/core/zoom.ts` and `SMALLEST_TEXT_PX` (the smallest font in `WORKBENCH_CSS`) in `charts/workbench.ts`, with the same two constants in `myflames/workbench.js`, clamp the fit ratio by the screen scale (1 in the workspace, `getScreenCTM()` in reports and the standalone SVG); a plan larger than that view starts at its first inputs and pans, Fit, a double click and a resize while fitted return to that opening view, and only an explicit zoom out goes smaller. The Execution tree prints Total on every row, leaves included (a leaf's total equals its self time), and `—` in Self and Total for an unmeasured operator, in `output_tree.py` and `charts/tree.ts` alike. ### Bundle and lazy loading The workspace build (`apps/workspace`, `npm run build`) keeps the first screen in the entry chunk: React, the shell (`main.tsx`), Home, the sidebar, saved connections, the command palette, Learn and the shared kit (about 365 KB, 1.1 MB before the split). Other places and views load their own chunk the first time they mount, through `lazyComponent` in `src/lazy.tsx` (React.lazy with its own Suspense boundary; the fallback shows nothing for 300 ms, then one "Loading…" line, and a chunk that cannot be read shows "This part of the workspace did not load." with Reload): - `main.tsx`: the Query editor (mounted hidden at startup; its chunk starts loading with sign-in and the session read, and calls to its handle made before it mounts wait in `withLab`), Query digest, Server (with Workload, Tuning and Database diagram), Replication, Cluster, Investigations, the Audit log, and the Plans chart and execution context. Once the first screen is up, `preloadWhenIdle` loads Server, Replication, Cluster and the Plans chart in idle time, one chunk at a time. - `Server.tsx`: the views it uses only as components (InnoDB, Tuning, Processlist, Waits, I/O, Indexes, Tables, Parameters, Database diagram (its own place, still drawn by Server), Users and roles), preloaded in idle time once the place has mounted. Health, Error log, Top statements, Locks, Instruments, Maintenance and Replication share helpers with `Server.tsx` and come with its chunk. - `QueryLab.tsx`: Table data, and Format SQL (`import("./sqlFormat")` on first use: sql-formatter 15.9.0, pinned in `package.json` and `package-lock.json`, with only its MySQL and MariaDB dialects and nearley, about 90 KB). Mermaid keeps its own chunks (Database diagram). The Query editor chunk carries the CodeMirror 6 editor (`src/editor/`: the pinned `@codemirror/state`, `view`, `commands`, `language`, `autocomplete`, `search` and `lint` packages with `@lezer/common`, `highlight` and `lr`; only `QueryLab.tsx` imports them, so the entry chunk stays free of them). The Settings page is its own chunk (`SettingsPage.tsx`, loaded lazily from `main.tsx`), which keeps `editorSettings.ts` and the settings UI out of the entry chunk. Rules for code that splits: - A part keeps the form it mounted with: before its chunk arrived it renders through Suspense, after that directly. A mounted place is never remounted because its chunk arrived, so mounting rules hold (Server, Replication and Cluster mount on first visit and stay mounted, views read on open only while on screen, Back keeps the mounted list) and `QueryLab`'s ref handle is forwarded. - Import a lazily loaded module only through `lazyComponent` (type imports are fine); one static value import puts it back in the entry chunk. The shell reads the lists of Server and Workload views from `serverViews.ts`. - Styles are not split. `src/styles.ts` imports every stylesheet in cascade order (`style.css`, then `themes.css` last) and `main.tsx` imports it first, so the order never depends on which chunk loads first; the built stylesheet is identical to the unsplit build. Add a new stylesheet to `styles.ts` too. - Code that looks up a lazy part's elements right after switching to it must wait for them: the Server toolbar measurement in `main.tsx` watches for the strip to appear, and `focusWhenMounted` in `Server.tsx` focuses a view's heading once it exists. - `test/bundle-split.mjs` (`npm run test:bundle-split`) checks that `styles.ts` lists every stylesheet in `src/` exactly once with `style.css` followed by `themes.css` last and `main.tsx` importing it first, that no lazily loaded module is also imported statically by `main.tsx`, `Server.tsx` or `QueryLab.tsx`, that the committed build has exactly one stylesheet, and that the entry chunk stays under 500,000 bytes (about 475 KB in 3.3.3; Home, the sidebar and the shell only, a place or view belongs in a lazy chunk). The chart runtime has its own 80 KB budget (`test_chart_data.py`). Large tables: `DataTable` and `PaginatedReportTable` sort and measure only when their rows change. `useStableRows` (`kit.tsx`) keeps the previous array while it holds the same objects, so a view that filters its report on every render (Processlist, Indexes) neither sorts again nor measures its columns again on a selection or a keystroke elsewhere. A hidden table retains its last nonzero frame width; its ResizeObserver tracks visibility separately and retries deferred row and height measurements when it becomes visible, including at the same width. Already measured rows keep their cache. `sortRows` reads each row's value once. `formatNumber` (`api.ts`) reuses one `Intl.NumberFormat` per options for `time`, `number`, `count` and `CompactNumber`: `toLocaleString` with options builds a new formatter on every call. Columns gutter: `DataTable`'s **Columns** control sits in a fixed 36 px gutter inside the table frame, outside the horizontally scrolling data viewport. A sticky header cell (or a trailing colgroup slot alone) is not enough: it overlays earlier data whenever the table overflows sideways. Width calculations use the data viewport, which excludes the gutter, so at every scroll offset the viewport ends at or before the gutter's left edge, and at the right end the last header and its numeric value end before it too; a table whose column minimums exceed the viewport still scrolls inside its frame. A trailing 36 px column exists only when the table has row actions, which scroll with their row (36 px more width in those tables, and no fixed control over a scrolling value); tables without row actions keep no empty trailing column. Resize handles, sorting, virtualization, persisted widths and hidden keys and the numeric minimum widths are unchanged. Suites find Columns by its accessible name, since it is outside the scrolling table; `kit-static.mjs` checks the markup without a browser and `kit-primitives.mjs` measures fitted and overflowing tables at 1440x900 and 720x600 in both appearances, with and without row actions, at the start, middle and end scroll offsets. Tables and Indexes use `PaginatedReportTable`'s filter, count, Rows, Export and paging locations (Tables' **Filter tables** joined that group; schema scope and Fresh numbers stay in `ViewLayout`'s toolbar), and every Tables list marks Table as its `primary` flexible column with a 220 px minimum. Indexes advice (unused and redundant) holds explanations and copyable SQL only: Set invisible/visible (Set ignored/not ignored on MariaDB) and Drop index have one write-action home in the inspector's action bar, with row and context menus as contextual entry points. `indexes.css` is registered in `styles.ts` to keep the fixed stylesheet order. ### Local authentication and request limits `WorkspaceServer.launch_url` carries a random, one-use `#launch=` secret, valid for 30 minutes. `api.ts` removes the fragment before any API call and exchanges it through `POST /api/auth/session` with `X-Myflames-Bootstrap: 1`. The server returns the request token and sets a per-instance cookie with `HttpOnly`, `SameSite=Strict`, and `Path=/api/`. The launch secret is never written to browser storage, HTML, or the workspace database. Fetching the page alone grants no API authority. `myflames.session-proof` in origin-scoped localStorage holds the request token. Bootstrap refresh and every subsequent API POST require both that proof in `X-Myflames-Token` and the cookie, plus the exact allowed Host and Origin. Cookies are host-scoped, so a copied cookie from another local port is insufficient without that origin's proof. A new server instance invalidates the old pair and requires its new launch URL. If browser storage is unavailable, the authenticated current tab still works; a reload requires a fresh launch. There is no CORS access. Responses use no-store and no-referrer policies. The server admits at most 32 request workers. Socket reads have a 15-second timeout. Bodies also have a total 15-second read deadline, so trickling body bytes cannot extend that deadline. The usual body limit is 12 MiB; session save permits 65 MiB for its bounded 64 MiB stored payload. Account requests have an additional 256 KiB encoded-data budget. ### Client and local-storage boundaries The desktop renderer uses an in-memory session partition, so UI preferences belong in the workspace SQLite store, not localStorage. Theme, sidebar width, Server inspector width, Server view navigation collapse, Health auto-refresh, Query editor Explain format, and File transfer hidden-file and Transfers-panel choices are persisted through `/api/settings/ui`. Browser development reads legacy localStorage once as a fallback and never promotes it over the backend answer. The renderer's session proof remains origin-scoped localStorage authentication data. Query editor split height remains part of the autosaved `editor_layout` session state. Read clients, capture jobs, writes, and editor sessions use the connector's clean environment, an empty temporary HOME, and an exclusive `--defaults-file`. Personal `.my.cnf` and `.mylogin.cnf` and system option files cannot redirect a saved credential. The login-file override is also isolated. Socket connections still use the explicit connection settings. Without an explicit socket, classic client option files set `protocol=TCP`, including for localhost with a port. An explicit socket selects `SOCKET`. MySQL Shell selects TCP through an explicit port; its socket options omit port so it cannot override the socket. Lifecycle control queries use the same 64 MiB stdout and 1 MiB stderr caps as the connector. Editor hello reads both `@@version` and `@@version_comment` and calls the shared flavor detector. Editor credentials are removed once the client handshake completes. Every short-lived client invocation owns a fresh mode-0600 option file, removed in a finally block when its subprocess exits (including failures and cancellation). Concurrent calls on one connection never share option files; close() remains idempotent and cannot remove another invocation's credentials. `connection_with_saved_password` copies and validates connection fields and profile policy metadata before looking up a secret. Arbitrary executable, socket, client-certificate/key, option-file, and initialization overrides do not pass through the browser's saved-credential path. CLI connection flags remain an explicit local choice. Clone checks the recipient's negotiated TLS before sending a remembered donor password, in addition to the reviewed pair and donor TLS policy checks. Workspace database files and SQLite sidecars, vault directories, keys, and locks reject symbolic links and foreign owners before opening or changing permissions. Creation uses exclusive creation; existing file descriptors are checked without following links where supported. POSIX directories are 0700 and files 0600; Windows retains its platform helper. SQLite connections close if setup fails. Session persistence redacts recognized SQL credential literals in editor text as well as password fields; ordinary SELECT drafts are retained. History redacts the actual reused editor session's password even when a later request supplies no password. ### Reviewed actions and session ownership Kill preparation, single replication skips, and lifecycle plans carry a server-issued review token. Its registry holds at most 256 entries for 300 seconds. Tokens bind the operation, connection identity and policy, and reviewed details. Checks happen before saved-password lookup; consumption is atomic at the send boundary after fresh state and policy checks. Missing, expired, altered, or replayed tokens require a fresh review. Tokens are never persisted. Lifecycle jobs re-read saved profile policy before connecting, after preflight, and before tool invocation. A deleted profile or changed endpoint/policy requires a fresh review; a rename alone does not. Clone donors are bound too, with read-only permitted for the donor read. Accounts and the Query editor retain their own bounded review registries and confirmation contracts. Every editor owner path checks the connection, including ended sessions, status, export, stop, close, commit, and rollback. Ended sessions compare endpoint and saved-profile identity; policy changes on the same endpoint do not transfer ownership. Explicit reconnect evaluates fresh policy. Live sessions retain full identity matching. A different connection cannot remove an ended session by opening its tab, or learn the other connection's name from an error. Lifecycle and capture status/cancel also enforce their endpoint owner before accessing the job. ### Shared CLI confirmation `dbops.cli_confirm` renders descriptions and prompts on stderr, implements `--yes`, terminal detection, default No, and exact typed guards, and returns the outcome to the command's existing audit owner. The write policy runs before credential prompts. Every non-terminal server write requires `--yes`, including ordinary SQL on Development. On a terminal, writes permitted by policy can still proceed without a prompt. Required names, targets, and acknowledgements match exactly; only the input line terminator is removed. EOF and Ctrl+C before sending are declined and audited. Unsent refusals and declines exit 2 with a stderr diagnostic, empty stdout even under `--json`, and an untouched `-o` destination. This applies to `locks --kill`, `sessions --kill`, `config set`, `config reset-persist`, account changes, `sql`, `dump`, `restore`, `clone`, and replication `skip`/`skip-loop`. Executed and partial results keep their existing schemas and exit behavior; read-only `--preflight`/`--fail-on` findings retain their finding contracts. Local `audit purge` has its separate confirmation contract. ### Profiles `python3 -m myflames profiles list [--json]`, `profiles set NAME [--type production|development] [--read-only | --read-write]`, `profiles forget NAME`, `profiles delete NAME` manage workspace connection profiles and their saved passwords. `--profile NAME_OR_ID` on `capture`, `top`, `sessions`, and the other server commands loads a profile and its remembered password; explicit flags override profile fields; a missing profile, or a saved password with a different host/port/user, exits 2. Lives in `myflames/workspace_cli.py` (`_resolve_connection`, `cmd_profiles`). Every profile carries `type` (`production` | `development`) and `read_only` (bool) in its payload (`workspace_store.PROFILE_SAFETY_FIELDS`), returned by `/api/profiles/list|save`, `profiles list --json` (`profiles-1.0`, additive) and accepted by `/api/profiles/save` (`value.type`, `value.read_only`). A save that omits them keeps the stored values (older UI forms), forget-password keeps them, `WorkspaceStore.set_profile_safety` changes them without touching the saved password. New profiles and every existing one are `production`, read-write: the database carries `PRAGMA user_version` (`STORE_VERSION` 1), and `_migrate` writes the two fields into older profile rows once; `_present` also defaults them on read. The type, never the password, is part of the connection identity reports and confirmations are bound to. Pasted connection fields: `live.connection_options` (every API request, profile save and test, the CLI connection flags) and `lifecycle._options` (dump, restore, clone) trim white space (`str.isspace`, so also the no-break space) and `live.INVISIBLE` (zero-width spaces and joiners, word joiner, byte order mark) from both ends of `host`, `ssl_ca` (and the lifecycle `ssl_cert`, `ssl_key`, `socket`), and from the end of `database` (MySQL and MariaDB refuse a database name ending in a space: `check_table_name` in `sql/table.cc`; a leading space is legal and kept). `user` and `password` are never changed. `live.clean_host` refuses a space inside the host, a `/` (a URL or path) and `host:port`, and removes the brackets of `[IPv6]`; a host that is only spaces counts as empty (127.0.0.1). Endpoint comparisons trim the same way (`workspace_store.endpoint_value`, used by `_same_endpoint`, `dbops._same_endpoint` and `dbops.connection_identity`, and `trimPasted` in `binding.ts` `connectionKey`), so a profile saved with a spaced host keeps its saved password and its Development type. The Home form trims Host when it loses focus and splits a pasted `host:port`, `[IPv6]:port` or `mysql://user:password@host:port/db` into its fields (`splitHost` in `Connections.tsx`); Port must be 1 to 65535 before Use. Tests: `test_live.py` (`test_pasted_spaces_around_host_and_paths_are_dropped`, `test_connection_identity_ignores_pasted_spaces`), `test_secret_store.py` (`test_pasted_host_spaces_keep_the_saved_password`) and `test_lifecycle.py`. New connection… (the picker's menu and the palette's **New connection**) goes Home and opens the Add connection form once: `main.tsx` raises `addConnection`, `Connections` (`addRequest`, `onAddHandled`) opens the form and clears the request. Connection form (`Connections.tsx`): a new connection's name is `defaultConnectionName(user, host, port)`, `user@host` plus `:port` when the port is a valid port other than 3306, kept in step with User, Host and Port until the name is edited or a preset or saved connection is loaded. Names compare after `trim().toLowerCase()`: when another saved connection has the same name, `#connection-name-problem` says "A saved connection named NAME already exists.", the field is `aria-invalid` and Save is disabled; editing a connection may keep its own name. `/api/connection/test` (`ui._test_connection_response`) opens one `MySQLConnection`, reads `server_version()` and `server_version_comment()` (identity through `server_info.product_identity`), then `query_rows("SHOW DATABASES")` in the same request, and returns `version`, `engine`, `flavor`, `product`, `schemas` and `databases` (the same list, at most `_TEST_DATABASES_LIMIT`, 1,000) and `databases_truncated`, plus `databases_error` only when SHOW DATABASES failed after the connection succeeded (password redacted; the test still succeeds) and `through_ssh` only for a connection through SSH. With `databases`, Default database is a pick list (`mysql`, `sys`, `performance_schema` and `information_schema` behind **Show system databases**, and **Type a name…** back to the text field with its datalist); with `databases_error` it stays a text field with `#connection-schema-hint` saying why. Tests: `test_ui.py` (`test_connection_test_databases_bounded_and_error_path`), `test_workspace_api.py` (`test_connection_and_preset_routes`), `apps/workspace/test/connections.mjs`. Home connections, the picker pill and the form (`Connections.tsx`, `style.css`; no endpoint or JSON change): `SafetyTags` is the type pill (`.type-tag.is-production` purple, `.is-development` teal) plus, when set, a Read-only outline pill; neither truncates (`.safety-tags` does not wrap in the table), and the Home table, the picker and the Audit log's Type column share it. The table's columns are select (48 px), Name, Type (184 px), the user@host:port address (`flex: true`, the leftover width), **Default database**, Password and Last used; an empty database and a connection not used in this window show "—" with the reason as `title` and in visually hidden text ("Not used in this window. Earlier use is not recorded."). The compact preset keeps a short type word beside each name (`.connection-type-short`: Prod or Dev; a read-only connection keeps its word with an outline, as in the picker). The form panel caps at 560 px, has Cancel beside Save connection, and Delete connection is a `text-button danger`. The picker pill hides `.picker-target` at 1,100 px and below, and `.safety-tags` there in the top bar (`.window-toolbar`) and everywhere at 650 px and below, showing `.connection-pill-type` in their place: `aria-hidden` (the Popover label keeps the full type), Prod or Dev in `--env-prod-text` or `--env-dev-text`, never a status color, and for a read-only connection the same word with a `currentColor` outline. The Session password field commits on **Set** (`.picker-password-set`, disabled until the value differs from the committed one), Enter or blur, all through the same `commitPassword`, with the hint "Set, Enter or leaving the field applies it for this window. It is never saved." Tests: `connections.mjs`, `profiles.mjs` (720 px pill, Set and the hint), `kit-static.mjs` (the two pills, the header, the "—" cell). Connection type on screen: `ConnectionTypeStrip` is a 3 px decorative strip (`aria-hidden`, no text, `pointer-events: none`) fixed to the window's top edge inside `.topbar-stack` on the places that show `SafetyStatus` (Query editor, Query digest, Database diagram, Schema versions, Server, Workload, Replication, Cluster, ProxySQL, Tuning), colored by `--conn-prod-strip`, `--conn-dev-strip` or `--conn-readonly-strip` in both appearances; the type word stays in the window footer. `ConnectionTypeBand` (`ConfirmSheet.band`) heads every write review and confirmation sheet (`ActionReview.tsx`, `ReviewedSqlAction.tsx` and Instruments through it, `MassKillDialog.tsx`, `Locks.tsx`, `Config.tsx`, `Accounts.tsx`, `Maintenance.tsx`, `TableData.tsx`, `QueryLab.tsx`, `Replication.tsx`, `TableAlterDialog.tsx`) with the type word and the connection label ("Production · prod-eu (10.0.0.5:3306)"), styled by `--conn-*-band-bg`, `-text` and `-line`. It names the connection the plan is bound to (`plan.connection`, `via.connection`, `session.connection`), never the picker's later choice. Tests: `config.mjs`, `locks.mjs`, `navigation.mjs`. #### SSH tunnels A connection (its settings, a profile through `PROFILE_FIELDS`, the session's connection in use) may carry `ssh_host`, `ssh_user` and `ssh_port`; `connection_options` outputs them only when set. Code: `myflames/ssh_tunnel.py`, wired through `connector.py`, `live.py`, `lifecycle.py`, `workspace_store.py`, `dbops.py`, `ui.py`, `workspace_cli.py`, `replication.py`, `error_log.py`, `editor_session.py`, `Connections.tsx` (`SshSettings`), `binding.ts` and the desktop launcher. - Validation: `ssh_tunnel.ssh_fields` (host `^[A-Za-z0-9_][A-Za-z0-9._-]{0,252}$`, user `^[A-Za-z0-9_][A-Za-z0-9._@-]{0,127}$`, so neither starts with `-` nor holds spaces, quotes, `%`, `:`, `/` or `;`; port 1 to 65535; pasted spaces trimmed; a user or port without a host refused) and `ssh_tunnel.check_connection` (the database host must be a host name or an IP address for `-L`, IPv6 bracketed; no socket; no VERIFY_IDENTITY, since the client would check 127.0.0.1). `sshProblem` in `Connections.tsx` is the client-side twin; Use refuses while it reports a problem. - Process: `ssh -N -T -o BatchMode=yes -o ExitOnForwardFailure=yes -o LogLevel=DEBUG1 -o UpdateHostKeys=no -o PermitLocalCommand=no -o ConnectTimeout=10 -o ServerAliveInterval=15 -o ServerAliveCountMax=3`, plus `-o ControlMaster=no -o ControlPath=none` on POSIX (no shared master outlives myflames), `-p PORT` and `-l USER` as separate arguments when set, then `-L 127.0.0.1:LOCAL:DBHOST:DBPORT -- TARGET`. `LogLevel` on the command line wins over any ssh_config setting; ClearAllForwardings is never passed (it would clear the tunnel's own `-L`), and there is no Unix-socket forward (the MySQL client treats a socket as secure transport and would send the password in clear). It is an argument list (no shell) with stdin from `/dev/null`, in its own process group (a POSIX session; on Windows a new process group without a window), so a terminal Ctrl+C cannot cut the tunnel under the KILL QUERY that cancels a statement. ssh gets an allowlisted environment (PATH, locale, temp and system roots) plus the real home (`MYFLAMES_SSH_HOME`) and agent socket (`MYFLAMES_SSH_AUTH_SOCK`, else `SSH_AUTH_SOCK`), no `DISPLAY` or `SSH_ASKPASS`, and never a database password (that stays in the 0600 client option file). Keys and the agent only: SSH passwords are never accepted or stored, and myflames never accepts a host key (the user's own `StrictHostKeyChecking` still applies). `find_ssh` never uses `shutil.which`: on Windows it takes `%SystemRoot%\System32\OpenSSH\ssh.exe`, then `Sysnative`, then only `ssh.exe` in absolute PATH folders with a drive or UNC share (quotes stripped); on POSIX PATH first, then `/usr/bin`, `/usr/local/bin`, `/opt/homebrew/bin` and `/opt/local/bin`. Empty, `.` and relative PATH entries are skipped everywhere; otherwise "ssh was not found". The host, user, database name and IPv6 patterns end with `\Z`, so a trailing newline never reaches `-L`. - Watchdog (POSIX, `myflames/ssh_watchdog.py`, stdlib only and importing nothing from myflames): ssh starts as `python -I ssh_watchdog.py -- ssh ...` (the packaged backend: `myflames-backend __myflames_ssh_watchdog -- ssh ...`, dispatched at the top of `backend-entry.py` before the CLI loads). The watchdog leads the tunnel's process group with a stdin pipe only the opening process holds, starts ssh in that group with stderr passed straight through, exits with ssh's status, forwards SIGTERM, SIGHUP and SIGINT (SIGKILL after `GRACE`, 2 s), and when the pipe closes (the owner ended, SIGKILL included) stops ssh and kills what is left of the group, such as a ProxyCommand. - Job object (Windows, `myflames/win_job.py`, stdlib only: ctypes and the documented kernel32 calls `CreateJobObjectW`, `SetInformationJobObject` with `JobObjectExtendedLimitInformation`, `SetHandleInformation`, `AssignProcessToJobObject`, `CreateToolhelp32Snapshot`/`Thread32First`/ `Thread32Next`, `OpenThread`, `ResumeThread`, `CloseHandle`; nothing runs at import). `TunnelManager._spawn` starts ssh.exe with `CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_SUSPENDED` and no watchdog, then `_join_job` calls `win_job.JOB.adopt(popen)`: `KillOnCloseJob.handle()` creates the process's one job once with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` and a non-inheritable handle that myflames never closes (a failed setup closes the empty job and is tried again next time), `adopt` assigns `popen._handle` and then resumes the threads of `popen.pid`, raising `OSError`. When the process ends in any way (a normal exit, a crash, `taskkill /F`), Windows closes the handle and ends every ssh in the job with what it started. When creating the job, assigning or resuming fails, ssh is killed and waited for (2 s) before it ran, its pipes closed, and the tunnel refused: "Windows could not tie the SSH tunnel to myflames (job object: REASON), so ssh was stopped before it connected. Nothing was sent." An interrupt (`KeyboardInterrupt`) while ssh.exe waits suspended also kills it first, then is raised again. Struct layouts are plain ctypes types, so tests check them on any OS (64-bit: basic limit 64 bytes, extended 144, THREADENTRY32 28). A process started from an SSH session is already in sshd's session job (no kill on close), and the assignment nests ssh.exe under it (Windows 8 and later); in the desktop app libuv's job for the backend allows silent breakaway, so ssh.exe is in no job before the assignment. The desktop's Windows stop (`taskkill /PID backend /T /F`) is unchanged; the job covers a backend crash, a backend killed by itself or the user, and an Electron crash (libuv's kill-on-close job ends the backend, whose job then ends ssh). Windows tunnels are not recorded in `ToolGroups` (process groups are POSIX). A normal close terminates only ssh.exe, so a ProxyCommand it started stays in the job until the backend exits; a backend that dies between starting ssh.exe and assigning it leaves a suspended ssh.exe that never ran (no port, no connection). Dump, restore and clone tools are not in the job and still outlive a crashed backend on Windows. Windows ssh.exe (OpenSSH_for_Windows 9.5p2 on Windows 11) reads `~/.ssh/config`, keys and `known_hosts` from the account's profile folder and ignores `HOME` and `USERPROFILE`; the Host alias list (`config_hosts`, `/api/ssh/hosts`) reads `MYFLAMES_SSH_HOME`, the same folder in practice. The environment allowlist never passes Win32-OpenSSH sshd's `C28FC6F98A2C44ABBBD89D6A3037D0D9_POSIX_FD_STATE`, which makes an inheriting ssh.exe hang before it signs in. Readiness is unchanged there (DEBUG1 lines end in CRLF, stripped). Tests: `test_ssh_tunnel.TestWindowsJob` (mocks, any OS) and `TestWindowsJobLive` (Windows only, real kernel32). - Readiness and errors: the local port comes from binding 127.0.0.1:0. The tunnel is ready only when ssh's own DEBUG1 lines on stderr say, in order and within `READY_TIMEOUT` (15 s) while ssh still runs, `Local forwarding listening on 127.0.0.1 port LOCAL.`, then `channel N: new port-listener [port listener]` (`channel N: new [port listener]` before OpenSSH 9), then `Entering interactive session.`. No TCP probe is made, so another local program listening on the port first never gets a lease (and nothing reaches the database while the tunnel opens); a session entered without this forward (ClearAllForwardings in ssh_config) fails at once naming that setting, and an ssh that never confirms times out and is stopped. Debug lines are matched and dropped: `stderr_text()` keeps only other lines and `failure_message` ignores them. A lease whose ssh ended is never reused (`Lease.alive()`), and the connector's legacy option file never names the port of a dead tunnel. A forward that failed to bind is retried once on a new port. ssh's messages become plain sentences (unknown host key: "Run `ssh X` once in Terminal to check and accept it"; changed host key; Permission denied for keys or agent; could not resolve; refused; timed out; no route; local port in use; the hint for an unknown host key says `ssh -p PORT HOST` for a non-default SSH port), otherwise the last non-debug line of its output with terminal controls escaped. When the forward cannot reach the database (ssh logs `open failed`), `MySQLConnection.run` adds "SSH host X could not reach the database at H:P (reason)", "does not allow port forwarding (AllowTcpForwarding)" or "could not resolve the database host" to the client's error. - Sharing and lifetime: `TUNNELS` (`TunnelManager`) keys tunnels by SSH host, SSH user, SSH port, database host and database port, and leases one per client invocation, editor session (held for the session) or lifecycle tool run. Every client path (`MySQLConnection._invocation_defaults`, the editor session, `lifecycle._credentials`) writes `host=127.0.0.1`, the tunnel's port and `protocol=TCP`; a connector with `ssh_host` and no tunnel refuses to build an option file (fail closed). A tunnel closes after `IDLE_SECONDS` (300) without users and at shutdown. `WorkspaceServer.server_close` starts a timer that runs `TUNNELS.close_all()` after `WorkspaceServer.TUNNEL_CLOSE_SECONDS` (3 s) even while the editor and lifecycle cleanup (which may still send KILL QUERY through a tunnel) runs on, and calls it again in a `finally`, so a failed cleanup never skips it; `close_all` signals every tunnel first, then waits, and a second caller waits for the first. The CLI closes them at exit: `cli.main()` first calls `_close_on_termination_signals()`, which turns SIGTERM and SIGHUP into `SystemExit(128 + signal)` (main thread only, only for a signal still at `SIG_DFL`), so atexit runs and the status is 143 or 129. The MCP server installs no handlers; the watchdog (POSIX) or the job object (Windows) covers it. After the desktop died and the backend's shutdown hung for 5 s, `backend-entry.py` (`_kill_owned_groups()`) SIGKILLs every group the backend owns (`TUNNELS.owned_groups()`: each tunnel's group and every group of the attached ToolGroups, read under a 0.5 s lock bound with `ToolGroups.snapshot(timeout=)`), never its own, before it SIGKILLs its own group. At most `MAX_TUNNELS` (8) are open, idle ones evicted first, and tunnels count toward `lifecycle.ToolGroups.MAX_GROUPS` (16, the same number as `MAX_TOOL_GROUPS` in `apps/desktop/backend.cjs`) with dump, restore and clone tools: `start()` refuses another one with `ToolLimit` and spawns nothing. A tunnel whose ssh died starts again on a new port on the next use, never under a running statement. It listens only on 127.0.0.1: another local user can reach that port while it is open, as with any `ssh -L`, and still needs database credentials; VERIFY_CA through the tunnel protects against a port taken over after ssh dies. - Identity: `dbops.connection_identity` appends `["ssh", host, user, port]` after the six endpoint fields only when SSH is set (`identity_endpoint` keeps it); `workspace_store.ENDPOINT_FIELDS` and the saved-password fingerprint include the SSH target only when set; `connectionKey` and `endpointKey` in `binding.ts` do the same. Identities without SSH are byte-for-byte unchanged. A saved password is released only when the SSH target matches the profile, and a Development type falls back to Production the same way. - CLI: `profiles set NAME --ssh HOST [--ssh-user USER] [--ssh-port PORT]` or `--no-ssh` (`WorkspaceStore.set_profile_ssh`); a changed tunnel points the profile at another endpoint, so its saved password is forgotten and it becomes production unless `--type` is given. `--ssh-user` and `--ssh-port` need `--ssh` ("--ssh-user and --ssh-port need --ssh HOST", exit 2), and `set` with nothing to change says "choose --type, --read-only, --read-write, --ssh or --no-ssh". `profiles list` shows `host:port via user@sshhost:port` in HOST (user and SSH port only when set); its JSON carries the fields. - Workspace: `POST /api/ssh/hosts` returns `ssh-hosts-1.0` `{hosts, ssh_found, message}`: the Host aliases of `~/.ssh/config` and its Includes (at most 32 files of 256 KiB, depth 4, 500 names; no patterns, negations or names the field refuses). It runs no ssh and reads no network. `/api/connection/test` adds `through_ssh: "Through SSH host X"`. `SshSettings` is a plain `
` (Connect through SSH), open for a connection through SSH; its SSH host field offers the aliases, read once when the section first opens. `connectionTarget` and `connectionLabel` add "via HOST", and `ConnectionTypeBand` uses that label, so every write review names the SSH host ("Prod (app@127.0.0.1:3306 via bastion)"). - Locality and CLONE: `lifecycle.refuse_clone_through_ssh` refuses CLONE when the donor or the recipient uses SSH (the recipient connects to the donor itself), and Clone's saved-donor list leaves such connections out; the MariaDB error-log file read, replication loopback source matching (`replication.reached_host`) and the physical backup locality check treat SSH as remote. A restore's typed target names the SSH target ("127.0.0.1:3306/shop via deploy@bastion"). - Tests: `test/test_ssh_tunnel.py` (`TestReadiness`, `TestOwnerExit`, `TestWorkspaceShutdown`, `TestDesktopEntry` and the Windows lookup tests; the fake ssh `test/_fake_ssh.py` logs what OpenSSH logs at DEBUG1; the live sshd test runs only with `MYFLAMES_SSH_LIVE=1`), `apps/workspace/test/connections-ssh.mjs` (run after `npm run build` with `node test/connections-ssh.mjs`; it also renders `ConnectionTypeBand` with `react-dom/server`), `apps/desktop/test/backend.test.cjs` (a full list of tool groups is read, one more is not). ### Write safety and audit `myflames/dbops.py` is the one safety layer for every statement that changes server state (db-operations skill). Editor run reviews also bind the **On error** mode through `editor_session._review_digest`: a Stop review cannot authorize Continue, or the reverse; changing the mode requires a fresh review. Its parts: - `classify(sql, backslash_escapes=None, key_columns=None)` returns `{kind: read|write|risky, category, reasons[], statements: [{text, start, end, verb, kind, category, reasons}], count, ambiguous}`. `split_statements` splits like the mysql client on top of `live.TOKEN` / `TOKEN_NO_BACKSLASH` (no second tokenizer; `TOKEN` reads `-- ` as a comment only before the client's ASCII white space, never Python's `\s`): comments, quoted strings and backtick identifiers, executable comments `/*! */` and `/*M! */` whose bodies are code (a delimiter inside splits, as `client/mysql.cc` does), `DELIMITER` lines at a line start with nothing pending (any first word starting with `delimiter`, as in `--binary-mode`; the argument parsed like the client's `get_arg`: quotes stripped, an unquoted one ends at a space, not a tab; a missing argument or one with a backslash keeps the old delimiter and is risky), and the client's backslash commands outside quotes (`\g` and `\G` end a statement, `\N` is NULL, any other is risky: `REASON_CLIENT_COMMAND`). `--` before another control character is risky (`REASON_DASH_CONTROL`; the client reads code, the server a comment). Each client statement is also cut at top-level `;` and the worst part counts (`REASON_MULTI`): under a custom delimiter the server runs every `;`-separated statement of one request. Statements carry `issues`. Without `backslash_escapes` both string readings are classified and the worse wins (`ambiguous`, reason `AMBIGUOUS_REASON`). An unclosed quote or comment is risky. Decisions: reads are SELECT, WITH ... SELECT, TABLE, VALUES, SHOW, HELP, DESCRIBE/DESC, EXPLAIN without ANALYZE, USE, CHECKSUM, transaction starts and ROLLBACK, UNLOCK, and `SET NAMES`, `SET [SESSION] TRANSACTION` (not READ WRITE), SET SESSION of `SESSION_READ_VARIABLES` (NAMES, CHARACTER SET and CHARSET are one item of the SET list; every item counts; a value that calls a function, uses `:=`, contains a subquery (SELECT or TABLE) or advances a MariaDB sequence makes that item a write: `_SET_VALUE_WRITES` on the scanner code, where a name of identifier characters (`_IDENT_CHAR`: `\w`, `$` and any non-ASCII character, non-ASCII spaces included, as both lexers accept; the scanner collapses only ASCII white space), a backtick name or a masked string (an ANSI_QUOTES `"f"`) before `(` is a call, plus `NEXT VALUE FOR` and a qualified `NEXTVAL` or quoted part (sql_mode=ORACLE `seq.NEXTVAL`); MariaDB `SET STATEMENT ... FOR` values get the same test. Only myflames' own text value, exactly `CONVERT(X'...' USING utf8mb4)` as the whole value, is exempt). Writes: INSERT/REPLACE, UPDATE/DELETE whose WHERE pins a key column (`key_columns`, given by the caller) to a value (`col = literal`, `literal = col`, `<=>`, `IN (literal, ...)`, not negated, no OR or XOR; the check is one linear token pass over at most `MAX_WHERE_CHECK` characters), changes of transaction_read_only or tx_read_only, `SET TRANSACTION READ WRITE`, `START TRANSACTION READ WRITE`, `SELECT ... FOR UPDATE|FOR SHARE|LOCK IN SHARE MODE` (`locking_read`), `INTO OUTFILE|DUMPFILE` (`file`), `INTO @var` and `:=`, GET_LOCK, NEXTVAL, other SET SESSION and user variables (`session`), COMMIT, XA START/END/PREPARE, temporary tables, ANALYZE/CHECK TABLE, FLUSH (not TABLES). Risky: DDL, TRUNCATE, RENAME, OPTIMIZE/REPAIR, HANDLER OPEN (its metadata lock lasts until HANDLER CLOSE or the session ends; HANDLER READ and CLOSE stay reads), UPDATE/DELETE without WHERE, with an always-true one, or without key information (`key_columns` None), KILL, SET GLOBAL/PERSIST/PERSIST_ONLY, RESET, `SESSION_RISKY_VARIABLES` (sql_log_bin, binlog_format, gtid_next, pseudo_thread_id, skip_replication, wsrep_on, ...; also inside MariaDB `SET STATEMENT ... FOR`), DO, replication (START/STOP REPLICA|SLAVE|GROUP_REPLICATION|ALL SLAVES, CHANGE, PURGE), CLONE, accounts (GRANT, REVOKE, CREATE/ALTER/DROP/RENAME USER|ROLE, SET PASSWORD, SET DEFAULT ROLE), LOAD DATA/XML, LOCK TABLES/INSTANCE, FLUSH TABLES, XA COMMIT/ROLLBACK, CALL, EXECUTE, `BEGIN NOT ATOMIC`, INSTALL, SHUTDOWN, and any unknown verb (`unknown`). EXPLAIN ANALYZE and MariaDB `ANALYZE stmt` take the inner statement's verdict (they run it); MariaDB `SET STATEMENT ... FOR` too. The cautious native-function allowlist treats unqualified, unquoted `SLEEP`, `UUID` and `UUID_SHORT` as reads, including on read-only connections. This does not exempt `GET_LOCK`, `RELEASE_LOCK`, `BENCHMARK`, unknown functions, qualified/quoted calls, or nested calls that change state. Function names are read with `_IDENT_CHAR`, so `SELECT €()` and `CONCAT\u00a0(` (a no-break space is part of the name) are calls of unverified functions. A classification is a hint: a SELECT can still call a stored function that writes, so on a read-only connection the server enforces it too: run `READ_ONLY_SESSION_GUARD` (`SET SESSION TRANSACTION READ ONLY`, returned as `session_guard` by `decide`) in the session first; table writes then fail with 1792, and the statements that would lift it are writes. - `decide(verdict, connection_type, read_only, name)` returns `{action: allow|confirm|refuse, kind, category, connection_type, read_only, tone: danger|primary, title, text, reasons, statements}`. Matrix: read allows everywhere; write confirms on production, allows on development; risky confirms on both; read-only refuses every write. `tone` is primary only when the kind is not risky and every non-read statement is in `session`, `transaction` or `locking_read`; within one kind `_worst` prefers a danger-tone category, so order never matters. `gate(decision, confirmed)` returns None or `("refused" | "needs_confirmation", text)`; write endpoints call it before opening any connection and require `confirmed: true` when the action is confirm (`/api/live/kill`'s confirmation is its `expect` identity). `connection_safety(profile, connection)` gives `{profile_id, profile_name, type, read_only, endpoint_matches}`: a request never lowers protection. An unsaved connection is production whatever it claims and may only ask for `read_only: true`; a profile's type applies only while the request keeps its `ENDPOINT_FIELDS` (host, port, user, TLS), else production; its read-only flag applies either way. A profile save that changes the endpoint without choosing a type makes it production. `connection_identity(connection, safety)` is the key reports and confirmations bind to, the Python twin of `connectionKey()` in `apps/workspace/src/binding.ts`: profile id, host, port, user, TLS mode and CA, then type and read-only only when not production and read-write (keys of default connections are unchanged). `report.flight_key` takes the same `safety`. Writes send with `WRITE_CLIENT_FLAGS` (`--comments`, `--binary-mode`, which turns off every client command except `\C` and DELIMITER in non-interactive use, on MySQL and MariaDB clients). All connector executions pass `connector.CLIENT_CHARSET_FLAGS` (`--default-character-set=utf8mb4` and `--init-command=SET NAMES utf8mb4`) to keep client byte encoding locale-independent and avoid MariaDB 10.11 server-default collation fallback when negotiating an unknown utf8mb4 collation. - Privileges (a hint, the server decides): `parse_grants` (global `ON *.*` and `ON db.*` grants; one SHOW GRANTS parser, also behind `locks.parse_kill_privilege`), `required_privileges(operation, engine, version, variable)` and `privilege_hint(...)` (`allowed` True, False or None) for `kill`, `set_global`, `set_persist`, `set_persist_only`, `reset_persist`, `set_session_restricted`, `replication`, `clone_donor`, `clone_recipient`, `write_when_read_only` and object privileges, per the db-operations table (MariaDB SUPER counts before 11.0, READ_ONLY ADMIN before 10.11; `ALLOWED_BY_SUPER_BEFORE_110000`). `read_grants(conn)` reads USER(), CURRENT_USER() and SHOW GRANTS, tagged, with `--comments`. - Audit: table `audit` in `~/.myflames/workspace.sqlite3` (owner-only, columns `workspace_store.AUDIT_COLUMNS`: id, attempted_at, finished_at (ISO-8601 UTC), status `pending|ok|error|declined|refused|unknown`, outcome (operation status such as `killed`, `denied`, `gone`, `read_only`, `no_terminal`), surface `ui|cli`, os_user, operation (`kill`, `kill_query`, ...), profile_id, profile_name, connection_type, read_only, host, port, db_user, engine, server_version, statements (JSON list, as sent, redacted), target (the identity confirmed), verified, policy, error_code, message, rows_affected, after, duration_ms). `record_attempt` writes `pending` before sending (a failure raises and nothing is sent), `complete` finishes it; `record_outcome` writes declined, refused, or failed-before-sending attempts as one finished row in one transaction; `AuditTrail` wraps one write for callers (`attempt`, `complete`, `outcome`, `fail`, `pending`). `fail` after `attempt` finishes the record as `unknown` for an interrupt, a client time limit or client error 2013 (`may_have_run`: the statement may have reached the server), else `error`. Records left `pending` or finished `unknown` read as `outcome_unknown: true`. `redact` removes literals after IDENTIFIED BY / AS / USING, PASSWORD(...), SET PASSWORD, `*PASSWORD = '...'` (SOURCE_PASSWORD, MASTER_PASSWORD, START REPLICA PASSWORD, CREATE SERVER OPTIONS), REPLACE '...' after a redacted password, and the connection's own password anywhere (also with doubled or backslash-escaped quotes). Retention: 90 days by default (`settings` table, `audit_retention_days`, 1 to 3650), purged on every insert and when the setting changes. `audit-1.0` envelope: `{schema_version, retention_days, records[]}`; each record has a nested `connection` object. A write through SSH also records `connection.ssh` (only when set) in the `ssh` column, which `WorkspaceStore._add_audit_ssh` adds on demand without a `user_version` bump; every audit site passes `ssh_host`, `ssh_user` and `ssh_port` with host, port and user, and the Audit log inspector says Through SSH. CSV export flattens it, puts the `ssh` column last and quotes cells starting with `= + - @`. - CLI: `python3 -m myflames audit [list|export] [--since DAYS] [--server NAME] [--json|--csv] [-o PATH] [-q]` (`list` is the default, `--limit N` default 50, text columns WHEN (UTC), STATUS, FROM, OPERATION, SERVER, STATEMENT, ID; `export` writes every matching record, JSON by default) and `audit purge --older-than DAYS [--yes]` (0 deletes all; asks on a terminal, refuses with exit 1 without one unless `--yes`; declined exits 1). Lives in `workspace_cli.cmd_audit`. - Endpoints (token, no server connection): `POST /api/audit/list` (`since_days`, `server`, `status`, `limit` default 500, `before` a record id for the next page; every filter applies before the limit, keyset order attempted_at then rowid) returns `audit-1.0` with `has_more`; `/api/audit/export` (`format` json|csv, filters including `status`) returns `{format, content, mime, filename}`; `/api/audit/settings` (`retention_days` to change it) returns `{retention_days}`; `/api/audit/declined` (`operation`, `statements` as the confirmation sheet showed them, optional `target`, `connection`) records a cancelled confirmation as `declined` and returns `{audit_id, status}` (the workspace's Kill sheet calls it on Cancel and Escape through `declineKill` / `recordDeclined`, with the tagged KILL and the identity it would have sent). Write endpoints are listed in `ui._WRITE_PATHS`: they fill the saved password themselves, after the policy, and are never in `_SERVER_VIEW_PATHS`. - Object change history (`POST /api/audit/object`, `ObjectChanges.tsx`; store queries in `workspace_store.py`, request checks in `dbops.py`): takes `{server, kind, key}` (plus optional `ssh`). `server` is the Audit log's `host:port` endpoint (at most 300 characters), matched case-insensitively against the recorded host and port, never a saved-connection label. `kind` is `parameter`, `account` or `index`: a parameter key is its exact name string (the `{name}` form is also accepted), an account key is `{name, host, role}` with `role` a strict boolean, an index key is `{schema, table, index}`. Names are at most 256 characters and cannot contain NUL; empty account names and hosts are retained where the account serializer permits them. Bad requests return the usual authenticated API 400. The response is `{schema_version: "audit-1.0", records}` with zero to five of the newest matching records, ordered by `attempted_at` descending then insertion order descending; only `ok` and `unknown` statuses qualify, and every filter applies before `LIMIT 5`. Parameters match `target.name` on the variable operation names (`set_global`, `set_persist`, `set_persist_only`, `set_session`, `reset_persist`); accounts match `target.account` through `accounts._name` for the recorded engine; indexes match `editor_run` records whose `target.alter_table` names that exact index (a statement recorded against the whole table never matches one index, so it is not attributed to one). No statement-text matching is used. The lookup is one local SQLite SELECT on the existing store, with no server connection and no SELECT when the store file does not exist; execution is interrupted at progress checkpoints after 250 ms or about 200,000 SQLite VM instructions, which produces a short local-history error pointing to the Audit log. The route shares the Host/Origin, session-cookie, token, POST allowlist, JSON-body and request-size checks of the other audit routes; no SQLite JSON extension is required. `/api/audit/list` and `/api/audit/export` accept an optional `id` (a 32-character lowercase hexadecimal audit id), applied before paging and export; audit navigation uses the existing `myflames-open-audit` event, selects and filters to that record, and offers **Show all records**. The inspector (`ObjectChanges.tsx`) shows only the newest record, with "Kept on this computer." and readable operation names (the raw operation key on hover): the stored redacted SQL in a box with Copy beside it, the relative attempted time with the exact timestamp on hover, the stored outcome, and **Open in Audit log**. For a known single-step parameter change, **Undo** pre-fills the existing variable sheet with the earlier value (`mode` and `value` only; the SQL is always built afresh by the normal variable planner, never replayed from a record) and is omitted for non-ok outcomes, account and index inspectors, compound SET PERSIST inverses, session changes and missing or redacted previous values (a recorded NULL value still gets Undo). Each inspector open reads once, and a completed parameter action refreshes its open inspector's local history. Tests: `test/test_audit_object.py`, `apps/workspace/test/object-changes-unit.mjs` and `object-changes-fixture.mjs`. - Workspace (`Audit.tsx`, `audit.css`): only labels and words change on screen; stored values stay as recorded. Columns are Time, Status, Operation, Connection, Type (`SafetyTags`), Statements, Error, Duration; Type and Duration are `detailColumns`, dropped by the compact preset when the view is narrower than 960 px. Times are local (`when`) with `" (UTC)"` as `title`, in the table and the inspector's Record section. The inspector maps stored outcome keys (`OUTCOME_WORDS`: `timeout` Timed out, `gone` Already ended, `unverified` Could not verify, and so on) and policy values (`POLICY_WORDS`: `confirm` Requires confirmation, `risky` Risky, `production` Production) to words, with `Stored as "KEY"` on hover; sections share one label column; each statement has its own Copy (copied as stored). The policy's `connection_type` is labelled **Judged as** (`POLICY_LABELS`). It can differ from the record's `connection.type` (the saved connection's type) because `connection_safety` judges a connection used with other settings than the saved ones as Production; the inspector then says "The connection is Development; this write was judged as Production." with that reason. The About ⓘ sits in the summary line once records are listed and keeps its toolbar place while the log is empty. Tests: `apps/workspace/test/audit.mjs` (column order, Type pills, inspector words and hovers, Judged as, local times, statement Copy, the ⓘ). - Tests: `test/test_dbops.py` (classification table, splitting, both backslash readings, policy matrix, privileges on both engines, redaction, audit lifecycle with a crash left pending, retention and purge, export, migration, CLI and endpoints) and `TestKillAudit` in `test/test_locks.py`. Every test that reaches the store uses a temporary HOME (`LockCase.run` wraps each lock test in `private_home()`). ### SQL CLI `myflames/sql_cli.py:cmd_sql` is dispatched by `cli.main` as `myflames sql`. Input is mutually exclusive `-e/--execute SQL`, `-f/--file FILE` (UTF-8; `-` means stdin), or stdin by default. Terminal stdin without a source is bad input. Every command reads and writes UTF-8 on redirected standard streams: `cli.main` calls `_utf8_standard_streams`, because Windows gives a redirected stream the ANSI code page (output with other characters crashed, and piped UTF-8 SQL or `--password-stdin` was misread). A console keeps Python's own Unicode path. The editor's 1,000,000-character script cap applies before connection. Connection flags come from `workspace_cli._add_connection_args`, with deferred `_resolve_connection` for profiles, saved passwords and `-p`. The adapter reads profile safety and calls `editor_session._plan_run`, `_decision` and `_gate` before password resolution or connection. Confirmation uses the editor's exact statement digest, expiring single-use token, and decline path. Every non-terminal write refuses without `--yes`; terminal stdin prompts on stderr with default No when the policy requires confirmation. `--yes` bypasses the prompt; read-only still refuses. A changed endpoint, default database or profile safety during password resolution refuses before opening a client. Once connected, the script is re-planned against the session's actual sql_mode; changed statements or policy need authorization again. `EditorSession.start_run(Run(...))` executes the script in one client, without helpers between user statements (the reviewed ALTER guard is an explicit statement, included in results and audit). Writes use `AuditTrail(operation="sql", surface="cli")`, including refused and declined attempts; no editor history entry is created. Production safe updates, read-only session guards, truncation, KILL QUERY cancellation and unknown write outcomes come from the editor engine. The session is closed in `finally`; no implicit COMMIT, no reconnect. Flags: `--format table|csv|json|tsv|markdown|insert` (default table), `--json` (overrides `--format`), `--limit N` (1 to 100,000; default 1,000), `--timeout S` (finite 0 to 86,400 seconds; default 0 disables it), `--yes`, `--confirm-target NAME`, `--insert-table NAME` (default `result`), `-o/--output PATH`, `-q/--quiet`. Results are stdout unless `-o` is set; messages, truncation notices and server errors are stderr. Errors retain the statement number, SQLSTATE, server code and editor line/column position. Quiet suppresses summaries and, with `--yes`, the confirmation description; errors and truncation notices remain visible. Both JSON options emit one envelope for runs with results or statement outcomes, including statement errors and partial runs: `{"schema_version":"sql-1.0","status":...,"results":[],"counts":null, "error":null,"stopped":null,"message":null,"audit_id":null}`. `status` is `complete`, `error`, `session_ended`, `stopped`, `refused` or `declined`. Completed runs reuse the editor's ordered result records (`rows`, `ok`, `error`) and counts; `statement` is zero-based, errors include `position`. No connection credentials or raw script are added. NULL is `null`; values with unknown column types remain strings. When numeric column metadata is supplied, small integer types within JavaScript's safe integer range and finite FLOAT/DOUBLE/REAL values become JSON numbers; BIGINT, DECIMAL, binary values, and values outside that range remain strings to preserve precision. Live editor XML currently provides no type metadata, so those values remain strings. Duplicate column names remain ordered columns plus row arrays. CSV, TSV and Markdown use `export_result`; `insert` uses `export_result("sql", result, table=args.insert_table)` to emit INSERT statements into the user-named table (default `result`). The name is validated before execution and quoted as one identifier, including any dots. It shares the UI exporter's identifier quoting and literals: typed binary columns use `X'..'`, hex-looking text without binary metadata stays quoted text, NULL stays NULL, and empty result sets emit no INSERT. Table mode JSON-quotes text to distinguish SQL NULL from empty text and the literal string NULL; values in known numeric columns are unquoted. INSERT also leaves known numeric values unquoted; untyped numeric-looking text remains quoted. Non-JSON result sets are concatenated in execution order, each with its own headers or INSERT target. JSON retains boundaries and metadata, including truncation. Credentials and SQL password literals are redacted on both output streams and in audit records. Exit codes: 0 complete, 1 statement failure or stopped run, 2 invalid/unreadable input, connection failure (including an ended connection during a run), or any failure/refusal/decline before sending a statement, including failure to create a pre-send audit record. Pre-send failures write a diagnostic to stderr only: stdout stays empty, even with either JSON option or `--quiet`, and no output file is created. Errors after statement outcomes retain the JSON envelope and any preceding results on stdout, including connection loss with exit 2. Tests: `HOME=$(mktemp -d) MYFLAMES_SECRET_BACKEND=vault python3 -m unittest discover -s test -p 'test_sql_cli.py' -v` uses the editor's fake MySQL/MariaDB clients, not a live server. CLI SQL confirmations record the actual refusal, decline, or execution outcome. Preparing the confirmation is not itself an audited refusal, including with `--yes`. DROP DATABASE/SCHEMA uses `dbops.cli_confirm(expected=target, supplied=args.confirm_target)`; `--yes` alone never satisfies a typed guard. The comparison preserves case and spaces. Pre-send refusal/decline remains exit 2 with no stdout or output-file changes. `_emit` builds the payload separately from diagnostics and passes it to `cli._write_output`; this implements cli-ux's output vocabulary, while `--insert-table` implements query-editor section 10's user-named INSERT target. ALTER opens a session for its read-only preflight before prompting; read-only, script-shape and non-TTY/`--yes` checks still precede credentials. The final policy read also covers edits during that review. The confirmation on stderr prints `myflames: ALTER predicted: SUMMARY. TEXT REASON` (or the reason it was not predicted) before `myflames: ALTER preflight: {json}`, whose JSON carries the same `prediction` as the workspace review; no flag or help text changed. ### Query editor sessions `myflames/editor_session.py` runs any SQL from a Query editor tab in that tab's own server session (query-editor skill). `myflames sql` uses the same planner, write gate and session engine from the CLI. - Process: one `mysql`/`mariadb` client per tab, stdin kept open, started by `EditorSession.start` with the connector's 0600 `--defaults-file` (deleted once the client has connected; the password never reaches argv) and `--xml --binary-as-hex --binary-mode --comments --force --quick --unbuffered -vv --skip-reconnect --default-character-set=utf8mb4` (plus `--skip-commands` when the client's `--help` lists `--commands`). `--force` is required: the batch client exits at its first error otherwise, which would end the session; myflames itself stops a script at the first error by sending the next statement only after the previous one succeeded. Ended on `/close`, connection switch (a request for another identity is refused, so the UI closes first), idle timeout (`EditorSessions.reap`, default 30 minutes, `idle_minutes` 1 to 1440), and server exit (`WorkspaceServer.server_close` calls `EditorSessions.close`; an `atexit` hook kills leftover clients). Never reconnected: an ended session answers runs with `status: "session_ended"` and `SESSION_ENDED_TEXT` until `/close` or `/open`. - Client: opening a session uses the connector's per-server choice and keeps the binary paired with its engine-specific option file. The handshake remembers valid endpoint engine/version facts. The tab pins its resolved client for plan and KILL QUERY helpers even after Settings changes; each helper rechecks trust before starting. New sessions use the current choice. Authentication-plugin connection failures preserve `client-auth-plugin`. Tests: `test/test_editor_session.py` (`ProcessTests`, `PinnedClientTrustTests`) and `test/test_connector.py` (`TestVersionAwareClients`, `TestClientSecurityFixes`). - Framing: a random client delimiter is set once (`DELIMITER __mf_`); each statement is written as `\n\ndelimiter\n`. The bare `delimiter` line makes the client print `ERROR at line N: DELIMITER must be followed by ...` on stderr without contacting the server; N is the line myflames wrote it on, so it ends the statement exactly and adds no server statement between user statements (ROW_COUNT(), FOUND_ROWS(), SHOW WARNINGS and GET DIAGNOSTICS keep working within a run). Server errors carry the line their statement started on, which attributes them. stdout and stderr are separate pipes, each read by its own thread: the MariaDB client writes an error before flushing stdout, so a merged stream could misorder them. On stdout, `-vv` echoes each statement between `--------------` lines; the echo is skipped by its line count (`Step.echo_lines`), then come XML result sets (parsed by structure: values are XML-escaped, so ``, ` ` and `` cannot occur inside them; `xsi:nil` is NULL), `N rows in set[, W warnings]`, `Query OK, N rows affected[, W warnings]` and the server's info line. A statement's stdout block ends at the next echo; the run's closing helper (a tagged status SELECT) closes the last one. Leading `--`/`#` comment lines are dropped before sending (the client would send them as a statement of their own) and trailing white space is trimmed (the client does that too). - Planning (`plan_statements`): `dbops.split_statements` with the session's backslash reading (`@@sql_mode`, read at start and after every run); a statement with `unclosed` or `issues` (client backslash command, also inside a `/*+ */` optimizer hint, which the client does not treat as a comment; `--` before a control character; unusable DELIMITER), a NUL, a leading `delimiter` word, or dollar-quoted text (`$tag$`, read as a string by MySQL 8.1+ clients) is refused with `status: "invalid"`; so is a statement whose quotes read differently under NO_BACKSLASH_ESCAPES after a statement that may change `sql_mode` in the same run. `selection: {start, end}` runs only that part. Offsets in requests and responses are UTF-16 code units (JavaScript string indexes; `Offsets`). - Values: NULL is `null`; everything else is the client's text (big integers, DECIMAL, dates as printed); binary columns print as `0x` plus upper-case hex and the column gets `hex: true` when every non-null value has that form. It is a guess (a text column holding such strings looks the same): SQL export writes `X'..'` only for columns the caller marks `binary: true`. Column types are `null`: the XML carries none and `--column-type-info` does nothing with `--xml`. An empty result set has no column names in the XML (`columns_known: false`). - Limits: `limit` (default 1,000, up to 100,000) rows per result set; the next row past it marks the result `truncated`. Only a statement that is one plain read (classified `read`, one server statement) is stopped with `/*myflames:editor*/ KILL QUERY ` from a second connection (`stopped: "row_limit"`, its 1317 shown as `interrupted`, not a failure); anything else (CALL, several statements under a custom DELIMITER, a write) runs to its end and the rows past the limit are read and dropped (`"row_limit_read"`), so a KILL never undoes a write. Also cut: more than 6 Mi characters of values per run (under the 12 MiB request limit, so a shown result can be sent back for export) or one row over 4 Mi characters (`size_limit`, `size_limit_read`). While a run is running, status responses carry no rows. Load more re-runs with a larger limit. Stop (`EditorSession.stop`) sends the same KILL for the running user statement; `stopped` is true only when the KILL was sent. A statement it interrupts (1317 or 3169) is `stopped` and undone; one that ended normally is `ok` and took effect, and later statements do not run. A statement still running `STOP_GRACE` (15) seconds after a KILL ends the session (`unresponsive`). `force: true` ends the session instead. KILLs and new statements are serialized (`send_lock`) and a KILL is never sent while a helper runs, so it cannot hit another statement; both servers also clear a KILL QUERY that lands between statements at the next command. `timeout` (seconds) stops a run the same way. The `CONNECTION_ID()` read at start is checked after every run; a different one ends the session. A statement's error text never ends the session by itself (server messages quote table data): a lost connection (1053, 1927, 2006, 2013, 2055, 4031) ends it when the run's status helper fails with one, or when the client exits. stderr: one server error per statement; every following line belongs to its message until the exact `ERROR at line : DELIMITER` line of that statement. - Transactions: after each run `autocommit`, `sql_mode`, `sql_safe_updates` and the transaction state are read with `/*myflames:editor*/` helpers: MariaDB `@@in_transaction`; MySQL the `STATE` of `performance_schema.events_transactions_current` for `PS_CURRENT_THREAD_ID()` (`in_transaction: null` with a `transaction_note` when the consumer, the `transaction` instrument or the thread's instrumentation is off, or the table cannot be read). These helpers make ROW_COUNT() and SHOW WARNINGS in the next run describe them. `/commit` and `/rollback` send tagged COMMIT and ROLLBACK; `/close` with an open or unknown transaction answers `transaction_open` or `transaction_unknown` unless `discard: true`. A statement that commits implicitly (DDL except CREATE/DROP TEMPORARY TABLE, GRANT/REVOKE, LOCK/UNLOCK TABLES, START TRANSACTION, BEGIN, SET autocommit = 1, ANALYZE/OPTIMIZE/REPAIR/CHECK TABLE, FLUSH, RESET, replication statements; `implicit_commit`) while a transaction is open or unknown always asks, also on Development, with `warnings`. - Safety: every run is classified per statement with `dbops.classify` (the session's backslash reading; before the session exists both readings) and judged by `dbops.decide` with `dbops.connection_safety` (a profile's type only while the endpoint matches; unsaved connections are production). `confirm` answers `status: "needs_confirmation"` with the exact statements and a one-time random `token` (`EditorSessions.issue_token`, valid `TOKEN_TTL` = 300 seconds, bound to a hash of the tab, the connection identity, the operation and the statements, including the **On error** mode for editor runs); changing Stop to Continue or back requires a fresh review. The run goes ahead only with `confirmed: true` and that token (`take_token` uses it up), so a confirmation never covers other statements or a later replay. `decline: true` records a declined attempt. Refused, declined and run writes get one audit record per run (`operation: "editor_run"`, the non-read statements, redacted; `unknown` when the session ended while a statement was out); reads are not audited. Read-only connections also start the session with `dbops.READ_ONLY_SESSION_GUARD` and refuse statements that would lift it. Production sessions start with `SET SESSION sql_safe_updates = 1`, Development leaves it off. A tab may turn it on (`safe_updates: true` on `/open` or the first `/run`); turning it off is `/open` with `safe_updates: false`, a session write judged by the policy (Production confirms) and audited as `editor_safe_updates`; the saved policy is re-read after the password lookup and again after the client connects, right before `SET SESSION sql_safe_updates = 0` (a change refuses, sends nothing and ends a session that request started). MariaDB `SET STATEMENT` of `transaction_read_only`, `tx_read_only` or `sql_safe_updates` is a write (`dbops.SESSION_GUARD_VARIABLES`); read-only connections also refuse `READ WRITE` switches matched with quoted identifiers restored. The audit record is written before anything is sent; when it cannot be, nothing is sent (`audit_failed`) and the tab stays usable. The saved password is filled only after the policy allowed the operation (ALTER metadata reads may precede its confirmation). `_policy_changed` re-reads profile type/read-only after password lookup and immediately before `start_run`; drift returns an audited refusal even if the old decision allowed Development DML. This implements db-operations section 1 step 6 and section 5's backend enforcement rule. Sessions are keyed by tab id plus `dbops.connection_identity` (saved connection id, host, port, user, TLS mode and CA, type and read-only). Concurrent runs on one tab answer 409 `code: "busy"`; at most 8 live sessions (`too_many_sessions`). `EditorSessions.open` never returns a live session of another identity, so requests racing on one tab cannot share it. - DDL confirmation (db-operations sections 6, 7 and 9): `_decision` refuses multiple DDL statements, including those grouped by a custom DELIMITER, before credentials. Run them one at a time. A CREATE routine's body is one DDL. DDL embedded in anonymous blocks or SET STATEMENT wrappers refuses: submit it as standalone SQL so its target and safeguards can be reviewed. Temporary-table DDL also confirms. Multiple DML statements still share one review. DROP DATABASE/SCHEMA carries `confirmation.typed_target`; `_gate` requires `payload.typed_target` to match the decoded database identifier exactly, alongside the single-use token. Read-only refusal takes precedence. - ALTER review (db-operations section 9): `_plan_run` adds the exact `/*myflames:editor*/ SET SESSION lock_wait_timeout = 5` before ALTER, leaving the user's SQL intact. It is shown, token-bound, audited and executed as its own statement in the same session; any error stops before ALTER. The setting persists in the tab afterwards. The skill gives `N`, not a numeric value; five seconds is the chosen application policy, per metadata-lock wait, not a total ALTER deadline. Longer MariaDB WAIT clauses and MySQL SET_VAR overrides of this timeout refuse before credentials. ALTER must be the only user statement in its run so preceding SQL cannot change the reviewed schema or table. `_alter_review` holds `run_lock` while reading DATABASE(), table metadata and Locks' existing transaction/MDL/session readers. `locks.alter_table_preflight` filters MDL SQL to the target table, caps collections at 500, attributes transactions through granted MDL, and labels unavailable/truncated coverage and unattributed open transactions. Approximate size is `information_schema.TABLES.DATA_LENGTH + INDEX_LENGTH` for the persistent table; temporary tables may be absent or shadow it. The review writes `approx_bytes` (unchanged) with `PerfShared.bytes` in binary units ("120.6 KiB (data and indexes)"), the grouped exact bytes on hover, and Unknown for null. The response's `alter_preflight` includes schema, table, engine/version, table_engine, approx_bytes, metadata_locks, transactions, unattributed_transactions, sessions, coverage flags, warnings and suggestion. Tokens also bind the reviewed schema/table, connection ID and server identity; changed session context requires a fresh confirmation. `start_run` also rechecks DATABASE() under `run_lock` before an unqualified ALTER, closing the gap for a concurrent USE between review and execution. `_alter_suggestion` offers INPLACE/LOCK=NONE only for recognized InnoDB ADD/DROP COLUMN or INDEX forms on MySQL 8.4+ and MariaDB 10.11+, and never when the prediction below is INSTANT (the review then says "No rewrite offered: the server is predicted to run this ALTER instantly."; on MySQL ALGORITHM=INPLACE turns an instant ADD or DROP COLUMN into a rebuild, `handler0alter.cc:1053-1056`). Existing algorithm/lock clauses, partitioning, comments and unknown cases get no rewrite, with an explanation. Suggested SQL is displayed separately; using it requires editing and a new review. INPLACE can rebuild a table, and LOCK=NONE does not remove metadata-lock acquisition. The UI points to Server > Locks; no automatic SQL rewrite or lock killing occurs. Source checks (mysql-expert's source-verification rule): local `mysql-server/sql/sql_table.cc:17360-17367` rejects INSTANT with a nondefault LOCK; `18470-18525` enforces requested INPLACE/NONE. Tag `mysql-8.4.0` has the same checks at `16499-16506` and `17604-17666`. Local `mariadb-server/sql/sql_alter.cc:139-223`, tag `mariadb-10.11.1:136-215`, validates requested algorithms and locks, including rebuild-capable INPLACE. MySQL rebuild evidence: `storage/innobase/handler/handler0alter.cc:927-949` and `3042-3043` (`innobase_need_rebuild` in the in-place path). SESSION timeout scope/ranges: MySQL `sql/sys_vars.cc:2378-2382`, MariaDB `sql/sys_vars.cc:1592-1596`. See also the official [MySQL operations table](https://dev.mysql.com/doc/refman/8.4/en/innodb-online-ddl-operations.html) and [MariaDB online DDL overview](https://mariadb.com/docs/server/server-usage/storage-engines/innodb/innodb-online-ddl/innodb-online-ddl-overview). Callers send the ALTER alone: the Tables view's Add column… and Remove column… (`TableAlterDialog.tsx`) once prefixed their own `SET SESSION lock_wait_timeout` line, which `_decision` refuses ("Review ALTER separately"), so they could never run. - ALTER prediction (`myflames/alter_algorithm.py`): `predict(alter_sql, create_table_sql, engine, version, facts=None)` never raises for SQL input and mirrors the server's three steps (`fill_alter_inplace_info` flags, `mysql_alter_table`'s forced COPY cases, InnoDB's `check_if_supported_inplace_alter`), each rule citing mysql-server 9.7 or mariadb-server 13.0 and version-gated where mysql-8.4.0, mariadb-10.11.16 or 11.4.10 differ. It returns `predicted`, `algorithm` (`INSTANT`, `INPLACE`, `COPY` or null), `rebuild`, `concurrent_dml`, `summary` ("INPLACE, rebuilds the table"), `text` (the outcome sentence), `reason`, `source`, `clauses` (`{text, algorithm, rebuild, concurrent_dml, summary, outcome, reason, source}` per clause), `notes` and `needs`. The statement's outcome is all clauses together, as the server computes it; when that is slower than every clause alone, `notes` says "Together these clauses…". `facts` may carry `foreign_key_checks`, `sql_mode`, `innodb_page_size`, `innodb_strict_mode`, `old_alter_table` (MySQL), `alter_algorithm` (MariaDB before 11.5), `old_mode`, `innodb_instant_alter_column_allowed` and `innodb_file_per_table` (MariaDB): a missing setting falls back to the server default and `notes` says "Assumes the server defaults: …". Table facts have no default: `total_row_versions` (MySQL INNODB_TABLES; the budget is 64 through 9.0.1 and 255 from 9.1.0), `fts_doc_id_index` (a hidden FTS_DOC_ID left by an old FULLTEXT index), `system_tablespace` (MariaDB), `referenced_columns` (other tables' foreign keys) and `default_collations` (MariaDB `character_set_collations`); when the outcome depends on a missing one the result is `predicted: false` and it is listed in `needs`. Not predicted: MySQL before 8.4 or from 10, MariaDB before 10.11 or from 13.1; partitioned, temporary, system-versioned and non-InnoDB tables, functional index parts and MariaDB compressed columns; partition and tablespace clauses, ENABLE/DISABLE KEYS, WITH/WITHOUT VALIDATION, ADD PERIOD or SYSTEM VERSIONING; table options other than COMMENT, AUTO_INCREMENT, character set and collation, ROW_FORMAT, KEY_BLOCK_SIZE, ENGINE and the STATS_*, MIN_ROWS, MAX_ROWS and CHECKSUM family; generated column expression, type or storage changes, dropping or renaming a column a generated column reads, inline REFERENCES, VECTOR columns or indexes, MariaDB column-level CHECK in ADD or MODIFY; a row near InnoDB's record limit; ALTER IGNORE on MySQL; MariaDB `alter_algorithm` values other than DEFAULT or COPY and a non-default `innodb_instant_alter_column_allowed`. `editor_session._alter_review` adds `prediction` to `alter_preflight` from reads through the same locked helper: `SHOW CREATE TABLE`, one `SELECT @@…` of the engine's `_PREDICTION_SETTINGS`, and only when `needs` asks one INNODB_TABLES (MySQL) or INNODB_SYS_TABLES (MariaDB) row with FTS_DOC_ID_INDEX, KEY_COLUMN_USAGE (MySQL) or INNODB_SYS_FOREIGN (MariaDB) for referenced columns, and CHARACTER_SETS (MariaDB). A failed read leaves its fact unknown; an exception gives `predicted: false` with its class name and never blocks the review. QueryLab's ALTER sheet shows a Predicted fact row first and a `
` "Why: …" (`AlterPrediction.tsx` `AlterPredictionWhy`, shared with Schema versions) with each clause's reason and source and the notes; `ReviewedSqlAction` (Indexes' Set invisible… and Drop, Tables' Add column… and Remove column…) shows one "Predicted: …" line. Live evidence: `test/fixtures/alter_algorithm/ live-mysql-8.4.json` (MySQL 8.4.11) and `live-mariadb-11.4.json` (MariaDB 11.4.13), 107 cases each, every case run with no ALGORITHM clause and with INSTANT, INPLACE with LOCK=NONE, INPLACE, COPY with LOCK=NONE and COPY on a fresh 100-row table (rebuild seen from the InnoDB table id, COPY from rows affected, concurrency from whether LOCK=NONE was accepted). `test_alter_algorithm.LiveFixtureTests` asserts every outcome and every accepted or refused explicit attempt. Not live-checked (source only): row-version exhaustion, MySQL's empty-table INPLACE preference (8.4.4+ and 9.2+, a note), `old_alter_table`, MariaDB `old_mode=LOCK_ALTER_TABLE_COPY`, MariaDB 10.11 and MySQL 9.x behaviour. `scripts/record-alter-algorithm-fixtures.py` rebuilds the fixtures on a lab server only: loopback `--host`, its own database `myflames_alter_probe` (dropped at the end), `sql_log_bin = 0`, and the password from the GA matrix credentials file in a 0600 defaults file, never printed. Tests: `test/test_alter_algorithm.py`, `apps/workspace/test/ editor.mjs` (the Predicted row and the Why disclosure). - History: one `records` row of kind `editor_history` per run (`WorkspaceStore.history_add|history_list|history_clear`): SQL redacted with `dbops.redact` (and the connection's password), connection name, host and port, time, duration, statement and row counts, status and error code; the oldest are dropped beyond 1,000 runs or 4 MiB. - Export (`export_result`, pure): CSV (RFC 4180, CRLF, NULL empty and unquoted, `""` for an empty string, optional BOM and formula guard), TSV for the clipboard, JSON (`{columns, rows}` arrays by default, objects with repeated names suffixed), SQL INSERT (backtick identifiers with doubled backticks; NULL; numbers unquoted only for columns the caller types numeric; `X'..'` for columns marked `binary: true`; `'..'` with doubled quotes, or `_utf8mb4 X'..'` when the text holds a backslash or a control character, so the output does not depend on NO_BACKSLASH_ESCAPES; same for MySQL and MariaDB), Markdown (escaped pipes and Markdown characters, `
` for newlines, `*NULL*`). For SQL INSERT only, when a result lacks types, the editor makes at most one `live/catalog` read on that result's source connection and borrows declared types only for plain column references in a single-table SELECT, matching select items by position and source names case-insensitively (aliases do not change the source name; a lone `*` or `t.*` maps by result name). Expressions, ambiguous result shapes or mixed wildcards, UNIONs, joins, WITH, missing source schema/table metadata and failed reads leave untyped values quoted; existing server result types always take precedence. - Privilege preview: `POST /api/editor/preview {connection, tab_id, sql, selection? | cursor?}` uses `_plan_run` and `dbops.classify`, exactly as Run does before connecting. It returns `status`, `scope`, `statements[]` (`index`, `kind`, `action_keys`, `state: allowed|denied|unknown`, `missing`, `reason`), `aggregate` (`state`, `missing`, `reason`, `warning`) and `policy` (`action`, `text`). Invalid SQL returns `status: invalid`, `code`, `message`, no statements and an unknown aggregate. No SQL or credentials are echoed. Preview opens no connection, retrieves no saved password and sends no SQL. `ui._accounts_response` caches successful `privileges-1.0` reads in workspace memory by the same connection identity as the editor; refresh invalidates the old entry first, overlapping reads keep the latest, and account applies invalidate the cache. Without a matching report the answer is unknown. `privileges.statement_privileges` maps classified units to existing action keys and `can()` answers; unsupported grammar and incomplete variable-specific checks remain unknown. A tab that sent SET ROLE, account SQL, opaque CALL/EXECUTE or temporary-table DDL remains unverified until reconnected. A role/account change in a proposed batch also makes subsequent statements unknown. Preview never changes the session itself. QueryLab debounces the selected/cursor and whole-tab previews by 300 ms, discards replies after text, scope, connection, session or privilege-report changes, and checks the matching answer again in keyboard Run handlers. Only a definitive denial for every selected statement greys a Run button; mixed batches remain enabled with a warning, and unknown shows Unverified. Denied buttons stay focusable with the reason in their tooltip and accessible description. The read-only policy refuses independently. Stop, Roll back and session closing retain their existing behavior; Run still performs its normal policy checks, confirmation and audit. - Endpoints (`editor_session.PATHS`, token-checked, loopback): `open`, `run`, `preview`, `status`, `stop`, `commit`, `rollback`, `use`, `close`, `history`, `export`, `file/open`, `file/save` under `/api/editor/`; `run` and `commit` are in `ui._WRITE_PATHS`, `open`, `stop` and `use` in `ui._CONNECTION_PATHS`. `/api/editor/status`, `stop`, `use` and `close` enforce session ownership by requiring the matching `connection` (`_connection_facts`, `session.identity == identity`); an unknown tab or mismatched connection returns `status: "none"`, stops nothing, refuses `use`, or returns `closed: true` with `session: None`. Shapes: docs/QUERY_WORKSPACE.md. - Tests: `test/test_editor_session.py`: replays of real MySQL 8.4 and MariaDB 11.4 client output (`test/fixtures/editor/*.json`, stdin built by the module's own framing, recorded from throwaway containers, including a KILL QUERY while rows stream), the fake client `test/_fake_mysql_client.py` (copied onto PATH as `mysql`; MySQL and MariaDB modes) for the session, Stop, limits, policy and audit, identity, idle timeout and history, and the export formats. - What runs is decided on the server: `/run` takes the whole text with a `selection` (split with `delimiter_at`, the delimiter in effect at its start) or a `cursor` (`statement_at` over `dbops.split_statements` with the session's backslash reading; `split_statements` takes the initial `delimiter`). `statement_at` and `sqlSelection.ts` `statementAt` are twins; both run `apps/workspace/test/fixtures/sql-split.json` (`test/test_sql_split_twins.py`, `test/sql-selection.mjs`), which also pins backslash modes, `\g` and executable comments. `decline: true` is answered first on `/run`, `/commit`, `/rollback` and `/open`: it never executes, whatever the policy says by then (a write is recorded as declined). - Explain (`_plan_run`): `/run` with `explain_format` (`table`, `tree`, `json`) explains exactly one statement in the tab's session, like MySQL Workbench. It prefixes `EXPLAIN FORMAT=TRADITIONAL|TREE|JSON ` (MariaDB's Table is plain `EXPLAIN `, which is always tabular there; MySQL 9.7 defaults `explain_format` to TREE in `sql/sys_vars.cc`, so Table names TRADITIONAL) and records `explain_prefix` so error offsets still point into the editor text. Tree needs MySQL 8.0.16 or later (refused otherwise). More than one statement (also through a DELIMITER) is `invalid_statement`, and so is a statement that starts with `ANALYZE` after optional `FORMAT=`, `EXTENDED` or `PARTITIONS`, because `EXPLAIN ANALYZE` executes. The prefixed text is classified like any statement, so EXPLAIN of a DELETE is a read, runs on a read-only connection without confirmation, and changes no row. Planning still evaluates constant parts (a derived table without tables is materialized while the plan is built, `sql/sql_derived.cc`; verified on MySQL 9.7: `EXPLAIN SELECT * FROM (SELECT GET_LOCK('x', 0)) a` leaves the lock held; stored functions ran this way before 8.0.42, 8.4.5 and 9.3.0, Bug#37560280), so `dbops` applies the SELECT expression checks to the explained statement (named locks, `:=`, sequences, locking clauses, and functions that are not verified native readers) without the INTO check; DDL after EXPLAIN stays a read because the server refuses it. An optional `parameters` object fills `:name` placeholders with `live.fill_parameters` (the literals of `bind_query`: hex strings, finite numbers, NULL, lists for IN; refused when backslash and NO_BACKSLASH_ESCAPES readings disagree); a statement without placeholders is sent as written, and Run never binds. No SELECT projection, transaction wrapper or session setting change. Messages and history show the exact `EXPLAIN …` sent (`statement.sent`). The UI's Explain format select (`explain_format` in the UI preferences store, with a one-time legacy `myflames.editor.explainFormat` localStorage fallback) shows the rows in an "Explain" result tab with Export and Explore; Explore captures the original statement (`live/start`, mode `explain`, SELECT guards apply) and opens Plans. Run analysis keeps the capture path, and its result is the "Analysis" tab with its own Explore (`test/test_editor_session.py`, `test/editor-explain-live.mjs` against a real server). - Workspace UI (`apps/workspace/src`): `QueryLab.tsx` keeps a `Runtime` per tab in page memory (session status, the connection key and connection it was opened with, the connection of the request on its way, where the results came from (connection key and session id, for Load more), a request generation, notes); the runtime ref is updated in the same task as each change. `runSql` sends the text with the selection or the caret (`sqlSelection.sqlRun`; its statement range only draws the tint), `wait: 2`, then long-polls `/status` (`wait: 5`) until the run ends; a failed poll keeps the run active (Stop stays) and retries. Every execution path, Explain and Run analysis included, refuses while the tab's session is on another connection. The mismatch banner names the session's server and the connection in use and offers Close session; Run, Run all, Explain and Run analysis are disabled. Results keep From <connection>, even after closing that session, and Load more requires the original session and connection. Stop, Commit and Roll back use the session's own connection, never the picker's. Export lives in the results tab row and applies to the selected result. A restore probe is marked done only once answered and is dropped when a request started meanwhile. `needs_confirmation` opens a ConfirmSheet; Confirm re-reads the write policy (`useWritePolicy().check()`) and sends nothing when the connection key changed, else resends with `confirmed` and the token; a reply that asks again says whether the token expired; Cancel and Escape resend with `decline: true` (the server audits it). Commit and Roll back keep the tab's results; closing a tab calls `/close` and only on `transaction_open` or `transaction_unknown` asks Commit and close or Roll back and close (`discard: true`). After a reload the active tab asks `/status` once and adopts a session still open. `editor/SqlEditor.tsx` (the CodeMirror 6 component: `editor/sqlLanguage.ts` builds one Lezer tree per document from the `sqlHighlight.ts` tokenizer, driving the syntax colors and the bracket or quote pair next to the caret, both off above `HIGHLIGHT_LIMIT` (60,000) characters; `editor/marks.ts` draws the statement tint, the run flash, the error underline and the gutter line marks, and `editor/visual.ts` the active-line and selection-match highlights), `ResultsPane.tsx` (results tabs, `DataTable` grid, Messages, Export, copy menu), `SchemaBrowser.tsx` (`/api/live/schemas` through `useSchemaCatalog` once per connection identity, the first time the pane is visible with a connection, then `/api/live/catalog` on expand; cached per connection key and kept while hidden; the header has Reload schemas with the busy, retry and connection-scoped behavior; with no connection it asks for one), `HistoryPanel.tsx`, `editor.css`. Session restore: tab `limit`, `selection`, `result_tab`, and `query_lab.editor_layout` (height, browser and width, history, run time limit), reported only once changed from the defaults. Browser suite `test/editor.mjs` (`npm run test:editor`). - Editor component (`apps/workspace/src/editor/`, CodeMirror 6): one `EditorState` per tab in a per-tab document store (`createDocumentStore`; the state carries the tab's own undo history, so undo is per tab, and external value replacements are one undo step through `isolateHistory`). Settings reconfigure Compartments, never remount the view. Every document includes the phrase overrides **Problems**, **No problem warnings**, **Close** and **SQL suggestions**. The host captures the lint panel's Close click, closes it and focuses the editor; CodeMirror content event handlers do not receive panel clicks. The shortcuts popover renders arrow glyphs and uses Esc, Space, Tab and platform-specific Return/Enter. Several selections: Run, Explain and Run analysis read only the main cursor or selection (`getSelection()`; `getSelections()` exists for checks). Run all runs the whole tab (`sqlSelection.sqlRun`, `all: true`), and Format SQL refuses several ranges ("Format SQL works with one cursor or selection; several are set. Keep one and try again."). Escape closes suggestions, else keeps only the main cursor, else closes Find, Replace or Go to line through `findHooks.close`, else closes the lint panel when open. Each handled step consumes Escape; otherwise it falls through to Stop and CodeMirror's Escape-then-Tab focus handling. Closing the Find controller clears marks and returns focus without changing the current selection or scrolling to the last match. Select all occurrences (`Shift-Mod-l`, only with Multiple cursors on) expands an empty caret using `state.wordAt`, or accepts several ranges with identical selected text, then delegates to CodeMirror's selection-match search. Unequal ranges are left unchanged. The standard macOS `Ctrl-k` binding prevents the default event and stops propagation so deleting to line end does not also open the command palette. The Next match label mentions Ctrl+G opening Go to line only off macOS. The desktop Edit menu's Undo and Redo reach the focused editor's CodeMirror history through the `window.__myflamesEditCommand` bridge, which accepts only the two literal commands `"undo"` and `"redo"` and reports an empty history as handled so Chromium's own undo never runs (`apps/desktop/main.cjs` falls back to the native editing command when no editor has focus). Feature suites: `test/editor-core.mjs` (`npm run test:editor-core`), `test/edit-menu.mjs` (`npm run test:edit-menu`), and the renderless unit suites `test/editor-core-unit.mjs`, `test/editor-commands-unit.mjs`, `test/editor-find-unit.mjs`, `test/sql-tree-parity.mjs` (Node, no browser). - Safe updates explanation: `SafeUpdatesInfo.tsx` is the standard `InfoPopover` (ⓘ, "About safe updates") beside the Safe updates checkbox in Run options (`.safe-updates-row`). Its wording follows the server source, not the manuals: MySQL refuses (1175, before any row changes) a single-table UPDATE or DELETE with no index usable for its WHERE (`quick_keys` empty) and no LIMIT, and a multiple-table one that scans a table it changes (`CheckSqlSafeUpdate`); MariaDB refuses the same and also a DELETE whose WHERE is missing or constant even with a LIMIT (`const_cond` in sql_delete.cc), a multiple-table one with a full scan of any joined table (`error_if_full_join`), and a multiple-table DELETE without a WHERE even under EXPLAIN (`multi_delete_precheck`); MySQL never refuses EXPLAIN; the server variable does not limit SELECT (the client's `--safe-updates` adds `sql_select_limit` and `max_join_size`, which myflames never sets). Its two documentation links (`SAFE_UPDATES_DOCS`) open with `target="_blank"` and must pass the desktop `externalLink` allowlist (`dev.mysql.com`, `mariadb.com`; checked by `apps/desktop/test/backend.test.cjs` against the source and by the browser suite against the rendered page). `EditorSplitButton` keeps its panel open when a popover inside it opens (the `myflames-popover` event names an element inside the panel) and leaves Escape to that popover first; `.editor-options-popover:has(.popover)` drops the panel's entrance transform, which would otherwise be the nested popover's containing block. Browser suite `test/safe-updates-info.mjs` (`npm run test:safe-updates-info`; `SAFE_UPDATES_SHOTS=` writes screenshots at 1440x900 and 720x520, light and dark). - Query tab menu (`QueryTabMenu.tsx`, the shared `.context-menu` with `useFocusScope({ menu: true })`): right-click, Shift+F10 or the ContextMenu key on a tab (`aria-haspopup="menu"`, the tab's `data-tab-id`) opens Rename… (F2), Duplicate, Close and Close others for that tab; Escape or a click elsewhere closes it and focus returns to the tab. Rename keeps the inline field (double-click, F2, the menu, and the palette's **Rename query tab** through `QueryLabHandle.renameTab`): trimmed, at most `MAX_TAB_NAME` (64) characters (`maxLength`; the session normalizer allows 200; a longer name is cut by `clipName`, which never splits a surrogate pair), Enter on an empty name keeps the field open with `aria-invalid` and a message in `.editor-feedback`, blur keeps the old name, Escape cancels. Duplicate copies the tab (SQL, parameters, limit, source and target binding, not the results tab) right after it as "NAME copy" (`copyName`). Close others calls `requestClose` (now returning `closed`, `asks`, `running` or `error`) tab by tab, skips running tabs and stops at the first one that asks Commit or Roll back. Labels end in an ellipsis past 240 px (`.query-tab-label`); the tab's tooltip has the whole name. - Format SQL: `formatSql` in `QueryLab.tsx` (toolbar `IconButton` `data-action="format"`, icon `format`, Shift+Alt+F on the tab panel by `e.code === "KeyF"`, and the palette through `QueryLabHandle.formatSql`, which switches the Query editor to its Editor view and waits for the text area to be on screen, never formatting a hidden editor). It reads the textarea, loads `sqlFormat.ts` with `import()`, calls `formatEditorText` (a selection that starts or ends inside a token of the whole text, under every reading, is refused; the whole text after the change goes through `compareSql`, since a fragment alone cannot show it sat inside a string), and replaces the selection (or all the text) with one `execCommand("insertText")` (text changed, a selection made, changed or cleared, or the editor hidden while the chunk loaded, or an edit the browser refuses, changes nothing and says so), so the browser's undo restores it in one step; a selection stays on the formatted text, otherwise `mapOffset` keeps the caret, read after the chunk loaded, next to the same character. `sqlFormat.formatSql` splits with `splitStatements` and formats statement by statement with `formatDialect` (`mysql`, or `mariadb` when the tab's session is MariaDB; `tabWidth: 2`, `keywordCase: "preserve"`, `paramTypes` `?` and `:name`), keeps DELIMITER blocks, stored programs and compound statements, client commands, unclosed quotes or comments, names in square brackets, statements the formatter cannot read and statements whose executable comments or hints it would change exactly as written, and joins statements with one blank line (other gaps stay as written). `sqlFormatCheck.ts` holds the guarantee: `tokenize` (the server's lexical rules: `-- ` needs white space, `X'..'` `B'..'` `N'..'` are one token, `@var`, `:name`), `caseSafe` (words reserved in both servers, each statement's first word and the keywords of a statement opening, never next to a `.`, including a dot at the edge of an executable comment beside the word; an executable comment is code and ends a statement's opening, while plain comments and `/*+` hints are skipped), `upperKeywords` and `compareSql`, which runs under every reading in `READINGS` (with and without backslash escapes, and with `[name]` as one quoted name, as MariaDB 10.4.5+ reads it under sql_mode=MSSQL, MDEV-19142) and refuses any change beyond white space, plain comment white space, line comment trailing space and safe keyword case, or a change of the space between an IGNORE_SPACE function and its parenthesis. `RESERVED` and `IGNORE_SPACE_FUNCTIONS` were computed from the server sources (MySQL `sql/lex.h` symbols not declared `%token` in `sql_yacc.yy`, as `gen_keyword_list.cc` does, intersected with MariaDB `lex.h` symbols in no `keyword_*` rule; MySQL `SYM_FN` and MariaDB `sql_functions[]`). A refusal, a kept statement or "Already formatted" is said in `.editor-feedback` (`is-error` for a refusal); nothing is sent to the server. Unit tests `test/sql-format.mjs` (`npm run test:sql-format`, no build: the modules are compiled by `test/sql-format-load.mjs`); browser suite `test/editor-tools.mjs` (`npm run test:editor-tools`; `EDITOR_TOOLS_SHOTS=` writes screenshots at 1440x900 and 720x520, light and dark). - Toolbar layout (`editor.css`): the editor toolbar wraps onto another row whenever its items do not fit, at any pane width; no fixed breakpoint can promise one row, since the Database picker's longest name, the scope, the transaction state and the privilege note all change its width. An item shrinks below its content only when it clips that content: the plain transaction state (Auto-commit, Manual commit, Session ended) keeps its full width, and the transaction meter shortens with an ellipsis only when a row is too narrow for it. The privilege note's basis is its whole sentence (`flex: 1 1 auto; min-width: min(100%, 24em)`): it stays on a row only where it fits whole, otherwise starts the next row, and ends with an ellipsis only when even a full row is too narrow (the 720 px window, or a 1040 px window with the schema browser open); its tooltip keeps the full text. In a pane of 1,100 px or less the groups may also wrap and the scope shortens. Browser suite `test/editor-toolbar-layout.mjs` (`npm run test:editor-toolbar-layout`; `EDITOR_TOOLBAR_SHOTS=` keeps screenshots) asserts that no two toolbar labels paint over each other and none leaves the toolbar, and that the note shows its whole sentence wherever one toolbar row can hold it (always at 1440 px, and at 1040 px with the schema browser closed), at 1440, 1040 and 720 px, light and dark, with the schema browser open and closed, one or two statements, Auto-commit and the transaction meter. - The editor's room (`measureEditorRoom`) is set only when the measured value changes (`measuredRoom`): a no-op update from its every-commit layout effect kept re-rendering while a lower-priority caret update waited, and React stopped with "Maximum update depth exceeded" when Format SQL replaced the text. - Schema browser endpoint: `POST /api/live/catalog` (`ui._CATALOG_PATHS`, read-only, saved password filled like the views) answers `schema_browser.catalog_report`: `catalog-1.0` tables of one schema (`information_schema.TABLES`, at most 200 per page), one table's columns and indexes (`COLUMNS`, `STATISTICS` read by name), or one schema's object group when `group` is `"routines"`, `"triggers"` or `"events"` (`level: "objects"`, `limit: 200` (`MAX_OBJECTS`), `truncated: bool`, and `objects`: `routines` `{name, kind: "procedure" | "function"}` from `information_schema.ROUTINES` with `ROUTINE_TYPE IN ('PROCEDURE', 'FUNCTION')`, MariaDB packages excluded; `triggers` `{name, table, event, timing}` from `information_schema.TRIGGERS`; `events` `{name, status}` from `information_schema.EVENTS`), tagged `/*myflames:editor*/`, names as hex literals. Optional `prefix` (literal text, including `%` and `_`) and `after` (exclusive continuation) are forwarded to the module after `check_table` validation, before opening a connection: null/empty means absent; otherwise strings of at most 64 characters, with blank-only text, NUL, LF and CR rejected. Pages use binary table-name order and return `next_after` when truncated. `stats: true` (only a literal true) adds `engine`, `rows` (`TABLE_ROWS`, the server's estimate) and `bytes` (`DATA_LENGTH + INDEX_LENGTH`) to each table, None for views, and `stats` to the report; Maintenance > Dump reads it for the one chosen database (MariaDB opens each table of that schema to answer). In `SchemaBrowser.tsx`, expanding a schema lists **Routines**, **Triggers** and **Events** folders after its tables and views; opening a folder loads its group on demand, double-click or Enter/Space on an object inserts `.` at the editor cursor, and its context menu offers **Insert name** and **Show CREATE PROCEDURE / FUNCTION / TRIGGER / EVENT** (appended and run via `onQuery`). Tests: `test/test_schema_browser.py`, `test/test_ui.py`. - Find and replace (`apps/workspace/src/editor/FindBar.tsx`, `editor/find.ts`, `editor/findMarks.ts`, `editor-find.css`): `⌘F` (`Ctrl+F`) opens Find and `⌥⌘F` (`Ctrl+H` on Windows and Linux; `Ctrl+Alt+F` also works there) opens Find and replace above the editor. A single-line selection seeds the Find field; there is no 200-character selection limit. `Enter` / `⇧Enter` in Find and `⌘G` / `⇧⌘G` (`Ctrl+G` / `Ctrl+Shift+G`) step between matches (`Ctrl+G` opens Go to line when Find is closed on Windows and Linux); Escape closes the bar and returns to the editor. Toggles are **Match case** (`Aa`), **Whole word** (`|ab|`) and **Regular expression** (`.*`). `computeFind` uses a Unicode literal search and, for literal whole words, letters, numbers, `_` and `$` as word characters. Regex mode uses JavaScript `g` / `gi` expressions (no `u`), with JavaScript `\b` boundaries for Whole word, and ignores zero-length matches. `createRegexFinder` runs regex searches in a terminable worker, with `FIND_REGEX_TIMEOUT_MS` = 250 ms and "Pattern too slow to search" on timeout; invalid patterns set `aria-invalid` and report an error. Searches retain at most `FIND_MATCH_LIMIT` (100,000) matches, append `+` to a capped count, and draw at most `FIND_MARK_LIMIT` (1,000) marks, including above `HIGHLIGHT_LIMIT` (60,000 characters). **Replace** and **Replace all** insert replacement text literally, including `$&` and `$1`; capture-group expansion is not implemented. They plan CodeMirror changes (`planReplace`) dispatched as one transaction with `isolateHistory`, so one undo restores the text; a single Replace remembers its undo anchor, and an immediate undo returns the find anchor to the undone match. Tests: `apps/workspace/test/editor-find.mjs` and `test/editor-find-unit.mjs`. - Open and save `.sql` files, Continue on error, and the tab's default database picker (`QueryLab.tsx`, `QueryTabMenu.tsx`, `ResultsPane.tsx`, `session.ts`, `myflames/editor_session.py`, `myflames/file_picker.py`): - **Open and save `.sql` files**: **Open SQL file…** in the query tab menu or `⌘O` / `Ctrl+O` inside the Query editor calls `POST /api/editor/file/open` (`{}`). The native file dialog (`file_picker.choose_sql_file`, `.sql` and `.txt`, serialized by `folder_picker._DIALOG_LOCK`, 120 s timeout) resolves and checks its chosen path. The reader then opens through the checked parent without following a file or folder swapped for a symbolic link; it refuses anything but a regular file and checks the 5 MiB limit (`SQL_MAX_BYTES`, 5,242,880 bytes) both on the open descriptor and by reading at most one byte beyond the limit, so a file that grows during the read is refused too. It strips a UTF-8 BOM, replaces invalid UTF-8 bytes with `U+FFFD` with a `warning`, and opens a new tab named after the file (without `.sql` / `.txt`, clipped to 64 characters). The process-local `_FILE_TOKENS` map keeps at most 200 opaque tokens bound to the resolved path and its parent directory's device/inode; the renderer never supplies a write path. `⌘S` / `Ctrl+S` saves via `POST /api/editor/file/save` (`{sql, token}`). `⇧⌘S` / `Ctrl+Shift+S`, or Save without a binding, uses `{sql, save_as: true, name}` and `choose_save_file`. An `unknown_token` after a backend restart opens Save as within the same Save operation; success, cancellation or failure is reported, and a cancelled or failed save or close keeps the tab's unsaved edits. Save as suggests the bound file's name, or `.sql` without a binding. `_clean_suggested_name` removes path components and controls, replaces colons with hyphens, appends `.sql` when needed and clips the suggested name to 255 characters. On macOS and Windows the sanitized name reaches the native dialog through `MYFLAMES_SAVE_NAME` unchanged, including quotes and Unicode, never as script source. Save accepts at most 8,000,000 characters and `.sql` or `.txt` destinations. It refuses a symbolic-link target, directories, special files, and a parent whose identity changed since selection ("Use Save as to choose the file again"). When it adds `.sql` to a name without an extension, publication never replaces an existing file, including one created after validation: choose the full filename in Save as to approve replacement. `write_text_atomic` writes UTF-8 without BOM to a temporary file, flushes and `fsync`s it, then uses `os.replace` for an approved full name or an atomic no-clobber link when `.sql` was added. With directory-descriptor support, the parent stays pinned during creation, publication and cleanup; other platforms recheck its identity. An existing regular file owned by this user with one hard link keeps its `0777` permission bits; if the temporary file lands in a different group, group permissions are set to the old permissions for others. Other files use `0666` less the umask with directory-descriptor support; the temporary-file fallback uses owner-only permissions. A file-backed tab whose `sql !== file.savedSql` shows an edited dot (`title="Edited since the last save"`), adds `Edited` to the window status bar, and asks **Unsaved changes** with **Save**, **Don't save** and **Cancel** before closing the tab. Tests: `test/test_editor_files.py`, `test/test_file_picker.py`, `test/test_editor_session.py`, `apps/workspace/test/editor-files-unit.mjs` and `editor-file-safety.mjs`. - **Continue on error**: **Run options** offers **On error: Stop / Continue**, default Stop (stored per tab as `on_error?: "stop" | "continue"` in `session-1.0` and sent to `POST /api/editor/run`). `_review_digest` includes `on_error`, so approving a write in one mode never approves running it in the other. Continue applies only to `scope == "all"` (**Run all**); Stop, loss of the session, and safety or review refusals still prevent further statements. After a Continue run finishes, Messages counts actual statement statuses: succeeded (`ok`), failed (`error`), not run (`not_run` or `pending`), stopped (`stopped`) and outcome unknown (`session_ended` or `running`), showing the last three counts when nonzero, and lists each failure with its statement number and jump link. Error 1213 adds "Error 1213: an InnoDB deadlock rolls back the victim's whole transaction" and error 1205 adds "Error 1205: an InnoDB lock wait timeout rolls back the whole transaction only with innodb_rollback_on_timeout ON": engine behavior, never a claimed outcome, since a script can SIGNAL either code and a metadata lock wait also ends with 1205. The On error ⓘ explains that by default an InnoDB error rolls back only the failed statement; a deadlock, or a lock wait timeout with `innodb_rollback_on_timeout` ON, rolls back the whole transaction. - **Default database picker**: **Database** (`