Release 0.2.5

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

.github/ISSUE_TEMPLATE/bug.yml

@@ -163,6 +163,17 @@ body:
         a photo of a terminal is hard to read. Paste the whole traceback if it crashed.
       render: text
 
+  - type: textarea
+    id: log
+    attributes:
+      label: The log file
+      description: >
+        MeshTerm keeps one at `~/.meshterm/meshterm.log` (or wherever `MESHTERM_HOME`
+        points). Attach it, or paste the last twenty lines. If the problem is hard to
+        catch, set **Log detail** to `DEBUG` on the Preferences page, do it once more,
+        and send that instead — it records a great deal more.
+      render: text
+
   - type: textarea
     id: extra
     attributes:

.github/workflows/ci.yml

@@ -111,5 +111,9 @@ jobs:
         run: |
           python -m venv /tmp/fresh
           /tmp/fresh/bin/pip install --quiet dist/*.whl
-          cd /tmp && /tmp/fresh/bin/meshterm --help > /dev/null
-          echo "the wheel installs and the console script runs"
+          cd /tmp
+          /tmp/fresh/bin/meshterm --help > /dev/null
+          # A tool-provided subcommand, not just --help: the tools are discovered at
+          # runtime, so a broken package still answers --help perfectly well.
+          /tmp/fresh/bin/meshterm contacts --help > /dev/null
+          echo "the wheel installs, the console script runs, and its tools registered"

.github/workflows/installers.yml

@@ -78,8 +78,14 @@ jobs:
           # source tree fails here rather than on someone's laptop.
           cd "$(mktemp -d)"
           "$GITHUB_WORKSPACE/$bin" --help > /dev/null
+          # Reads the asset files, so a bundle missing its pages fails here.
           "$GITHUB_WORKSPACE/$bin" specimen > /dev/null
-          echo "runs, and finds its assets"
+          # And a tool-provided subcommand, which is the check that matters. Every tool is
+          # found at runtime by `pkgutil.iter_modules`, so a bundle that omits them still
+          # starts, still prints help, still draws the specimen — and has an empty menu
+          # with nothing in it but Quit. `--help` passing proves almost nothing on its own.
+          "$GITHUB_WORKSPACE/$bin" contacts --help > /dev/null
+          echo "runs, finds its assets, and its tools registered"
 
       - name: Name it after the version and the platform
         shell: bash

CHANGELOG.md

@@ -7,8 +7,143 @@ numbers follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) — wi
 SemVer itself makes for a leading zero: while the major version is `0`, a **minor** bump is
 allowed to change behaviour, not just add to it.
 
+<!--
+  At 0.9.0 — the first public release — everything below collapses into a single entry
+  reading "first public release", with the headline features under it. Nobody arriving at
+  a project on its launch day wants a changelog of the fortnight before it: the versions
+  under 0.9.0 were never released anywhere, and their entries are notes to ourselves about
+  getting ready. Keep the dates and the tags; replace the prose.
+-->
+
 ## [Unreleased]
 
+## [0.2.5] — 2026-09-07
+
+### Fixed
+
+- **Every icon was a box in the classic Windows console.** That console — which is what a
+  double-clicked build still gets — draws no emoji at all, whatever font it is set to, so
+  the menu came up as rows of replacement characters.
+
+  MeshTerm now works out which console it is running in and, on that one, draws its icons
+  through the compact single-character table it already keeps for the PicoCalc: `☼` for an
+  advert, `¶` for a message, `★` for the trophy case. Nothing else about the desktop
+  layout changes — same width, same colours, same accented names. Running in Windows
+  Terminal or VS Code's terminal keeps the emoji, and `MESHTERM_EMOJI=1` or `=0` forces
+  the matter either way. `meshterm platform` reports which it chose and why.
+
+### Added
+
+- **MeshTerm offers to reopen itself in Windows Terminal.** The classic Windows console —
+  what you get from a double-click — can't show the emoji icons at all, whatever font it
+  is given: the only two Windows fonts with emoji in them are proportional, and a console
+  won't take one. A terminal is the only thing that fixes it, so MeshTerm now offers to
+  move there. One keypress, nothing installed, nothing changed — and you get the app as
+  it was drawn: icons, charts, path chips and all.
+
+- **MeshTerm can install a font its charts will actually draw in** — for anyone who stays
+  in the classic console. That console does no font fallback at all, and none of the fonts
+  it offers can draw braille, which every timeline and activity graph in MeshTerm is made
+  of. Neither can Hack Nerd Font, JetBrains Mono, Fira Code, Source Code Pro, or even
+  DejaVu Sans Mono; the usual advice works only because most terminals quietly fall back
+  to a proportional font.
+
+  So MeshTerm now ships Cascadia Mono PL — Microsoft's console font, SIL OFL — and on
+  that console offers to use it. If you already have Cascadia (every Windows 11 machine,
+  and anyone with Windows Terminal) it just switches to it. If not, it offers to install
+  it for you: no administrator rights, nothing downloaded, 723 KB. Saying no explains
+  what saying no looks like and asks once more; a second no is remembered and never
+  raised again. Preferences → Display → Console setup changes your mind about either
+  offer.
+
+## [0.2.4] — 2026-09-07
+
+### Fixed
+
+- **MeshTerm crashed on startup on Windows.** Building the screen raised
+  `ctypes.ArgumentError: expected LP__CSBI instance instead of pointer to
+  CONSOLE_SCREEN_BUFFER_INFO`, and on a double-clicked build the traceback and the window
+  it was printed in were destroyed together.
+
+  `ctypes.windll.kernel32` is a cache: every caller in a process gets the same object, and
+  each function on it is a shared attribute. The emoji-width probe declared
+  `GetConsoleScreenBufferInfo` as taking a pointer to *its* copy of the screen-buffer
+  struct — which rewrote the signature for prompt_toolkit, which then called that same
+  function with a pointer to *its* copy. Same layout, different class; ctypes refused.
+
+  Nothing in MeshTerm reaches for `ctypes.windll` any more. Five call sites now take
+  private handles from `core/win32dll.py`, so a signature declared for one purpose is
+  invisible to everything else in the process.
+
+### Changed
+
+- The log-detail preference offers the plain level names — Error, Warning, Info, Debug —
+  rather than descriptions of them. Someone being talked through a problem is told "set it
+  to debug", not "set it to everything".
+
+## [0.2.3] — 2026-09-07
+
+### Changed
+
+- The log is a plain text file, `~/.meshterm/meshterm.log`, one readable line per record
+  with the traceback under the line that raised it. It was JSON Lines on the theory that
+  something would replay it; nothing ever did, and the job it actually has is being opened
+  by a person who has hit a problem.
+- It rotates, at 2 MB across three files. It used to grow without limit — a real one
+  reached 11 MB in ten weeks, which is a lot of disk on a handheld and an unreasonable
+  thing to attach to an issue.
+- **How much it keeps is a preference** — `log_level`, under a new Diagnostics group,
+  defaulting to `WARNING`. The file now holds the problems rather than a narration of a
+  working session: of the last twenty thousand records in a real log, twelve were a
+  warning or an error.
+
+### Added
+
+- One interactive MeshTerm per data directory. A second one is turned away with the way
+  out in the message, rather than quietly overwriting the first one's contacts and
+  settings. The lock is held by the operating system, so a crash releases it — a process
+  id in a file would leave a lock nobody could explain.
+- Failures are written down. Every unhandled error reaches the log with its traceback and
+  the terminal says where to find it; expected errors go in as warnings, because a log
+  that only holds crashes cannot answer "what happened just before". The bug report form
+  asks for the file.
+- The window stays open after a crash when MeshTerm owns it. Double-clicking the
+  executable on Windows gives the process its own console, which is destroyed the instant
+  the process ends — so an error was drawn and erased together and all anyone saw was a
+  flash. It now waits for a keypress, but only on that path: a run from a shell leaves its
+  output on screen already, and a successful run should not make anyone press a key.
+- A readable answer when there is no Windows console. Git Bash, MSYS and Cygwin are not
+  Windows consoles, and prompt_toolkit's own error says so in the language of its
+  internals, arriving as a traceback that reads like a broken app rather than the
+  instruction it is.
+
+### Fixed
+
+- All ten stores write through one helper, and the file each writes to first is named
+  for the process writing it. They shared a fixed `.tmp` name, so two copies of MeshTerm
+  saving at the same moment took turns inside one scratch file and then each renamed
+  whatever was in it over the real one. The rename was always atomic; what was being
+  renamed was not.
+
+## [0.2.2] — 2026-09-07
+
+### Fixed
+
+- **The downloadable builds were missing every tool.** They started, printed help and drew
+  the specimen card, and had a menu with nothing in it but Quit — no contacts, no map, no
+  trace, no chat. Tools are found at runtime with `pkgutil.iter_modules`, which finds
+  nothing inside a frozen bundle, so none of them registered. The packaging now collects
+  them, and the smoke tests run a tool-provided subcommand instead of only `--help`, which
+  a gutted build passes perfectly well.
+
+### Added
+
+- `MESHTERM_HOME` points config and data somewhere other than `~/.meshterm`. Every copy of
+  MeshTerm shared one directory, so trying a downloaded build meant letting it open the
+  same history database as the one you use — the valuable half of an install, with no way
+  to keep a second copy away from it. Also useful for a portable install, or two radios
+  kept apart.
+
 ## [0.2.1] — 2026-09-07
 
 ### Fixed
@@ -83,6 +218,9 @@ deliberately not reconstructed here.
 - Two `TYPE_CHECKING` imports the test suite referenced but never imported, on paths that
   happened never to run.
 
-[Unreleased]: https://github.com/jpmartineau/MeshTerm/compare/v0.2.1...HEAD
+[Unreleased]: https://github.com/jpmartineau/MeshTerm/compare/v0.2.4...HEAD
+[0.2.4]: https://github.com/jpmartineau/MeshTerm/releases/tag/v0.2.4
+[0.2.3]: https://github.com/jpmartineau/MeshTerm/releases/tag/v0.2.3
+[0.2.2]: https://github.com/jpmartineau/MeshTerm/releases/tag/v0.2.2
 [0.2.1]: https://github.com/jpmartineau/MeshTerm/releases/tag/v0.2.1
 [0.2.0]: https://github.com/jpmartineau/MeshTerm/tree/v0.2.0

NOTICE

@@ -22,3 +22,12 @@ project and its original author. A fork that keeps soliciting
 donations through that link, or through a lookalike of it, without
 clearly redirecting them to itself, is not affiliated with this
 project and is not authorized to do so.
+
+--------------------------------------------------------------------------------
+
+Bundled font: meshterm/assets/fonts/CascadiaMonoPL.ttf is Cascadia Mono PL,
+Copyright (c) 2019 - Present, Microsoft Corporation, with Reserved Font Name
+Cascadia Code. It is redistributed here unmodified under the SIL Open Font
+License, Version 1.1, which is included beside it as CascadiaMono-OFL.txt and
+is its only license -- the Apache License above does not apply to it. The
+inclusion of this font does not imply that Microsoft endorses MeshTerm.

README.md

@@ -58,22 +58,79 @@ your mesh's history is worth.
 ### Download a build
 
 **[⬇ Latest release](https://github.com/jpmartineau/MeshTerm/releases/latest)** — one file,
-no Python needed. Windows, macOS (Apple silicon) and Linux (x64 and ARM64, so the uConsole
-is covered).
+no Python needed. Windows, macOS (Intel and Apple silicon), and Linux (x64 and ARM64, so
+the uConsole is covered).
 
-Download it, make it runnable, and run it:
+MeshTerm is a terminal program, so **open a terminal and run it from there.** You can
+double-click it and it will work, but you'll get whatever console your system picks, and
+if anything goes wrong at startup the window closes before you can read why.
 
-```bash
-chmod +x meshterm-*            # macOS and Linux only
-./meshterm-*
+**Windows** — open Windows Terminal or PowerShell, `cd` to your downloads, then:
+
+```powershell
+.\meshterm-0.2.5-windows-x64.exe
 ```
 
-> **Your system will complain the first time.** These builds aren't code-signed — signing
-> costs money on both platforms and this is a free side project. macOS says *"cannot be
-> opened because the developer cannot be verified"*; clear it with
-> `xattr -d com.apple.quarantine meshterm-*` and run it again. Windows shows *"Windows
-> protected your PC"*; click **More info → Run anyway**. Each release ships a `SHA256SUMS`
-> file if you'd rather check the download yourself.
+**macOS and Linux** — open Terminal, `cd` to your downloads, then:
+
+```bash
+chmod +x meshterm-0.2.5-*
+./meshterm-0.2.5-*
+```
+
+### A word about terminals, on Windows
+
+MeshTerm is drawn with emoji icons, braille charts and powerline path chips. Whether you
+see them is up to your *terminal*, not really your font: a modern terminal, asked for a
+character its font doesn't have, quietly borrows it from another font on the machine.
+That's why the app looks right in Windows Terminal, in VS Code's terminal, and on macOS
+and Linux — usually with a font that contains almost none of it.
+
+The classic Windows console — the black `cmd.exe` window you get from a double-click —
+doesn't borrow. It draws what its one font holds and empty boxes for everything else, and
+no font fixes the icons there: the only two fonts on a Windows machine with emoji in them
+are proportional, and a console won't take a proportional font.
+
+So when MeshTerm lands in that console it offers to move: **reopen in Windows Terminal**,
+one keypress, nothing installed and nothing changed. That's the whole app, exactly as the
+screenshots show it. Windows Terminal is already on every Windows 11 machine and is a free
+install on Windows 10.
+
+Stay in the classic console and MeshTerm offers the next best thing instead — the charts
+and marks, without the icons. It ships
+[Cascadia Mono PL](https://github.com/microsoft/cascadia-code), Microsoft's own console
+font and one of the very few monospace faces that carries braille at all, and will install
+it just for you: no administrator rights, nothing downloaded. If you already have Cascadia
+it simply switches to it.
+
+You can decline both and MeshTerm still runs. Preferences → Display → Console setup is
+where you change your mind.
+
+Rename it to something you don't mind typing and put it somewhere on your `PATH`, and it
+becomes just `meshterm` from anywhere.
+
+> **Your system will complain the first time, and it's right to.** These builds aren't
+> code-signed — signing costs real money on both platforms and this is a free side
+> project.
+>
+> - **macOS**: *"cannot be opened because the developer cannot be verified"*. Clear it with
+>   `xattr -d com.apple.quarantine meshterm-0.2.5-*` and run it again.
+> - **Windows**: *"Windows protected your PC"*. Click **More info → Run anyway**.
+>
+> Every release ships a `SHA256SUMS` file if you'd rather check the download first.
+
+> **Trying a build without touching your real data.** MeshTerm keeps everything in
+> `~/.meshterm` — your history database, contacts, channel keys — and *every* copy of
+> MeshTerm uses that same folder. Set `MESHTERM_HOME` to try one in isolation:
+>
+> ```bash
+> MESHTERM_HOME=~/meshterm-test ./meshterm-0.2.5-*      # macOS, Linux
+> ```
+> ```powershell
+> $env:MESHTERM_HOME = "$HOME\meshterm-test"; .\meshterm-0.2.5-windows-x64.exe
+> ```
+>
+> Same variable if you run two radios and want them kept apart.
 
 ### Or install with pip
 
@@ -357,6 +414,15 @@ tiles by [OpenFreeMap](https://openfreemap.org/). OpenStreetMap data is availabl
 with a small built-in reader for the [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec)
 format.
 
+### Bundled font
+
+MeshTerm ships **Cascadia Mono PL**, © 2019–present Microsoft Corporation, redistributed
+unmodified under the [SIL Open Font License 1.1](meshterm/assets/fonts/CascadiaMono-OFL.txt).
+It's offered to Windows users whose console can't draw the charts — see
+[A word about fonts](#a-word-about-fonts). Microsoft doesn't endorse MeshTerm; the font is
+simply the right tool, being one of the very few monospace faces that carries the braille
+block the timelines are drawn from.
+
 ### Open-source dependencies
 
 MeshTerm is built with these libraries; each is used under its own license (see the
@@ -385,3 +451,9 @@ license (see [NOTICE](NOTICE)); a redistributed fork should go by its own name.
 donate link built into the app supports this project and its original author —
 forks that keep soliciting through it without redirecting it to themselves aren't
 affiliated with this project.
+
+The bundled font is **not** covered by that license. `meshterm/assets/fonts/CascadiaMonoPL.ttf`
+is Microsoft's Cascadia Mono PL, redistributed unmodified under the SIL Open Font License
+1.1, which travels with it as
+[CascadiaMono-OFL.txt](meshterm/assets/fonts/CascadiaMono-OFL.txt) and stays its only
+license.

meshterm/__init__.py

@@ -5,7 +5,7 @@ Supports USB, Bluetooth and TCP companion connection. For Windows, macOS and Lin
 
 from datetime import datetime
 
-__version__ = "0.2.1"
+__version__ = "0.2.5"
 __author__ = "Jean-Pierre Martineau"
 
 #: The year MeshTerm was first published; the copyright span starts here.

meshterm/assets/fonts/CascadiaMono-OFL.txt

@@ -0,0 +1,94 @@
+Copyright (c) 2019 - Present, Microsoft Corporation,
+with Reserved Font Name Cascadia Code.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

meshterm/cli.py

@@ -10,23 +10,28 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import sys
 from pathlib import Path
 
 import typer
+from rich.console import Console
 
 from .context import AppContext
+from .core import win32dll
 from .core.admin_store import AdminStore
 from .core.config import Settings
 from .core.connection import DeviceCommandError, is_connection_lost
 from .core.device_config import DeviceConfigError
 from .core.device_store import DeviceStore
-from .core.preferences import PreferenceError
+from .core.instancelock import InstanceBusy, hold_instance_lock
+from .core.preferences import PreferenceError, Preferences
 from .core.selection import DeviceSelectionError
-from .persistence.logging import configure_logging
+from .persistence.logging import configure_logging, get_logger, level_from_name, log_path
 from .persistence.repository import Repository
-from .platforms import Resolution, resolve, set_platform
+from .platforms import Resolution, resolve, set_platform, without_emoji
 from .tools import all_tools
 from .tools.base import Tool, ToolResult
+from .ui.termfont import emoji_support
 from .ui.theme import make_console
 
 
@@ -134,16 +139,33 @@ def main_callback(
         _platform_resolution = resolve(platform)
     except ValueError as exc:
         raise typer.BadParameter(str(exc), param_hint="--platform") from exc
-    set_platform(_platform_resolution.platform)
+    # A terminal that cannot draw emoji is asked about here rather than in resolve(),
+    # which answers "which flavour" from the flag, the env and the device tree and should
+    # stay that pure — this is the *terminal's* limit, and it applies whichever flavour
+    # those three chose. See meshterm.ui.termfont.emoji_support.
+    active = _platform_resolution.platform
+    if not emoji_support().supported:
+        active = without_emoji(active)
+    set_platform(active)
 
     settings = Settings.load()
     if db_path is not None:
         settings.db_path = db_path
 
     console = make_console()
-    configure_logging(console, settings.config_dir, level=logging.INFO, quiet=quiet or json_output)
+    # Loaded before logging is configured, because how much goes in the file is one of
+    # them — and handed to the context afterwards so the file is not read twice.
+    prefs = Preferences.load(settings.config_dir / "preferences.yaml")
+    configure_logging(
+        console,
+        settings.config_dir,
+        level=logging.INFO,
+        file_level=level_from_name(prefs.log_level),
+        quiet=quiet or json_output,
+    )
 
     app_ctx = AppContext(
+        preferences=prefs,
         console=console,
         settings=settings,
         repo=Repository(settings.db_path),
@@ -166,7 +188,249 @@ def main_callback(
     if ctx.invoked_subcommand is None:
         from .ui.menu import run_menu
 
-        asyncio.run(_drive(run_menu(app_ctx), app_ctx))
+        # Before prompt_toolkit takes the screen: this can change the console's own font,
+        # or hand the whole session to a better terminal, and the full-screen frame should
+        # be drawn once, in whatever it ends up in.
+        if _offer_a_console_that_can_draw_meshterm(console, prefs):
+            return
+
+        # The interactive session is the one that holds the stores in memory and rewrites
+        # them whole, so it is the one that claims the directory. One-shot subcommands are
+        # brief and mostly read; blocking `meshterm contacts` because a menu is open in
+        # another window would be an obstacle rather than a guard.
+        try:
+            with hold_instance_lock(settings.config_dir):
+                asyncio.run(_drive(run_menu(app_ctx), app_ctx))
+        except InstanceBusy as exc:
+            console.print(f"[err]✗[/err] {exc}")
+            raise typer.Exit(code=1) from None
+        except Exception as exc:
+            if type(exc).__name__ == "NoConsoleScreenBufferError":
+                # prompt_toolkit needs a real Win32 console and reports its absence in the
+                # language of its own internals. A traceback reads as "this app is broken"
+                # when the answer is "open a different terminal", so answer that instead.
+                get_logger().warning("no Windows console available: %s", exc)
+                _report_no_windows_console(console)
+                raise typer.Exit(code=1) from None
+            # Logged before it is re-raised, and this is the case the log matters most for:
+            # a session launched by double-clicking the executable owns its console window,
+            # so when it dies the window closes with it and takes the traceback along. The
+            # file is the only thing left to read afterwards.
+            get_logger().exception("the interactive session raised an unhandled error")
+            _report_log_location(console, settings.config_dir)
+            raise
+
+
+def _offer_a_console_that_can_draw_meshterm(console: Console, prefs: Preferences) -> bool:
+    """On the classic Windows console, offer the reader something better than it.
+
+    Two offers, in the order of how much they buy. **Windows Terminal** first, because it
+    is the only one that gets the whole app: emoji icons included, which no font can put
+    on the classic console — the only Windows fonts carrying emoji are proportional, and
+    a console will not take one. Then, for a reader who stays, **a font** that can at
+    least draw the charts and the marks.
+
+    Args:
+        console: The console to ask on.
+        prefs: The preference set, read for a previous refusal and written on a new one.
+
+    Returns:
+        ``True`` when the session is being reopened elsewhere and this one should stop.
+    """
+    from .ui.termfont import classic_console
+
+    if not classic_console() or prefs.get("console_setup") == "off":
+        return False
+    if _offer_windows_terminal(console):
+        return True
+    _offer_a_font_this_console_can_draw(console, prefs)
+    return False
+
+
+def _offer_windows_terminal(console: Console) -> bool:
+    """Offer to reopen the session in Windows Terminal, where the app looks like itself.
+
+    Asked with yes as the default, which is not how the font offer is asked: this one
+    changes nothing on the machine — no install, no setting, one new window — and it is
+    the only answer that gets the reader the app as it was drawn.
+
+    Args:
+        console: The console to ask on.
+
+    Returns:
+        Whether Windows Terminal was started and this session should stand down.
+    """
+    from .core import winterminal
+
+    if winterminal.available() is None:
+        return False
+
+    console.print()
+    console.print("[accent]•[/accent]  This is the classic Windows console, and it can only")
+    console.print("   draw part of MeshTerm — no icons, and no charts.")
+    console.print()
+    console.print("   [accent]Windows Terminal[/accent] draws all of it, and you have it.")
+    console.print("   MeshTerm can reopen itself there now. Nothing is installed")
+    console.print("   and nothing is changed; it is just a better window.")
+    console.print()
+    if not _asks_yes(console, "   Reopen in Windows Terminal? [Y/n] ", default=True):
+        return False
+    if winterminal.reopen():
+        console.print("[ok]✓[/ok]  Reopening in Windows Terminal.")
+        get_logger().info("reopened the session in Windows Terminal")
+        return True
+    console.print("[warn]⚠[/warn]  Windows Terminal would not start. Staying here.")
+    get_logger().warning("could not start Windows Terminal")
+    return False
+
+
+def _offer_a_font_this_console_can_draw(console: Console, prefs: Preferences) -> None:
+    """Offer a font that can at least draw the charts and marks, for a reader who stays.
+
+    The console does no font fallback: whatever its font lacks is a box, and its default
+    — Consolas, or Lucida Console under Windows PowerShell — lacks most of what MeshTerm
+    is drawn with, including every one of the 44 braille cells the timelines are made of.
+
+    Two shapes, depending on what is already there: a machine with Windows Terminal (and
+    every Windows 11 machine) already has Cascadia, so the offer is only to *use* it; a
+    bare Windows 10 gets the offer to install the copy MeshTerm ships.
+
+    Declining is answered with a plain description of what declining looks like, and then
+    asked once more — a reader who has never seen the app has no way to know what "some
+    glyphs may not render" is going to mean. A second decline is remembered, in the
+    ``console_setup`` preference, so the question is asked twice in total and never again.
+
+    Args:
+        console: The console to ask on.
+        prefs: The preference set, read for a previous refusal and written on a new one.
+    """
+    from .core import consolefont
+    from .ui.termfont import face_draws_charts, installed_chart_font
+
+    if face_draws_charts(consolefont.current_face()):
+        return
+
+    installed = installed_chart_font()
+    for asking_again in (False, True):
+        if asking_again:
+            console.print()
+            console.print("[warn]⚠[/warn]  Then MeshTerm is going to look wrong here.")
+            console.print()
+            console.print("   Every chart — the signal timelines, the activity graphs — is")
+            console.print("   drawn from braille characters this console's font does not")
+            console.print("   have, so they will come out as rows of empty boxes. So will")
+            console.print("   the ✓ and ✗ marks, and the ★ on the map.")
+            console.print()
+            console.print("   Nothing is broken and nothing is lost — the app works, and")
+            console.print("   this is only about what the font can draw. It is your")
+            console.print("   console, so it is your call.")
+            console.print()
+        elif installed:
+            console.print()
+            console.print("[accent]•[/accent]  This console's font can't draw MeshTerm's charts.")
+            console.print(f"   You already have [accent]{installed}[/accent], which can.")
+            console.print()
+        else:
+            console.print()
+            console.print("[accent]•[/accent]  This console's font can't draw MeshTerm's charts.")
+            console.print("   MeshTerm ships [accent]Cascadia Mono PL[/accent] — Microsoft's")
+            console.print("   console font — and can install it just for you. No")
+            console.print("   administrator rights, nothing downloaded, 723 KB.")
+            console.print()
+
+        verb = "Use it" if installed else "Install and use it"
+        if _asks_yes(console, f"   {verb}? [y/N] "):
+            _use_a_better_console_font(console, installed)
+            return
+
+    prefs.set("console_setup", "off")
+    try:
+        prefs.save()
+    except (OSError, RuntimeError) as exc:  # a read-only config dir is not fatal here
+        get_logger().warning("could not remember the console setup choice: %s", exc)
+    console.print()
+    console.print("[muted]   Leaving it as it is. Change your mind on the Preferences[/muted]")
+    console.print("[muted]   page, under Display → Console setup.[/muted]")
+    console.print()
+
+
+def _use_a_better_console_font(console: Console, installed: str | None) -> None:
+    """Install (when needed) and select the font, and say plainly what happened."""
+    from .core import consolefont
+
+    face = installed
+    if face is None:
+        if not consolefont.install_bundled_font():
+            console.print("[err]✗[/err]  The font could not be installed. Leaving the")
+            console.print("   console as it is.")
+            get_logger().warning("bundled console font could not be installed")
+            return
+        face = consolefont.BUNDLED_FACE
+
+    if consolefont.use(face):
+        console.print(f"[ok]✓[/ok]  Now drawing with [accent]{face}[/accent].")
+        get_logger().info("console font set to %s", face)
+    else:
+        # Installed but not selected: the font is there for next time and for the
+        # console's own properties dialog, which is worth saying rather than swallowing.
+        console.print(f"[warn]⚠[/warn]  {face} is installed, but this console kept its own")
+        console.print("   font. It will be available the next time you open one.")
+        get_logger().warning("console refused the font %s", face)
+
+
+def _asks_yes(console: Console, prompt: str, *, default: bool = False) -> bool:
+    """Ask a yes/no question on the console.
+
+    Not a TUI dialog: this runs before prompt_toolkit owns the screen, alongside the other
+    plain-console reports here. An unanswerable prompt — no stdin, a closed pipe — takes
+    the default, and each caller's default is the answer that costs the reader least.
+
+    Args:
+        console: The console to ask on.
+        prompt: The question, ending in its own spacing.
+        default: The answer an empty line means, and the one an unreadable stdin takes.
+
+    Returns:
+        Whether the reader said yes.
+    """
+    console.print(prompt, end="")
+    try:
+        answer = input().strip().lower()
+    except (EOFError, KeyboardInterrupt, OSError):
+        console.print()
+        return default
+    if not answer:
+        return default
+    return answer in {"y", "yes"}
+
+
+def _report_log_location(console: Console, config_dir: Path) -> None:
+    """Point at the log after a fault, since it is the copy that outlives the terminal."""
+    console.print()
+    console.print(f"[muted]The details are in {log_path(config_dir)}[/muted]")
+    console.print("[muted]Attach it to a bug report. For more detail next time, raise[/muted]")
+    console.print("[muted]'Log detail' on the Preferences page.[/muted]")
+
+
+def _report_no_windows_console(console: Console) -> None:
+    """Explain a console MeshTerm cannot draw in, and how to get one it can.
+
+    Reached when prompt_toolkit finds no Win32 console screen buffer: a Git Bash, MSYS or
+    Cygwin shell — which announce themselves as ``xterm`` and are not Windows consoles at
+    all — or a process whose output has been redirected away from one.
+    """
+    console.print("[err]✗[/err] MeshTerm needs a Windows console, and could not find one.")
+    console.print()
+    console.print("That usually means one of two things:")
+    console.print()
+    console.print("  • You are in Git Bash, MSYS or Cygwin. Those are not Windows consoles.")
+    console.print("    Open [accent]Windows Terminal[/accent] or [accent]PowerShell[/accent]")
+    console.print("    and run it from there.")
+    console.print("  • The output is piped or redirected somewhere. The full-screen menu")
+    console.print("    needs the terminal itself.")
+    console.print()
+    console.print("Every screen also has a subcommand, and those pipe fine —")
+    console.print("try [accent]meshterm --help[/accent].")
 
 
 @app.command(name="platform")
@@ -177,6 +441,10 @@ def platform_command() -> None:
     flavour a given invocation would run as, and why — the ``--platform``/
     ``MESHTERM_PLATFORM`` inputs, what ``/proc/device-tree/model`` reports (``None`` off
     the actual hardware), and which of those decided it.
+
+    It also reports the terminal's own emoji verdict, which is a separate question from
+    the flavour and the usual reason a Windows session looks plainer than the screenshots
+    (see :func:`meshterm.ui.termfont.emoji_support`).
     """
     assert _platform_resolution is not None  # set by the callback that always runs first
     r = _platform_resolution
@@ -186,6 +454,16 @@ def platform_command() -> None:
     console.print(f"  MESHTERM_PLATFORM:       {r.env or '(not set)'}")
     console.print(f"  /proc/device-tree/model: {r.detected_model or '(unavailable)'}")
 
+    emoji = emoji_support()
+    verdict = "yes" if emoji.supported else "no — icons use the compact glyphs"
+    console.print(f"icons:    [accent]{verdict}[/accent]  (source: {emoji.source})")
+    if not emoji.supported and emoji.source == "console":
+        console.print(
+            "  this is the classic Windows console, which draws no emoji whatever font\n"
+            "  it is set to. Windows Terminal and VS Code's terminal both do — running\n"
+            "  MeshTerm in one gets the icons back. MESHTERM_EMOJI=1 overrides this."
+        )
+
 
 @app.command(name="specimen")
 def specimen_command() -> None:
@@ -218,20 +496,30 @@ def run_tool_command(tool: Tool, params: dict) -> None:
         asyncio.run(_drive(_execute_and_render(tool, params, _state), _state))
     except (DeviceSelectionError, DeviceConfigError, DeviceCommandError, PreferenceError) as exc:
         # Expected user-facing error (ambiguous/absent device, a bad config or preference
-        # value, or a transient command failure): show the message, not a traceback.
+        # value, or a transient command failure): show the message, not a traceback. Logged
+        # at warning because it is a thing that went wrong, even though it is an ordinary
+        # one — a log that only holds crashes cannot answer "what happened before it".
+        get_logger().warning("%s failed: %s", tool.name, exc)
         _state.console.print(f"[err]✗[/err] {exc}")
         raise typer.Exit(1) from exc
     except Exception as exc:
         # A dropped serial link (device unplugged/powered off mid-command) can't be recovered
         # from in a one-shot scripted run the way the interactive menu offers — but it should
-        # still read as a clean message, not a traceback. Anything else propagates as before.
-        if not is_connection_lost(exc):
-            raise
-        _state.console.print(
-            "[err]✗[/err] the connection to your device was lost "
-            "(it may have been unplugged or powered off)."
-        )
-        raise typer.Exit(1) from exc
+        # still read as a clean message, not a traceback.
+        if is_connection_lost(exc):
+            get_logger().warning("%s lost the device connection: %s", tool.name, exc)
+            _state.console.print(
+                "[err]✗[/err] the connection to your device was lost "
+                "(it may have been unplugged or powered off)."
+            )
+            raise typer.Exit(1) from exc
+        # Anything else is a real fault. It still reaches the terminal as a traceback,
+        # because a person looking at one wants to see it — but it also lands in the log,
+        # which is the copy that survives the terminal being closed and is the one thing
+        # worth attaching to a bug report.
+        get_logger().exception("%s raised an unhandled error", tool.name)
+        _report_log_location(_state.console, _state.settings.config_dir)
+        raise
 
 
 async def _drive(coro, ctx: AppContext) -> None:
@@ -280,9 +568,59 @@ def _register_all() -> None:
 _register_all()
 
 
+def _owns_its_console() -> bool:
+    """Whether this process is the only one on its console — i.e. it was double-clicked.
+
+    Windows gives a console to a process launched from Explorer and destroys it the moment
+    that process ends, so an error message is displayed and erased in the same instant.
+    Launched from a shell instead, the console belongs to the shell and survives.
+
+    ``GetConsoleProcessList`` tells the two apart: it reports how many processes are
+    attached to this console. One is us, alone, holding a window that dies with us.
+
+    Returns:
+        ``True`` only on Windows, and only when nothing else shares the console.
+    """
+    if sys.platform != "win32":
+        return False
+    try:
+        import ctypes
+
+        buffer = (ctypes.c_uint * 4)()
+        count = win32dll.kernel32().GetConsoleProcessList(buffer, 4)
+    except Exception:  # pragma: no cover - no console at all, or a stubbed kernel32
+        return False
+    return count == 1
+
+
 def main() -> None:
-    """Console-script entry point."""
-    app()
+    """Console-script entry point.
+
+    Holds the window open after a failure when MeshTerm owns it, because otherwise the
+    error is drawn and destroyed together and the person who needs to read it sees a
+    flash. Only on that path: a successful run should not make anyone press a key, and a
+    run from a shell leaves its output on the screen anyway.
+    """
+    try:
+        app()
+    except SystemExit as exit_request:
+        if exit_request.code and _owns_its_console():
+            _wait_before_the_window_closes()
+        raise
+    except BaseException:
+        if _owns_its_console():
+            _wait_before_the_window_closes()
+        raise
+
+
+def _wait_before_the_window_closes() -> None:
+    """Ask for a keypress so a message stays readable, and never fail doing it."""
+    try:
+        print()
+        print("-- Press Enter to close this window --")
+        input()
+    except Exception:  # pragma: no cover - stdin closed, redirected, or gone
+        pass
 
 
 if __name__ == "__main__":

meshterm/core/admin_store.py

@@ -14,11 +14,10 @@ a multi-user secret store; treat the file accordingly.
 from __future__ import annotations
 
 import json
-import os
-import stat
 from dataclasses import dataclass
 from pathlib import Path
 
+from .atomicwrite import write_atomically
 from .models import Contact, LoginResult, utcnow
 
 
@@ -139,11 +138,4 @@ class AdminStore:
 
     def _write(self, records: dict[str, dict]) -> None:
         """Persist ``records`` atomically with owner-only permissions where supported."""
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(records, indent=2), encoding="utf-8")
-        try:  # best-effort: not all platforms/filesystems honor chmod
-            os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
-        except OSError:  # pragma: no cover - platform-dependent
-            pass
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(records, indent=2), owner_only=True)

meshterm/core/advert_store.py

@@ -20,6 +20,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 
+from .atomicwrite import write_atomically
 from .models import utcnow
 
 #: The direct (zero-hop) cadence choices offered in the editor, in hours.
@@ -190,10 +191,7 @@ class AdvertStore:
 
     def _write(self, records: dict[str, dict]) -> None:
         """Persist ``records`` atomically (crash mid-write keeps the previous file)."""
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(records, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(records, indent=2))
 
 
 def _as_hours(value: object, default: int) -> int:

meshterm/core/atomicwrite.py

@@ -0,0 +1,54 @@
+"""THE way MeshTerm replaces a file it owns: all of the new contents, or none of them.
+
+Every store under ``core/`` keeps its state in one file that it rewrites whole. Writing
+in place means a crash — or a laptop lid closing — halfway through leaves a truncated
+file where a contact list used to be, so each write goes to a neighbouring temporary file
+first and lands with a single rename, which the filesystem either does or doesn't.
+
+The neighbouring file's name carries the writing process's id. That is not fussiness:
+MeshTerm's data directory is shared by every copy on the machine — a checkout, a
+downloaded build, a second instance for a second radio — and a fixed ``.tmp`` name means
+two of them writing at the same moment take turns clobbering one scratch file, then each
+rename whatever is in it over the real one. The rename is atomic; the thing being renamed
+was not. Per-process names make the two writes independent again, and the last rename
+simply wins, which is a lost update rather than a corrupted file.
+
+``MESHTERM_HOME`` is the way to avoid sharing the directory in the first place — see
+:func:`meshterm.core.config.default_config_dir`.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+from pathlib import Path
+
+__all__ = ["write_atomically"]
+
+
+def write_atomically(path: Path, text: str, *, owner_only: bool = False) -> None:
+    """Replace ``path`` with ``text`` in one step, creating parent directories as needed.
+
+    Args:
+        path: The file to replace. Its directory is created if it does not exist.
+        text: The complete new contents, written as UTF-8.
+        owner_only: Restrict the file to the owner (``0600``) before it is put in place,
+            for anything holding a credential. Applied to the temporary file rather than
+            the destination, so there is no moment where the real file exists with wider
+            permissions. Best-effort: not every platform or filesystem honours it.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(f"{path.suffix}.{os.getpid()}.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        if owner_only:
+            try:
+                os.chmod(tmp, stat.S_IRUSR | stat.S_IWUSR)
+            except OSError:  # pragma: no cover - platform-dependent
+                pass
+        tmp.replace(path)
+    except BaseException:
+        # A failed write leaves no litter behind. `missing_ok` because the failure may
+        # well have been the write that would have created it.
+        tmp.unlink(missing_ok=True)
+        raise

meshterm/core/channel_store.py

@@ -30,6 +30,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from .atomicwrite import write_atomically
 from .channels import (
     CHANNEL_SECRET_BYTES,
     CHANNEL_SLOT_EMPTY_RUN,
@@ -156,10 +157,7 @@ class ChannelStore:
                 if channels
             }
         }
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(data, indent=2))
 
 
 def _channel_from_json(entry: object) -> RememberedChannel | None:

meshterm/core/config.py

@@ -15,6 +15,7 @@ keys used to sit in this file with no screen behind them.
 
 from __future__ import annotations
 
+import os
 import sys
 from dataclasses import dataclass, field
 from pathlib import Path
@@ -26,15 +27,31 @@ else:  # pragma: no cover - exercised only on 3.10
     import tomli as tomllib
 
 
+#: Points MeshTerm's config and data somewhere other than the home directory. For trying a
+#: build without letting it near a real history, for a portable install on a stick, and for
+#: running two radios out of two directories. Read every time rather than cached, so a test
+#: can move it between cases.
+CONFIG_DIR_ENV = "MESHTERM_HOME"
+
+
 def default_config_dir() -> Path:
     """Return the directory MeshTerm uses for config and data.
 
-    Resolves to ``.meshterm`` under the OS-defined home directory (``%USERPROFILE%``
-    on Windows, ``$HOME`` on Unix), as reported by :meth:`Path.home`.
+    ``$MESHTERM_HOME`` wins if it is set and not empty. Otherwise this resolves to
+    ``.meshterm`` under the OS-defined home directory (``%USERPROFILE%`` on Windows,
+    ``$HOME`` on Unix), as reported by :meth:`Path.home`.
+
+    The override exists because the database is the valuable part of an install — a
+    running record of everything the radio has overheard — and there was no way to point a
+    second copy of MeshTerm at a different one. A downloaded build would happily open the
+    same 34MB file as the checkout it was built from.
 
     Returns:
         The resolved configuration directory path (not guaranteed to exist).
     """
+    override = os.environ.get(CONFIG_DIR_ENV, "").strip()
+    if override:
+        return Path(override).expanduser()
     return Path.home() / ".meshterm"
 
 

meshterm/core/consolefont.py

@@ -0,0 +1,254 @@
+r"""Installing and selecting a console font on Windows, for one user, without admin.
+
+The classic Windows console does no font fallback: a character its configured font lacks
+is drawn as a box, and nothing rescues it (see :func:`meshterm.ui.termfont.emoji_support`
+for the sibling problem). Its default font is Consolas, which carries 57 of the 122
+non-ASCII characters MeshTerm draws and *none* of the 44 braille cells the charts are
+made of. Windows PowerShell's classic console is worse still — its default, Lucida
+Console, drops even ``●``.
+
+So on that host MeshTerm offers to fix the font. Two Win32 facts make that possible
+without an installer and without administrator rights:
+
+* A font installs **for one user** by copying it under ``%LOCALAPPDATA%\Microsoft\
+  Windows\Fonts``, registering it under ``HKCU``, and telling the session about it with
+  ``AddFontResourceW`` plus a ``WM_FONTCHANGE`` broadcast. No elevation anywhere.
+* A console selects a font with ``SetCurrentConsoleFontEx``, which — verified on
+  Windows 10 22H2 — accepts a face the console's own properties dialog will not even
+  list. That dialog only offers what is registered under the machine-wide
+  ``Console\TrueTypeFont`` key (Lucida Console and Consolas here), so without this API
+  the user could install the font and still be unable to pick it.
+
+**A font install is one-way inside a session.** Once loaded, Windows locks the file: it
+cannot be deleted even by an elevated process, and even after the font cache service is
+restarted — it frees at the next logon. So nothing here offers to uninstall one, and the
+install is written to be safe to repeat rather than reversible.
+
+Everything is best-effort. A failure at any step leaves the app running with the font it
+already had, which is the state it would have been in anyway.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from . import win32dll
+
+#: Where the bundled font lives, found the way every other asset is (see
+#: :mod:`meshterm.ui.about`) so it keeps resolving inside a PyInstaller bundle.
+FONT_DIR = Path(__file__).resolve().parent.parent / "assets" / "fonts"
+
+#: The font MeshTerm ships and offers to install. Cascadia Mono PL is Microsoft's own
+#: console font, SIL OFL (licence beside it), and the ``PL`` build adds the powerline
+#: separators the path lines are drawn with — 723KB for 109 of our 122 characters, all 44
+#: braille cells and all 3 powerline glyphs, where the 2.4MB Nerd Font build covers no
+#: more. Practically every mainstream coder font — Hack, JetBrains Mono, Fira Code, Source
+#: Code Pro, even DejaVu Sans *Mono* — carries no braille at all; Cascadia and Iosevka are
+#: the exceptions, which is why this is not a matter of taste.
+BUNDLED_FONT = FONT_DIR / "CascadiaMonoPL.ttf"
+
+#: Its family name, as the ``name`` table spells it — what ``SetCurrentConsoleFontEx``
+#: and the ``HKCU`` registration must both be given, exactly.
+BUNDLED_FACE = "Cascadia Mono PL"
+
+_USER_FONTS = "Microsoft/Windows/Fonts"
+_FONT_REGISTRY = r"Software\Microsoft\Windows NT\CurrentVersion\Fonts"
+
+_HWND_BROADCAST = 0xFFFF
+_WM_FONTCHANGE = 0x001D
+_SMTO_ABORTIFHUNG = 0x0002
+
+#: ``FF_MODERN | TMPF_VECTOR | TMPF_TRUETYPE`` — what a console expects a TrueType face to
+#: declare. Passing 0 here makes the call succeed and quietly keep the old raster font.
+_FF_MODERN_TRUETYPE = 54
+
+
+def user_font_dir() -> Path:
+    r"""The per-user font folder — writable without admin, unlike ``C:\Windows\Fonts``."""
+    local = os.environ.get("LOCALAPPDATA") or str(Path.home() / "AppData" / "Local")
+    return Path(local) / _USER_FONTS
+
+
+def install_bundled_font() -> bool:
+    """Install the bundled font for this user, and make the session aware of it.
+
+    Safe to repeat: an already-installed copy is left alone rather than overwritten, both
+    because the file is locked once loaded and because there is nothing to gain.
+
+    Returns:
+        ``True`` when the font is installed and usable (including when it already was).
+    """
+    if sys.platform != "win32" or not BUNDLED_FONT.is_file():
+        return False
+    try:
+        import ctypes
+        import winreg
+
+        target = user_font_dir() / BUNDLED_FONT.name
+        if not target.exists():
+            target.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(BUNDLED_FONT, target)
+
+        if not _add_font_resource(target):
+            return False
+
+        # The registration is what survives a logout; AddFontResourceW alone lasts only
+        # as long as this session. Per-user entries hold the full path, machine-wide ones
+        # hold a bare filename — this is the per-user key, so the path goes in.
+        with winreg.CreateKeyEx(
+            winreg.HKEY_CURRENT_USER, _FONT_REGISTRY, 0, winreg.KEY_SET_VALUE
+        ) as key:
+            winreg.SetValueEx(key, f"{BUNDLED_FACE} (TrueType)", 0, winreg.REG_SZ, str(target))
+
+        # Tell everything already running that the font list changed. Timed out and
+        # allowed to abort on a hung window, because a broadcast that waits on every top
+        # level window is a good way to stall a startup path.
+        user32 = win32dll.user32()
+        user32.SendMessageTimeoutW(
+            _HWND_BROADCAST,
+            _WM_FONTCHANGE,
+            0,
+            0,
+            _SMTO_ABORTIFHUNG,
+            1000,
+            ctypes.byref(ctypes.c_ulong()),
+        )
+        return True
+    except Exception:  # pragma: no cover - an install that fails leaves the old font
+        return False
+
+
+def _add_font_resource(path: Path) -> bool:
+    """Make a font file usable by this process, without installing anything.
+
+    ``AddFontResourceW`` adds to the font table for the running process; the ``HKCU``
+    registration beside it is what makes the font permanent, and Windows reads that at the
+    *next logon*. Between those two facts sits the case this exists for: a second MeshTerm
+    launch in the same session finds its own registration and believes the font is ready,
+    when nothing has loaded it into this new process yet.
+
+    Args:
+        path: The font file, wherever it is.
+
+    Returns:
+        Whether at least one face was added.
+    """
+    if sys.platform != "win32" or not path.is_file():
+        return False
+    try:
+        import ctypes
+
+        gdi32 = ctypes.WinDLL("gdi32", use_last_error=True)
+        return bool(gdi32.AddFontResourceW(ctypes.c_wchar_p(str(path))))
+    except Exception:  # pragma: no cover - best effort, like everything else here
+        return False
+
+
+def use(face: str) -> bool:
+    """Draw this console with ``face``, loading our own copy first if that is what it is.
+
+    The plain :func:`select` is enough for a font the system installed — the Cascadia that
+    comes with Windows 11 or with Windows Terminal. It is *not* enough for the copy
+    MeshTerm installed itself in an earlier run of the same session: that one is registered
+    but not yet loaded (see :func:`_add_font_resource`), and selecting it silently keeps
+    the old font. So a refusal is retried once, after loading it.
+
+    Args:
+        face: The family to draw with.
+
+    Returns:
+        Whether the console is now drawing with ``face``.
+    """
+    if select(face):
+        return True
+    if face == BUNDLED_FACE and _add_font_resource(user_font_dir() / BUNDLED_FONT.name):
+        return select(face)
+    return False
+
+
+def current_face() -> str | None:
+    """The face this console is drawing with, or ``None`` off a console."""
+    return _console_font(None)
+
+
+def select(face: str) -> bool:
+    """Point this console at ``face``, and confirm it took.
+
+    The call reports success even where the console quietly kept the font it had, so the
+    answer here is a read-back rather than the return value.
+
+    Args:
+        face: The family name, spelled as the font's own ``name`` table spells it.
+
+    Returns:
+        Whether the console is now drawing with ``face``.
+    """
+    return _console_font(face) == face
+
+
+def _console_font(face: str | None) -> str | None:
+    """Read the console's font, first setting it to ``face`` when one is given.
+
+    One function for both because the struct, the handle and the failure modes are the
+    same, and because setting without reading back proves nothing.
+
+    Args:
+        face: The family to select, or ``None`` to only read.
+
+    Returns:
+        The face the console is drawing with afterwards, or ``None`` if it could not
+        be asked (no console, not Windows, a failed call).
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class _COORD(ctypes.Structure):
+            _fields_ = [("X", wintypes.SHORT), ("Y", wintypes.SHORT)]
+
+        class _CONSOLE_FONT_INFOEX(ctypes.Structure):
+            _fields_ = [
+                ("cbSize", wintypes.ULONG),
+                ("nFont", wintypes.DWORD),
+                ("dwFontSize", _COORD),
+                ("FontFamily", wintypes.UINT),
+                ("FontWeight", wintypes.UINT),
+                ("FaceName", ctypes.c_wchar * 32),
+            ]
+
+        kernel32 = win32dll.kernel32()
+        kernel32.GetStdHandle.argtypes = [wintypes.DWORD]
+        kernel32.GetStdHandle.restype = wintypes.HANDLE
+        for name in ("GetCurrentConsoleFontEx", "SetCurrentConsoleFontEx"):
+            fn = getattr(kernel32, name)
+            fn.argtypes = [wintypes.HANDLE, wintypes.BOOL, ctypes.POINTER(_CONSOLE_FONT_INFOEX)]
+            fn.restype = wintypes.BOOL
+
+        handle = kernel32.GetStdHandle(wintypes.DWORD(-11).value)  # STD_OUTPUT_HANDLE
+        info = _CONSOLE_FONT_INFOEX()
+        info.cbSize = ctypes.sizeof(_CONSOLE_FONT_INFOEX)
+        if not kernel32.GetCurrentConsoleFontEx(handle, False, ctypes.byref(info)):
+            return None
+
+        if face is not None:
+            # Keep the height the reader already chose and let the width follow the face;
+            # a console font is picked for legibility at a size, and changing that out
+            # from under someone is not what they agreed to.
+            info.FaceName = face[:31]
+            info.FontFamily = _FF_MODERN_TRUETYPE
+            info.dwFontSize = _COORD(0, info.dwFontSize.Y or 16)
+            info.FontWeight = 400
+            kernel32.SetCurrentConsoleFontEx(handle, False, ctypes.byref(info))
+            after = _CONSOLE_FONT_INFOEX()
+            after.cbSize = ctypes.sizeof(_CONSOLE_FONT_INFOEX)
+            if not kernel32.GetCurrentConsoleFontEx(handle, False, ctypes.byref(after)):
+                return None
+            return after.FaceName or None
+        return info.FaceName or None
+    except Exception:  # pragma: no cover - a probe that fails is an unknown, not a crash
+        return None

meshterm/core/contact_store.py

@@ -49,6 +49,7 @@ import json
 from dataclasses import dataclass
 from pathlib import Path
 
+from .atomicwrite import write_atomically
 from .models import Contact, advert_time
 
 
@@ -332,10 +333,7 @@ class ContactStore:
                 if contacts
             }
         }
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(data, indent=2))
 
 
 def _contact_to_json(contact: RememberedContact) -> dict:

meshterm/core/courier_store.py

@@ -19,6 +19,7 @@ from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 
+from .atomicwrite import write_atomically
 from .models import utcnow
 
 #: Message states: waiting in the outbox, landed, or abandoned after the retry budget.
@@ -253,10 +254,7 @@ class CourierStore:
                 for m in self._load()
             ],
         }
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(data, indent=2))
 
 
 def _as_int(value: object, default: int) -> int:

meshterm/core/device_store.py

@@ -19,6 +19,7 @@ import json
 from dataclasses import dataclass
 from pathlib import Path
 
+from .atomicwrite import write_atomically
 from .discovery import (
     TRANSPORT_BLE,
     TRANSPORT_SERIAL,
@@ -259,7 +260,4 @@ class DeviceStore:
             },
             "last": last,
         }
-        # Atomic-ish replace so a crash mid-write can't truncate the existing registry.
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(payload, indent=2))

meshterm/core/instancelock.py

@@ -0,0 +1,94 @@
+"""One interactive MeshTerm per data directory, and a clear answer when you want two.
+
+Every copy of MeshTerm on a machine reads and writes the same ``~/.meshterm`` — a
+checkout, a downloaded build, a second instance for a second radio. Nothing about how it
+was installed changes that. Two running at once will not corrupt anything (the database
+is in WAL mode and every file lands by rename) but each holds the JSON stores in memory
+and rewrites them whole, so the second one to save quietly discards the first one's
+changes. A lost contact is much harder to notice than a crash.
+
+So the interactive session takes an exclusive lock on the directory it is using, and a
+second one is turned away with the fix in the message: set ``MESHTERM_HOME``.
+
+The lock is held by the operating system rather than written down as a process id in a
+file. A pid file has to answer "is that process still alive?", the answer is different on
+every platform, and it is wrong after a reboot recycles the number — so a crash leaves a
+lock nobody can explain and everybody works around. An OS lock is released when the
+process ends, however it ends.
+
+One-shot CLI subcommands do not take it. They are brief, mostly read, and blocking
+``meshterm contacts`` because a menu is open elsewhere would be an obstacle rather than a
+guard.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from pathlib import Path
+
+__all__ = ["InstanceBusy", "LOCK_NAME", "hold_instance_lock"]
+
+#: The lock file, kept beside the data it guards. Empty; only the lock on it matters.
+LOCK_NAME = ".lock"
+
+
+class InstanceBusy(RuntimeError):
+    """Raised when another interactive MeshTerm already holds this data directory."""
+
+    def __init__(self, config_dir: Path) -> None:
+        """Build the message, which is mostly the way out of the situation."""
+        super().__init__(
+            f"Another MeshTerm is already using {config_dir}.\n\n"
+            "Two of them sharing one directory will quietly overwrite each other's\n"
+            "contacts and settings, so this one stopped instead.\n\n"
+            "To run a second one — a downloaded build beside your own, or a second\n"
+            "radio — give it a directory of its own:\n\n"
+            "    MESHTERM_HOME=~/meshterm-other meshterm\n"
+        )
+        self.config_dir = config_dir
+
+
+def _try_lock(handle) -> bool:
+    """Take an exclusive, non-blocking lock on an open file; ``False`` if someone has it."""
+    if sys.platform == "win32":
+        import msvcrt
+
+        try:
+            msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+        except OSError:
+            return False
+        return True
+
+    import fcntl
+
+    try:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+    except OSError:
+        return False
+    return True
+
+
+@contextmanager
+def hold_instance_lock(config_dir: Path) -> Iterator[None]:
+    """Hold ``config_dir`` for this process, releasing it however the process ends.
+
+    Args:
+        config_dir: The data directory to claim.
+
+    Raises:
+        InstanceBusy: Another interactive MeshTerm holds it.
+    """
+    config_dir.mkdir(parents=True, exist_ok=True)
+    path = config_dir / LOCK_NAME
+    handle = open(path, "a+b")  # noqa: SIM115 - closed in the finally below
+    try:
+        if not _try_lock(handle):
+            raise InstanceBusy(config_dir)
+        yield
+    finally:
+        # Closing releases the lock on every platform. The file itself stays: deleting it
+        # would race a second process that has already opened it and is about to lock,
+        # which is how one directory ends up handed to two of them.
+        handle.close()

meshterm/core/mute_store.py

@@ -23,6 +23,8 @@ from __future__ import annotations
 import json
 from pathlib import Path
 
+from .atomicwrite import write_atomically
+
 
 class MuteStore:
     """Reads and writes the set of channels whose notifications are muted, memory-first.
@@ -92,7 +94,4 @@ class MuteStore:
     def _save(self) -> None:
         """Persist the whole muted set atomically (a crash mid-write keeps the old file)."""
         data = {"muted": sorted(self._state)}
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(data, indent=2))

meshterm/core/preferences.py

@@ -42,6 +42,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
+from .atomicwrite import write_atomically
 from .watch_store import DEFAULT_SILENCE_HOURS, OFF, SILENCE_CHOICES_H
 
 #: Display groups, in the order the page and the file present them. The order is the
@@ -56,6 +57,7 @@ GROUPS: tuple[str, ...] = (
     "Map",
     "History",
     "Display",
+    "Diagnostics",
 )
 
 
@@ -123,6 +125,24 @@ _WIDTH_CHOICES: dict[str, str] = {"auto": "auto", "yes": "yes", "no": "no"}
 #: Every preference MeshTerm has, in page order. Adding one here gives it a row on the
 #: Preferences page, a key in the YAML file, a ``preferences get``/``set`` CLI face, and a
 #: default — nothing else has to follow.
+#: What the log file keeps. The plain level names, which are what every other tool calls
+#: these — someone being talked through a problem is being told "set it to debug", not
+#: "set it to everything".
+#: What MeshTerm may offer when it lands in a console that cannot draw it. Only ever
+#: consulted on the classic Windows console, the one host with no font fallback of its own.
+_CONSOLE_SETUP_CHOICES: dict[str, str] = {
+    "ask": "Ask",
+    "off": "Leave it alone",
+}
+
+_LOG_LEVEL_CHOICES: dict[str, str] = {
+    "ERROR": "Error",
+    "WARNING": "Warning",
+    "INFO": "Info",
+    "DEBUG": "Debug",
+}
+
+
 PREFERENCES: tuple[PrefSpec, ...] = (
     # --- Sending -----------------------------------------------------------------
     PrefSpec(
@@ -282,6 +302,32 @@ PREFERENCES: tuple[PrefSpec, ...] = (
         default="auto",
         choices=_WIDTH_CHOICES,
     ),
+    PrefSpec(
+        key="console_setup",
+        label="Console setup",
+        help="Offer a better terminal or font when this console can't draw MeshTerm",
+        group="Display",
+        value_type="enum",
+        # "ask", not "always": changing the font of a window someone else opened is not
+        # ours to do unasked. Declining twice writes "off" here, which is how the offer
+        # stops being made rather than being made every launch.
+        default="ask",
+        choices=_CONSOLE_SETUP_CHOICES,
+    ),
+    # --- Diagnostics ---------------------------------------------------------------
+    PrefSpec(
+        key="log_level",
+        label="Log detail",
+        help="How much MeshTerm writes to its log file",
+        group="Diagnostics",
+        value_type="enum",
+        # Problems, not a narration of a working session. The file used to take
+        # everything, which buried the dozen interesting lines under twenty thousand
+        # dull ones and made it awkward to attach to a bug report.
+        default="WARNING",
+        choices=_LOG_LEVEL_CHOICES,
+        relaunch=True,
+    ),
 )
 
 _BY_KEY: dict[str, PrefSpec] = {spec.key: spec for spec in PREFERENCES}
@@ -602,10 +648,7 @@ class Preferences:
         """
         if self._path is None:
             raise RuntimeError("these preferences have no file to save to")
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(self.as_yaml(), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, self.as_yaml())
 
 
 #: The set installed for this process. Starts as a defaults-only, file-less instance so

meshterm/core/remote_store.py

@@ -17,6 +17,7 @@ from datetime import datetime
 from pathlib import Path
 
 from .admin_store import admin_key
+from .atomicwrite import write_atomically
 from .models import Contact, utcnow
 
 #: How many command-line entries are kept per node (newest last).
@@ -109,7 +110,4 @@ class RemoteStore:
 
     def _write(self, records: dict[str, dict]) -> None:
         """Persist ``records`` atomically (crash mid-write keeps the previous file)."""
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(records, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(records, indent=2))

meshterm/core/settings_store.py

@@ -32,6 +32,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from .atomicwrite import write_atomically
 from .device_config import DeviceConfigError, format_value, get_spec, parse_value
 
 if TYPE_CHECKING:
@@ -147,10 +148,7 @@ class SettingsStore:
                 if values
             }
         }
-        self._path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = self._path.with_suffix(self._path.suffix + ".tmp")
-        tmp.write_text(json.dumps(data, indent=2), encoding="utf-8")
-        tmp.replace(self._path)
+        write_atomically(self._path, json.dumps(data, indent=2))
 
 
 @dataclass(frozen=True)

meshterm/core/win32dll.py

@@ -0,0 +1,64 @@
+"""Private handles on the Windows DLLs, because ``ctypes.windll`` is shared with everyone.
+
+``ctypes.windll.kernel32`` is a cache. Every caller in the process gets the *same*
+``WinDLL`` object, and each function on it is a cached attribute — so
+``ctypes.windll.kernel32.GetConsoleScreenBufferInfo`` is one object, shared by this
+application and every library inside it. Setting ``.argtypes`` on it is not configuration,
+it is a process-wide mutation, and the last writer wins.
+
+That is not theoretical. It crashed MeshTerm on Windows:
+
+* ``ui/tui/emoji_width.py`` measured an emoji by asking the console for its cursor
+  position, and declared ``GetConsoleScreenBufferInfo`` as taking a pointer to *its* copy
+  of the screen-buffer struct.
+* prompt_toolkit later called the very same function object with a pointer to *its* copy
+  of the same struct — identical layout, different class.
+* ctypes compared the two classes, found them unequal, and refused:
+  ``expected LP__CSBI instance instead of pointer to CONSOLE_SCREEN_BUFFER_INFO``.
+
+The application died while building its screen, which on a double-clicked build meant the
+traceback and the window it was drawn in disappeared together.
+
+Constructing ``WinDLL`` directly builds a *new* object with its own function cache, so
+declarations made on it are visible only to the caller that made them. Each call here
+returns a fresh one: two parts of MeshTerm declaring the same function differently is the
+same bug in miniature, and the cost is one small object at a call site that runs rarely.
+
+The rule this exists to enforce: **nothing in MeshTerm touches ``ctypes.windll``.**
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+
+__all__ = ["kernel32", "user32"]
+
+
+def _library(name: str) -> ctypes.WinDLL:
+    """Load ``name`` into a WinDLL of our own.
+
+    Args:
+        name: The DLL to load, without its extension.
+
+    Returns:
+        A private handle whose function signatures nobody else can see or change.
+
+    Raises:
+        RuntimeError: If called anywhere but Windows, where these do not exist.
+    """
+    if sys.platform != "win32":  # pragma: no cover - the callers all guard on platform
+        raise RuntimeError(f"{name} is a Windows library")
+    # `use_last_error` keeps GetLastError intact for the caller, which is the only way to
+    # tell "the call failed" from "the call succeeded and returned zero".
+    return ctypes.WinDLL(name, use_last_error=True)
+
+
+def kernel32() -> ctypes.WinDLL:
+    """A private handle on ``kernel32`` — console, handles, memory."""
+    return _library("kernel32")
+
+
+def user32() -> ctypes.WinDLL:
+    """A private handle on ``user32`` — clipboard, keyboard state, windows."""
+    return _library("user32")

meshterm/core/winterminal.py

@@ -0,0 +1,90 @@
+"""Reopening the session in Windows Terminal, which is where MeshTerm looks like itself.
+
+MeshTerm is drawn with emoji icons, braille charts and powerline path chips. Whether any
+of that reaches the screen is decided by the *terminal*, not by MeshTerm and not really by
+the font either: a modern terminal, asked for a character its font lacks, quietly borrows
+the glyph from another font on the machine. That is why the app looks right in Windows
+Terminal, in VS Code's terminal, and on macOS and Linux — and why it looks right there
+even though the font the reader chose usually holds almost none of it. Measured on a
+development machine, the everyday choices — Hack Nerd Font, JetBrains Mono, Fira Code,
+Source Code Pro — carry no braille at all, and no monospace font anywhere carries emoji.
+
+The classic Windows console does not do that. It draws what its one font holds and boxes
+for the rest, so on that host the emoji cannot be shown *at all* — the only two fonts on a
+Windows machine with emoji glyphs, Segoe UI Emoji and Segoe UI Symbol, are proportional,
+and a console will not take a proportional font. No font choice fixes it, which leaves
+exactly one thing that does: a different terminal.
+
+So when MeshTerm finds itself in that console and Windows Terminal is installed — it is on
+every Windows 11 machine, and a free install on 10 — it offers to reopen itself there.
+One keypress, and the app looks the way it was drawn instead of the way conhost can
+manage. Declining falls back to :mod:`meshterm.core.consolefont`, which makes the best of
+the console the reader chose to stay in.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+
+#: Set in the reopened session, so a relaunch can never chain into another one. Windows
+#: Terminal is not a classic console and so would not qualify anyway — this is the belt to
+#: that braces, and it costs one environment variable.
+REOPENED_ENV = "MESHTERM_REOPENED"
+
+
+def available() -> str | None:
+    """The path to ``wt.exe``, or ``None`` when Windows Terminal is not installed.
+
+    Found on ``PATH``, where Windows puts an execution alias for it under
+    ``%LOCALAPPDATA%/Microsoft/WindowsApps``.
+    """
+    if sys.platform != "win32" or os.environ.get(REOPENED_ENV):
+        return None
+    return shutil.which("wt.exe")
+
+
+def own_command() -> list[str]:
+    """The command that would start this same session again.
+
+    A frozen build is its own executable and takes the arguments as they were given. A
+    development or ``pip`` install is reached through its interpreter, because the console
+    script's own path is not something ``wt`` can be relied on to resolve.
+
+    Returns:
+        The program and its arguments, ready to hand to Windows Terminal.
+    """
+    if getattr(sys, "frozen", False):
+        return [sys.executable, *sys.argv[1:]]
+    return [sys.executable, "-m", "meshterm", *sys.argv[1:]]
+
+
+def reopen() -> bool:
+    """Start this session again in Windows Terminal, in the same directory.
+
+    The new window is not a child in any meaningful sense — the caller exits immediately
+    afterwards and the two never talk — so nothing is waited on and no pipes are held.
+
+    Returns:
+        Whether Windows Terminal was started. ``False`` leaves the caller exactly where it
+        was, which is why the offer is only ever a detour and never a dead end.
+    """
+    terminal = available()
+    if terminal is None:
+        return False
+    environment = dict(os.environ, **{REOPENED_ENV: "1"})
+    try:
+        # `--` ends wt's own option parsing, so MeshTerm's flags reach MeshTerm rather
+        # than being read as Windows Terminal's (verified: `--mock` and `--profile x`
+        # arrive intact). `-d` keeps the working directory, which relative paths given
+        # on the command line depend on.
+        subprocess.Popen(  # noqa: S603 - the argv is ours, not the reader's
+            [terminal, "-d", os.getcwd(), "--", *own_command()],
+            env=environment,
+            close_fds=True,
+        )
+        return True
+    except OSError:
+        return False

meshterm/persistence/logging.py

@@ -1,13 +1,28 @@
-"""Structured logging setup.
+"""Logging setup: a plain text file you can open, and a console that stays out of the way.
 
-Two sinks are configured: a Rich-formatted console handler for human-readable output,
-and a JSON-lines file handler that captures every record for later replay/analysis.
+Two sinks. The console handler is Rich-formatted and shows what a person watching the
+terminal should see. The file handler writes ordinary log lines to
+``<config_dir>/meshterm.log`` — one record per line, timestamp, level, logger, message,
+with a traceback indented under the line that raised it.
+
+Plain text on purpose. The file used to be JSON Lines, on the theory that something might
+replay it; nothing ever did, and the one job it actually has is being opened by a person
+who has hit a problem — often the person reporting it, who then pastes the last twenty
+lines into an issue. That reader has a text editor, not a JSON parser.
+
+The file rotates. It used to be a single :class:`~logging.FileHandler`, which grows
+without limit: a real one reached 11MB over ten weeks, which is both a lot of disk on a
+handheld and an unreasonable thing to attach to a bug report.
+
+How much is written is a preference — ``log_level``, defaulting to ``WARNING``, so the
+file holds the problems rather than a narration of a working session. Turn it down to
+``INFO`` or ``DEBUG`` when chasing something.
 """
 
 from __future__ import annotations
 
-import json
 import logging
+from logging.handlers import RotatingFileHandler
 from pathlib import Path
 
 from rich.console import Console
@@ -15,28 +30,49 @@ from rich.logging import RichHandler
 
 _LOGGER_NAME = "meshterm"
 
+#: The log file, in the config directory beside the data it describes.
+LOG_FILENAME = "meshterm.log"
 
-class JsonlFormatter(logging.Formatter):
-    """Format log records as one JSON object per line."""
+#: Keep this much before rolling over, and this many rolled files. Roughly a fortnight of
+#: a chatty session at DEBUG, and small enough that the whole set can be attached to an
+#: issue without apology.
+_MAX_BYTES = 2 * 1024 * 1024
+_BACKUP_COUNT = 3
 
-    def format(self, record: logging.LogRecord) -> str:
-        """Serialize a log record to a compact JSON string.
+#: ``2026-09-07 14:23:11 WARNING  meshterm.core.connection: link lost, retrying``
+#: Level is padded so the messages line up; the logger name says which part spoke.
+_LINE_FORMAT = "%(asctime)s %(levelname)-8s %(name)s: %(message)s"
+_TIME_FORMAT = "%Y-%m-%d %H:%M:%S"
 
-        Args:
-            record: The record to format.
 
-        Returns:
-            A single-line JSON document.
-        """
-        payload = {
-            "ts": self.formatTime(record, "%Y-%m-%dT%H:%M:%S"),
-            "level": record.levelname,
-            "logger": record.name,
-            "msg": record.getMessage(),
-        }
-        if record.exc_info:
-            payload["exc"] = self.formatException(record.exc_info)
-        return json.dumps(payload)
+#: The levels the ``log_level`` preference offers, by their own names. Spelled out rather
+#: than taken from ``logging.getLevelName``, whose string-to-number direction is deprecated,
+#: or ``getLevelNamesMapping``, which arrived in 3.11 and this package supports 3.10.
+_LEVELS: dict[str, int] = {
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+}
+
+
+def level_from_name(name: str, *, fallback: int = logging.WARNING) -> int:
+    """Turn a ``log_level`` preference value into a level number.
+
+    Args:
+        name: A level name, in any case.
+        fallback: Used when the name is unrecognised — a hand-edited ``preferences.yaml``
+            with a typo in it should lose some log detail, not stop the app from starting.
+
+    Returns:
+        The matching level number.
+    """
+    return _LEVELS.get(name.strip().upper(), fallback)
+
+
+def log_path(log_dir: Path) -> Path:
+    """Return the log file's path, for an error message that wants to name it."""
+    return log_dir / LOG_FILENAME
 
 
 def configure_logging(
@@ -44,14 +80,16 @@ def configure_logging(
     log_dir: Path,
     *,
     level: int = logging.INFO,
+    file_level: int = logging.WARNING,
     quiet: bool = False,
 ) -> logging.Logger:
     """Configure and return the application logger.
 
     Args:
         console: The Rich console the handler should render to.
-        log_dir: Directory for the ``meshterm.log.jsonl`` event file.
+        log_dir: Directory for the ``meshterm.log`` file.
         level: Console log level.
+        file_level: File log level, from the ``log_level`` preference.
         quiet: When ``True``, suppress console output (file logging continues).
 
     Returns:
@@ -70,9 +108,14 @@ def configure_logging(
         logger.addHandler(rich_handler)
 
     log_dir.mkdir(parents=True, exist_ok=True)
-    file_handler = logging.FileHandler(log_dir / "meshterm.log.jsonl", encoding="utf-8")
-    file_handler.setLevel(logging.DEBUG)
-    file_handler.setFormatter(JsonlFormatter())
+    file_handler = RotatingFileHandler(
+        log_path(log_dir),
+        maxBytes=_MAX_BYTES,
+        backupCount=_BACKUP_COUNT,
+        encoding="utf-8",
+    )
+    file_handler.setLevel(file_level)
+    file_handler.setFormatter(logging.Formatter(_LINE_FORMAT, datefmt=_TIME_FORMAT))
     logger.addHandler(file_handler)
 
     _quiet_library_console(file_handler)
@@ -100,8 +143,8 @@ def _quiet_library_console(file_handler: logging.Handler) -> None:
     1. Give the root logger a :class:`~logging.NullHandler` so ``basicConfig`` — which only
        acts when the root has no handlers — becomes a no-op and never adds its stream handler.
     2. Take each known library logger off propagation and attach only ``file_handler``, so
-       its records are still captured to the JSON-lines log but never reach the console, even
-       if some other code path installs a root stream handler anyway.
+       its records are still captured to the log but never reach the console, even if some
+       other code path installs a root stream handler anyway.
 
     Args:
         file_handler: The application's file handler to also capture library records to.

meshterm/platforms.py

@@ -19,7 +19,7 @@ from __future__ import annotations
 
 import os
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
 from pathlib import Path
 
 
@@ -342,10 +342,30 @@ def resolve(flag: str | None = None) -> Resolution:
     return Resolution(flag, env, model, "default", REGULAR)
 
 
+def without_emoji(platform: Platform) -> Platform:
+    """The same platform with its icons routed through the compact glyph table.
+
+    A terminal that cannot draw emoji is not a different *flavour* — the classic Windows
+    console has the desktop's width, colour depth and keyboard, and wants every other
+    thing :data:`REGULAR` says. Only the one flag moves, which is what the seam's flags
+    being independent is for: ``ascii_fold`` stays off, so accents and the rest of the
+    BMP still come through.
+
+    Args:
+        platform: The resolved platform.
+
+    Returns:
+        ``platform`` itself when its icons are already compact, else a copy with
+        ``emoji`` cleared.
+    """
+    return platform if not platform.emoji else replace(platform, emoji=False)
+
+
 __all__ = [
     "Platform",
     "REGULAR",
     "PICOCALC",
+    "without_emoji",
     "PLATFORM",
     "get_platform",
     "set_platform",

meshterm/ui/termfont.py

@@ -1,4 +1,25 @@
-"""Terminal font detection — can this terminal draw powerline path separators?
+"""Terminal capability detection — what can this terminal actually draw?
+
+Two questions, both answered out-of-band because a terminal cannot be asked in-band: a
+glyph it does not have still occupies its cell, so the screen looks the same whether the
+character arrived or not.
+
+**Powerline separators**, below, are a *font* question — read the terminal's configured
+face and match it against fonts known to carry the block.
+
+**Emoji** (:func:`emoji_support`) are a *host* question, and only on Windows. The classic
+console — ``conhost``, which is what a double-clicked program still gets — rasterises
+through GDI with the console font and nothing behind it, so an emoji lands as a
+replacement box however the font is configured. Everything that replaced it draws them
+fine. So the verdict identifies the host, structurally rather than from the environment
+(``WT_SESSION`` is inherited across process launches, so a program started from Windows
+Terminal into a console of its own still claims to be in one), and a ``False`` routes
+every icon through the compact single-glyph table :func:`meshterm.ui.theme.glyph` already
+keeps for the PicoCalc — that whole vocabulary is BMP, so it draws wherever the plain
+status marks already do.
+
+Both verdicts are hints that pick a default, and both have an override for the reader who
+knows better than the probe: ``MESHTERM_POWERLINE`` and ``MESHTERM_EMOJI``.
 
 The path-line widget (:mod:`~meshterm.ui.pathline`) can render a hop sequence as
 interlocking powerline segments — each hop a colour-filled chip, joined by the solid
@@ -57,6 +78,8 @@ from dataclasses import dataclass
 from functools import lru_cache
 from pathlib import Path
 
+from ..core import win32dll
+
 #: Coverage levels a verdict (or a recommended font) can carry, strongest first.
 FULL = "full"
 CORE = "core"
@@ -460,7 +483,7 @@ def _conhost_face() -> str | None:
         import ctypes
         import ctypes.wintypes as wintypes
 
-        kernel32 = ctypes.windll.kernel32
+        kernel32 = win32dll.kernel32()
         if not kernel32.GetConsoleWindow():
             return None
 
@@ -675,3 +698,239 @@ def installed_recommended() -> RecommendedFont | None:
             return matched
         best = best or matched
     return best
+
+
+# --- emoji support ----------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EmojiSupport:
+    """Whether this terminal can show an emoji at all, and what decided that.
+
+    Attributes:
+        supported: ``True`` when an emoji icon reaches the screen as itself.
+        source: ``"env"`` (the ``MESHTERM_EMOJI`` override), ``"platform"`` (not Windows,
+            so not the classic console's problem), ``"console"`` (the host was identified
+            — see :func:`_is_classic_console`), or ``"no-console"`` (nothing to identify:
+            output is redirected, or the call failed).
+    """
+
+    supported: bool
+    source: str
+
+
+def _is_classic_console() -> bool | None:
+    """Whether this process is drawing into a genuine ``conhost`` window.
+
+    Which is the whole question, because that host renders through GDI with the console
+    font and no emoji font behind it, while everything that replaced it — Windows
+    Terminal, VS Code's terminal, anything over ssh — draws emoji as a matter of course.
+
+    It cannot be asked in band. A missing glyph still occupies its cell, so the screen
+    reads back exactly as it would have if the character had drawn: measured on Windows 10
+    22H2, a classic console stores ``📡`` intact and advances two cells while showing a
+    single replacement box, and a ConPTY (which does draw it) reads back as U+FFFD because
+    the buffer behind it is updated asynchronously. A write-and-read-back probe answers
+    both hosts *backwards*, which is the trap this docstring exists to record.
+
+    Nor can the environment be trusted alone: ``WT_SESSION`` is inherited by child
+    processes, so a program launched from Windows Terminal into a console of its own still
+    carries it and would answer for the wrong host.
+
+    So the host is identified structurally, from two independent facts, and both must
+    agree before anything is dimmed (the costly mistake is stripping icons from a terminal
+    that could draw them):
+
+    * **The console font has a real pixel width.** A ConPTY's hidden conhost reports a
+      stub — face ``Consolas``, cell width ``0`` — because nothing is rasterised there.
+    * **The buffer is taller than its window.** A classic console owns its scrollback
+      (9001 rows by default); under a ConPTY the terminal owns it, so the buffer is
+      exactly the window.
+
+    Returns:
+        ``True`` for a genuine classic console, ``False`` for anything else drawing to a
+        console, and ``None`` when there is no console on stdout (redirected output, not
+        Windows, or the call failed) — an unknown is never a reason to degrade.
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        import ctypes
+        from ctypes import wintypes
+
+        class _COORD(ctypes.Structure):
+            _fields_ = [("X", wintypes.SHORT), ("Y", wintypes.SHORT)]
+
+        class _SMALL_RECT(ctypes.Structure):
+            _fields_ = [
+                ("Left", wintypes.SHORT),
+                ("Top", wintypes.SHORT),
+                ("Right", wintypes.SHORT),
+                ("Bottom", wintypes.SHORT),
+            ]
+
+        class _CSBI(ctypes.Structure):
+            _fields_ = [
+                ("dwSize", _COORD),
+                ("dwCursorPosition", _COORD),
+                ("wAttributes", wintypes.WORD),
+                ("srWindow", _SMALL_RECT),
+                ("dwMaximumWindowSize", _COORD),
+            ]
+
+        class _CONSOLE_FONT_INFOEX(ctypes.Structure):
+            _fields_ = [
+                ("cbSize", wintypes.ULONG),
+                ("nFont", wintypes.DWORD),
+                ("dwFontSize", _COORD),
+                ("FontFamily", wintypes.UINT),
+                ("FontWeight", wintypes.UINT),
+                ("FaceName", ctypes.c_wchar * 32),
+            ]
+
+        # Safe to declare: this handle is ours alone (see meshterm.core.win32dll). The
+        # explicit restype matters — ctypes would assume a 32-bit int and truncate the
+        # 64-bit HANDLE, turning every later call into a silent failure.
+        kernel32 = win32dll.kernel32()
+        kernel32.GetStdHandle.argtypes = [wintypes.DWORD]
+        kernel32.GetStdHandle.restype = wintypes.HANDLE
+        kernel32.GetConsoleScreenBufferInfo.argtypes = [wintypes.HANDLE, ctypes.POINTER(_CSBI)]
+        kernel32.GetConsoleScreenBufferInfo.restype = wintypes.BOOL
+        kernel32.GetCurrentConsoleFontEx.argtypes = [
+            wintypes.HANDLE,
+            wintypes.BOOL,
+            ctypes.POINTER(_CONSOLE_FONT_INFOEX),
+        ]
+        kernel32.GetCurrentConsoleFontEx.restype = wintypes.BOOL
+
+        handle = kernel32.GetStdHandle(wintypes.DWORD(-11).value)  # STD_OUTPUT_HANDLE
+        info = _CSBI()
+        # Fails when stdout is a pipe or a file — nothing is being drawn, so there is
+        # nothing to answer, and this is what keeps redirected and CI runs out of it.
+        if not kernel32.GetConsoleScreenBufferInfo(handle, ctypes.byref(info)):
+            return None
+
+        font = _CONSOLE_FONT_INFOEX()
+        font.cbSize = ctypes.sizeof(_CONSOLE_FONT_INFOEX)
+        if not kernel32.GetCurrentConsoleFontEx(handle, False, ctypes.byref(font)):
+            return None
+
+        rasterised = font.dwFontSize.X > 0
+        owns_scrollback = info.dwSize.Y > (info.srWindow.Bottom - info.srWindow.Top + 1)
+        return rasterised and owns_scrollback
+    except Exception:  # pragma: no cover - a probe that fails is an unknown, not a crash
+        return None
+
+
+def _emoji_support(
+    environ: Mapping[str, str] | None = None,
+    *,
+    console_probe: Callable[[], bool | None] = _is_classic_console,
+    system: str | None = None,
+) -> EmojiSupport:
+    """The uncached verdict (see :func:`emoji_support` for the ladder)."""
+    env = os.environ if environ is None else environ
+    override = (env.get("MESHTERM_EMOJI") or "").strip().lower()
+    if override in {"0", "off", "no", "none", "false"}:
+        return EmojiSupport(False, "env")
+    if override in {"1", "on", "yes", "true"}:
+        return EmojiSupport(True, "env")
+
+    if (sys.platform if system is None else system) != "win32":
+        return EmojiSupport(True, "platform")
+    classic = console_probe()
+    if classic is None:
+        return EmojiSupport(True, "no-console")
+    return EmojiSupport(not classic, "console")
+
+
+@lru_cache(maxsize=1)
+def classic_console() -> bool:
+    """Whether this session is drawing into a genuine ``conhost`` window.
+
+    The one host with no font fallback of its own, so the only one where the configured
+    font's own repertoire decides what the reader sees. See :func:`_is_classic_console`
+    for how it is identified, and why not from the environment.
+    """
+    return _is_classic_console() is True
+
+
+@lru_cache(maxsize=1)
+def emoji_support() -> EmojiSupport:
+    """Whether emoji icons can be drawn here, decided once and cached.
+
+    The ladder: the ``MESHTERM_EMOJI`` override, then everything that isn't Windows (where
+    a UTF-8 terminal draws them as a matter of course), then :func:`_is_classic_console`.
+    Cached because a session does not change host halfway through.
+
+    Returns:
+        The :class:`EmojiSupport` verdict.
+    """
+    return _emoji_support(os.environ)
+
+
+def emoji_enabled() -> bool:
+    """Whether icons should render as emoji rather than through the compact table."""
+    return emoji_support().supported
+
+
+# --- chart glyphs -----------------------------------------------------------------
+
+
+#: Families measured to carry the Braille Patterns block (U+2800–U+28FF) that
+#: :mod:`meshterm.ui.braillechart` draws every timeline from.
+#:
+#: The list is short on purpose, and each entry is a measurement rather than a
+#: reputation: reading the ``cmap`` of every font installed on a development machine
+#: (2026-09-07) found that nearly no monospace font carries the block at all. Hack Nerd
+#: Font, JetBrains Mono, Fira Code, Source Code Pro, Consolas, Lucida Console and — the
+#: surprise — DejaVu Sans *Mono* all measure zero of 256. DejaVu *Sans*, which is
+#: proportional, carries all 256, which is where the widespread "install DejaVu for
+#: braille" advice comes from: it works only because terminals fall back from the mono
+#: face to the proportional one for that block.
+#:
+#: Which is the point. On every host that falls back — Windows Terminal, VS Code's
+#: terminal, macOS, Linux — the charts draw whatever the chosen font holds, so this list
+#: never has to be right. It matters on the one host with no fallback at all, the classic
+#: Windows console, where a font outside this list means boxes where the charts should be.
+CHART_FONTS: tuple[str, ...] = (
+    # Microsoft's console font: 44/44, and the family MeshTerm bundles (see
+    # meshterm.core.consolefont). Covers the PL and NF builds by prefix.
+    "cascadia mono",
+    "cascadia code",
+    # The Nerd Font patches of the same, which keep what they patch.
+    "caskaydiacove",
+    "caskaydiamono",
+    # Widely reported to carry the block; not measured here, no copy to hand.
+    "iosevka",
+)
+
+
+def face_draws_charts(face: str | None) -> bool:
+    """Whether ``face`` can draw the braille the timelines are made of.
+
+    Args:
+        face: A configured font family, in any spelling, or ``None``.
+
+    Returns:
+        Whether it is one of :data:`CHART_FONTS`.
+    """
+    if not face:
+        return False
+    normal = normalize_face(face)
+    return any(normal.startswith(known) for known in CHART_FONTS)
+
+
+def installed_chart_font() -> str | None:
+    """The first installed family that can draw the charts, or ``None``.
+
+    What separates "select the font they already have" — every Windows 11 machine, and
+    anyone who has installed Windows Terminal — from "offer to install ours".
+
+    Returns:
+        The family name as installed, or ``None`` when nothing installed can do it.
+    """
+    for family in _installed_families():
+        if face_draws_charts(family):
+            return family
+    return None

meshterm/ui/tui/emoji_width.py

@@ -89,6 +89,8 @@ from collections.abc import Callable
 
 from prompt_toolkit.layout.controls import FormattedTextControl
 
+from ...core import win32dll
+
 #: The zero-width joiner: the tell that the codepoints it sits between are **one glyph**
 #: (``🤷‍♂️``, ``👨‍👩‍👧``), which a terminal draws in the width of the sequence's base.
 _ZWJ = "‍"
@@ -309,7 +311,10 @@ def _win_probe_width(probe: str) -> int | None:
             ("dwMaximumWindowSize", _COORD),
         ]
 
-    kernel32 = ctypes.windll.kernel32
+    # A private handle: declaring these signatures on `ctypes.windll.kernel32` would
+    # rewrite them for prompt_toolkit too, which calls the same function object with a
+    # struct class of its own. See meshterm.core.win32dll.
+    kernel32 = win32dll.kernel32()
     # Declare signatures explicitly. Without this ctypes assumes a 32-bit int
     # return, which truncates the 64-bit console HANDLE and makes every
     # subsequent call fail — silently reducing the probe to "no measurement".

meshterm/ui/tui/session.py

@@ -29,6 +29,7 @@ from prompt_toolkit.utils import get_cwidth
 from rich.console import RenderableType
 from rich.text import Text
 
+from ...core import win32dll
 from ...platforms import get_platform
 from ...services import modifier_watch
 from . import fastrender, fkeys, frame
@@ -168,9 +169,7 @@ def _right_ctrl_down() -> bool:
     if sys.platform != "win32":
         return False
     try:
-        import ctypes
-
-        return bool(ctypes.windll.user32.GetAsyncKeyState(0xA3) & 0x8000)  # VK_RCONTROL
+        return bool(win32dll.user32().GetAsyncKeyState(0xA3) & 0x8000)  # VK_RCONTROL
     except Exception:  # noqa: BLE001 - a failed probe just leaves the plain action
         return False
 
@@ -191,8 +190,10 @@ def _read_clipboard() -> str:
         import ctypes
 
         CF_UNICODETEXT = 13
-        user32 = ctypes.windll.user32
-        kernel32 = ctypes.windll.kernel32
+        # Private handles; the argtypes below would otherwise be declared on objects
+        # every library in the process shares. See meshterm.core.win32dll.
+        user32 = win32dll.user32()
+        kernel32 = win32dll.kernel32()
         user32.GetClipboardData.restype = ctypes.c_void_p
         user32.GetClipboardData.argtypes = [ctypes.c_uint]
         kernel32.GlobalLock.restype = ctypes.c_void_p
@@ -282,13 +283,20 @@ def _has_wide_glyph(text: str) -> bool:
     ``>= 0x1100`` guard skips the ASCII/Latin bulk of a frame before the width lookup, which
     matters because this runs over the whole composed frame on every repaint.
 
-    On a platform that draws no emoji the answer is ``False`` by construction — its console
-    font is a fixed 512-glyph set with no wide glyph in it, so nothing a frame can contain
-    would return ``True``. Answering from the platform instead of the text skips a
-    per-character scan of the entire frame on every repaint, and with it the scrub machinery
-    that a ``True`` would arm, leaving the cheap differential paint permanently in play.
+    On a platform that folds its frames to a fixed font the answer is ``False`` by
+    construction — that font is a 512-glyph set with no wide glyph in it, so nothing a
+    composed frame can contain would return ``True``. Answering from the platform instead
+    of the text skips a per-character scan of the entire frame on every repaint, and with
+    it the scrub machinery that a ``True`` would arm, leaving the cheap differential paint
+    permanently in play.
+
+    The fold is the guarantee, not the icon table: a terminal that merely can't draw
+    *emoji* (the classic Windows console — see :func:`meshterm.ui.termfont.emoji_support`)
+    still renders the rest of the BMP, and a contact named in CJK is two cells wide there
+    like anywhere else. Reading ``emoji`` here instead would have skipped the scan on a
+    frame that genuinely needed it, and smeared the row.
     """
-    if not get_platform().emoji:
+    if get_platform().ascii_fold:
         return False
     return any(ord(ch) >= 0x1100 and get_cwidth(ch) == 2 for ch in text)
 

packaging/meshterm.spec

@@ -18,6 +18,11 @@ datas = [
 ]
 
 hiddenimports = [
+    # Every tool module. `meshterm.tools` finds these with `pkgutil.iter_modules` at
+    # import time, so nothing static ever names one, and a frozen build without this line
+    # starts with an empty registry: no menu entries but Quit, and no CLI subcommands.
+    # The app launches and looks like it works, which is the worst way for this to fail.
+    *collect_submodules("meshterm.tools"),
     # bleak picks its backend at runtime by platform, so static analysis never sees the
     # one that actually gets used. Collect all of them and let the unused ones sit.
     *collect_submodules("bleak.backends"),

tests/test_config.py

@@ -8,7 +8,9 @@ from __future__ import annotations
 
 from pathlib import Path
 
-from meshterm.core.config import Settings
+import pytest
+
+from meshterm.core.config import CONFIG_DIR_ENV, Settings, default_config_dir
 
 
 def test_connect_on_start_defaults_true() -> None:
@@ -42,3 +44,30 @@ def test_tcp_profile_defaults_port(tmp_path: Path) -> None:
     config.write_text('[profiles.wifi]\nhost = "meshcore.local"\n', encoding="utf-8")
     profile = Settings.load(config).profiles["wifi"]
     assert profile.is_tcp and profile.tcp_endpoint == "meshcore.local:5000"
+
+
+def test_config_dir_defaults_to_the_home_directory(monkeypatch: pytest.MonkeyPatch) -> None:
+    """With no override set, config and data live in ``.meshterm`` under the user's home."""
+    monkeypatch.delenv(CONFIG_DIR_ENV, raising=False)
+    assert default_config_dir() == Path.home() / ".meshterm"
+
+
+def test_config_dir_follows_the_override(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    """``$MESHTERM_HOME`` moves the whole directory, so a build can run beside a real one.
+
+    This is what keeps a downloaded binary from opening the same database as the checkout
+    it was built from — the history is the valuable half of an install, and there was no
+    way to point a second copy somewhere else.
+    """
+    monkeypatch.setenv(CONFIG_DIR_ENV, str(tmp_path / "elsewhere"))
+    assert default_config_dir() == tmp_path / "elsewhere"
+
+
+def test_config_dir_ignores_an_empty_override(monkeypatch: pytest.MonkeyPatch) -> None:
+    """An unset-but-present or whitespace value falls back rather than resolving to nowhere.
+
+    A shell that exports the variable empty is common enough that treating "" as "put the
+    data in the current directory" would be a nasty way to scatter someone's history.
+    """
+    monkeypatch.setenv(CONFIG_DIR_ENV, "   ")
+    assert default_config_dir() == Path.home() / ".meshterm"

tests/test_consolefont.py

@@ -0,0 +1,213 @@
+"""Tests for the bundled console font and the machinery that installs and selects it.
+
+The Win32 half cannot be exercised off Windows, and should not be exercised *on* it by a
+test suite — installing a font is a change to the machine, and one that cannot be undone
+inside a session (Windows locks the file once it is loaded). So what is pinned here is
+everything that can be checked without touching the system: that the font we ship is the
+font we say we ship, that it can actually draw what MeshTerm draws, and that every entry
+point degrades rather than raises where there is no console to talk to.
+
+The font's own coverage is asserted from its ``cmap``, which makes this the desktop
+counterpart to :mod:`meshterm.ui.fontset` — the PicoCalc's device-verified inventory.
+"""
+
+from __future__ import annotations
+
+import struct
+import sys
+from pathlib import Path
+
+import pytest
+
+from meshterm.core import consolefont
+from meshterm.ui.termfont import CHART_FONTS, face_draws_charts, installed_chart_font
+
+BRAILLE = range(0x2800, 0x2900)
+
+
+def _cmap(path: Path) -> set[int]:
+    """Every codepoint a TrueType font maps, read from its ``cmap`` table.
+
+    A short format-4 reader rather than a dependency: the question asked here is narrow
+    and the alternative is trusting a font file we ship without ever looking inside it.
+    """
+    data = path.read_bytes()
+    count = struct.unpack(">H", data[4:6])[0]
+    tables = {}
+    for i in range(count):
+        offset = 12 + i * 16
+        tag, _, start, _length = struct.unpack(">4sIII", data[offset : offset + 16])
+        tables[tag.decode("latin-1")] = start
+
+    cmap = tables["cmap"]
+    covered: set[int] = set()
+    for i in range(struct.unpack(">H", data[cmap + 2 : cmap + 4])[0]):
+        record = cmap + 4 + i * 8
+        sub = cmap + struct.unpack(">HHI", data[record : record + 8])[2]
+        if struct.unpack(">H", data[sub : sub + 2])[0] != 4:
+            continue
+        seg_bytes = struct.unpack(">H", data[sub + 6 : sub + 8])[0]
+        segs = seg_bytes // 2
+        ends = struct.unpack(f">{segs}H", data[sub + 14 : sub + 14 + seg_bytes])
+        starts_at = sub + 16 + seg_bytes
+        starts = struct.unpack(f">{segs}H", data[starts_at : starts_at + seg_bytes])
+        deltas_at = starts_at + seg_bytes
+        deltas = struct.unpack(f">{segs}h", data[deltas_at : deltas_at + seg_bytes])
+        ranges_at = deltas_at + seg_bytes
+        ranges = struct.unpack(f">{segs}H", data[ranges_at : ranges_at + seg_bytes])
+        for seg in range(segs):
+            for cp in range(starts[seg], min(ends[seg], 0xFFFF) + 1):
+                if ranges[seg] == 0:
+                    glyph = (cp + deltas[seg]) & 0xFFFF
+                else:
+                    at = ranges_at + seg * 2 + ranges[seg] + (cp - starts[seg]) * 2
+                    if at + 2 > len(data):
+                        continue
+                    glyph = struct.unpack(">H", data[at : at + 2])[0]
+                    if glyph:
+                        glyph = (glyph + deltas[seg]) & 0xFFFF
+                if glyph:
+                    covered.add(cp)
+    return covered
+
+
+def test_the_font_we_ship_is_present_with_its_licence() -> None:
+    """It is redistributed under the SIL OFL, which travels with the file or not at all."""
+    assert consolefont.BUNDLED_FONT.is_file()
+    licence = consolefont.FONT_DIR / "CascadiaMono-OFL.txt"
+    assert licence.is_file()
+    text = licence.read_text(encoding="utf-8")
+    assert "SIL Open Font License" in text
+    assert "Reserved Font Name" in text
+
+
+def test_the_bundled_font_can_draw_the_charts() -> None:
+    """The reason this font and not another: it has the braille block, and few do.
+
+    Measured across every font on a development machine, no mainstream coder font carried
+    it — Hack Nerd Font, JetBrains Mono, Fira Code, Source Code Pro and even DejaVu Sans
+    *Mono* all hold none of the 256. Shipping one that cannot draw a chart would leave the
+    offer technically successful and visibly pointless.
+    """
+    covered = _cmap(consolefont.BUNDLED_FONT)
+    missing = [cp for cp in BRAILLE if cp not in covered]
+    assert not missing, f"{len(missing)} braille cells missing from the bundled font"
+
+
+def test_the_bundled_font_covers_the_marks_and_the_path_chips() -> None:
+    """The rest of what a classic console has to draw from its font alone.
+
+    The powerline separators are why the ``PL`` build is the one bundled rather than the
+    plain one: 25KB more, and the path lines keep their chips.
+    """
+    covered = _cmap(consolefont.BUNDLED_FONT)
+    for mark in "✓❯◉●○▲■─│╭╮╰╯▌▐░▒▓█←↑→↓↔↕…":
+        assert ord(mark) in covered, f"{mark!r} is not in the bundled font"
+    for chip in "":  # the powerline separator and its round caps
+        assert ord(chip) in covered, f"U+{ord(chip):04X} is not in the bundled font"
+
+
+def test_the_bundled_face_is_what_the_font_calls_itself() -> None:
+    """``SetCurrentConsoleFontEx`` matches on the family name exactly, so a typo is silent.
+
+    It would install the font, fail to select it, and report a console that "kept its own
+    font" — with nothing anywhere naming the real cause.
+    """
+    data = consolefont.BUNDLED_FONT.read_bytes()
+    count = struct.unpack(">H", data[4:6])[0]
+    name_table = next(
+        struct.unpack(">4sIII", data[12 + i * 16 : 28 + i * 16])[2]
+        for i in range(count)
+        if struct.unpack(">4sIII", data[12 + i * 16 : 28 + i * 16])[0] == b"name"
+    )
+    records, strings = struct.unpack(">HH", data[name_table + 2 : name_table + 6])
+    families = set()
+    for i in range(records):
+        at = name_table + 6 + i * 12
+        platform, encoding, language, name_id, length, offset = struct.unpack(
+            ">HHHHHH", data[at : at + 12]
+        )
+        if (platform, encoding, language, name_id) == (3, 1, 0x409, 1):
+            start = name_table + strings + offset
+            families.add(data[start : start + length].decode("utf-16-be"))
+    assert consolefont.BUNDLED_FACE in families, f"font calls itself {families}"
+
+
+def test_the_bundled_face_is_one_we_would_accept() -> None:
+    """The font we install has to satisfy the check that decides whether to offer it.
+
+    Otherwise MeshTerm installs it, selects it, and offers again on the next launch.
+    """
+    assert face_draws_charts(consolefont.BUNDLED_FACE)
+
+
+def test_chart_fonts_are_matched_by_family_however_spelled() -> None:
+    """Cascadia ships plain, PL and NF builds, and the Nerd Font patches rename it.
+
+    Matched on the *family* name, which is what a terminal's config, the ``HKCU``
+    registration and ``SetCurrentConsoleFontEx`` all speak — never the filename. Those
+    differ here: ``CascadiaMonoPL.ttf`` calls itself ``Cascadia Mono PL``, spaced.
+    """
+    assert face_draws_charts("Cascadia Mono")
+    assert face_draws_charts("Cascadia Mono PL")
+    assert face_draws_charts("Cascadia Mono NF")
+    assert face_draws_charts("  cascadia   code  ")  # spacing and case are normalised
+    assert face_draws_charts("CaskaydiaCove Nerd Font Mono")
+
+
+def test_the_fonts_that_cannot_draw_charts_are_not_claimed() -> None:
+    """Every one of these was measured at zero braille cells; a wrong yes here is a lie.
+
+    It would leave a reader on a classic console with boxes for charts and no offer to
+    fix them, which is the exact failure the whole check exists to prevent.
+    """
+    for face in (
+        "Consolas",
+        "Lucida Console",
+        "Courier New",
+        "Hack Nerd Font Mono",
+        "JetBrains Mono",
+        "Fira Code",
+        "Source Code Pro",
+        "DejaVu Sans Mono",
+    ):
+        assert not face_draws_charts(face), f"{face} does not carry the braille block"
+    assert not face_draws_charts(None)
+    assert not face_draws_charts("")
+
+
+def test_every_chart_font_entry_is_normalised() -> None:
+    """The list is compared against normalised faces, so an entry with capitals never hits."""
+    for entry in CHART_FONTS:
+        assert entry == entry.lower().strip()
+        assert "  " not in entry
+
+
+def test_asking_the_machine_what_it_has_never_raises() -> None:
+    """Best-effort, on every platform: a font scan that throws would take startup with it."""
+    assert installed_chart_font() is None or isinstance(installed_chart_font(), str)
+
+
+def test_reading_the_console_font_never_raises() -> None:
+    """Under pytest there is no console worth asking, and the answer must simply be None."""
+    assert consolefont.current_face() is None or isinstance(consolefont.current_face(), str)
+
+
+def test_the_user_font_directory_is_under_the_users_own_profile() -> None:
+    """The whole point of the per-user location: no administrator rights are involved."""
+    directory = consolefont.user_font_dir()
+    assert directory.parts[-3:] == ("Microsoft", "Windows", "Fonts")
+    assert "AppData" in str(directory) or "Local" in str(directory)
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="would touch the real machine")
+def test_installing_is_a_no_op_where_there_are_no_windows_fonts() -> None:
+    """Off Windows the offer is never made, and the install refuses rather than pretends."""
+    assert consolefont.install_bundled_font() is False
+    assert consolefont.select("Cascadia Mono PL") is False
+    assert consolefont.use("Cascadia Mono PL") is False
+
+
+def test_a_font_resource_is_only_added_from_a_file_that_exists(tmp_path: Path) -> None:
+    """The retry path takes a path that may well not be there, and must not raise on it."""
+    assert consolefont._add_font_resource(tmp_path / "nothing.ttf") is False

tests/test_instancelock.py

@@ -0,0 +1,110 @@
+"""Tests for the one-interactive-session-per-directory guard, and the atomic writer.
+
+Both exist for the same reason: every copy of MeshTerm on a machine shares one data
+directory unless told otherwise, so two of them running at once is a thing that happens
+by accident rather than by choice.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+from meshterm.core.atomicwrite import write_atomically
+from meshterm.core.instancelock import LOCK_NAME, InstanceBusy, hold_instance_lock
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+
+
+def test_the_lock_is_released_when_the_holder_leaves(tmp_path: Path) -> None:
+    """Two sessions in sequence are fine; the guard is against overlap, not against reuse."""
+    with hold_instance_lock(tmp_path):
+        pass
+    with hold_instance_lock(tmp_path):
+        pass
+
+
+def test_the_lock_file_lives_beside_the_data(tmp_path: Path) -> None:
+    """The lock sits in the directory it guards, and the directory is made if missing."""
+    target = tmp_path / "not-yet"
+    with hold_instance_lock(target):
+        assert (target / LOCK_NAME).exists()
+
+
+def test_a_second_process_is_turned_away(tmp_path: Path) -> None:
+    """The real test of an OS lock: another *process* cannot take it.
+
+    Nothing in-process proves anything here — a lock that only excluded the thread that
+    already holds it would pass a single-process test and fail in the one situation it
+    exists for.
+    """
+    program = (
+        "import pathlib, sys\n"
+        f"sys.path.insert(0, {str(REPO_ROOT)!r})\n"
+        "from meshterm.core.instancelock import hold_instance_lock, InstanceBusy\n"
+        "try:\n"
+        f"    with hold_instance_lock(pathlib.Path({str(tmp_path)!r})):\n"
+        "        print('TAKEN')\n"
+        "except InstanceBusy:\n"
+        "    print('REFUSED')\n"
+    )
+    with hold_instance_lock(tmp_path):
+        done = subprocess.run(
+            [sys.executable, "-c", program], capture_output=True, text=True, timeout=60
+        )
+    assert done.stdout.strip() == "REFUSED", done.stderr[-500:]
+
+
+def test_the_refusal_says_how_to_run_two(tmp_path: Path) -> None:
+    """The message is mostly the way out, because that is what the reader needs next.
+
+    Someone who sees this is doing something reasonable — trying a downloaded build, or
+    running a second radio — so being told *no* without being told *how* would be the
+    unhelpful half of the answer.
+    """
+    message = str(InstanceBusy(tmp_path))
+    assert "MESHTERM_HOME" in message
+    assert str(tmp_path) in message
+
+
+def test_a_write_lands_whole_or_not_at_all(tmp_path: Path) -> None:
+    """The written file holds exactly what was asked for, and no scratch file survives."""
+    target = tmp_path / "sub" / "contacts.json"
+    write_atomically(target, json.dumps({"a": 1}))
+    assert json.loads(target.read_text(encoding="utf-8")) == {"a": 1}
+    assert list(tmp_path.rglob("*.tmp")) == []
+
+
+def test_the_scratch_file_is_named_for_its_writer(tmp_path: Path, monkeypatch) -> None:
+    """Two processes writing the same file must not share one temporary name.
+
+    The rename is atomic; the thing being renamed is not. A fixed ``.tmp`` name lets two
+    writers interleave inside one scratch file and then each rename whatever ended up
+    there over the real one.
+    """
+    seen: list[Path] = []
+    real = Path.write_text
+
+    def spy(self: Path, *args: object, **kwargs: object) -> int:
+        seen.append(self)
+        return real(self, *args, **kwargs)  # type: ignore[arg-type]
+
+    monkeypatch.setattr(Path, "write_text", spy)
+    write_atomically(tmp_path / "x.json", "{}")
+    assert seen and str(__import__("os").getpid()) in seen[0].name
+
+
+def test_a_failed_write_leaves_no_litter(tmp_path: Path, monkeypatch) -> None:
+    """A write that raises cleans up after itself rather than leaving a partial file."""
+
+    def boom(self: Path, *args: object, **kwargs: object) -> int:
+        raise OSError("disk full")
+
+    monkeypatch.setattr(Path, "write_text", boom)
+    with pytest.raises(OSError):
+        write_atomically(tmp_path / "y.json", "{}")
+    assert list(tmp_path.rglob("*.tmp")) == []

tests/test_logging.py

@@ -0,0 +1,109 @@
+"""Tests for the log file: plain text, bounded, and holding the things that went wrong.
+
+The log's one real job is being opened by a person who has hit a problem — often the
+person reporting it. Every assertion here is about that reader.
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from rich.console import Console
+
+from meshterm.persistence.logging import (
+    LOG_FILENAME,
+    configure_logging,
+    get_logger,
+    level_from_name,
+    log_path,
+)
+
+
+def _read(log_dir: Path) -> str:
+    for handler in get_logger().handlers:
+        handler.flush()
+    return log_path(log_dir).read_text(encoding="utf-8")
+
+
+def test_the_log_is_plain_text(tmp_path: Path) -> None:
+    """One readable line per record: when, how bad, who said it, and what."""
+    configure_logging(Console(quiet=True), tmp_path, file_level=logging.WARNING, quiet=True)
+    get_logger("core.connection").warning("link lost, retrying")
+    line = _read(tmp_path).splitlines()[0]
+    assert "WARNING" in line
+    assert "meshterm.core.connection" in line
+    assert "link lost, retrying" in line
+    # A date as well as a time. "it happened at 14:40" is useless a week later.
+    assert line.startswith("20")
+
+
+def test_the_file_is_named_plainly(tmp_path: Path) -> None:
+    """``meshterm.log`` — an extension every text editor already opens."""
+    assert log_path(tmp_path).name == LOG_FILENAME == "meshterm.log"
+
+
+def test_the_level_keeps_the_quiet_records_out(tmp_path: Path) -> None:
+    """At the default, the file holds problems rather than a narration of a working run.
+
+    This is the whole point of the default being WARNING: a log where the dozen useful
+    lines sit under twenty thousand dull ones is one nobody reads.
+    """
+    configure_logging(Console(quiet=True), tmp_path, file_level=logging.WARNING, quiet=True)
+    log = get_logger()
+    log.debug("opened a screen")
+    log.info("connected to a radio")
+    log.warning("something went wrong")
+    written = _read(tmp_path)
+    assert "something went wrong" in written
+    assert "opened a screen" not in written
+    assert "connected to a radio" not in written
+
+
+def test_turning_it_up_lets_everything_through(tmp_path: Path) -> None:
+    """DEBUG is there for chasing something, and keeps what WARNING drops."""
+    configure_logging(Console(quiet=True), tmp_path, file_level=logging.DEBUG, quiet=True)
+    get_logger().debug("opened a screen")
+    assert "opened a screen" in _read(tmp_path)
+
+
+def test_a_traceback_goes_in_with_the_record(tmp_path: Path) -> None:
+    """An exception's traceback is written under the record that reports it.
+
+    This is most of why the file is worth attaching to a bug report: the terminal scrolls
+    away and gets closed, and this copy does not.
+    """
+    configure_logging(Console(quiet=True), tmp_path, file_level=logging.WARNING, quiet=True)
+    try:
+        raise ValueError("the device said something impossible")
+    except ValueError:
+        get_logger().exception("tool raised")
+    written = _read(tmp_path)
+    assert "tool raised" in written
+    assert "ValueError: the device said something impossible" in written
+    assert "Traceback (most recent call last)" in written
+
+
+def test_the_file_is_bounded(tmp_path: Path) -> None:
+    """It rotates. An unbounded log reached 11MB in ten weeks on a real install."""
+    configure_logging(Console(quiet=True), tmp_path, file_level=logging.WARNING, quiet=True)
+    handler = next(h for h in get_logger().handlers if hasattr(h, "maxBytes"))
+    assert handler.maxBytes > 0
+    assert handler.backupCount > 0
+
+
+def test_a_level_name_becomes_a_level(tmp_path: Path) -> None:
+    """The preference stores a name; the handler needs a number."""
+    assert level_from_name("DEBUG") == logging.DEBUG
+    assert level_from_name("warning") == logging.WARNING
+    assert level_from_name("  Error ") == logging.ERROR
+
+
+def test_a_nonsense_level_still_starts_the_app() -> None:
+    """A typo in a hand-edited preferences file loses log detail, not the app.
+
+    Someone editing YAML by hand and writing ``WARN`` should get a slightly quieter log,
+    not a program that refuses to launch.
+    """
+    assert level_from_name("WARN") == logging.WARNING
+    assert level_from_name("") == logging.WARNING

tests/test_platforms.py

@@ -6,12 +6,20 @@ sanity — PicoCalc being strictly the narrower, plainer flavour.
 
 from __future__ import annotations
 
+import dataclasses
 from pathlib import Path
 
 import pytest
 
 import meshterm.platforms as platforms_mod
-from meshterm.platforms import PICOCALC, REGULAR, get_platform, resolve, set_platform
+from meshterm.platforms import (
+    PICOCALC,
+    REGULAR,
+    get_platform,
+    resolve,
+    set_platform,
+    without_emoji,
+)
 
 
 def test_regular_is_todays_behaviour() -> None:
@@ -142,3 +150,52 @@ def test_resolve_auto_detect_is_conservative(monkeypatch: pytest.MonkeyPatch) ->
     r = resolve()
     assert r.platform is REGULAR
     assert r.detected_model == "Raspberry Pi 4 Model B"
+
+
+# -- the emoji-less variant ------------------------------------------------------------
+
+
+def test_without_emoji_moves_one_flag_and_nothing_else() -> None:
+    """A terminal that can't draw emoji is not a different flavour.
+
+    The classic Windows console has the desktop's width, colour depth, borders and
+    keyboard — only the icons have to change. Every other field must survive, and
+    ``ascii_fold`` above all: folding there would strip accents from names the console
+    renders perfectly well.
+    """
+    plain = without_emoji(REGULAR)
+    assert plain.emoji is False
+    assert plain.ascii_fold is False
+    assert plain.truecolor is True
+    assert plain.readable_cols == REGULAR.readable_cols
+    assert plain.footer_fkeys is REGULAR.footer_fkeys
+
+    changed = {
+        f.name
+        for f in dataclasses.fields(REGULAR)
+        if getattr(plain, f.name) != getattr(REGULAR, f.name)
+    }
+    assert changed == {"emoji"}
+
+
+def test_without_emoji_leaves_an_already_compact_platform_alone() -> None:
+    """A platform whose icons are already compact comes back untouched.
+
+    The same object, not a copy that would compare equal but break every ``is`` check
+    the suite makes against PICOCALC.
+    """
+    assert without_emoji(PICOCALC) is PICOCALC
+
+
+def test_the_emoji_less_variant_still_drives_the_theme() -> None:
+    """The derived platform is a real one: binding it routes icons through the table.
+
+    This is the whole point — the seam's flags are independent, so clearing one reaches
+    the glyph funnel without dragging the console font's fold along with it.
+    """
+    from meshterm.ui.theme import fold_text, glyph
+
+    set_platform(without_emoji(REGULAR))
+    assert glyph("📡") == "☼"  # the advert icon, compacted
+    assert fold_text("café Montréal") == "café Montréal"  # no fold
+    assert get_platform().readable_cols == 72

tests/test_termfont.py

@@ -1,8 +1,9 @@
 """Terminal-font detection tests: the recommended list, the ladder, the verdict.
 
-Everything runs against injected environments and temp settings files — no test
-touches the real registry, the real Win32 console, or the machine's actual fonts —
-so the suite decides the same verdicts on any box.
+Every verdict runs against injected environments, temp settings files and injected
+probes, so the suite decides the same answers on any box. Two tests deliberately do
+touch the real machine — the installed-font scan and the console buffer probe — and both
+assert only that asking is safe, never what this particular box replies.
 """
 
 from __future__ import annotations
@@ -17,6 +18,8 @@ from meshterm.ui.termfont import (
     NONE,
     UNKNOWN,
     RecommendedFont,
+    _emoji_support,
+    _is_classic_console,
     _powerline_support,
     _read_jsonc,
     _vscode_default_face,
@@ -252,3 +255,83 @@ def test_installed_recommended_never_raises() -> None:
     """
     result = installed_recommended()
     assert result is None or isinstance(result, RecommendedFont)
+
+
+# --- emoji support ----------------------------------------------------------------
+
+
+def test_emoji_is_only_the_windows_consoles_problem() -> None:
+    """Everywhere but Windows, a terminal draws emoji and the question does not arise.
+
+    The probe is never even run there — a Linux or macOS session pays nothing for a limit
+    only the classic console has.
+    """
+
+    def never_called() -> bool | None:
+        raise AssertionError("the console probe must not run off Windows")
+
+    for system in ("linux", "darwin", "freebsd"):
+        verdict = _emoji_support({}, console_probe=never_called, system=system)
+        assert (verdict.supported, verdict.source) == (True, "platform")
+
+
+def test_a_classic_console_turns_the_icons_compact() -> None:
+    """The verdict that matters: conhost draws no emoji, so the icons go compact.
+
+    This is the double-clicked build on Windows — the case the whole check exists for.
+    """
+    verdict = _emoji_support({}, console_probe=lambda: True, system="win32")
+    assert (verdict.supported, verdict.source) == (False, "console")
+
+
+def test_every_other_windows_terminal_keeps_its_emoji() -> None:
+    """Windows Terminal, VS Code's terminal and ssh all draw them; nothing changes."""
+    verdict = _emoji_support({}, console_probe=lambda: False, system="win32")
+    assert (verdict.supported, verdict.source) == (True, "console")
+
+
+def test_an_unanswerable_probe_never_degrades_the_ui() -> None:
+    """No console to identify (redirected output, a failed call) leaves emoji on.
+
+    An unknown is not evidence of a limit. Degrading on one would strip the icons from
+    every piped or redirected run, which is most of the test suite and all of CI.
+    """
+    verdict = _emoji_support({}, console_probe=lambda: None, system="win32")
+    assert (verdict.supported, verdict.source) == (True, "no-console")
+
+
+def test_the_override_beats_the_probe_both_ways() -> None:
+    """``MESHTERM_EMOJI`` wins, as the powerline gate's override does.
+
+    Someone on a console this cannot recognise knows their own glass better than a probe
+    does — and the negative direction is how anyone asks for the compact icons on purpose.
+    """
+    forced_on = _emoji_support({"MESHTERM_EMOJI": "1"}, console_probe=lambda: True, system="win32")
+    assert (forced_on.supported, forced_on.source) == (True, "env")
+
+    def never_called() -> bool | None:
+        raise AssertionError("the override decides before the probe runs")
+
+    forced_off = _emoji_support({"MESHTERM_EMOJI": "0"}, console_probe=never_called, system="linux")
+    assert (forced_off.supported, forced_off.source) == (False, "env")
+
+
+def test_an_inherited_wt_session_cannot_speak_for_the_host() -> None:
+    """The environment is not consulted, and this is why.
+
+    ``WT_SESSION`` is inherited by child processes, so a program launched from Windows
+    Terminal into a console of its own still carries it — measured, not supposed. Reading
+    it would have answered for the terminal that did the launching.
+    """
+    env = {"WT_SESSION": "670f6626-8bdf-4c09-9164-b1eef91abe4f"}
+    verdict = _emoji_support(env, console_probe=lambda: True, system="win32")
+    assert verdict.supported is False
+
+
+def test_identifying_the_host_never_raises() -> None:
+    """Whatever this machine is, asking is safe and answers one of three things.
+
+    It runs on a startup path, so "it degrades rather than raises" is the property that
+    keeps an unusual host from taking the app down with it.
+    """
+    assert _is_classic_console() in (True, False, None)

tests/test_theme16.py

@@ -150,6 +150,24 @@ def test_every_glyph_map_target_is_in_the_console_font() -> None:
             )
 
 
+def test_every_glyph_map_target_stays_inside_the_bmp() -> None:
+    """The table has a second consumer that the console font cannot speak for.
+
+    The classic Windows console keeps one 16-bit code unit per cell, so a character above
+    U+FFFF is replaced by U+FFFD before its font is ever consulted — which is why MeshTerm
+    routes icons through this table there too (see
+    :func:`meshterm.ui.termfont.emoji_support`). A substitute "improved" into an emoji
+    would draw fine on the PicoCalc's own font and silently break every Windows console,
+    so the plane is asserted here rather than left to the font whitelist to imply.
+    """
+    for emoji, compact in theme._GLYPH_MAP.items():
+        for ch in compact:
+            assert ord(ch) <= 0xFFFF, (
+                f"{emoji!r} maps to {compact!r}; {ch!r} is above U+FFFF and no classic "
+                f"Windows console can hold it"
+            )
+
+
 def test_glyph_map_targets_never_widen_their_icon() -> None:
     """A compact form at most matches its emoji's measured width (the fold pads the rest)."""
     for emoji, compact in theme._GLYPH_MAP.items():

tests/test_win32dll.py

@@ -0,0 +1,81 @@
+"""Tests for the private Windows DLL handles.
+
+These pin a crash that only ever appeared in a frozen build on Windows, which is the
+worst place for a bug to live: no traceback survived, because the window it was printed
+in was destroyed by the same exit that printed it.
+
+``ctypes.windll.kernel32`` is a cache shared by the whole process. MeshTerm's emoji-width
+probe declared ``GetConsoleScreenBufferInfo`` as taking a pointer to its own copy of the
+screen-buffer struct; prompt_toolkit then called that same function object with a pointer
+to *its* copy — same layout, different class — and ctypes refused the call while the app
+was building its screen.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import sys
+
+import pytest
+
+from meshterm.core import win32dll
+
+pytestmark = pytest.mark.skipif(sys.platform != "win32", reason="Windows libraries")
+
+
+def test_each_handle_is_its_own() -> None:
+    """Two callers get two objects, so neither can see the other's declarations."""
+    assert win32dll.kernel32() is not win32dll.kernel32()
+    assert win32dll.user32() is not win32dll.user32()
+
+
+def test_the_shared_windll_is_the_thing_being_avoided() -> None:
+    """The premise: ``ctypes.windll`` hands the same function object to every caller.
+
+    If this ever stops being true the module is unnecessary — but until then it is the
+    reason it exists, so it is worth asserting rather than assuming.
+    """
+    first = ctypes.windll.kernel32.GetConsoleScreenBufferInfo
+    second = ctypes.windll.kernel32.GetConsoleScreenBufferInfo
+    assert first is second
+
+
+def test_declaring_a_signature_does_not_reach_the_shared_one() -> None:
+    """The regression itself: our declarations must not be visible to anyone else.
+
+    Before this module existed, the assignment below rewrote the signature that
+    prompt_toolkit's console output later called through, and the application died on
+    startup with ``expected LP__CSBI instance instead of pointer to
+    CONSOLE_SCREEN_BUFFER_INFO``.
+    """
+
+    class _MineAlone(ctypes.Structure):
+        _fields_ = [("whatever", ctypes.c_int)]
+
+    shared = ctypes.windll.kernel32.GetConsoleScreenBufferInfo
+    before = shared.argtypes
+
+    private = win32dll.kernel32()
+    private.GetConsoleScreenBufferInfo.argtypes = [
+        ctypes.c_void_p,
+        ctypes.POINTER(_MineAlone),
+    ]
+
+    assert ctypes.windll.kernel32.GetConsoleScreenBufferInfo.argtypes == before
+    assert private.GetConsoleScreenBufferInfo is not shared
+
+
+def test_the_probe_leaves_the_shared_signature_alone() -> None:
+    """End to end: running the emoji probe must not disturb the process-wide function.
+
+    The narrow assertion above can pass while the real call site still reaches for
+    ``ctypes.windll``, so this exercises the code that actually crashed.
+    """
+    from meshterm.ui.tui import emoji_width
+
+    shared = ctypes.windll.kernel32.GetConsoleScreenBufferInfo
+    before = shared.argtypes
+    # No console under pytest, so this returns None rather than measuring. That is fine:
+    # the declarations happen before the first call either way, which is what matters.
+    emoji_width._win_probe_width("x")  # noqa: SLF001 - the point is this private path
+    assert ctypes.windll.kernel32.GetConsoleScreenBufferInfo.argtypes == before

tests/test_winterminal.py

@@ -0,0 +1,75 @@
+"""Tests for reopening the session in Windows Terminal.
+
+Nothing here starts a terminal. What is pinned is the command that *would* be run — which
+is the part that can be silently wrong, because a mistake in it produces a window that
+opens, fails, and closes faster than anyone can read it.
+"""
+
+from __future__ import annotations
+
+import sys
+
+import pytest
+
+from meshterm.core import winterminal
+
+
+def test_it_is_only_ever_windows(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Every other platform's terminal already draws the whole app; there is nothing to fix."""
+    monkeypatch.setattr(sys, "platform", "linux")
+    assert winterminal.available() is None
+    assert winterminal.reopen() is False
+
+
+def test_a_reopened_session_never_offers_to_reopen_again(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The loop guard. Windows Terminal would not qualify anyway, and this is the backstop.
+
+    A relaunch that could chain is not a cosmetic bug: each one spawns a window and exits,
+    so the reader would watch windows open forever.
+    """
+    monkeypatch.setattr(sys, "platform", "win32")
+    monkeypatch.setenv(winterminal.REOPENED_ENV, "1")
+    assert winterminal.available() is None
+    assert winterminal.reopen() is False
+
+
+def test_a_frozen_build_relaunches_itself(monkeypatch: pytest.MonkeyPatch) -> None:
+    """The installer's own executable takes the arguments exactly as they were given."""
+    monkeypatch.setattr(sys, "frozen", True, raising=False)
+    monkeypatch.setattr(sys, "executable", r"C:\Downloads\meshterm.exe")
+    monkeypatch.setattr(sys, "argv", ["meshterm", "--mock", "--profile", "home"])
+    assert winterminal.own_command() == [
+        r"C:\Downloads\meshterm.exe",
+        "--mock",
+        "--profile",
+        "home",
+    ]
+
+
+def test_a_source_install_relaunches_through_its_interpreter(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``-m meshterm``, not the console script.
+
+    The script's path is a wrapper whose location varies by install method (venv, pipx,
+    user site), while the interpreter running us is a fact we already hold. Using the
+    interpreter also guarantees the new window gets the same environment as this one.
+    """
+    monkeypatch.delattr(sys, "frozen", raising=False)
+    monkeypatch.setattr(sys, "executable", r"C:\venv\Scripts\python.exe")
+    monkeypatch.setattr(sys, "argv", ["meshterm", "--mock"])
+    assert winterminal.own_command() == [r"C:\venv\Scripts\python.exe", "-m", "meshterm", "--mock"]
+
+
+def test_the_program_name_is_never_passed_on_as_an_argument(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """``argv[0]`` is how this process was named, not something to hand to the next one.
+
+    Passing it through would reach MeshTerm as a stray positional argument and be rejected
+    by Typer — in a brand new window that then closes.
+    """
+    monkeypatch.setattr(sys, "frozen", True, raising=False)
+    monkeypatch.setattr(sys, "executable", r"C:\meshterm.exe")
+    monkeypatch.setattr(sys, "argv", [r"C:\some\other\name.exe"])
+    assert winterminal.own_command() == [r"C:\meshterm.exe"]