feat(desktop): add Windows support with an NSIS installer and release job (#81)

## Related Issue

No prior issue. The problem is described below.

## Problem

`apps/desktop` shipped a macOS-only application. `build.win` used the
`dir`
target, which emits an unpacked directory and no installer, so Windows
had
nothing to distribute and `electron-updater` had no `latest.yml` feed to
read.

Three Windows defects also lived in the shell itself, each dead or wrong
code
rather than a missing feature:

- `host-supervisor.ts` terminated the Host with `child.kill()`. Windows
has no
signal delivery, so that is `TerminateProcess` on one PID and the Host's
own
children — node-pty shells, subagent hosts — survived and kept holding
the
  loopback port.
- The packaged-runtime guard tested `nodeExecutable.includes('/')`,
which is
never true for `C:\...\Pythinker.exe`. The check could not fire on
Windows.
- No `app.setAppUserModelId`, so taskbar pinning did not survive an
installer
  upgrade and toasts were attributed to a generated identity.

Separately, `apps/desktop`'s 65 vitest cases and its typecheck script
ran in no
required check, so a desktop regression merged green.

## What changed

**Windows packaging** — per-user NSIS installer (`oneClick: false`,
`perMachine: false`, elevation allowed, installation directory
selectable,
desktop and Start Menu shortcuts), `dist:win`, and a `windows-latest`
release
job running in parallel with `mac`. `verify-win-installer.ts` sniffs the
DOS and
PE headers of both artifacts rather than trusting the file extension.

`dist:win` refuses to run anywhere but native Windows x64. This is not
caution:
`stage-runtime.ts` runs `pnpm deploy` on the build machine, and the
closure
resolves platform-gated natives — a macOS-staged tree carries
`@opentui/core-darwin-arm64` and cannot produce a working Windows build.

**Windows runtime** — tree kill via `taskkill /T /F`, `isAbsolute()` for
the
artifact guard, `setAppUserModelId`, and an `afterPack` check for the
win32
`node-pty` prebuilds.

**Release workflow** — an unset GitHub secret interpolates to an empty
string,
not to an absent variable, and electron-builder resolves an empty
`CSC_LINK` as
a certificate path: `path.resolve(appDir, '')` is the app directory, so
the
macOS job died on `not a file`. Credentials are now exported only when
they
carry a value, which also fixed the pre-existing macOS failure. Windows
artifacts are unsigned until `WIN_CSC_LINK` and `WIN_CSC_KEY_PASSWORD`
are
configured; the job passes them through, so enabling signing needs no
code
change.

**Staging** — Node refuses to spawn a `.cmd` shim without a shell, so
`pnpm.cmd`
raised `EINVAL`. And pnpm joins its workspace root with the deploy
target rather
than resolving it, so an absolute path on another volume became
`D:\repo\C:\Users\...`. The target is now workspace-relative, which is
correct
whether pnpm joins or resolves, and the staging directory moved onto the
repository's own volume.

**CI gates** — `apps/desktop` registered in the root vitest projects,
plus a
per-package typecheck step. Deliberately not added to the `tsgo` loop,
which
covers the source tsconfig and would silently skip
`tests/tsconfig.json`.

Out of scope, and left alone: the reference implementation's Windows ACL
runner
and pwsh sandbox trampoline (`packages/kaos` and `agent-core` carry
their own
win32 handling), Windows arm64, Linux packaging, and signing
certificates.
`apps/vscode` has the same CI-gate omission; that is pre-existing and
belongs in
its own change.

## How this was verified

Windows packaging cannot be validated on a macOS workstation, so the
proof is a
green CI run, not a local claim.

Run
[31914773126](https://github.com/PyModel/pythinker-code/actions/runs/31914773126)
— `mac: success`, `windows: success`:

```
• building  target=nsis file=dist\Pythinker-0.1.0-x64-Setup.exe archs=x64 oneClick=false perMachine=false
• building block map  blockMapFile=dist\Pythinker-0.1.0-x64-Setup.exe.blockmap
• uploading  file=Pythinker-0.1.0-x64-Setup.exe provider=github
```

Artifacts: `desktop-windows` 134 MB, `desktop-macos` 329 MB, with
`latest.yml`
and a `.blockmap` so Windows auto-update downloads differentially.

Three earlier runs failed and each fix is a separate commit, so the
sequence is
reviewable: `EINVAL` on `.cmd`, then empty signing credentials, then the
pnpm
deploy target.

Locally, every added test was mutation-proved — the guard was reverted,
the test
was watched go red, then restored and watched go green. That includes
the new CI
gate itself: breaking a desktop test now fails root `pnpm run test` with
`FAIL |@pymodel/pythinker-desktop| tests/stage-runtime.spec.ts`, which
it could
not do before this change.

Full root suite: 682 files, 10184 passed, 71 skipped. Desktop typecheck
and
`pnpm run lint` both exit 0.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [x] I have linked a related issue, or explained the problem above.
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added Windows x64 NSIS installer packaging with customizable
installation location, shortcuts, and optional signing.
  * Added a Windows desktop release workflow and distribution command.
* **Bug Fixes**
* Improved Windows process-tree shutdown and packaged runtime
validation.
  * Fixed Windows application identity and runtime staging behavior.
* Added installer validation to catch invalid or incomplete release
artifacts.
* **Documentation**
* Documented Windows packaging requirements, installer output, signing
options, and current platform limitations.
* **Tests**
* Expanded automated coverage for Windows packaging, staging, runtime
checks, and process termination.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

.changeset/desktop-taskkill-timeout.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-desktop': patch
+---
+
+Bound the Windows process-tree kill so a stalled taskkill cannot freeze desktop shutdown

.changeset/desktop-windows-ci-fixes.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-desktop': patch
+---
+
+Fix Windows runtime staging and skip empty signing credentials in the desktop release workflow

.changeset/desktop-windows-deploy-target.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-desktop': patch
+---
+
+Stage the desktop Host closure inside the workspace so pnpm deploy resolves the target on Windows

.changeset/desktop-windows-packaging.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-desktop': patch
+---
+
+Add the Windows NSIS installer target, release script, and release workflow job

.changeset/desktop-windows-runtime.md

@@ -0,0 +1,5 @@
+---
+'@pymodel/pythinker-desktop': patch
+---
+
+Fix Windows process-tree shutdown, packaged-runtime guards, and taskbar identity in the desktop app

.github/workflows/ci.yml

@@ -88,3 +88,5 @@ jobs:
         run: pnpm --filter @pymodel/dashboard-server run typecheck
       - name: Typecheck dashboard-web
         run: pnpm --filter @pymodel/dashboard-web run typecheck
+      - name: Typecheck desktop
+        run: pnpm --filter @pymodel/pythinker-desktop run typecheck

.github/workflows/desktop-release.yml

@@ -51,16 +51,33 @@ jobs:
       # Without Developer ID signing secrets, electron-builder publishes an
       # ad-hoc/self-signed app. macOS auto-update will not accept unsigned updates,
       # but this still proves packaging and the feed shape.
+      # An unset GitHub secret interpolates to an empty string, and
+      # electron-builder resolves an empty CSC_LINK as a certificate path
+      # (path.resolve(appDir, '') === appDir), failing with "not a file".
+      # Export only the variables that carry a value.
+      - name: Resolve macOS signing credentials
+        shell: bash
+        env:
+          IN_CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
+          IN_CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
+          IN_APPLE_ID: ${{ secrets.APPLE_ID }}
+          IN_APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          IN_APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          for name in CSC_LINK CSC_KEY_PASSWORD APPLE_ID APPLE_APP_SPECIFIC_PASSWORD APPLE_TEAM_ID; do
+            input="IN_${name}"
+            value="${!input:-}"
+            if [ -n "$value" ]; then printf '%s<<__EOF__\n%s\n__EOF__\n' "$name" "$value" >> "$GITHUB_ENV"; fi
+          done
+          if [ -z "${IN_CSC_LINK:-}" ]; then
+            echo 'CSC_IDENTITY_AUTO_DISCOVERY=false' >> "$GITHUB_ENV"
+            echo 'No macOS signing certificate configured; building unsigned.'
+          fi
       - name: Package and publish desktop release
         working-directory: apps/desktop
         run: pnpm exec electron-builder --mac dmg zip --publish always
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          CSC_LINK: ${{ secrets.MAC_CSC_LINK }}
-          CSC_KEY_PASSWORD: ${{ secrets.MAC_CSC_KEY_PASSWORD }}
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
 
       - name: Upload macOS artifacts for manual runs
         if: github.event_name == 'workflow_dispatch'
@@ -72,3 +89,67 @@ jobs:
             apps/desktop/dist/*.zip
             apps/desktop/dist/latest-mac.yml
           if-no-files-found: error
+
+  windows:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # pinned from v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # pinned from v6
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # pinned from v6
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Stamp desktop version for tag builds
+        if: startsWith(github.ref, 'refs/tags/desktop-v')
+        shell: bash
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          export DESKTOP_VERSION="${TAG_NAME#desktop-v}"
+          node -e 'const fs = require("node:fs"); const path = "apps/desktop/package.json"; const packageJson = JSON.parse(fs.readFileSync(path, "utf8")); packageJson.version = process.env.DESKTOP_VERSION; fs.writeFileSync(path, `${JSON.stringify(packageJson, null, 2)}\n`);'
+
+      - name: Build workspace
+        run: pnpm --workspace-root run build
+
+      - name: Stage desktop runtime
+        working-directory: apps/desktop
+        run: node --import tsx scripts/stage-runtime.ts
+
+      # Only non-empty WIN_CSC_* signing secrets are exported. Without them,
+      # Windows artifacts are unsigned and installers trigger a SmartScreen
+      # warning on first run.
+      - name: Resolve Windows signing credentials
+        shell: bash
+        env:
+          IN_WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
+          IN_WIN_CSC_KEY_PASSWORD: ${{ secrets.WIN_CSC_KEY_PASSWORD }}
+        run: |
+          for name in WIN_CSC_LINK WIN_CSC_KEY_PASSWORD; do
+            input="IN_${name}"
+            value="${!input:-}"
+            if [ -n "$value" ]; then printf '%s<<__EOF__\n%s\n__EOF__\n' "$name" "$value" >> "$GITHUB_ENV"; fi
+          done
+      - name: Package and publish desktop release
+        working-directory: apps/desktop
+        run: pnpm exec electron-builder --win nsis --x64 --publish always
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload Windows artifacts for manual runs
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # pinned from v7
+        with:
+          name: desktop-windows
+          path: |
+            apps/desktop/dist/*.exe
+            apps/desktop/dist/latest.yml
+          if-no-files-found: error

apps/desktop/README.md

@@ -64,11 +64,15 @@ hdiutil detach "$MOUNT_POINT"
 rmdir "$MOUNT_POINT"
 ```
 
+### Windows
+
+Run `pnpm run dist:win` on a native Windows x64 host; cross-building from macOS is not possible because the staged Host closure contains platform-gated native packages. The output is `dist/Pythinker-<version>-x64-Setup.exe`, an assisted NSIS installer that defaults to a per-user install, offers a per-machine option that requires elevation, and lets you select the installation directory. Artifacts are unsigned unless `WIN_CSC_LINK` and `WIN_CSC_KEY_PASSWORD` are set.
+
 ## Known limitations
 
 The first desktop assembly uses a loopback HTTP Host. The renderer and Host protocol remain unchanged so the application can replace the transport with the IPC carrier reserved by the GUI architecture without changing product features.
 
-The signed installer path currently targets macOS. Windows and Linux packaging creates unpacked applications; their installer formats and distribution signing remain release work.
+The signed installer path currently targets macOS. Linux packaging creates an unpacked application; its installer format and distribution signing remain release work.
 
 ## Model Experience
 

apps/desktop/package.json

@@ -11,7 +11,8 @@
     "dev": "pnpm -C ../pythinker-code run build && tsc -p tsconfig.json && tsdown && electron .",
     "package": "pnpm --workspace-root run build && node --import tsx scripts/stage-runtime.ts && electron-builder --dir",
     "dist": "pnpm --workspace-root run build && node --import tsx scripts/stage-runtime.ts && electron-builder",
-    "dist:mac": "node --import tsx scripts/release-mac.ts"
+    "dist:mac": "node --import tsx scripts/release-mac.ts",
+    "dist:win": "node --import tsx scripts/release-win.ts"
   },
   "license": "MIT",
   "devDependencies": {
@@ -67,9 +68,24 @@
     "win": {
       "icon": "build/icon.png",
       "target": [
-        "dir"
+        {
+          "target": "nsis",
+          "arch": [
+            "x64"
+          ]
+        }
       ]
     },
+    "nsis": {
+      "allowElevation": true,
+      "allowToChangeInstallationDirectory": true,
+      "artifactName": "Pythinker-${version}-${arch}-Setup.${ext}",
+      "createDesktopShortcut": true,
+      "createStartMenuShortcut": true,
+      "oneClick": false,
+      "perMachine": false,
+      "shortcutName": "Pythinker"
+    },
     "linux": {
       "category": "Development",
       "target": [

apps/desktop/scripts/release-win.ts

@@ -0,0 +1,37 @@
+/** Build the Windows NSIS installer from a native Windows host. */
+
+import { spawnSync } from 'node:child_process'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { verifyWindowsInstaller } from './verify-win-installer'
+
+function run(command: string, args: readonly string[], cwd: string): void {
+  const result = spawnSync(command, args, { cwd, stdio: 'inherit', shell: process.platform === 'win32' })
+  if (result.error !== undefined) throw result.error
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} exited with ${String(result.status)}`)
+}
+
+/** Build and verify the unsigned Windows installer. */
+export function releaseWin(): void {
+  if (process.platform !== 'win32') {
+    throw new Error('The Windows installer must be built on Windows: the staged Host closure contains platform-specific native packages')
+  }
+  if (process.arch !== 'x64') {
+    throw new Error(`The Windows installer targets x64; this host is ${process.arch}`)
+  }
+  const desktopRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+  run('pnpm', ['--workspace-root', 'run', 'build'], desktopRoot)
+  run('node', ['--import', 'tsx', 'scripts/stage-runtime.ts'], desktopRoot)
+  run('pnpm', ['exec', 'electron-builder', '--win', 'nsis', '--x64', '--publish', 'never'], desktopRoot)
+  verifyWindowsInstaller(desktopRoot)
+}
+
+const invokedPath = process.argv[1]
+if (invokedPath !== undefined && resolve(invokedPath) === fileURLToPath(import.meta.url)) {
+  try {
+    releaseWin()
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}