v0.31.8 — Windows Desktop Frame

v0.31.8 — Windows Desktop Frame

Date: 2026-08-07

Highlights

• Adds the native Windows Desktop Frame: guided first-run onboarding, tabbed Pi
  conversations over real ConPTY sessions, setup health, persona inspection,
  subscription login, and controlled Pi maintenance in one window.
• Makes the Frame the primary Windows shortcut while preserving Mirror Mind (Terminal) as an independent recovery and maintenance path.
• Pins Pi exactly to the homologated 0.83.0 release; install and update paths
  converge absent, older, and newer versions to that pin and never use @latest.
• Gates every Frame PTY through one session authority so Pi cannot update while
  Mirror, login, shell, or bootstrap sessions are open.
• Packages the Frame and its native ConPTY dependency through one fail-closed
  build path before compiling installer 0.31.0.
• Validates the integrated release on Python 3.10/3.12, TypeScript, documentation,
  Pester, PSScriptAnalyzer, 63 Frame tests, session simulation, packaged
  Electron/ConPTY, and a real non-ASCII USERPROFILE smoke.

Where We Started

The existing Windows installer could bootstrap Mirror Mind and open Pi in a
terminal, but the experience still exposed installation and runtime mechanics as
the product. First-run identity setup, subscription login, health diagnosis, and
conversation management were separate terminal interactions. That path remained
valuable for recovery, but it was not yet the coherent desktop experience tested
through the ES-004 functional mockup.

The first Frame proposal proved the product direction and a viable
Electron/ConPTY stack. Release review then exposed a stricter boundary: a native
window also becomes an installer, updater, credential-transit, native-binary,
and session-lifecycle responsibility. Shipping it required more than rendering a
terminal inside Electron.

What Changed

The Frame now installs as a private component of Mirror Mind and follows the
Mirror release version. Its renderer runs sandboxed with context isolation and no
Node integration. A narrow preload API reaches main-process handlers that verify
their sender, reject unexpected navigation and windows, validate environment
values against CR/LF injection, and execute only fixed command-registry entries.
Pi owns OAuth tokens; the Frame observes only readiness and completion signals.

Onboarding performs the real .env → memory init → seed flow and remains
recoverable when initialization fails. Reinstalling preserves the identity home
without silently rebinding it. The user explicitly enters the same identity name,
and OpenRouter credentials remain guarded transient state until persistence.

All PTYs participate in one SessionGate. Mirror conversations, hidden login,
system terminals, and bootstrap sessions prevent a concurrent Pi update. The
homologated Pi version lives in installer/pi-version.txt; both installer and
packaged Frame read that installed authority and converge precisely to 0.83.0.
A missing or malformed pin disables automatic Pi maintenance rather than falling
back to an uncontrolled version.

Packaging is now reproducible outside CI. frame/scripts/package.ps1
materializes the pinned Electron binary, assembles runtime dependencies, and
feeds one verified payload into Inno Setup. Missing MirrorFrame.exe, ConPTY,
preload, renderer, or required assets aborts the build. CI follows the same
npm ci → tests → simulator → package → verify → installer → smoke → upload
route and exercises the installed path under a genuinely non-ASCII Windows user
profile.

Distribution Boundary

The downloadable artifact is MirrorMind-Setup-0.31.0.exe. Installer versioning
is independent because 0.31.0 describes the materially changed bootstrapper;
the Frame inside it is version 0.31.8, matching Mirror itself.

The installer is not code-signed in this release. Windows SmartScreen may warn
before execution. The release publishes a SHA-256 checksum so users can verify
the exact artifact produced by the integrated GitHub Actions run.

Conscious Exclusions

• No automatic Mirror-core update inside the Frame. The installed Frame and
  core move together through a new installer; conscious manual maintenance
  remains available through the Terminal shortcut.
• No unpinned Pi channel. Moving beyond Pi 0.83.0 requires rerunning the
  login, OAuth, fallback, and update compatibility matrix.
• No code-signing certificate. The first installer remains unsigned, with
  the SmartScreen consequence documented rather than hidden.
• No Microsoft Store distribution or TD-003 transport work. Those require a
  separate delivery and trust boundary.
• No Python-core redesign. The Frame orchestrates the existing CLI and does
  not alter the core under src/memory/.
• No in-executable Mirror icon stamping. Installer shortcuts and the window
  carry Mirror branding, while the executable resource may still show Electron's
  default icon in some Windows surfaces.

What We Learned

A desktop shell is not merely a new presentation layer. Once it owns onboarding,
PTYs, updates, and installation, correctness depends on authority boundaries that
remain valid when the renderer is wrong, the path contains spaces or accents,
the native ABI differs from ordinary Node, or a setup attempt fails halfway.
Making those boundaries executable in the canonical packaging and CI route was
what turned the Frame from a promising prototype into a releasable Windows path.

Next Horizon

The next evidence should come from installing the exact release asset on a clean
Windows environment and observing real onboarding and daily conversation use.
Code signing, executable-resource branding, broader distribution, and any future
Frame-aware core updater remain separate decisions informed by that use.

Release Artifact

• Windows installer: MirrorMind-Setup-0.31.0.exe
• SHA-256: 27A1CD58154AF13A3E2205BD85FF09C7413C3ACB57103931026E0EA14895085B
• Signing: unsigned; Windows SmartScreen may display a warning.