fix(desktop): bound the Windows tree kill and correct the installer docs

spawnSync blocks the Electron main loop, so a stalled taskkill could freeze
shutdown indefinitely. Cap it and let the existing fallback degrade to a
single-process kill.

The README claimed a per-user installer with no elevation required. With
oneClick and perMachine both false, electron-builder shows an install-mode page,
so per-user is the default rather than the contract. Describe the real behavior
and pin it with a test.

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

apps/desktop/README.md

@@ -66,7 +66,7 @@ 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`, a per-user NSIS installer with no elevation required and a selectable installation directory. Artifacts are unsigned unless `WIN_CSC_LINK` and `WIN_CSC_KEY_PASSWORD` are set.
+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
 

apps/desktop/src/host-supervisor.ts

@@ -6,6 +6,7 @@ import type { Readable } from 'node:stream'
 const READINESS_PREFIX = 'Pythinker server: '
 const DEFAULT_READINESS_TIMEOUT_MS = 90_000
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000
+const TASKKILL_TIMEOUT_MS = 5_000
 const MAX_STARTUP_OUTPUT_CHARS = 32_768
 
 /** Incremental parser for the Web Host's canonical readiness line. */
@@ -303,6 +304,8 @@ export function spawnPythinkerServer(options: SpawnPythinkerServerOptions): Host
  * Windows has no signal delivery: `child.kill` calls TerminateProcess on one
  * PID, so the Host's own children (node-pty shells, subagent hosts) survive and
  * keep holding the loopback port. `taskkill /T` walks the tree instead.
+ * Because this call is synchronous, keep it bounded so a stalled taskkill falls
+ * back to a single-process kill instead of blocking the Electron main loop indefinitely.
  *
  * ponytail: /F makes every Windows stop a forced stop — Node cannot deliver a
  * graceful SIGTERM to a Windows child at all. Add a stdin or IPC shutdown
@@ -313,7 +316,10 @@ function killProcessTree(child: ChildProcessByStdio<null, Readable, Readable>, s
     child.kill(signal)
     return
   }
-  const result = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { windowsHide: true })
+  const result = spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], {
+    windowsHide: true,
+    timeout: TASKKILL_TIMEOUT_MS,
+  })
   if (result.error !== undefined || result.status !== 0) child.kill(signal)
 }
 

apps/desktop/tests/host-supervisor.spec.ts

@@ -331,7 +331,7 @@ describe('desktop Host process', () => {
       stdout: Buffer.alloc(0),
       stderr: Buffer.alloc(0),
       status: 0,
-      signal: null,
+      signal: 'SIGTERM',
     })
     vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
 
@@ -347,11 +347,44 @@ describe('desktop Host process', () => {
     expect(spawnSync).toHaveBeenCalledWith(
       'taskkill',
       ['/pid', '4242', '/T', '/F'],
-      { windowsHide: true },
+      { windowsHide: true, timeout: 5_000 },
     )
     expect(child.kill).not.toHaveBeenCalled()
   })
 
+  it('falls back to killing the Windows Host when taskkill times out', async () => {
+    const child = {
+      pid: 4242,
+      stdout: { on: vi.fn(), off: vi.fn() },
+      stderr: { on: vi.fn(), off: vi.fn() },
+      on: vi.fn(),
+      off: vi.fn(),
+      kill: vi.fn(),
+    }
+    vi.mocked(spawn).mockReturnValue(child as never)
+    vi.mocked(spawnSync).mockReturnValue({
+      pid: 4242,
+      output: [],
+      stdout: Buffer.alloc(0),
+      stderr: Buffer.alloc(0),
+      status: null,
+      signal: null,
+      error: Object.assign(new Error('spawnSync taskkill ETIMEDOUT'), { code: 'ETIMEDOUT' }),
+    })
+    vi.spyOn(process, 'platform', 'get').mockReturnValue('win32')
+
+    const { spawnPythinkerServer } = await import('../src/host-supervisor')
+    const host = spawnPythinkerServer({
+      nodeExecutable: 'node',
+      cliEntry: '/tmp/launcher.mjs',
+      cwd: '/tmp',
+      env: {},
+    })
+    host.kill('SIGTERM')
+
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM')
+  })
+
   it('uses child.kill unchanged on non-Windows', async () => {
     const child = {
       pid: 4242,

apps/desktop/tests/packaging-config.spec.ts

@@ -112,6 +112,12 @@ describe('desktop packaging configuration', () => {
     expect(desktopPackage.scripts['dist:win']).toBe('node --import tsx scripts/release-win.ts')
   })
 
+  it('offers an assisted installer that defaults to a per-user install', () => {
+    expect(desktopPackage.build.nsis.oneClick).toBe(false)
+    expect(desktopPackage.build.nsis.perMachine).toBe(false)
+    expect(desktopPackage.build.nsis.allowElevation).toBe(true)
+  })
+
   it('exposes desktop commands at the repository root', () => {
     expect(rootPackage.scripts['dev:desktop']).toBe('pnpm -C apps/desktop run dev')
     expect(rootPackage.scripts['package:desktop']).toBe('pnpm -C apps/desktop run package')

apps/desktop/tests/verify-win-installer.spec.ts

@@ -37,21 +37,21 @@ describe('Windows installer verification', () => {
   it('accepts the installer and unpacked shell when both are PE binaries', async () => {
     await withFixture(async (root) => {
       await createFixture(root, portableExecutable())
-      expect(() => verifyWindowsInstaller(root)).not.toThrow()
+      expect(() => { verifyWindowsInstaller(root) }).not.toThrow()
     })
   })
 
   it('rejects a missing installer', async () => {
     await withFixture(async (root) => {
       await createFixture(root)
-      expect(() => verifyWindowsInstaller(root)).toThrow('ENOENT')
+      expect(() => { verifyWindowsInstaller(root) }).toThrow('ENOENT')
     })
   })
 
   it('rejects an artifact without a DOS header', async () => {
     await withFixture(async (root) => {
       await createFixture(root, portableExecutable('ZZ'))
-      expect(() => verifyWindowsInstaller(root)).toThrow(/no DOS header/)
+      expect(() => { verifyWindowsInstaller(root) }).toThrow(/no DOS header/u)
     })
   })
 
@@ -61,14 +61,14 @@ describe('Windows installer verification', () => {
       truncated.write('MZ', 0, 2, 'latin1')
       truncated.writeUInt32LE(0x80, 0x3c)
       await createFixture(root, truncated)
-      expect(() => verifyWindowsInstaller(root)).toThrow(/out-of-range PE offset/)
+      expect(() => { verifyWindowsInstaller(root) }).toThrow(/out-of-range PE offset/u)
     })
   })
 
   it('rejects an artifact without a PE signature', async () => {
     await withFixture(async (root) => {
       await createFixture(root, portableExecutable('MZ', 'NE\0\0'))
-      expect(() => verifyWindowsInstaller(root)).toThrow(/no PE signature/)
+      expect(() => { verifyWindowsInstaller(root) }).toThrow(/no PE signature/u)
     })
   })
 })