dsh-alk-pet 0.5.0 → 0.5.1

package/README.md

@@ -99,9 +99,22 @@ dsh plugin --profile web add /absolute/path/to/dsh-alk-pet
 - **不要**将 WebUI 暴露到不受信任的网络。
 - **不要**把插件的回环地址检查视为登录鉴权或访问控制。
 
-Windows 原生窗口通过 PowerShell 启动，并使用分层窗口实现逐像素透明。若系统策略禁止运行 PowerShell 脚本，插件会自动回退到网页内宠物。
+Windows 原生窗口由随包的 `native/windows/pet.ps1`（Windows PowerShell 5.1 + WinForms 分层窗口）提供，使用分层窗口实现逐像素透明。DSH 启动子进程时会隐藏控制台，因此脚本完全通过标准输入/输出的 UTF-8 管道收发消息，不依赖控制台代码页；窗口真正可见后还会发送一次 `ready` 握手，Host 收到握手才隐藏网页内宠物，避免出现“原生窗口没起来、网页里也看不到宠物”的空窗。原生窗口异常退出时会自动重启两次；启动后若在 25 秒内没有变得可见，也会视为失败并自动回退到网页内宠物。
 
-随包提供的 macOS Helper 当前为 Apple Silicon 版本。Intel Mac 会自动回退到网页版本，也可以使用本机工具链重新构建。Linux 不提供原生悬浮窗，仅使用 WebUI 页面内版本。原生窗口异常退出时会自动重启两次；仍无法运行则自动回退。
+如果 Windows 上只看到网页内宠物，通常说明原生 Helper 启动失败。请查看以下日志（首次写入时自动创建）：
+
+- `%LOCALAPPDATA%\dsh-alk-pet\helper.log`：Helper 自身的启动过程、窗口可见状态与异常堆栈。
+- `%LOCALAPPDATA%\dsh-alk-pet\host.log`：Host 侧的启动参数、子进程 stderr 与重试记录。
+
+常见原因与处理方式：
+
+- **系统策略禁止运行 PowerShell 脚本**（AppLocker、WDAC 或企业策略）：需要为本插件放行 `powershell.exe`，否则只能继续使用网页内宠物。
+- **PowerShell 不在 PATH 中**：插件会优先使用 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`，也可以用环境变量 `DSH_ALK_PET_POWERSHELL` 指定绝对路径。
+- **安全软件拦截脚本或弹出确认框**：请为插件目录和 PowerShell 放行。
+
+Windows 版会把宠物位置保存到 `%LOCALAPPDATA%\dsh-alk-pet\window.json`。
+
+随包提供的 macOS Helper 当前为 Apple Silicon 版本。Intel Mac 会自动回退到网页版本，也可以使用本机工具链重新构建。Linux 不提供原生悬浮窗，仅使用 WebUI 页面内版本。
 
 ## 授权与声明
 
@@ -119,6 +132,7 @@ Windows 原生窗口通过 PowerShell 启动，并使用分层窗口实现逐像
 ```sh
 npm test                 # 运行测试
 npm run check:assets     # 校验动画素材
+npm run check:windows    # 解析 Windows PowerShell 脚本并交叉编译其中的 C#（需要 pwsh / .NET SDK，缺失时自动跳过）
 npm run build:assets     # 修改素材后重新生成资源
 npm run build:native     # macOS：构建原生 Helper（需要 Swift 工具链）
 ```

package/assets/animations/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.5.0",
+  "version": "0.5.1",
   "frameMs": 83,
   "assetVersion": "5bbfc464d343",
   "clips": {

package/native/windows/pet.ps1

@@ -1,7 +1,44 @@
-Add-Type -AssemblyName System.Windows.Forms
-Add-Type -AssemblyName System.Drawing
-[Console]::InputEncoding = New-Object System.Text.UTF8Encoding($false)
-[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+# dsh-alk-pet Windows helper.
+#
+# The host launches this script with Node's windowsHide option, so the process
+# has no console. Never assign [Console]::InputEncoding or [Console]::OutputEncoding
+# here: those setters call SetConsoleCP/SetConsoleOutputCP and throw
+# "The handle is invalid" when no console exists, which aborts the helper before
+# it can create its window. The C# protocol code below reads and writes UTF-8
+# directly on the inherited stdout/stdin pipes instead.
+$ErrorActionPreference = 'Stop'
+
+$helperLogPath = $null
+try {
+    $helperLogDirectory = Join-Path $env:LOCALAPPDATA 'dsh-alk-pet'
+    $helperLogPath = Join-Path $helperLogDirectory 'helper.log'
+    if (-not (Test-Path -LiteralPath $helperLogDirectory)) {
+        New-Item -ItemType Directory -Force -Path $helperLogDirectory | Out-Null
+    }
+    if ((Test-Path -LiteralPath $helperLogPath) -and ((Get-Item -LiteralPath $helperLogPath).Length -gt 65536)) {
+        Remove-Item -LiteralPath $helperLogPath -Force
+    }
+} catch {
+    $helperLogPath = $null
+}
+
+function Write-HelperLog([string]$Message) {
+    if (-not $helperLogPath) { return }
+    try {
+        Add-Content -LiteralPath $helperLogPath -Value ('[' + (Get-Date).ToString('yyyy-MM-dd HH:mm:ss.fff') + '] ' + $Message) -Encoding UTF8
+    } catch {
+    }
+}
+
+try {
+    Add-Type -AssemblyName System.Windows.Forms
+    Add-Type -AssemblyName System.Drawing
+    Add-Type -AssemblyName System.Web.Extensions
+} catch {
+    Write-HelperLog ('failed to load assemblies: ' + $_.Exception.ToString())
+    [Console]::Error.WriteLine('[dsh-alk-pet] windows helper failed to load assemblies: ' + $_.Exception.Message)
+    exit 1
+}
 
 $source = @'
 using System;
@@ -12,6 +49,7 @@ using System.Drawing.Imaging;
 using System.Drawing.Text;
 using System.IO;
 using System.Runtime.InteropServices;
+using System.Text;
 using System.Threading;
 using System.Windows.Forms;
 using System.Web.Script.Serialization;
@@ -100,6 +138,15 @@ public class PetForm : Form {
     [DllImport("user32.dll")]
     private static extern bool SetProcessDpiAwarenessContext(IntPtr value);
 
+    [DllImport("user32.dll")]
+    private static extern bool ShowWindow(IntPtr hwnd, int nCmdShow);
+
+    [DllImport("user32.dll")]
+    private static extern bool SetWindowPos(IntPtr hwnd, IntPtr insertAfter, int x, int y, int cx, int cy, uint flags);
+
+    [DllImport("user32.dll")]
+    private static extern bool IsWindowVisible(IntPtr hwnd);
+
     // ------------------------------------------------------------------
     // Constants
     // ------------------------------------------------------------------
@@ -126,6 +173,15 @@ public class PetForm : Form {
     private const float BUBBLE_MIN_WIDTH = 164f;
     private const float BUBBLE_TITLE_PAD = 45f;
     private const float BUBBLE_DETAIL_PAD = 34f;
+    private const int SW_SHOWNOACTIVATE = 4;
+    private const uint SWP_NOSIZE = 0x0001;
+    private const uint SWP_NOMOVE = 0x0002;
+    private const uint SWP_NOACTIVATE = 0x0010;
+    private const uint SWP_SHOWWINDOW = 0x0040;
+    private static readonly IntPtr HWND_TOPMOST = new IntPtr(-1);
+    // Node's windowsHide startup info carries SW_HIDE, which Windows applies to
+    // the first ShowWindow call. Retry the explicit show for a moment afterwards.
+    private const int VISIBILITY_RETRY_TICKS = 25;
 
     // ------------------------------------------------------------------
     // Persisted / injected state
@@ -136,9 +192,9 @@ public class PetForm : Form {
     private ToolTip chipToolTip;
 
     private string petState = "idle";
-    private string title = "待机中";
-    private string status = "待机中";
-    private string detail = "待机中";
+    private string title = "\u5F85\u673A\u4E2D";
+    private string status = "\u5F85\u673A\u4E2D";
+    private string detail = "\u5F85\u673A\u4E2D";
     private bool showBubble = true;
     private bool viewed = false;
     private bool reducedMotion = false;
@@ -150,6 +206,9 @@ public class PetForm : Form {
     private string assetVersion = ""; // parsed for protocol completeness; native rendering ignores it
     private string animationState = "idle";
     private int frameNumber = 1;
+    private StreamWriter protocolOutput = null;
+    private int visibilityAttempts = 0;
+    private bool readyAnnounced = false;
 
     // ------------------------------------------------------------------
     // DPI / layout
@@ -299,6 +358,7 @@ public class PetForm : Form {
         base.OnShown(e);
         try {
             TopMost = true;
+            ForceVisible();
             RenderFrame();
         } catch (Exception) {
         }
@@ -420,9 +480,14 @@ public class PetForm : Form {
         // Dedicated parser instance: the reader thread and the UI thread must not
         // share the same JavaScriptSerializer instance.
         JavaScriptSerializer parser = new JavaScriptSerializer();
+        StreamReader reader = null;
         try {
+            // Read UTF-8 directly from the inherited stdin pipe. Relying on
+            // Console.ReadLine would require a console input code page, which
+            // does not exist for a windowsHide child process.
+            reader = new StreamReader(Console.OpenStandardInput(), new UTF8Encoding(false), true);
             string line;
-            while ((line = Console.ReadLine()) != null) {
+            while ((line = reader.ReadLine()) != null) {
                 Dictionary<string, object> data = null;
                 try {
                     data = parser.DeserializeObject(line) as Dictionary<string, object>;
@@ -439,6 +504,11 @@ public class PetForm : Form {
                 }));
             }
         } catch (Exception) {
+        } finally {
+            try {
+                if (reader != null) reader.Dispose();
+            } catch (Exception) {
+            }
         }
         InvokeOnUi(new Action(delegate {
             try {
@@ -473,7 +543,7 @@ public class PetForm : Form {
                 frameNumber = 1;
             }
         }
-        if (data.TryGetValue("title", out value)) title = value == null ? "当前任务" : Convert.ToString(value);
+        if (data.TryGetValue("title", out value)) title = value == null ? "\u5F53\u524D\u4EFB\u52A1" : Convert.ToString(value);
         if (data.TryGetValue("label", out value)) status = value == null ? "" : Convert.ToString(value);
         if (data.TryGetValue("detail", out value)) detail = value == null ? "" : Convert.ToString(value);
         if (data.TryGetValue("showBubble", out value) && value != null) showBubble = SafeBool(value, showBubble);
@@ -574,7 +644,12 @@ public class PetForm : Form {
     }
 
     private void OnAnimationTick(object sender, EventArgs e) {
-        if (closing || reducedMotion) return;
+        if (closing) return;
+        if (!readyAnnounced && visibilityAttempts < VISIBILITY_RETRY_TICKS) {
+            visibilityAttempts++;
+            ForceVisible();
+        }
+        if (reducedMotion) return;
         int count;
         if (!clips.TryGetValue(animationState, out count) || count < 1) count = 1;
         if (frameNumber < count) {
@@ -1344,7 +1419,7 @@ public class PetForm : Form {
             string value = Convert.ToString(raw);
             if (!String.IsNullOrEmpty(value)) return value;
         }
-        return "当前任务";
+        return "\u5F53\u524D\u4EFB\u52A1";
     }
 
     private int BubbleTaskWidth(Dictionary<string, object> task, int titlePad, int detailPad) {
@@ -1529,17 +1604,51 @@ public class PetForm : Form {
 
     private void SendJson(Dictionary<string, object> payload) {
         try {
-            Console.WriteLine(json.Serialize(payload));
-            Console.Out.Flush();
+            if (protocolOutput == null) {
+                protocolOutput = new StreamWriter(Console.OpenStandardOutput(), new UTF8Encoding(false));
+                protocolOutput.AutoFlush = true;
+            }
+            protocolOutput.WriteLine(json.Serialize(payload));
         } catch (Exception) {
         }
     }
 
+    /**
+     * Windows applies the STARTUPINFO wShowWindow value to the first ShowWindow
+     * of the process. Node's windowsHide passes SW_HIDE, so the layered pet
+     * window would be created but stay invisible without an explicit show.
+     */
+    private void ForceVisible() {
+        if (closing || !IsHandleCreated) return;
+        try {
+            ShowWindow(Handle, SW_SHOWNOACTIVATE);
+            SetWindowPos(Handle, HWND_TOPMOST, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOACTIVATE | SWP_SHOWWINDOW);
+        } catch (Exception) {
+        }
+        AnnounceReadyIfVisible();
+    }
+
+    private void AnnounceReadyIfVisible() {
+        if (readyAnnounced || closing || !IsHandleCreated) return;
+        try {
+            if (!IsWindowVisible(Handle)) return;
+        } catch (Exception) {
+            return;
+        }
+        readyAnnounced = true;
+        Dictionary<string, object> payload = new Dictionary<string, object>();
+        payload["type"] = "ready";
+        payload["pid"] = System.Diagnostics.Process.GetCurrentProcess().Id;
+        payload["width"] = Width;
+        payload["height"] = Height;
+        SendJson(payload);
+    }
+
     private void UpdateChipTooltip(int index) {
         try {
             if (chipToolTip == null) return;
             if (index >= 0 && index < tasks.Count) {
-                chipToolTip.SetToolTip(this, TaskTitleOf(tasks[index]) + " · " + StatusLabelOf(StatusOf(tasks[index])));
+                chipToolTip.SetToolTip(this, TaskTitleOf(tasks[index]) + " \u00B7 " + StatusLabelOf(StatusOf(tasks[index])));
             } else {
                 chipToolTip.SetToolTip(this, "");
             }
@@ -1548,11 +1657,11 @@ public class PetForm : Form {
     }
 
     private static string StatusLabelOf(string chipStatus) {
-        if (chipStatus == "running") return "运行中";
-        if (chipStatus == "waiting") return "等待确认";
-        if (chipStatus == "success") return "已完成";
-        if (chipStatus == "error") return "失败";
-        return "待机";
+        if (chipStatus == "running") return "\u8FD0\u884C\u4E2D";
+        if (chipStatus == "waiting") return "\u7B49\u5F85\u786E\u8BA4";
+        if (chipStatus == "success") return "\u5DF2\u5B8C\u6210";
+        if (chipStatus == "error") return "\u5931\u8D25";
+        return "\u5F85\u673A";
     }
 
     // ------------------------------------------------------------------
@@ -1648,13 +1757,34 @@ public class PetForm : Form {
 }
 '@
 
+$petForm = $null
 try {
-    Add-Type -TypeDefinition $source -ReferencedAssemblies 'System.Windows.Forms','System.Drawing','System.Web.Extensions'
+    $references = @(
+        [System.Windows.Forms.Form].Assembly.Location,
+        [System.Drawing.Bitmap].Assembly.Location,
+        [System.Web.Script.Serialization.JavaScriptSerializer].Assembly.Location,
+        [System.ComponentModel.Component].Assembly.Location
+    ) | Where-Object { $_ } | Select-Object -Unique
+
+    Add-Type -TypeDefinition $source -ReferencedAssemblies $references
     [PetForm]::SetupDpiAwareness()
     [System.Windows.Forms.Application]::EnableVisualStyles()
-    $petForm = New-Object PetForm -ArgumentList (Join-Path $PSScriptRoot '..\..\assets\animations')
+
+    $assetDirectory = Join-Path $PSScriptRoot '..\..\assets\animations'
+    if (-not (Test-Path -LiteralPath $assetDirectory)) {
+        Write-HelperLog ('asset directory missing: ' + $assetDirectory)
+    }
+    Write-HelperLog ('starting windows helper; pid=' + $PID + '; assets=' + $assetDirectory)
+    $petForm = New-Object PetForm -ArgumentList $assetDirectory
     [System.Windows.Forms.Application]::Run($petForm)
+    Write-HelperLog 'windows helper window closed'
 } catch {
-    [Console]::Error.WriteLine('[dsh-alk-pet] windows helper failed: ' + $_.Exception.ToString())
+    $failure = $_.Exception.ToString()
+    Write-HelperLog ('fatal: ' + $failure)
+    [Console]::Error.WriteLine('[dsh-alk-pet] windows helper failed: ' + $failure)
     exit 1
+} finally {
+    if ($petForm -ne $null) {
+        try { $petForm.Dispose() } catch { }
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-alk-pet",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Unofficial desktop pet plugin for DeepSeek Harness (DSH) with native floating windows on macOS/Windows.",
   "license": "MIT",
   "publishConfig": {
@@ -46,6 +46,7 @@
     "test": "node --test test/*.test.js",
     "build:assets": "node scripts/build-assets.mjs",
     "check:assets": "node scripts/build-assets.mjs --check",
+    "check:windows": "node scripts/check-windows-helper.mjs",
     "build:native": "node scripts/build-native.mjs",
     "build": "npm run build:assets && npm run build:native"
   },

package/src/helper-log.js

@@ -0,0 +1,49 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+const MAX_LOG_BYTES = 256 * 1024
+
+function logPathFor(platform, env) {
+  const home = env.HOME || env.USERPROFILE || ''
+  if (platform === 'win32') {
+    const base = env.LOCALAPPDATA || join(home, 'AppData', 'Local')
+    return join(base, 'dsh-alk-pet', 'host.log')
+  }
+  if (platform === 'darwin') {
+    return join(home, 'Library', 'Logs', 'dsh-alk-pet', 'host.log')
+  }
+  return join(env.XDG_STATE_HOME || join(home, '.local', 'state'), 'dsh-alk-pet', 'host.log')
+}
+
+/**
+ * Best-effort append-only log for native helper diagnostics.
+ *
+ * The DSH desktop shell discards a plugin host's console output, so a Windows
+ * user whose native helper keeps falling back would otherwise have no clue why.
+ * The log is created lazily on the first write; failures never throw.
+ */
+export function createHelperLog({ platform = process.platform, env = process.env, timestamp = () => new Date().toISOString() } = {}) {
+  let path = null
+  let prepared = false
+  return function log(message) {
+    const line = `[${timestamp()}] ${String(message ?? '').replace(/\s+$/u, '')}\n`
+    try {
+      if (!path) {
+        path = logPathFor(platform, env)
+        if (!path) return
+      }
+      if (!prepared) {
+        mkdirSync(dirname(path), { recursive: true })
+        prepared = true
+      }
+      try {
+        if (statSync(path).size > MAX_LOG_BYTES) renameSync(path, `${path}.1`)
+      } catch {}
+      appendFileSync(path, line)
+    } catch {
+      // Diagnostics must never break the pet.
+    }
+  }
+}
+
+export { logPathFor }

package/src/index.js

@@ -2,6 +2,7 @@ import { readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { loadManifest } from './assets.js'
+import { createHelperLog } from './helper-log.js'
 import { startNative } from './native.js'
 import { HOVER_TTL_MS, PetRuntime } from './pet-runtime.js'
 
@@ -68,13 +69,15 @@ export function apply(ctx, config = {}, options = {}) {
   const clients = new Set()
   const imageCache = new Map()
   let native = null
+  let nativeReady = false
   let carouselTimer = null
   let nextDelay = 2000
   let hoverSweep = null
   let heartbeat = null
   let disposed = false
 
-  const snapshot = () => runtime.snapshot({ native: native !== null })
+  const nativeActive = () => native !== null && (!native.requiresReady || nativeReady)
+  const snapshot = () => runtime.snapshot({ native: nativeActive() })
 
   const broadcast = () => {
     const current = snapshot()
@@ -120,15 +123,31 @@ export function apply(ctx, config = {}, options = {}) {
     }
   }
 
+  const logHelper = options.log ?? createHelperLog()
+  const log = (message) => {
+    console.warn('[dsh-alk-pet]', message)
+    logHelper(message)
+  }
+
   if (runtime.config.enabled) {
     native = startHelper({
       onAction,
-      onLog: (message) => console.warn('[dsh-alk-pet]', message),
+      onLog: log,
+      onReady: () => {
+        nativeReady = true
+        broadcast()
+      },
+      onDisconnect: () => {
+        if (!nativeReady) return
+        nativeReady = false
+        broadcast()
+      },
       onExit: (error) => {
         native = null
+        nativeReady = false
         runtime.setHover('native', false)
         broadcast()
-        console.warn('[dsh-alk-pet] native helper unavailable:', error?.message ?? error)
+        log(`native helper unavailable: ${error?.message ?? error}`)
       },
     })
   }
@@ -167,7 +186,7 @@ export function apply(ctx, config = {}, options = {}) {
   function configHandler(req, res) {
     if (!local(req)) { res.writeHead(403); res.end(); return }
     res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' })
-    res.end(JSON.stringify({ ...runtime.configSnapshot(), native: native !== null }))
+    res.end(JSON.stringify({ ...runtime.configSnapshot(), native: nativeActive() }))
   }
 
   function image(req, res) {
@@ -250,6 +269,7 @@ export function apply(ctx, config = {}, options = {}) {
     onEvent?.()
     native?.stop()
     native = null
+    nativeReady = false
     clients.forEach((res) => { try { res.end() } catch {} })
     clients.clear()
     imageCache.clear()

package/src/native.js

@@ -1,16 +1,22 @@
 import { spawn } from 'node:child_process'
-import { accessSync, closeSync, constants, openSync, readSync } from 'node:fs'
+import { accessSync, closeSync, constants, existsSync, openSync, readSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const root = dirname(dirname(fileURLToPath(import.meta.url)))
 const helperPath = join(root, 'runtime/bin/darwin/dsh-alk-pet-helper')
+const windowsScriptPath = join(root, 'native/windows/pet.ps1')
 const assetsPath = join(root, 'assets/animations')
 
 const MACHO_MAGIC_64 = 0xfeedfacf
 const CPU_TYPE_ARM64 = 0x0100000c
 const CPU_TYPE_X64 = 0x01000007
 
+const DEFAULT_READY_TIMEOUT_MS = 25_000
+const RESTART_DELAY_MS = 1200
+const STDERR_LIMIT = 4096
+const OUTPUT_LINE_LIMIT = 65536
+
 function isExecutable(path) {
   try {
     accessSync(path, constants.X_OK)
@@ -35,29 +41,90 @@ function machOArch(path) {
   }
 }
 
+function truncate(value, limit = 400) {
+  const text = String(value ?? '').replace(/\s+$/u, '')
+  return text.length > limit ? `${text.slice(0, limit)}...` : text
+}
+
+/**
+ * Resolves the Windows PowerShell executable without relying only on PATH.
+ *
+ * The DSH desktop host is started by the Electron shell with a curated
+ * environment, so `powershell.exe` is not guaranteed to be resolvable by name.
+ * The absolute Windows PowerShell location is tried first; a bare name is kept
+ * as the last resort so the spawn error still surfaces through `onLog`.
+ */
+export function resolveWindowsPowerShell({ env = process.env, fileExists = existsSync } = {}) {
+  const explicit = env.DSH_ALK_PET_POWERSHELL
+  if (typeof explicit === 'string' && explicit.trim()) {
+    return fileExists(explicit.trim()) ? explicit.trim() : 'powershell.exe'
+  }
+  const systemRoot = env.SystemRoot || env.windir || 'C:\\Windows'
+  const candidates = [
+    join(systemRoot, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+    join(systemRoot, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+  ]
+  for (const candidate of candidates) {
+    if (fileExists(candidate)) return candidate
+  }
+  return 'powershell.exe'
+}
+
+/** Arguments used to launch the Windows WinForms helper script. */
+export function windowsHelperArgs(scriptPath = windowsScriptPath) {
+  return ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', scriptPath]
+}
+
 /**
- * Starts the platform native pet window. The helper is restarted a couple of
- * times when it exits unexpectedly; onExit fires once when it is given up
- * (or was never startable).
+ * Starts the platform native pet window.
+ *
+ * The helper is restarted a couple of times when it exits unexpectedly. On
+ * Windows the helper must also announce itself with a `{"type":"ready"}` line
+ * once its layered window is actually visible; a helper that stays alive but
+ * never becomes visible is killed by the startup watchdog so the in-page
+ * fallback can take over (the window is launched with `windowsHide`, and a
+ * silent child process would otherwise leave the user with no pet at all).
+ *
+ * `onExit` fires once when the helper is given up (or was never startable),
+ * `onReady` fires when the native window is usable, and `onDisconnect` fires
+ * on every unexpected helper exit before a restart is attempted.
  */
-export function startNative({ onExit = () => {}, onAction = () => {}, onLog = () => {}, restarts = 2 } = {}) {
+export function startNative({
+  onExit = () => {},
+  onAction = () => {},
+  onLog = () => {},
+  onReady = () => {},
+  onDisconnect = () => {},
+  restarts = 2,
+  readyTimeoutMs = DEFAULT_READY_TIMEOUT_MS,
+  restartDelayMs = RESTART_DELAY_MS,
+  platform = process.platform,
+  spawnProcess = spawn,
+  fileExists = existsSync,
+  darwinHelperPath = helperPath,
+  darwinAssetsPath = assetsPath,
+} = {}) {
   let command
   let args
-  if (process.platform === 'darwin') {
-    if (!isExecutable(helperPath)) {
+  if (platform === 'darwin') {
+    if (!isExecutable(darwinHelperPath)) {
       onLog('helper missing or not executable; using in-page overlay')
       return null
     }
-    const arch = machOArch(helperPath)
+    const arch = machOArch(darwinHelperPath)
     if (arch && arch !== process.arch) {
       onLog(`helper is built for ${arch} but this host is ${process.arch}; using in-page overlay`)
       return null
     }
-    command = helperPath
-    args = [assetsPath]
-  } else if (process.platform === 'win32') {
-    command = 'powershell.exe'
-    args = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', join(root, 'native/windows/pet.ps1')]
+    command = darwinHelperPath
+    args = [darwinAssetsPath]
+  } else if (platform === 'win32') {
+    if (!fileExists(windowsScriptPath)) {
+      onLog(`windows helper script missing: ${windowsScriptPath}; using in-page overlay`)
+      return null
+    }
+    command = resolveWindowsPowerShell({ fileExists })
+    args = windowsHelperArgs(windowsScriptPath)
   } else {
     return null
   }
@@ -66,52 +133,114 @@ export function startNative({ onExit = () => {}, onAction = () => {}, onLog = ()
   let stopped = false
   let attempt = 0
   let restartTimer = null
+  let ready = false
+  let lastStderr = ''
 
   const spawnOnce = () => {
     if (stopped) return
     let finished = false
+    let readyTimer = null
     let output = ''
-    const processHandle = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
+    let stderrTail = ''
+    const processHandle = spawnProcess(command, args, { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true })
     const spawnedAt = Date.now()
     child = processHandle
+    ready = false
+
+    const clearReadyTimer = () => {
+      if (readyTimer !== null) {
+        clearTimeout(readyTimer)
+        readyTimer = null
+      }
+    }
 
     const fail = (error) => {
       if (finished) return
       finished = true
+      clearReadyTimer()
       if (child === processHandle) child = null
       if (stopped) return
+      ready = false
+      onDisconnect(error)
       // A helper that stays alive for a while earns a fresh restart budget.
       if (Date.now() - spawnedAt > 30_000) attempt = 0
       attempt += 1
+      const detail = stderrTail.trim() || lastStderr
+      if (stderrTail.trim()) lastStderr = stderrTail.trim()
+      const message = detail ? `${error?.message ?? 'unknown'}: ${truncate(detail, 800)}` : error?.message ?? 'unknown'
       if (attempt <= restarts) {
-        const delay = 1200 * attempt
-        onLog(`helper stopped (${error?.message ?? 'unknown'}); restarting in ${delay}ms`)
+        const delay = restartDelayMs * attempt
+        onLog(`helper stopped (${message}); restarting in ${delay}ms`)
         restartTimer = setTimeout(spawnOnce, delay)
         restartTimer.unref?.()
       } else {
-        onExit(error)
+        const finalError = new Error(message)
+        onLog(`native helper unavailable: ${message}`)
+        onExit(finalError)
       }
     }
 
+    const announceReady = () => {
+      if (ready) return
+      ready = true
+      clearReadyTimer()
+      onLog(`native helper ready after ${Date.now() - spawnedAt}ms`)
+      onReady()
+    }
+
     processHandle.stdout.on('data', (chunk) => {
       output += String(chunk)
-      if (output.length > 65536) output = ''
+      if (output.length > OUTPUT_LINE_LIMIT) output = output.slice(-OUTPUT_LINE_LIMIT)
       let end
       while ((end = output.indexOf('\n')) >= 0) {
-        const line = output.slice(0, end)
+        const line = output.slice(0, end).trim()
         output = output.slice(end + 1)
-        try { onAction(JSON.parse(line)) } catch {}
+        if (!line) continue
+        let action
+        try {
+          action = JSON.parse(line)
+        } catch {
+          onLog(`unexpected windows helper output: ${truncate(line, 200)}`)
+          continue
+        }
+        if (action?.type === 'ready') {
+          announceReady()
+          continue
+        }
+        try { onAction(action) } catch {}
       }
     })
     processHandle.stdin.on('error', () => {})
-    processHandle.stderr.on('data', (data) => onLog(String(data).trim()))
+    processHandle.stderr.on('data', (data) => {
+      const text = String(data)
+      stderrTail = (stderrTail + text).slice(-STDERR_LIMIT)
+      const trimmed = text.trim()
+      if (trimmed) onLog(trimmed)
+    })
     processHandle.on('error', fail)
     processHandle.on('exit', (code, signal) => fail(new Error(`helper exited (${code ?? signal})`)))
+
+    // Windows only: a hidden helper that never announces itself would otherwise
+    // suppress the in-page fallback forever.
+    if (platform === 'win32' && readyTimeoutMs > 0) {
+      readyTimer = setTimeout(() => {
+        if (finished || stopped || ready) return
+        const detail = stderrTail.trim()
+        const error = new Error(`helper did not become visible within ${readyTimeoutMs}ms${detail ? `: ${truncate(detail, 800)}` : ''}`)
+        onLog(error.message)
+        fail(error)
+        try { processHandle.kill() } catch {}
+      }, readyTimeoutMs)
+      readyTimer.unref?.()
+    }
   }
 
   spawnOnce()
 
   return {
+    // Windows helpers must announce readiness before the in-page overlay hides.
+    requiresReady: platform === 'win32',
+    isReady: () => ready,
     send(message) {
       if (!child || child.exitCode !== null || child.stdin.destroyed) return
       try { child.stdin.write(`${JSON.stringify(message)}\n`) } catch {}