Skip to content

Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.

feat(windows): preserve tray identity in signed production builds (#2272)

Joshuaa77fdce34dbc
diff --git a/CLAUDE.md b/CLAUDE.md
index dd01a4b2e..fee16f8a9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -882,6 +882,9 @@ UI icons come from `src/components/icons/` (vendored Nucleo core outline compone
- **Launch at login**: `HKCU\...\Run` entry written by Electron, named after the AppUserModelId, carrying `--hidden` so a login launch goes to the tray
- Read the state from `executableWillLaunchAtLogin`; `openAtLogin` misses a startup app disabled from Task Manager or Settings
- `resources/nsis/installer.nsh` removes the `Run` and `StartupApproved\Run` values on uninstall (but not on update), which Electron itself never cleans up
+- **Tray identity**: signed production builds pass a permanent GUID to `new Tray()` (`tray.js`) so Windows keeps the user's tray placement across updates. Never change the GUID
+ - Windows binds an unsigned executable's GUID to its path, so the GUID is gated on the `windowsTrayIdentity` marker that `electron-builder.json` injects through `extraMetadata`
+ - `electron-builder.json` forces Windows code signing; unsigned Windows builds (PR CI, local) must use `electron-builder.unsigned-win.json`, which clears the marker. Never run the `win-unpacked` a failed signed build leaves behind: it carries the marker and may be unsigned
- **Push-to-Talk**: Native key listener binary (`windows-key-listener.exe`) enables true push-to-talk
- Uses Windows Low-Level Keyboard Hook (`WH_KEYBOARD_LL`)
- Supports compound hotkeys (e.g., `Ctrl+Shift+F11`)
diff --git a/docs/superpowers/specs/2026-09-21-windows-tray-identity-design.md b/docs/superpowers/specs/2026-09-21-windows-tray-identity-design.md
new file mode 100644
index 000000000..898a5babf
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-21-windows-tray-identity-design.md
@@ -0,0 +1,96 @@
+# Windows tray identity design
+
+Date: 2026-09-21
+Branch: `feat/windows-tray-identity`
+
+## Outcome and boundary
+
+Give the signed production Windows tray icon one permanent identifier so Windows can associate the user's visibility and ordering choices with the same icon after relaunches and updates. This improves identity; Windows and the user still control visibility and ordering. The first release adopting this identity may require the user to arrange the icon once again.
+
+macOS has its own tray GUID from #2267; this change does not reuse it. Do not programmatically promote the Windows icon out of overflow or position it beside system controls.
+
+## Decision
+
+Use Electron's supported `new Tray(image, guid)` only when all three conditions hold:
+
+1. `process.platform === "win32"`.
+2. The channel already resolved by `main.js` is `process.env.OPENWHISPR_CHANNEL === "production"`.
+3. The packaged `package.json` contains `windowsTrayIdentity: true`.
+
+Use the permanent Windows production GUID **`9afd9bd5-53da-42ef-8334-6e2b494c66fe`**. Keep it unchanged across versions and executable paths. Every other Windows case, and Linux, keeps calling `new Tray(image)` with exactly one argument.
+
+`main.js` resolves and sets the channel before loading `TrayManager`, so the tray reuses that value instead of inferring a second one. Development and staging have their own profile and single-instance lock, so they can run beside production. They receive no GUID, even when packaged and signed, so they cannot claim the production identifier.
+
+Installed and portable production builds share this identity. Both use the production profile and the same single-instance lock, so they never run at the same time. Native acceptance must exercise the extracted portable executable, whose temporary path can change between builds.
+
+## Signing contract
+
+The marker tells the runtime that the build came from the signed configuration:
+
+- `electron-builder.json` sets `extraMetadata.windowsTrayIdentity: true` and `win.forceCodeSigning: true`.
+- `electron-builder.unsigned-win.json` (PR CI and local unsigned builds) overrides the marker to `false` and `win.forceCodeSigning` to `false`, next to its existing `win.azureSignOptions: null`.
+- The source `package.json` never carries the marker, so development runs never see it. Electron-builder injects it into the packaged metadata.
+
+Electron-builder 26 already fails a marked build that would ship unsigned. With Azure configured, its signer returns true or throws, so a failed Trusted Signing call (the PowerShell module exiting nonzero) stops the build. `forceCodeSigning` covers the rest: it fails a default-config build that nulls `win.azureSignOptions` without switching to the unsigned configuration (signtool then finds no certificate and returns false), and it rejects `signExecutable: false` and `signAndEditExecutable: false`. It does not catch deliberate opt-outs that keep the marker: a `signExts` rule excluding the main executable (`signIf()` returns before the `forceCodeSigning` check), a custom signtool `sign` hook that skips signing, or overriding `forceCodeSigning` on the default configuration. Build unsigned Windows packages only with the unsigned configuration; no packaging guard is added for those cases.
+
+A signed build that fails at signing still leaves a `dist/win-unpacked` carrying the marker, and it may be unsigned. Never launch it: an unsigned run binds the production GUID to its path, and the signed install on the same machine may then get no tray icon. Run native acceptance on a clean VM snapshot.
+
+The marker is a build contract, not a runtime tamper detector. Before native acceptance or release, verify that the **running inner executable** has a valid Authenticode signature and a publisher subject containing `O=Gizmo Labs Inc.`. Keep that organization consistent across releases; an Azure account, profile, or publisher change requires fresh identity acceptance.
+
+## Why this approach
+
+| Option | Assessment |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Marked package + enforced signing | Selected. Small runtime change; uses the existing signed and unsigned configurations; supports one identity across signed install and portable paths. Relies on electron-builder's own signing enforcement. |
+| One GUID for every Windows build | Unsafe for unsigned copies: Windows binds an unsigned GUID to its executable path, and a moved copy may fail to add its icon. |
+| Deterministic GUID derived from executable path | Avoids reusing an unsigned identity at a new path, but loses the useful cross-path behavior for signed installs and changing portable extraction paths. Adds identity hashing without satisfying this outcome. |
+| Runtime Authenticode check | Could check the actual binary, but adds a Windows subprocess, launch delay, timeout/policy failures, and a second identity when verification is unavailable. Unnecessary for the controlled build contract. |
+| Marker written from `afterSign` alone | Insufficient: builder 26.15.3 `signApp()` can return true on an unsigned build, causing `afterSign` to run. Actual signature verification would need another build process; forcing signing is smaller. |
+
+No retry with a different GUID is added. Electron 41.10.5 logs a failed native `Shell_NotifyIcon(NIM_ADD)` call without throwing to JavaScript, so the existing `try/catch` cannot detect or repair it. A broken identity means no tray icon at all, which is why native acceptance gates the release.
+
+## Constraints
+
+- Windows identity/persistence only; visibility and exact placement remain controlled by Windows and the user.
+- No new native helpers, dependencies, runtime subprocesses, registry edits, shell restarts, private APIs, or simulated dragging.
+- Preserve existing icon loading, menu actions, tooltip, click handling, error handling, and macOS/Linux behavior.
+- Native acceptance scope: Windows 10 x64 and Windows 11 x64, with exact OS builds and app/artifact versions recorded.
+- Run native acceptance before the first release that ships this identity.
+
+## Validation and acceptance
+
+Automated tests (`test/helpers/trayPlacement.test.js`, shared with the macOS GUID) pin the GUID for marked production Windows builds and check that Linux, development, staging, and a missing or `false` marker keep the one-argument constructor. They cannot prove the signature of a build artifact.
+
+Native evidence, for each Windows version:
+
+1. Record the existing released app's tray state, adopt the candidate signed installer, and record whether first adoption preserves or resets it.
+2. Manually promote/reorder the icon, quit normally, relaunch twice, reboot, then upgrade to a second candidate signed on a different day. Azure Trusted Signing issues short-lived certificates that rotate daily, so this pair checks that Windows keys the GUID to the publisher rather than to one certificate. Record visibility and order after each step.
+3. End the app from Task Manager, then relaunch. A failed icon add is only logged, so confirm the icon returns after a process that never removed it, not only after a normal quit.
+4. Put the icon back in overflow and repeat relaunch/update checks to prove the user's hidden choice is respected.
+5. Repeat at another installation path and with two signed portable versions. Record each running inner executable's path, signature status, subject, version, and SHA; moving only the outer portable launcher is insufficient.
+6. Run unsigned production packages and development/staging variants from two paths. Their tray must remain usable, and a separately runnable channel must not take over production's identity.
+7. Check left-click toggle, right-click menu, quick actions, quit, and no extra icons. Record actual ordering without claiming guaranteed adjacency to Windows controls.
+
+Identify the running executable and its signature in PowerShell, choosing the main process id from the first command:
+
+```powershell
+Get-Process OpenWhispr | Select-Object Id, Path
+$trayProcessId = Read-Host 'OpenWhispr main process id'
+$trayExePath = (Get-Process -Id $trayProcessId).Path
+$traySignature = Get-AuthenticodeSignature -LiteralPath $trayExePath
+$traySignature | Select-Object Status, Path, @{Name='Subject';Expression={$_.SignerCertificate.Subject}}
+Get-FileHash -LiteralPath $trayExePath -Algorithm SHA256
+Get-CimInstance Win32_OperatingSystem | Select-Object Caption, Version, BuildNumber
+```
+
+Require `Status: Valid` and a subject containing `O=Gizmo Labs Inc.` before treating a build as the signed case. Do not edit the registry, restart Explorer, or force icon placement to manufacture a passing result.
+
+Status: no native Windows session, signed candidate, or update pair has been exercised yet. Every step above is unverified.
+
+## Evidence
+
+- [Electron 41.10.5 tray contract](https://github.com/electron/electron/blob/v41.10.5/docs/api/tray.md#new-trayimage-guid) and [native add implementation](https://github.com/electron/electron/blob/v41.10.5/shell/browser/ui/win/notify_icon.cc).
+- [Microsoft notification identity rules](https://learn.microsoft.com/en-us/windows/win32/api/shellapi/ns-shellapi-notifyicondataw#troubleshooting) and [preference retention](https://devblogs.microsoft.com/oldnewthing/20171027-00/?p=97296).
+- [Electron-builder v26 metadata/signing configuration](https://www.electron.build/v26/docs/configuration/) and [Windows options](https://www.electron.build/v26/docs/win/). Current v27 documentation has different signing option names; use v26 here.
+- [Microsoft Authenticode inspection](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.security/get-authenticodesignature?view=powershell-7.5).
+- Installed builder sources (26.15.3): `node_modules/app-builder-lib/out/winPackager.js:106-132,234-239` (signing and `forceCodeSigning` checks), `platformPackager.js:610-613` (`forceCodeSigning` resolution), `packager.js:276-277` and `fileTransformer.js:88-91` (`extraMetadata` merged and written into the packaged `package.json`), `codeSign/windowsSignAzureManager.js:46-69` (Trusted Signing).
diff --git a/electron-builder.json b/electron-builder.json
index f04d8edd4..9a5dd6663 100644
--- a/electron-builder.json
+++ b/electron-builder.json
@@ -1,6 +1,9 @@
{
"appId": "com.gizmolabs.openwhispr",
"afterPack": "scripts/afterPack.js",
+ "extraMetadata": {
+ "windowsTrayIdentity": true
+ },
"productName": "OpenWhispr",
"protocols": {
"name": "OpenWhispr Protocol",
@@ -176,6 +179,7 @@
"win": {
"target": ["nsis", "portable"],
"icon": "src/assets/icon.ico",
+ "forceCodeSigning": true,
"azureSignOptions": {
"endpoint": "https://eus.codesigning.azure.net/",
"certificateProfileName": "openwhispr-release",
diff --git a/electron-builder.unsigned-win.json b/electron-builder.unsigned-win.json
index a8e7ea6a7..c68378f7c 100644
--- a/electron-builder.unsigned-win.json
+++ b/electron-builder.unsigned-win.json
@@ -1,6 +1,10 @@
{
"extends": "electron-builder.json",
+ "extraMetadata": {
+ "windowsTrayIdentity": false
+ },
"win": {
- "azureSignOptions": null
+ "azureSignOptions": null,
+ "forceCodeSigning": false
}
}
diff --git a/src/helpers/tray.js b/src/helpers/tray.js
index 76ca273b1..d9cc77196 100644
--- a/src/helpers/tray.js
+++ b/src/helpers/tray.js
@@ -4,6 +4,12 @@ const fs = require("fs");
const debugLogger = require("./debugLogger");
const dockManager = require("./dockManager");
const { i18nMain } = require("./i18nMain");
+const { windowsTrayIdentity } = require("../../package.json");
+
+// Permanent identity for signed production Windows builds; keep across releases.
+// Windows binds an unsigned executable's GUID to its path, so only builds from the
+// signed config, which sets windowsTrayIdentity, may use it.
+const WINDOWS_PRODUCTION_TRAY_GUID = "9afd9bd5-53da-42ef-8334-6e2b494c66fe";
// macOS saves the menu-bar position under this GUID, so changing it resets every
// user's placement. Electron lowercases the GUID before handing it to macOS, so
@@ -152,6 +158,14 @@ class TrayManager {
systemPreferences.registerDefaults({ [MACOS_TRAY_POSITION_KEY]: 0 });
this.tray = new Tray(trayIcon, MACOS_TRAY_GUID);
this.tray.setIgnoreDoubleClickEvents(true);
+ } else if (
+ process.platform === "win32" &&
+ process.env.OPENWHISPR_CHANNEL === "production" &&
+ windowsTrayIdentity === true
+ ) {
+ // Other channels have their own profile and single-instance lock, so they can
+ // run beside production and must not claim its GUID.
+ this.tray = new Tray(trayIcon, WINDOWS_PRODUCTION_TRAY_GUID);
} else {
this.tray = new Tray(trayIcon);
}
diff --git a/test/helpers/trayPlacement.test.js b/test/helpers/trayPlacement.test.js
index 60c44228b..cd8f14b02 100644
--- a/test/helpers/trayPlacement.test.js
+++ b/test/helpers/trayPlacement.test.js
@@ -4,15 +4,16 @@ const fs = require("node:fs");
const path = require("node:path");
const vm = require("node:vm");
-// Spelled out rather than imported: a new GUID resets every user's saved
-// menu-bar position, so changing it should fail here.
-const TRAY_GUID = "eb809902-04b5-5b08-b12a-f81d6f27e185";
+// Spelled out rather than imported: a new GUID resets every user's saved tray
+// position, so changing either should fail here.
+const MACOS_TRAY_GUID = "eb809902-04b5-5b08-b12a-f81d6f27e185";
+const WINDOWS_TRAY_GUID = "9afd9bd5-53da-42ef-8334-6e2b494c66fe";
const trayPath = path.join(__dirname, "../../src/helpers/tray.js");
const traySource = fs.readFileSync(trayPath, "utf8");
-// Runs tray.js in its own context so each test picks a platform without
-// touching the real process.platform.
-async function createTrayOn(platform) {
+// Runs tray.js in its own context so each test picks a platform, channel, and
+// packaged metadata without touching the real process.
+async function createTrayOn(platform, { channel = "production", metadata = {} } = {}) {
const calls = [];
const icon = { isEmpty: () => false };
const stubs = {
@@ -35,6 +36,7 @@ async function createTrayOn(platform) {
registerDefaults: (defaults) => calls.push(["register", { ...defaults }]),
},
},
+ "../../package.json": metadata,
"./debugLogger": { error: (...args) => calls.push(["error", ...args]) },
"./dockManager": {},
"./i18nMain": { i18nMain: { t: (key) => key } },
@@ -44,7 +46,7 @@ async function createTrayOn(platform) {
traySource,
{
module: loadedModule,
- process: { platform },
+ process: { platform, env: { OPENWHISPR_CHANNEL: channel } },
require: (specifier) => stubs[specifier] ?? require(specifier),
},
{ filename: trayPath }
@@ -56,19 +58,33 @@ async function createTrayOn(platform) {
return { calls, icon };
}
+const signedBuild = { windowsTrayIdentity: true };
+
test("macOS registers the starting position before creating its tray under the fixed GUID", async () => {
const { calls, icon } = await createTrayOn("darwin");
assert.deepEqual(calls, [
- ["register", { [`NSStatusItem Preferred Position ${TRAY_GUID}`]: 0 }],
- ["construct", icon, TRAY_GUID],
+ ["register", { [`NSStatusItem Preferred Position ${MACOS_TRAY_GUID}`]: 0 }],
+ ["construct", icon, MACOS_TRAY_GUID],
["ignoreDoubleClick", true],
]);
});
-for (const platform of ["win32", "linux"]) {
- test(`${platform} creates its tray without a GUID or a starting position`, async () => {
- const { calls, icon } = await createTrayOn(platform);
+test("a signed production Windows build creates its tray under the fixed Windows GUID", async () => {
+ const { calls, icon } = await createTrayOn("win32", { metadata: signedBuild });
+
+ assert.deepEqual(calls, [["construct", icon, WINDOWS_TRAY_GUID]]);
+});
+
+for (const [label, platform, options] of [
+ ["Windows without the build marker", "win32", {}],
+ ["unsigned Windows", "win32", { metadata: { windowsTrayIdentity: false } }],
+ ["development Windows", "win32", { channel: "development", metadata: signedBuild }],
+ ["staging Windows", "win32", { channel: "staging", metadata: signedBuild }],
+ ["Linux", "linux", { metadata: signedBuild }],
+]) {
+ test(`${label} creates its tray without a GUID or a starting position`, async () => {
+ const { calls, icon } = await createTrayOn(platform, options);
assert.deepEqual(calls, [["construct", icon]]);
});