dsh-status-bar-plugin 0.2.5 → 0.2.6

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 wfz2006
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 wfz2006
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,100 +1,141 @@
-# dsh-status-bar
-
-DSH bundle for **DSH Status Bar** — a floating glass status bar for DeepSeek Harness.
-The npm name and the bundle row id are `dsh-status-bar-plugin`. npm already hosts an unrelated `dsh-statusbar`, so the registry rejects the shorter name as too similar.
-
-## What it does
-
-The plugin mounts one host row in DSH. At boot it waits for the local web server,
-asks the `connection` service for the authenticated host URL
-(`connection.authenticatedUrl(origin)`), and starts the desktop app with that link:
-
-```text
-electron <app dir> --dsh-link=<authenticated url> --launcher-pid=<host pid>
-```
-
-The companion connects with that link on launch, so nothing has to be pasted. The
-link travels only in the process arguments and is never logged — the plugin prints
-`[dsh-status-bar] Glass desktop companion launched (authenticated link redacted)`.
-The app rejects non-loopback links, credentials, hashes and sub-paths before it
-touches the network. `--launcher-pid` makes the companion exit when the DSH
-process it belongs to disappears; disposing the plugin kills the spawned tree.
-
-If the companion is already running, the second launch hits its single-instance
-lock: the existing window is focused and re-connected with the new link.
-
-## Install
-
-From npm, from the plugin market (once listed), or straight from the release
-tarball:
-
-```sh
-# npm: ~870 kB, fetches the 155 MB runtime once on first launch
-dsh plugin --profile web add dsh-status-bar-plugin
-
-# release tarball: 155 MB, self-contained, nothing downloaded later
-dsh plugin --profile web add https://github.com/wfz2006/dsh-status-bar/releases/latest/download/dsh-status-bar.tgz
-```
-
-Both end up as the same companion: the built desktop app plus an Electron
-runtime. The tarball carries them; the npm package reads the download URL from its
-own manifest (`dsh.statusBar.runtime`), fetches that tarball the first time DSH
-starts it — progress goes to the host log, roughly
-`[dsh-status-bar] downloading the Glass runtime: 40% of 155 MB` — and unpacks it
-into a per-version cache: `%LOCALAPPDATA%\dsh-status-bar\runtime-<version>` on
-Windows, `~/.cache/dsh-status-bar/runtime-<version>` elsewhere. Later launches
-reuse that cache, so the download happens once per version.
-
-> Renamed in 0.2.3. The old package id was `dsh-glass-plugin`; it still resolves
-> to the same app, but new installs should use `dsh-status-bar-plugin`.
-
-### From a checkout (development)
-
-The desktop profile can link the package instead of installing it:
-
-```jsonc
-// <profile>/package.json
-"dependencies": { "dsh-status-bar-plugin": "link:D:/codexwork/dsh/dsh-glass-spec/packages/dsh-status-bar" },
-"dsh": { "profile": { "bundles": [/* ... */ "dsh-status-bar-plugin"] } }
-```
-
-In a checkout the plugin uses `apps/desktop/out` as the app directory and the
-workspace `electron` package, so run `pnpm build` first. Point a junction or
-symlink at `node_modules/dsh-status-bar-plugin` if pnpm did not run, then restart DSH.
-
-## Configuration
-
-The bundle patch sets `autoLaunch: true`. To keep the plugin installed but stop it
-from launching the companion, override the row config in the profile patch:
-
-```yaml
-- id: dsh-status-bar-plugin
-  config:
-    autoLaunch: false
-```
-
-Other overrides, all optional:
-
-| key | meaning |
-|:--|:--|
-| `appDir` | directory holding `out/main/index.js` |
-| `electronBinary` | path to an Electron executable |
-| `runtimeDir` | where the downloaded runtime is cached |
-| `downloadUrl` | override the runtime tarball URL |
-| `autoReload` | relaunch the companion when the desktop bundle changes (default `true`) |
-
-The same settings are available through the environment:
-`DSH_STATUS_BAR_APP`, `DSH_STATUS_BAR_ELECTRON`, `DSH_STATUS_BAR_RUNTIME`,
-`DSH_STATUS_BAR_RUNTIME_URL`. The pre-0.2.3 names (`DSH_GLASS_*`) still work as
-fallbacks.
-
-## Requirements
-
-- Windows 11 x64 (the glass refraction reads the screen behind the window).
-- The desktop app is a separate Electron process; it needs a GPU-backed Electron
-  runtime, which the release tarball provides.
-
-## License
-
-MIT. The bundled Electron runtime keeps its own license files
-(`electron/dist/LICENSE`, `LICENSES.chromium.html`).
+# dsh-status-bar
+
+DSH bundle for **DSH Status Bar** — a floating glass status bar for DeepSeek Harness.
+The npm name and the bundle row id are `dsh-status-bar-plugin`. npm already hosts an unrelated `dsh-statusbar`, so the registry rejects the shorter name as too similar.
+
+## What it does
+
+The plugin mounts one host row in DSH. At boot it waits for the local web server,
+asks the `connection` service for the authenticated host URL
+(`connection.authenticatedUrl(origin)`), and starts the desktop app with that link:
+
+```text
+electron <app dir> --dsh-link=<authenticated url> --launcher-pid=<host pid>
+```
+
+The companion connects with that link on launch, so nothing has to be pasted. The
+link travels only in the process arguments and is never logged — the plugin prints
+`[dsh-status-bar] Glass desktop companion launched (authenticated link redacted)`.
+The app rejects non-loopback links, credentials, hashes and sub-paths before it
+touches the network. `--launcher-pid` makes the companion exit when the DSH
+process it belongs to disappears; disposing the plugin kills the spawned tree.
+
+If the companion is already running, the second launch hits its single-instance
+lock: the existing window is focused and re-connected with the new link.
+
+## Reopening a hidden or closed companion
+
+Hiding the window keeps the process alive; `Ctrl+Shift+G` toggles it back. After
+the user quits the companion, the plugin registers the DSH slash command
+`/status-bar`. Invoking it in any session asks DSH for a fresh authenticated link
+and either shows the existing instance through the single-instance hand-off or
+starts a new one. The command is registered even when `autoLaunch: false`, so a
+manually disabled companion can still be opened without restarting DSH. It never
+stores or replays an old token.
+
+## Install
+
+From npm, from the plugin market (once listed), or straight from the release
+tarball:
+
+```sh
+# npm: ~870 kB, fetches the 155 MB runtime once on first launch
+dsh plugin --profile web add dsh-status-bar-plugin
+
+# release tarball: 155 MB, self-contained, nothing downloaded later
+dsh plugin --profile web add https://github.com/wfz2006/dsh-status-bar/releases/latest/download/dsh-status-bar.tgz
+```
+
+Both end up as the same companion: the built desktop app plus an Electron
+runtime. The tarball carries them; the npm package reads the download URL from its
+own manifest (`dsh.statusBar.runtime`), fetches that tarball the first time DSH
+starts it, and unpacks it into a per-version cache:
+`%LOCALAPPDATA%\dsh-status-bar\runtime-<version>` on
+Windows, `~/.cache/dsh-status-bar/runtime-<version>` elsewhere. Later launches
+reuse that cache, so the download happens once per version.
+
+On Windows, a small native preparation window shows download progress before
+Electron is available. A failed download shows **Retry** and **Try later**;
+retry continues without restarting DSH. Cancel stops the preparation and keeps
+the verifiable partial for the next launch. A valid cache opens the companion
+directly, without flashing the preparation window.
+
+The downloader prefers system `curl` (and falls back to Node if unavailable),
+checks stalled connections, and makes up to three attempts. Partial files live
+beside the cache as `runtime-<version>.tgz.part`; Range resume requires an ETag or
+Last-Modified validator. If the server ignores Range or no validator exists,
+the file is downloaded afresh rather than concatenated incorrectly. Corrupt
+archives are discarded; extracted content must match the plugin version before
+it replaces a cache. A per-version lock prevents concurrent hosts from writing
+the same partial/cache. Plugin disposal aborts preparation and prevents late launch.
+
+The default GitHub URL is pinned to `releases/download/v<plugin-version>/...`,
+even for older manifests advertising `latest`. An explicit download URL override
+is respected; its archive must still match the installed plugin version. No
+authenticated DSH link is requested until the runtime is ready, and progress
+files contain no Host token or Cookie. Non-Windows environments retain log output;
+the native progress UI is Windows-only.
+
+> Renamed in 0.2.3. The old package id was `dsh-glass-plugin`; it still resolves
+> to the same app, but new installs should use `dsh-status-bar-plugin`.
+
+### From a checkout (development)
+
+The desktop profile can link the package instead of installing it:
+
+```jsonc
+// <profile>/package.json
+"dependencies": { "dsh-status-bar-plugin": "link:D:/codexwork/dsh/dsh-glass-spec/packages/dsh-status-bar" },
+"dsh": { "profile": { "bundles": [/* ... */ "dsh-status-bar-plugin"] } }
+```
+
+In a checkout the plugin uses `apps/desktop/out` as the app directory and the
+workspace `electron` package, so run `pnpm build` first. Point a junction or
+symlink at `node_modules/dsh-status-bar-plugin` if pnpm did not run, then restart DSH.
+
+## Configuration
+
+The bundle patch sets `autoLaunch: true`. To keep the plugin installed but stop it
+from launching the companion at boot, override the row config in the profile
+patch; `/status-bar` remains available for manual launches:
+
+```yaml
+- id: dsh-status-bar-plugin
+  config:
+    autoLaunch: false
+```
+
+Other overrides, all optional:
+
+| key | meaning |
+|:--|:--|
+| `appDir` | directory holding `out/main/index.js` |
+| `electronBinary` | path to an Electron executable |
+| `runtimeDir` | where the downloaded runtime is cached |
+| `downloadUrl` | override the runtime tarball URL |
+| `autoReload` | relaunch the companion when the desktop bundle changes (default `true`) |
+| `showStartupUI` | show native Windows preparation/error feedback (default `true`); disable only for intentionally headless use |
+
+The same settings are available through the environment:
+`DSH_STATUS_BAR_APP`, `DSH_STATUS_BAR_ELECTRON`, `DSH_STATUS_BAR_RUNTIME`,
+`DSH_STATUS_BAR_RUNTIME_URL`. The pre-0.2.3 names (`DSH_GLASS_*`) still work as
+fallbacks.
+
+## Requirements
+
+- Windows 11 x64 (the glass refraction reads the screen behind the window).
+- The desktop app is a separate Electron process; it needs a GPU-backed Electron
+  runtime, which the release tarball provides.
+
+## License
+
+MIT. The bundled Electron runtime keeps its own license files
+(`electron/dist/LICENSE`, `LICENSES.chromium.html`).
+
+## Development verification
+
+From the repository root, run `pnpm test` and `pnpm test:plugin-startup` after
+`pnpm build`. The latter uses a temporary thin-plugin install, local HTTP/Host,
+native WPF feedback and the actual workspace Electron through the documented
+`electronBinary` override. It does not reinstall or enable the production plugin.
+See [first-run recovery](../../docs/first-run-recovery.md) for evidence and limits.

package/cordis.patch.yml

@@ -1,12 +1,12 @@
-# dsh-status-bar-plugin bundle patch
-#
-# This is the `dsh.bundle.patch` layer of the local bundle package. When the
-# package is declared in a profile's dependencies, adding it to
-# `dsh.profile.bundles` mounts the row below at boot. The row resolves
-# `dsh-status-bar-plugin` from the profile's node_modules, where the `link:`
-# dependency points back at this directory.
-- insert:
-    - id: dsh-status-bar-plugin
-      name: 'dsh-status-bar-plugin'
-      config:
-        autoLaunch: true
+# dsh-status-bar-plugin bundle patch
+#
+# This is the `dsh.bundle.patch` layer of the local bundle package. When the
+# package is declared in a profile's dependencies, adding it to
+# `dsh.profile.bundles` mounts the row below at boot. The row resolves
+# `dsh-status-bar-plugin` from the profile's node_modules, where the `link:`
+# dependency points back at this directory.
+- insert:
+    - id: dsh-status-bar-plugin
+      name: 'dsh-status-bar-plugin'
+      config:
+        autoLaunch: true

package/lib/download.js

@@ -0,0 +1,153 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream, existsSync, readFileSync, writeFileSync, statSync, rmSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { get as httpGet } from 'node:http';
+import { get as httpsGet } from 'node:https';
+import { pipeline } from 'node:stream/promises';
+import { join } from 'node:path';
+
+export function abortError() { return Object.assign(new Error('已取消准备，下次启动可继续下载。'), { name: 'AbortError' }); }
+export function checkAbort(signal) { if (signal?.aborted) throw abortError(); }
+export function delay(ms, signal) {
+  checkAbort(signal);
+  return new Promise((resolve, reject) => {
+    const abort = () => { clearTimeout(timer); reject(abortError()); };
+    const timer = setTimeout(() => { signal?.removeEventListener('abort', abort); resolve(); }, ms);
+    signal?.addEventListener('abort', abort, { once: true });
+  });
+}
+const size = path => { try { return statSync(path).size; } catch { return 0; } };
+const json = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; } };
+function reset(part) { for (const path of [part, `${part}.json`]) rmSync(path, { force: true }); }
+function validator(headers) {
+  const tag = headers.etag;
+  return typeof tag === 'string' && !tag.startsWith('W/') ? tag : headers['last-modified'];
+}
+function finalHeaders(file) {
+  try {
+    const blocks = readFileSync(file, 'utf8').split(/\r?\n\r?\n/).filter(block => /^HTTP\//.test(block));
+    const last = blocks.at(-1); if (!last) return {};
+    const lines = last.split(/\r?\n/); const status = Number(lines.shift()?.split(' ')[1]);
+    return { status, headers: Object.fromEntries(lines.filter(line => line.includes(':')).map(line => { const i = line.indexOf(':'); return [line.slice(0, i).toLowerCase(), line.slice(i + 1).trim()]; })) };
+  } catch { return {}; }
+}
+function metadata(headers, source) {
+  const range = String(headers['content-range'] ?? '').match(/^bytes \d+-\d+\/(\d+)$/);
+  return { source, validator: validator(headers), total: range ? Number(range[1]) : Number(headers['content-length']) || 0 };
+}
+function curlAttempt(url, part, previous, options) {
+  const headersFile = `${part}.headers`;
+  rmSync(headersFile, { force: true });
+  const offset = size(part);
+  const program = process.platform === 'win32' ? join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'curl.exe') : 'curl';
+  const args = ['--silent', '--show-error', '--location', '--fail', '--connect-timeout', '15', '--max-time', String(options.timeoutMs / 1000),
+    '--speed-limit', '1', '--speed-time', String(Math.max(1, Math.ceil(options.idleMs / 1000))), '--proto-redir', '=https,http',
+    '--dump-header', headersFile, '--output', part];
+  if (new URL(url).protocol === 'https:') args.push('--proto', '=https', '--proto-redir', '=https');
+  if (offset) args.push('--continue-at', String(offset), '--header', `If-Range: ${previous.validator}`);
+  args.push('--url', url);
+  return new Promise((resolve, reject) => {
+    let child;
+    const progress = () => {
+      const result = finalHeaders(headersFile);
+      if (result.status === 200 || result.status === 206) {
+        const next = metadata(result.headers, options.source);
+        writeFileSync(`${part}.json`, JSON.stringify(next));
+        options.onProgress({ received: size(part), total: next.total });
+      }
+    };
+    const abort = () => child?.kill();
+    try { child = spawn(program, args, { windowsHide: true, stdio: 'ignore' }); }
+    catch (error) { reject(error); return; }
+    const timer = setInterval(() => { try { progress(); } catch (error) { child.kill(); reject(error); } }, 250); timer.unref();
+    const exiting = () => child.kill(); process.once('exit', exiting);
+    options.signal?.addEventListener('abort', abort, { once: true });
+    child.once('error', error => { clearInterval(timer); process.removeListener('exit', exiting); options.signal?.removeEventListener('abort', abort); reject(error); });
+    child.once('close', code => {
+      clearInterval(timer); options.signal?.removeEventListener('abort', abort);
+      process.removeListener('exit', exiting);
+      try {
+        progress(); checkAbort(options.signal);
+        const response = finalHeaders(headersFile);
+        if (code === 0) { resolve(); return; }
+        const completed = response.status === 416 && String(response.headers?.['content-range']).match(/^bytes \*\/(\d+)$/);
+        if (completed && Number(completed[1]) === offset && previous.total === offset) { resolve(); return; }
+        if (code === 33 || response.status === 416) reset(part);
+        reject(new Error(response.status >= 400 ? `下载服务返回 HTTP ${response.status}。` : `下载连接中断或超时（curl ${code ?? 'stopped'}）。`));
+      } catch (error) { reject(error); }
+      finally { rmSync(headersFile, { force: true }); }
+    });
+    if (options.signal?.aborted) abort();
+  });
+}
+async function nodeAttempt(url, part, previous, options, redirects = 5) {
+  checkAbort(options.signal);
+  const offset = size(part); let request; let timeout;
+  try {
+    const response = await new Promise((resolve, reject) => {
+      const headers = offset ? { Range: `bytes=${offset}-`, 'If-Range': previous.validator } : {};
+      request = (new URL(url).protocol === 'https:' ? httpsGet : httpGet)(url, { headers, signal: options.signal }, resolve);
+      request.once('error', reject);
+      request.setTimeout(options.idleMs, () => request.destroy(new Error('下载连接长时间没有数据。')));
+      timeout = setTimeout(() => request.destroy(new Error('下载超时。')), options.timeoutMs); timeout.unref();
+    });
+    const status = response.statusCode ?? 0;
+    if (status >= 300 && status < 400 && response.headers.location) {
+      response.resume();
+      const next = new URL(response.headers.location, url);
+      if (redirects <= 0 || new URL(url).protocol === 'https:' && next.protocol !== 'https:') throw new Error('下载重定向无效。');
+      return await nodeAttempt(next.href, part, previous, options, redirects - 1);
+    }
+    const complete = status === 416 && String(response.headers['content-range']).match(/^bytes \*\/(\d+)$/);
+    if (complete && Number(complete[1]) === offset && previous.total === offset) { response.resume(); return; }
+    if (status !== 200 && status !== 206) { response.resume(); if (status === 416) reset(part); throw new Error(`下载服务返回 HTTP ${status}。`); }
+    const range = String(response.headers['content-range'] ?? '').match(/^bytes (\d+)-(\d+)\/(\d+)$/);
+    if (status === 206 && (!offset || !range || Number(range[1]) !== offset || Number(range[2]) >= Number(range[3]))) {
+      response.destroy(); reset(part); throw new Error('续传范围不匹配，下一次重新下载。');
+    }
+    const next = metadata(response.headers, options.source);
+    writeFileSync(`${part}.json`, JSON.stringify(next));
+    let received = status === 206 ? offset : 0;
+    const report = () => { try { options.onProgress({ received, total: next.total }); } catch (error) { request.destroy(error); } };
+    response.on('data', chunk => { received += chunk.length; report(); });
+    const progress = setInterval(report, 250); progress.unref();
+    try { await pipeline(response, createWriteStream(part, { flags: status === 206 ? 'a' : 'w' }), { signal: options.signal }); }
+    finally { clearInterval(progress); }
+    if (next.total && size(part) !== next.total) throw new Error('下载文件不完整。');
+  } finally { clearTimeout(timeout); }
+}
+
+/** The partial file and its entity validator survive network errors/restarts.
+ * Curl uses the working Windows network path; Node is only the missing-curl fallback. */
+export async function downloadArchive(url, part, { signal, onProgress = () => {}, attempts = 3, idleMs = 30000, timeoutMs = 300000, backend = 'auto' } = {}) {
+  const parsed = new URL(url);
+  if (parsed.username || parsed.password || !['https:', 'http:'].includes(parsed.protocol) || parsed.protocol === 'http:' && !['127.0.0.1', 'localhost', '[::1]'].includes(parsed.hostname)) throw new Error('运行时地址必须使用 HTTPS。');
+  const source = createHash('sha256').update(url).digest('hex');
+  let useNode = backend === 'node'; let lastError;
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    checkAbort(signal);
+    const previous = json(`${part}.json`);
+    if (previous.source !== source || !previous.validator) reset(part);
+    if (existsSync(part) && previous.source === source && previous.total > 0 && size(part) === previous.total) return;
+    onProgress({ phase: 'downloading', received: size(part), total: previous.total || 0, attempt, message: '正在下载桌面运行时，完成后自动打开悬浮窗。' });
+    let reported = 0;
+    const options = { source, signal, idleMs, timeoutMs, onProgress: progress => {
+      const now = Date.now(); if (now - reported < 250 && progress.received !== progress.total) return;
+      reported = now; onProgress({ phase: 'downloading', attempt, ...progress });
+    } };
+    try {
+      if (!useNode) {
+        try { await curlAttempt(url, part, previous, options); }
+        catch (error) { if (!['ENOENT', 'EACCES', 'EPERM'].includes(error.code)) throw error; useNode = true; await nodeAttempt(url, part, previous, options); }
+      } else await nodeAttempt(url, part, previous, options);
+      checkAbort(signal); return;
+    } catch (error) {
+      checkAbort(signal); lastError = error;
+      if (attempt < attempts) {
+        onProgress({ phase: 'retrying', message: `下载中断，${attempt} 秒后重试；可验证的已下载部分会保留。`, attempt });
+        await delay(attempt * 1000, signal);
+      }
+    }
+  }
+  throw new Error(`${lastError?.message ?? '运行时下载失败。'} 已保留可续传的数据，可点击重试。`);
+}

package/lib/index.js

@@ -1,350 +1,165 @@
-// DSH bundle entry for the Glass companion.
-//
-// The desktop app is its own Electron process. This host plugin starts it once
-// the local web server is up, handing over the authenticated URL through
-// `--dsh-link` so Glass connects without the user pasting anything. When Glass
-// is already running, its single-instance lock focuses the existing window and
-// re-connects it with the new link.
-//
-// Three install shapes have to work:
-//
-//   - the release tarball, which ships the built app in `app/` and an Electron
-//     runtime in `electron/dist/` (self-contained, nothing to build);
-//   - the npm package, which ships only this plugin and fetches the same
-//     tarball once into a cache directory on first launch;
-//   - a checkout of the repository, where both live outside this package
-//     (`apps/desktop/out` and the workspace `electron` dependency).
-//
-// The child also receives `--launcher-pid`; Glass exits when that host process
-// disappears, and disposal kills the spawned tree so the companion follows DSH.
-import { spawn, spawnSync } from 'node:child_process';
-import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';
-import { get as httpsGet } from 'node:https';
-import { createRequire } from 'node:module';
-import { homedir, tmpdir } from 'node:os';
-import { dirname, join } from 'node:path';
+// DSH starts the companion only after its runtime and authenticated Host are
+// ready. Bootstrap work is cancellable and never replays a saved Host token.
+import { spawn } from 'node:child_process';
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureRuntime, resolveInstalled, resolveAvailable } from './runtime.js';
+import { createStartupStatus } from './startup-status.js';
 
 export const name = 'dsh-status-bar-plugin';
 export const inject = ['connection', 'webServer'];
-
-/** Package root: `lib/index.js` -> the directory that holds `package.json`. */
 const pluginRoot = fileURLToPath(new URL('../', import.meta.url));
-
-/** Where the light npm package writes the runtime it downloads on first run. */
-const DEFAULT_RUNTIME_URL = 'https://github.com/wfz2006/dsh-status-bar/releases/latest/download/dsh-status-bar.tgz';
-
-/** The download URL the published manifest advertises, if any. */
-function manifestRuntimeUrl() {
-  try {
-    const manifest = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
-    const url = manifest?.dsh?.statusBar?.runtime;
-    return typeof url === 'string' && url.length > 0 ? url : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Electron's binary sits at these relative paths inside a `dist/` directory. */
-function electronExecutables() {
-  if (process.platform === 'win32') return ['electron.exe'];
-  if (process.platform === 'darwin') return [join('Electron.app', 'Contents', 'MacOS', 'Electron')];
-  return ['electron'];
+function stamp(appDir) { try { return statSync(join(appDir, 'out', 'main', 'index.js')).mtimeMs; } catch { return 0; } }
+function killChild(child) {
+  if (!child || child.exitCode !== null || child.pid === undefined) return;
+  if (process.platform === 'win32') {
+    const killer = spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
+    killer.on('error', () => { try { child.kill(); } catch { /* Already gone. */ } });
+  } else { try { child.kill(); } catch { /* Already gone. */ } }
 }
-
-function firstFile(candidates) {
-  for (const candidate of candidates) {
-    if (typeof candidate === 'string' && candidate.length > 0 && existsSync(candidate)) return candidate;
+function launchEnv() { const env = { ...process.env }; delete env.ELECTRON_RUN_AS_NODE; return env; }
+export function apply(ctx, config = {}) {
+  let child; let timer; let watcher; let controller; let feedback;
+  let attempts = 0; let bundleStamp = 0; let preparing = false; let spawning = false;
+  let disposed = false; let paused = false; let failed = false;
+  let target = resolveAvailable(config, pluginRoot);
+  function stopClock() { clearInterval(timer); timer = undefined; }
+  function closeStatus() { feedback?.close(); feedback = undefined; }
+  function update(state) {
+    if (disposed || paused) return;
+    feedback ??= createStartupStatus(config, { retry, cancel }); feedback.update(state);
   }
-  return undefined;
-}
-
-function hasApp(candidate) {
-  return typeof candidate === 'string' && candidate.length > 0 && existsSync(join(candidate, 'out', 'main', 'index.js'));
-}
-
-function distBinary(distDir) {
-  return firstFile(electronExecutables().map(name => join(distDir, name)));
-}
-
-function packageVersion() {
-  try {
-    const manifest = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
-    return typeof manifest.version === 'string' ? manifest.version : '0.0.0';
-  } catch {
-    return '0.0.0';
+  function fail(message) {
+    if (disposed || paused) return;
+    failed = true; stopClock();
+    update({ phase: 'failed', message, received: 0, total: 0 });
   }
-}
-
-/**
- * The app directory holds `out/main/index.js`. The packaged copy wins, then an
- * explicit override, then the checkout layout used while developing.
- */
-function resolveAppDir(config) {
-  return firstFile([
-    config.appDir,
-    process.env.DSH_STATUS_BAR_APP,
-    process.env.DSH_GLASS_APP,
-    join(pluginRoot, 'app'),
-    join(pluginRoot, '..', '..', 'apps', 'desktop'),
-  ].filter(hasApp));
-}
-
-function resolveElectron(config, appDir) {
-  const explicit = firstFile([config.electronBinary, process.env.DSH_STATUS_BAR_ELECTRON, process.env.DSH_GLASS_ELECTRON].filter(value => typeof value === 'string'));
-  if (explicit) return explicit;
-
-  // Release tarball: the runtime travels with the package.
-  const bundled = distBinary(join(pluginRoot, 'electron', 'dist'));
-  if (bundled) return bundled;
-
-  // Source install: use the `electron` package installed next to the app (the
-  // workspace checkout) or next to this package (a registry dependency).
-  for (const base of [appDir, pluginRoot]) {
-    if (!base) continue;
-    try {
-      const manifest = createRequire(join(base, 'package.json')).resolve('electron/package.json');
-      const binary = distBinary(join(dirname(manifest), 'dist'));
-      if (binary) return binary;
-    } catch {
-      // Not installed this way; try the next base.
-    }
+  function cancel() {
+    if (disposed || paused) return;
+    paused = true; controller?.abort(); stopClock(); closeStatus();
   }
-  return undefined;
-}
-
-/** A layout that already has both halves of the companion. */
-function resolveInstalled(config) {
-  const appDir = resolveAppDir(config);
-  if (!appDir) return undefined;
-  const electron = resolveElectron(config, appDir);
-  return electron ? { appDir, electron } : undefined;
-}
-
-function runtimeRoot(config) {
-  const base = config.runtimeDir
-    ?? process.env.DSH_STATUS_BAR_RUNTIME
-    ?? process.env.DSH_GLASS_RUNTIME
-    ?? (process.platform === 'win32'
-      ? join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'dsh-status-bar')
-      : join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'dsh-status-bar'));
-  return join(base, `runtime-${packageVersion()}`);
-}
-
-function describeError(error) {
-  return error instanceof Error ? error.message : String(error);
-}
-
-/** Follows redirects; GitHub's release download resolves to a CDN host. */
-function download(url, destination, { redirects = 5 } = {}) {
-  return new Promise((resolve, reject) => {
-    const request = httpsGet(url, (response) => {
-      const status = response.statusCode ?? 0;
-      if (status >= 300 && status < 400 && response.headers.location) {
-        response.resume();
-        if (redirects <= 0) {
-          reject(new Error(`too many redirects while downloading ${url}`));
-          return;
-        }
-        const next = new URL(response.headers.location, url).href;
-        download(next, destination, { redirects: redirects - 1 }).then(resolve, reject);
-        return;
-      }
-      if (status !== 200) {
-        response.resume();
-        reject(new Error(`download failed with HTTP ${status}: ${url}`));
-        return;
-      }
-      const total = Number(response.headers['content-length'] ?? 0);
-      let received = 0;
-      let reported = 0;
-      const file = createWriteStream(destination);
-      response.on('data', (chunk) => {
-        received += chunk.length;
-        if (total > 0) {
-          const percent = Math.floor((received / total) * 100);
-          if (percent >= reported + 10) {
-            reported = percent - (percent % 10);
-            console.info(`[dsh-status-bar] downloading the Glass runtime: ${reported}% of ${Math.round(total / (1024 * 1024))} MB`);
-          }
-        }
-      });
-      response.pipe(file);
-      file.on('finish', () => file.close(() => resolve(received)));
-      file.on('error', (error) => {
-        rmSync(destination, { force: true });
-        reject(error);
+  function retry() {
+    if (disposed || preparing || spawning || child) return;
+    failed = paused = false; attempts = 0;
+    target = resolveAvailable(config, pluginRoot) ?? target;
+    if (target) startClock(); else prepare();
+  }
+  function prepare() {
+    if (preparing || target || disposed || paused || failed) return;
+    preparing = true; const current = new AbortController(); controller = current;
+    update({ phase: 'downloading', received: 0, total: 0, message: '首次启动需要准备桌面运行时，完成后自动打开悬浮窗。' });
+    void ensureRuntime(config, pluginRoot, { signal: current.signal, onProgress: update }).then(next => {
+      if (disposed || paused || current.signal.aborted || controller !== current) return;
+      target = resolveInstalled({ ...config, appDir: next.appDir }, pluginRoot) ?? next; bundleStamp = stamp(target.appDir);
+      update({ phase: 'launching', message: '运行时已就绪，正在连接 DSH 并打开悬浮窗。' });
+      startClock();
+    }, error => {
+      if (!current.signal.aborted && !disposed && !paused) fail(error instanceof Error ? error.message : '运行时准备失败，请点击重试。');
+    }).finally(() => { if (controller === current) { preparing = false; controller = undefined; } });
+  }
+  function startClock() {
+    if (timer || disposed || paused || failed) return;
+    timer = setInterval(tryLaunch, 250);
+  }
+  function spawnTracked(link) {
+    spawning = true; stopClock();
+    let spawned;
+    try {
+      spawned = spawn(target.electron, [target.appDir, `--dsh-link=${link}`, `--launcher-pid=${process.pid}`], {
+        cwd: target.appDir, detached: true, stdio: 'ignore', env: launchEnv(),
       });
+    } catch { spawning = false; fail('无法启动桌面运行时，请检查系统权限后重试。'); return; }
+    child = spawned;
+    spawned.once('error', error => {
+      if (child === spawned) child = undefined;
+      spawning = false;
+      const code = /^[A-Z0-9_]+$/.test(error.code ?? '') ? error.code : 'unknown';
+      fail(`桌面运行时未能启动（${code}），请检查运行时文件与权限后重试。`);
     });
-    request.on('error', (error) => {
-      rmSync(destination, { force: true });
-      reject(error);
+    spawned.once('spawn', () => {
+      spawning = false;
+      if (disposed || paused) { killChild(spawned); return; }
+      bundleStamp = stamp(target.appDir); closeStatus();
+      console.info('[dsh-status-bar] Glass desktop companion launched (authenticated link redacted)');
     });
-    request.setTimeout(15 * 60 * 1000, () => request.destroy(new Error(`timed out downloading ${url}`)));
-  });
-}
-
-/** `tar` ships with Windows 10+ (bsdtar), macOS and every mainstream Linux. */
-function extract(tarball, directory) {
-  const result = spawnSync('tar', ['-xzf', tarball, '-C', directory], { stdio: 'ignore', windowsHide: true });
-  if (result.status !== 0) {
-    throw new Error(`could not unpack ${tarball} (tar exited with ${result.status ?? result.signal}); extract it manually to ${directory}`);
+    spawned.once('exit', (code, signal) => {
+      if (child !== spawned) return;
+      child = undefined; spawning = false;
+      if (!disposed && !paused && (code !== 0 || signal)) fail('悬浮窗进程意外退出。点击重试可重新启动；若仍失败，请重新安装运行时。');
+    });
+    spawned.unref();
   }
-}
-
-/**
- * Downloads and unpacks the release tarball into the per-version cache, then
- * returns the same `{ appDir, electron }` shape as a bundled install.
- */
-async function fetchRuntime(config) {
-  const url = config.downloadUrl ?? process.env.DSH_STATUS_BAR_RUNTIME_URL ?? process.env.DSH_GLASS_RUNTIME_URL ?? manifestRuntimeUrl() ?? DEFAULT_RUNTIME_URL;
-  const root = runtimeRoot(config);
-  const cached = { appDir: join(root, 'app'), electron: distBinary(join(root, 'electron', 'dist')) };
-  if (hasApp(cached.appDir) && cached.electron) return cached;
-
-  const staging = `${root}.staging`;
-  const tarball = join(tmpdir(), `dsh-status-bar-${process.pid}-${Date.now()}.tgz`);
-  rmSync(staging, { recursive: true, force: true });
-  mkdirSync(staging, { recursive: true });
-  console.info(`[dsh-status-bar] first run: fetching the ~155 MB Glass runtime from ${url}`);
-  try {
-    const bytes = await download(url, tarball);
-    console.info(`[dsh-status-bar] unpacking the Glass runtime (${Math.round(bytes / (1024 * 1024))} MB)`);
-    extract(tarball, staging);
-    const unpacked = join(staging, 'package');
-    if (!hasApp(join(unpacked, 'app')) || !distBinary(join(unpacked, 'electron', 'dist'))) {
-      throw new Error('the downloaded archive does not contain app/ and electron/dist/');
-    }
-    rmSync(root, { recursive: true, force: true });
-    mkdirSync(root, { recursive: true });
-    renameSync(join(unpacked, 'app'), join(root, 'app'));
-    renameSync(join(unpacked, 'electron'), join(root, 'electron'));
-  } finally {
-    rmSync(tarball, { force: true });
-    rmSync(staging, { recursive: true, force: true });
+  function tryLaunch() {
+    if (disposed || paused || failed || spawning || child) return;
+    if (!target) { prepare(); return; }
+    if (++attempts > 600) { fail('DSH 本地服务尚未就绪，悬浮窗未启动。待 DSH 加载完成后点击重试。'); return; }
+    let link;
+    try { link = ctx.connection.authenticatedUrl(ctx.webServer.getOrigin()); } catch { return; }
+    if (typeof link !== 'string' || !/^https?:\/\//.test(link)) return;
+    spawnTracked(link);
   }
-
-  const electron = distBinary(join(root, 'electron', 'dist'));
-  if (!electron) throw new Error(`the runtime in ${root} has no Electron executable`);
-  return { appDir: join(root, 'app'), electron };
-}
-
-function killChild(child) {
-  if (!child || child.exitCode !== null || child.pid === undefined) return;
-  try { child.kill(); } catch { /* already gone */ }
-  if (process.platform === 'win32') spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true });
-}
-
-function bundleMtimeOf(appDir) {
-  try { return statSync(join(appDir, 'out', 'main', 'index.js')).mtimeMs; } catch { return 0; }
-}
-
-export function apply(ctx, config = {}) {
-  if (config.autoLaunch === false) return;
-  let child;
-  let attempts = 0;
-  let timer;
-  let watcher;
-  let bundleStamp = 0;
-  let target = resolveInstalled(config);
-  let preparing = false;
-  let fatal;
-
-  const stopClock = () => {
-    if (timer) clearInterval(timer);
-    timer = undefined;
-  };
-
-  const startClock = () => {
-    if (!timer) timer = setInterval(tryLaunch, 250);
-  };
-
-  const useTarget = (next) => {
-    target = next;
-    bundleStamp = bundleMtimeOf(next.appDir);
-    startClock();
-  };
-
-  const prepare = () => {
-    if (preparing || target || fatal) return;
-    preparing = true;
-    fetchRuntime(config).then((next) => {
-      preparing = false;
-      console.info(`[dsh-status-bar] Glass runtime ready at ${next.appDir}`);
-      useTarget(next);
-    }, (error) => {
-      preparing = false;
-      fatal = `[dsh-status-bar] could not prepare the Glass runtime: ${describeError(error)}`;
-      console.warn(fatal);
-      stopClock();
+  function wake(link) {
+    return new Promise((resolve, reject) => {
+      let spawned;
+      try {
+        spawned = spawn(target.electron, [target.appDir, `--dsh-link=${link}`, `--launcher-pid=${process.pid}`], {
+          cwd: target.appDir, detached: true, stdio: 'ignore', env: launchEnv(),
+        });
+      } catch (error) { reject(error); return; }
+      spawned.once('spawn', () => resolve());
+      spawned.once('error', reject);
+      spawned.unref();
     });
-  };
-
-  const tryLaunch = () => {
-    if (fatal) return;
+  }
+  // The command is the recovery entry for a hidden window and for a companion
+  // the user quit earlier. A running instance receives the second-instance
+  // hand-off and shows itself; a missing one is launched with a fresh link.
+  async function showCompanion() {
+    if (disposed) return { kind: 'error', text: '插件已停用，请重启 DSH。' };
+    failed = paused = false; attempts = 0;
     if (!target) {
-      // The npm build has no app yet: fetch it once, then keep waiting for the
-      // web server in the background instead of counting down against it.
-      prepare();
-      return;
+      if (!preparing) prepare();
+      return { kind: 'success', text: '正在准备桌面运行时，完成后会自动打开悬浮窗。' };
     }
-    attempts += 1;
-    if (attempts > 600) {
-      stopClock();
-      console.warn('[dsh-status-bar] no web server origin after 150s; the Glass companion was not started');
-      return;
-    }
-    let origin;
-    try { origin = ctx.webServer.getOrigin(); } catch { return; }
     let link;
-    try { link = ctx.connection.authenticatedUrl(origin); } catch { return; }
-    if (!link || !/^https?:\/\//.test(link)) return;
-
-    const env = { ...process.env };
-    delete env.ELECTRON_RUN_AS_NODE;
-    const spawned = spawn(target.electron, [target.appDir, `--dsh-link=${link}`, `--launcher-pid=${process.pid}`], {
-      cwd: target.appDir,
-      detached: true,
-      stdio: 'ignore',
-      env,
-    });
-    child = spawned;
-    spawned.on('exit', () => { if (child === spawned) child = undefined; });
-    spawned.unref();
-    bundleStamp = bundleMtimeOf(target.appDir);
-    stopClock();
-    console.info('[dsh-status-bar] Glass desktop companion launched (authenticated link redacted)');
-  };
-
-  if (typeof ctx.effect === 'function') {
-    ctx.effect(() => () => {
-      stopClock();
-      if (watcher) clearInterval(watcher);
-      watcher = undefined;
-      killChild(child);
-      child = undefined;
-    });
+    try { link = ctx.connection.authenticatedUrl(ctx.webServer.getOrigin()); } catch { link = undefined; }
+    if (typeof link !== 'string' || !/^https?:\/\//.test(link)) return { kind: 'error', text: 'DSH 本地服务尚未就绪，请稍后再试。' };
+    if (child) {
+      try { await wake(link); return { kind: 'success', text: '已请求显示悬浮窗。' }; }
+      catch { return { kind: 'error', text: '无法显示悬浮窗，请稍后重试。' }; }
+    }
+    if (spawning) return { kind: 'success', text: '正在打开悬浮窗。' };
+    startClock(); tryLaunch();
+    return { kind: 'success', text: '正在打开悬浮窗。' };
   }
-
-  if (target) {
-    startClock();
-  } else {
-    prepare();
+  function registerCommand() {
+    if (typeof ctx.inject !== 'function') return;
+    ctx.inject(['commands'], commandCtx => {
+      const register = () => commandCtx.commands.register({
+        name: 'status-bar',
+        description: '显示或重新启动 DSH Status Bar 悬浮窗',
+        recordInput: false,
+        handler: showCompanion,
+      });
+      if (typeof commandCtx.effect === 'function') commandCtx.effect(register);
+      else if (typeof ctx.effect === 'function') ctx.effect(register);
+      else register();
+    });
   }
-
+  registerCommand();
+  if (config.autoLaunch === false) return;
+  if (typeof ctx.effect === 'function') ctx.effect(() => () => {
+    disposed = true; controller?.abort(); stopClock(); clearInterval(watcher); watcher = undefined;
+    closeStatus(); killChild(child); child = undefined;
+  });
+  if (target) startClock(); else prepare();
   if (config.autoReload !== false) {
-    // Rebuild-and-reload loop: when the desktop bundle changes, relaunch the
-    // running companion with the current authenticated link. A user-initiated
-    // quit leaves `child` empty, so it is never resurrected by a build.
     watcher = setInterval(() => {
-      if (!target) return;
-      const stamp = bundleMtimeOf(target.appDir);
-      if (!child || !stamp || bundleStamp === 0 || stamp === bundleStamp) return;
-      bundleStamp = stamp;
-      console.info('[dsh-status-bar] desktop bundle changed; relaunching the Glass companion');
-      killChild(child);
-      child = undefined;
-      startClock();
-    }, 1500);
+      if (!target || !child || spawning || disposed || paused) return;
+      const nextStamp = stamp(target.appDir);
+      if (!nextStamp || !bundleStamp || nextStamp === bundleStamp) return;
+      bundleStamp = nextStamp; const previous = child; child = undefined; killChild(previous); attempts = 0; startClock();
+    }, 1500); watcher.unref();
   }
 }

package/lib/runtime.js

@@ -0,0 +1,132 @@
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, openSync, closeSync, writeFileSync, statSync, readdirSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { dirname, join, resolve, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { abortError, checkAbort, delay, downloadArchive } from './download.js';
+
+const DEFAULT_RUNTIME_URL = 'https://github.com/wfz2006/dsh-status-bar/releases/latest/download/dsh-status-bar.tgz';
+const json = path => { try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return {}; } };
+const firstFile = values => values.find(value => { try { return typeof value === 'string' && statSync(value).isFile(); } catch { return false; } });
+const hasApp = path => typeof path === 'string' && !!firstFile([join(path, 'out', 'main', 'index.js')]);
+export function packageVersion(root) {
+  const version = json(join(root, 'package.json')).version;
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?$/.test(version)) throw new Error('插件版本信息无效，请重新安装插件。');
+  return version;
+}
+export function cacheBase(config) {
+  return resolve(config.runtimeDir ?? process.env.DSH_STATUS_BAR_RUNTIME ?? process.env.DSH_GLASS_RUNTIME ??
+    (process.platform === 'win32' ? join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'dsh-status-bar') : join(process.env.XDG_CACHE_HOME ?? join(homedir(), '.cache'), 'dsh-status-bar')));
+}
+export function runtimeUrl(config, root) {
+  const explicit = config.downloadUrl ?? process.env.DSH_STATUS_BAR_RUNTIME_URL ?? process.env.DSH_GLASS_RUNTIME_URL;
+  const advertised = json(join(root, 'package.json')).dsh?.statusBar?.runtime;
+  const url = explicit ?? advertised ?? DEFAULT_RUNTIME_URL;
+  return !explicit && url === DEFAULT_RUNTIME_URL ? `https://github.com/wfz2006/dsh-status-bar/releases/download/v${packageVersion(root)}/dsh-status-bar.tgz` : url;
+}
+function binary(dist) {
+  const name = process.platform === 'win32' ? 'electron.exe' : process.platform === 'darwin' ? join('Electron.app', 'Contents', 'MacOS', 'Electron') : 'electron';
+  return firstFile([join(dist, name)]);
+}
+export function resolveInstalled(config, root) {
+  const appDir = [config.appDir, process.env.DSH_STATUS_BAR_APP, process.env.DSH_GLASS_APP, join(root, 'app'), join(root, '..', '..', 'apps', 'desktop')].find(hasApp);
+  if (!appDir) return;
+  let electron = firstFile([config.electronBinary, process.env.DSH_STATUS_BAR_ELECTRON, process.env.DSH_GLASS_ELECTRON]) ?? binary(join(root, 'electron', 'dist'));
+  for (const base of [appDir, root]) {
+    if (electron) break;
+    try { electron = binary(join(dirname(createRequire(join(base, 'package.json')).resolve('electron/package.json')), 'dist')); } catch { /* Try the other install shape. */ }
+  }
+  return electron ? { appDir, electron } : undefined;
+}
+function cachedRuntime(root, version) {
+  const appDir = join(root, 'app'); const electron = binary(join(root, 'electron', 'dist'));
+  return hasApp(appDir) && electron && json(join(appDir, 'package.json')).version === version ? { appDir, electron } : undefined;
+}
+export function resolveAvailable(config, root) {
+  const direct = resolveInstalled(config, root); if (direct) return direct;
+  const version = packageVersion(root);
+  const cached = cachedRuntime(join(cacheBase(config), `runtime-${version}`), version);
+  return cached ? resolveInstalled({ ...config, appDir: cached.appDir }, root) ?? cached : undefined;
+}
+async function lock(path, signal, onProgress) {
+  const owner = randomUUID();
+  for (;;) {
+    checkAbort(signal);
+    try {
+      const fd = openSync(path, 'wx');
+      try { writeFileSync(fd, JSON.stringify({ pid: process.pid, owner })); } finally { closeSync(fd); }
+      return () => { if (json(path).owner === owner) rmSync(path, { force: true }); };
+    } catch (error) {
+      if (error.code !== 'EEXIST') throw error;
+      const current = json(path); let alive = true;
+      if (Number.isSafeInteger(current.pid) && current.pid > 0) {
+        try { process.kill(current.pid, 0); } catch (error) { alive = error.code !== 'ESRCH'; }
+      } else { try { alive = Date.now() - statSync(path).mtimeMs < 10000; } catch { continue; } }
+      if (!alive) { rmSync(path, { force: true }); continue; }
+      onProgress({ phase: 'waiting', message: '另一个 DSH 窗口正在准备同版本运行时，完成后会自动继续。' });
+      await delay(500, signal);
+    }
+  }
+}
+function run(program, args, signal, capture = false) {
+  checkAbort(signal);
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(program, args, { stdio: ['ignore', capture ? 'pipe' : 'ignore', 'ignore'], windowsHide: true });
+    let output = ''; let excessive = false;
+    child.stdout?.on('data', chunk => { output += chunk.toString(); if (output.length > 16 * 1024 * 1024) { excessive = true; child.kill(); } });
+    const abort = () => child.kill(); signal?.addEventListener('abort', abort, { once: true });
+    child.once('error', error => { signal?.removeEventListener('abort', abort); reject(error); });
+    child.once('close', code => {
+      signal?.removeEventListener('abort', abort);
+      if (signal?.aborted) reject(abortError());
+      else if (code !== 0 || excessive) reject(new Error('运行时压缩包无法解压，请重试或安装自包含版本。'));
+      else resolvePromise(output);
+    });
+    if (signal?.aborted) abort();
+  });
+}
+function removeOwned(path, root) {
+  if (dirname(path) !== dirname(root) || !basename(path).startsWith(`${basename(root)}.`)) throw new Error('缓存临时路径无效。');
+  rmSync(path, { recursive: true, force: true });
+}
+export async function ensureRuntime(config, pluginRoot, { signal, onProgress = () => {} } = {}) {
+  const version = packageVersion(pluginRoot); const base = cacheBase(config); const root = join(base, `runtime-${version}`);
+  const cached = cachedRuntime(root, version); if (cached) return cached;
+  mkdirSync(base, { recursive: true });
+  const release = await lock(`${root}.lock`, signal, onProgress);
+  const part = `${root}.tgz.part`; const staging = `${root}.staging-${randomUUID()}`; const previous = `${root}.previous-${randomUUID()}`;
+  try {
+    const installedByPeer = cachedRuntime(root, version); if (installedByPeer) return installedByPeer;
+    // The exclusive lock proves that no other preparer owns these generated
+    // staging folders. An abrupt Host exit must not leave one unpack per retry.
+    for (const name of readdirSync(base)) if (name.startsWith(`${basename(root)}.staging-`) && /^[0-9a-f-]{36}$/.test(name.slice(`${basename(root)}.staging-`.length))) removeOwned(join(base, name), root);
+    await downloadArchive(runtimeUrl(config, pluginRoot), part, { signal, onProgress }); checkAbort(signal);
+    onProgress({ phase: 'unpacking', message: '下载完成，正在校验并解压运行时。' });
+    let entries;
+    try { entries = await run('tar', ['-tvzf', part], signal, true); }
+    catch (error) { if (error.name !== 'AbortError') { rmSync(part, { force: true }); rmSync(`${part}.json`, { force: true }); } throw error; }
+    // Reject links and traversal before extraction; only this package subtree is expected.
+    for (const line of entries.split(/\r?\n/).filter(Boolean)) {
+      const entry = line.match(/\b(package\/.*)$/)?.[1];
+      if (!['-', 'd'].includes(line[0]) || !entry || entry.includes('\\') || entry.split('/').some(part => part === '..' || part.includes(':'))) {
+        rmSync(part, { force: true }); rmSync(`${part}.json`, { force: true });
+        throw new Error('运行时压缩包包含不支持的条目。');
+      }
+    }
+    mkdirSync(staging);
+    await run('tar', ['-xzf', part, '-C', staging, '--no-same-owner', '--no-same-permissions'], signal);
+    const unpacked = join(staging, 'package');
+    if (json(join(unpacked, 'package.json')).version !== version || !cachedRuntime(unpacked, version)) {
+      rmSync(part, { force: true }); rmSync(`${part}.json`, { force: true });
+      throw new Error(`下载内容与插件 ${version} 不匹配，未覆盖现有缓存。请重试或安装对应版本的自包含包。`);
+    }
+    checkAbort(signal);
+    if (existsSync(root)) renameSync(root, previous);
+    try { renameSync(unpacked, root); }
+    catch (error) { if (existsSync(previous)) renameSync(previous, root); throw error; }
+    removeOwned(previous, root);
+    rmSync(part, { force: true }); rmSync(`${part}.json`, { force: true });
+    return cachedRuntime(root, version);
+  } finally { try { removeOwned(staging, root); } finally { release(); } }
+}

package/lib/startup-status.js

@@ -0,0 +1,51 @@
+import { spawn } from 'node:child_process';
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { cacheBase } from './runtime.js';
+
+/** Bootstrap feedback cannot depend on the Electron runtime being downloaded.
+ * The native window reads only these non-sensitive progress/command files. */
+export function createStartupStatus(config, { retry, cancel }) {
+  const id = randomUUID(); const base = cacheBase(config);
+  const statePath = join(base, `startup-${id}.json`); const actionPath = join(base, `startup-${id}.action`);
+  let panel; let timer; let closed = false; let state = {}; let lastLog = '';
+  const remove = () => { for (const path of [statePath, actionPath]) try { rmSync(path, { force: true }); } catch { /* A closing native reader may briefly hold the file. */ } };
+  function open() {
+    if (timer || closed) return;
+    mkdirSync(base, { recursive: true });
+    timer = setInterval(() => {
+      let action;
+      try { action = readFileSync(actionPath, 'utf8').trim(); rmSync(actionPath, { force: true }); } catch { return; }
+      if (action === 'retry') retry(); else if (action === 'cancel') cancel();
+    }, 250); timer.unref();
+    if (process.platform !== 'win32' || config.showStartupUI === false) return;
+    panel = spawn(join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'),
+      ['-NoLogo', '-NoProfile', '-NonInteractive', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-STA', '-File', fileURLToPath(new URL('./startup-window.ps1', import.meta.url)),
+        '-StatePath', statePath, '-ActionPath', actionPath, '-OwnerPid', String(process.pid)],
+      { stdio: 'ignore', windowsHide: true });
+    panel.once('error', () => { console.warn('[dsh-status-bar] 无法打开准备进度窗口，请查看插件日志。'); panel = undefined; });
+    panel.once('exit', () => { panel = undefined; if (!closed) cancel(); else remove(); });
+    panel.unref();
+  }
+  return {
+    update(patch) {
+      if (closed) return;
+      state = { ...state, ...patch };
+      // The reader retries transient sharing/partial-write errors on its next tick.
+      try { open(); writeFileSync(statePath, JSON.stringify(state)); }
+      catch { console.warn('[dsh-status-bar] 无法写入准备状态，请检查运行时缓存目录权限。'); }
+      const log = `${state.phase}:${Math.floor((state.total ? state.received / state.total : 0) * 10)}`;
+      if (log !== lastLog) {
+        lastLog = log;
+        (state.phase === 'failed' ? console.warn : console.info)(`[dsh-status-bar] ${state.message ?? state.phase}${state.total ? ` ${Math.min(100, Math.floor(state.received / state.total * 100))}%` : ''}`);
+      }
+    },
+    close() {
+      if (closed) return; closed = true; clearInterval(timer); timer = undefined;
+      if (panel) { panel.kill(); panel = undefined; }
+      remove();
+    },
+  };
+}

package/lib/startup-window.ps1

@@ -0,0 +1,75 @@
+param([string]$StatePath, [string]$ActionPath, [int]$OwnerPid)
+
+Add-Type -AssemblyName PresentationFramework, PresentationCore, WindowsBase
+
+function New-StartupWindow {
+  param([string]$StatePath, [string]$ActionPath, [int]$OwnerPid)
+  [xml]$markup = @'
+<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+        Title="DSH Status Bar · 准备悬浮窗" Width="456" Height="262"
+        ResizeMode="NoResize" WindowStartupLocation="CenterScreen" Background="#F7F9FC"
+        FontFamily="Microsoft YaHei UI" FontSize="13" ShowInTaskbar="True">
+  <Grid Margin="24,20,24,18">
+    <Grid.RowDefinitions><RowDefinition Height="Auto"/><RowDefinition Height="Auto"/><RowDefinition Height="Auto"/><RowDefinition Height="*"/><RowDefinition Height="Auto"/></Grid.RowDefinitions>
+    <TextBlock Name="Heading" Text="正在准备悬浮窗" FontSize="20" FontWeight="SemiBold" Foreground="#14263E"/>
+    <TextBlock Grid.Row="1" Name="Message" Text="首次启动需要下载桌面运行时。完成后会自动打开。" TextWrapping="Wrap" Foreground="#44566D" Margin="0,12,0,14"/>
+    <ProgressBar Grid.Row="2" Name="Progress" Height="6" Minimum="0" Maximum="100" Foreground="#426DDD" Background="#E2E8F0" BorderThickness="0" IsIndeterminate="True"/>
+    <TextBlock Grid.Row="3" Name="Detail" Text="连接中…" Foreground="#52657C" Margin="0,10,0,8" TextWrapping="Wrap"/>
+    <StackPanel Grid.Row="4" Orientation="Horizontal" HorizontalAlignment="Right">
+      <Button Name="Retry" Content="重试" Width="90" Height="30" Margin="0,0,10,0" Visibility="Collapsed" Background="#E6EDFF" Foreground="#244BB5"/>
+      <Button Name="Cancel" Content="取消" Width="90" Height="30" Background="#EDF0F5" Foreground="#283C54"/>
+    </StackPanel>
+  </Grid>
+</Window>
+'@
+  $reader = New-Object System.Xml.XmlNodeReader $markup
+  $window = [Windows.Markup.XamlReader]::Load($reader)
+  $model = @{ Window=$window; Retry=$window.FindName('Retry'); Cancel=$window.FindName('Cancel'); Finished=$false; CommandSent=$false }
+  $sendAction = {
+    param([string]$action)
+    [IO.File]::WriteAllText($ActionPath, $action, (New-Object Text.UTF8Encoding $false))
+    $model.CommandSent = $true
+  }.GetNewClosure()
+  $retryClick = {
+    & $sendAction 'retry'
+    $model.Retry.IsEnabled = $false
+    $window.FindName('Message').Text = '正在重新连接；可验证的已下载部分会继续使用。'
+  }.GetNewClosure()
+  $model.Retry.Add_Click($retryClick)
+  $cancelClick = { & $sendAction 'cancel'; $window.Close() }.GetNewClosure()
+  $model.Cancel.Add_Click($cancelClick)
+  $timer = New-Object Windows.Threading.DispatcherTimer
+  $timer.Interval = [TimeSpan]::FromMilliseconds(300)
+  $tick = {
+    try { $null = Get-Process -Id $OwnerPid -ErrorAction Stop }
+    catch { $model.Finished=$true; $window.Close(); return }
+    try {
+      $state = [IO.File]::ReadAllText($StatePath) | ConvertFrom-Json -ErrorAction Stop
+      $failed = $state.phase -eq 'failed'
+      $window.FindName('Heading').Text = $(if($failed){'悬浮窗暂未启动'}else{'正在准备悬浮窗'})
+      $window.FindName('Message').Text = [string]$state.message
+      $model.Retry.Visibility = $(if($failed){'Visible'}else{'Collapsed'})
+      $model.Retry.IsEnabled = $failed
+      $model.Cancel.Content = $(if($failed){'稍后再试'}else{'取消'})
+      $bar = $window.FindName('Progress')
+      $bar.IsIndeterminate = -not $failed -and ($state.phase -ne 'downloading' -or -not $state.total)
+      if($state.total){ $bar.Value=[Math]::Min(100, 100 * [double]$state.received / [double]$state.total) }
+      $window.FindName('Detail').Text = $(if($failed){'点击重试即可继续，无需重启 DSH。'}elseif($state.phase -eq 'unpacking'){'正在校验和解压，请稍候。'}elseif($state.total){'{0:N1} / {1:N1} MB  ·  仅本版本首次需要' -f ($state.received/1MB),($state.total/1MB)}else{'请保持 DSH 运行；可随时取消，下次继续。'})
+    } catch { # A writer can briefly hold the file. Retry on the next tick.
+    }
+  }.GetNewClosure()
+  $timer.Add_Tick($tick)
+  $closing = {
+    $timer.Stop()
+    if(-not $model.Finished -and -not $model.CommandSent){ & $sendAction 'cancel' }
+  }.GetNewClosure()
+  $window.Add_Closed($closing)
+  $timer.Start()
+  $model.Tick=$tick
+  return $model
+}
+
+if($MyInvocation.InvocationName -ne '.') {
+  $ui = New-StartupWindow -StatePath $StatePath -ActionPath $ActionPath -OwnerPid $OwnerPid
+  $null = $ui.Window.ShowDialog()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-status-bar-plugin",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Floating glass status bar for DeepSeek Harness: a frameless always-on-top window that shows session progress, pending approvals and questions.",
   "license": "MIT",
   "author": "wfz2006",

package/screenshots.json

@@ -1,7 +1,7 @@
-[
-  "assets/capsule.png",
-  "assets/peek.png",
-  "assets/expanded.png",
-  "assets/approval.png",
-  "assets/settings.png"
-]
+[
+  "assets/capsule.png",
+  "assets/peek.png",
+  "assets/expanded.png",
+  "assets/approval.png",
+  "assets/settings.png"
+]