@dimina-kit/devtools 0.4.0-dev.20260718095333 → 0.4.0-dev.20260718143821

package/dist/main/runtime/devtools-backend-before-quit.harness.d.ts

@@ -0,0 +1,61 @@
+import type { WorkbenchAppConfig } from '../../shared/types.js';
+import type { RuntimeBackend } from '@dimina-kit/electron-deck';
+declare const stubs: {
+    handlers: Map<string, (...args: unknown[]) => unknown>;
+    projectsJsonPath: string;
+    getProjectsJson(): string | null;
+    setProjectsJson(v: string | null): void;
+    projectsWithAppJson: Set<string>;
+    makeEmitter: () => {
+        listeners: Record<string, Set<(...args: unknown[]) => unknown>>;
+        on(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        once(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        off(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        removeListener(event: string, fn: (...args: unknown[]) => unknown): /*elided*/ any;
+        emit(event: string, ...args: unknown[]): void;
+    };
+    reset: () => void;
+};
+declare const devkitStubs: {
+    sessionClose: import("vitest").Mock<() => Promise<void>>;
+};
+declare const viewManagerStubs: {
+    createdManagers: Array<{
+        disposeAll: () => void;
+    }>;
+};
+export { stubs, devkitStubs, viewManagerStubs };
+/**
+ * Shared per-test setup both `devtools-backend-before-quit.test.ts` and
+ * `devtools-backend-shutdown-race.test.ts` need identically: reset modules
+ * (fresh `let`-scoped module-level state in `devtools-backend.ts` each
+ * test), reset the mock harness above, and dynamically re-import `electron`
+ * + `createDevtoolsBackend` — dynamic, not a static top-level import,
+ * because it must happen AFTER `vi.resetModules()` picks up a fresh module
+ * instance each test. Registers its own `beforeEach`; call once per
+ * describing test file. Returns a mutable state object (not individual
+ * values) because `beforeEach` reassigns its fields once per test, after
+ * this function itself has already returned.
+ */
+export interface BackendTestState {
+    createDevtoolsBackend: typeof import('./devtools-backend.js').createDevtoolsBackend;
+    electron: typeof import('electron');
+}
+export declare function registerBackendTestLifecycle(): BackendTestState;
+/**
+ * Shared setup for the two tests (one in `devtools-backend-before-quit.test.ts`,
+ * one in `devtools-backend-shutdown-race.test.ts`) that need to observe
+ * `assemble()` PAUSED mid-flight, inside a still-pending `config.onSetup`:
+ * builds the backend with a gated `onSetup`, runs `beforeReady`/`assemble`,
+ * and waits until the assembled `ViewManager` is actually reachable (proof
+ * `createDevtoolsRuntime` has progressed past instance construction) before
+ * handing control back — the caller then fires whatever quit-path event it's
+ * testing while `onSetup` is still gated, and is responsible for calling
+ * `releaseOnSetup()` + awaiting `assemblePromise` itself.
+ */
+export declare function startAssemblingWithGatedOnSetup(createDevtoolsBackend: BackendTestState['createDevtoolsBackend'], extraConfig?: Omit<WorkbenchAppConfig, 'onSetup'>): Promise<{
+    backend: RuntimeBackend;
+    assemblePromise: Promise<void>;
+    releaseOnSetup: () => void;
+}>;
+//# sourceMappingURL=devtools-backend-before-quit.harness.d.ts.map

package/dist/main/runtime/devtools-backend-before-quit.harness.js

@@ -0,0 +1,356 @@
+/**
+ * Shared vitest mock harness for `devtools-backend-before-quit.test.ts` and
+ * `devtools-backend-shutdown-race.test.ts` — both drive the REAL
+ * `createDevtoolsBackend`/`createDevtoolsRuntime` against this same
+ * electron/fs/`@dimina-kit/devkit`/view-manager mock set (lifted from
+ * `quit-flag-onclose.test.ts`), split out to keep each test file under the
+ * repo's 500-line file-length ratchet without duplicating ~350 lines of
+ * mock setup between them.
+ *
+ * `vi.mock(...)` calls here run once per importing test file's own isolated
+ * module graph (vitest scopes mocking per test file), so importing this
+ * module has the same effect as if each call were written directly in the
+ * importing file — both test files' `beforeEach` still dynamically
+ * `await import('./devtools-backend.js')` AFTER `vi.resetModules()`, well
+ * after this module's mock registrations have already run.
+ */
+import { beforeEach, expect, vi } from 'vitest';
+// ── Hoisted stub state (lifted from quit-flag-onclose.test.ts) ────────────
+// `export const x = vi.hoisted(...)` is rejected by vitest's hoisting
+// transform ("Cannot export hoisted variable") — declare then export below.
+const stubs = vi.hoisted(() => {
+    const handlers = new Map();
+    const projectsJsonPath = '/tmp/dimina-test-userdata/dimina-projects.json';
+    let projectsJsonContent = null;
+    const projectsWithAppJson = new Set();
+    function makeEmitter() {
+        const listeners = {};
+        return {
+            listeners,
+            on(event, fn) {
+                ;
+                (listeners[event] ??= new Set()).add(fn);
+                return this;
+            },
+            once(event, fn) {
+                const wrap = (...args) => {
+                    listeners[event]?.delete(wrap);
+                    return fn(...args);
+                };
+                (listeners[event] ??= new Set()).add(wrap);
+                return this;
+            },
+            off(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            removeListener(event, fn) {
+                listeners[event]?.delete(fn);
+                return this;
+            },
+            emit(event, ...args) {
+                for (const fn of [...(listeners[event] ?? [])])
+                    fn(...args);
+            },
+        };
+    }
+    function reset() {
+        handlers.clear();
+        projectsJsonContent = null;
+        projectsWithAppJson.clear();
+    }
+    return {
+        handlers,
+        projectsJsonPath,
+        getProjectsJson() {
+            return projectsJsonContent;
+        },
+        setProjectsJson(v) {
+            projectsJsonContent = v;
+        },
+        projectsWithAppJson,
+        makeEmitter,
+        reset,
+    };
+});
+// ── electron stub ────────────────────────────────────────────────────────
+// `app` is a live emitter so `registerAppLifecycle` can attach a
+// `before-quit` listener that the test fires directly.
+vi.mock('electron', () => {
+    const ipcEmitter = stubs.makeEmitter();
+    const ipcMain = {
+        ...ipcEmitter,
+        handle: vi.fn((channel, fn) => {
+            stubs.handlers.set(channel, fn);
+        }),
+        removeHandler: vi.fn((channel) => {
+            stubs.handlers.delete(channel);
+        }),
+        on: vi.fn((event, fn) => ipcEmitter.on(event, fn)),
+        removeListener: vi.fn((event, fn) => ipcEmitter.removeListener(event, fn)),
+    };
+    const appEmitter = stubs.makeEmitter();
+    const app = {
+        ...appEmitter,
+        isPackaged: true,
+        whenReady: vi.fn(() => Promise.resolve()),
+        getPath: vi.fn(() => '/tmp/dimina-test-userdata'),
+        quit: vi.fn(),
+        setName: vi.fn(),
+        commandLine: {
+            getSwitchValue: vi.fn(() => ''),
+            appendSwitch: vi.fn(),
+        },
+    };
+    // `WebContents` and `BrowserWindow` below both wrap a `stubs.makeEmitter()`
+    // and need the SAME on/once/off/removeListener/emit delegation (the
+    // emitter's own methods use `this` internally, so a plain property copy
+    // would call them with the wrong receiver — each needs `.bind(em)`). Shared
+    // base class instead of re-declaring the same 5 bound fields in both.
+    class EmittingStub {
+        em = stubs.makeEmitter();
+        on = this.em.on.bind(this.em);
+        once = this.em.once.bind(this.em);
+        off = this.em.off.bind(this.em);
+        removeListener = this.em.removeListener.bind(this.em);
+        emit = this.em.emit.bind(this.em);
+    }
+    class WebContents extends EmittingStub {
+        destroyed = false;
+        id = Math.floor(Math.random() * 1e6);
+        send = vi.fn();
+        isDestroyed = () => this.destroyed;
+        openDevTools = vi.fn();
+        closeDevTools = vi.fn();
+        setDevToolsWebContents = vi.fn();
+        setWindowOpenHandler = vi.fn();
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        executeJavaScript = vi.fn(() => Promise.resolve(undefined));
+        reload = vi.fn();
+        getType = () => 'window';
+        getURL = () => '';
+        debugger = {
+            attach: vi.fn(),
+            detach: vi.fn(),
+            isAttached: () => false,
+            on: vi.fn(),
+            removeListener: vi.fn(),
+            sendCommand: vi.fn(() => Promise.resolve({ entries: [] })),
+        };
+        close = vi.fn(() => {
+            this.destroyed = true;
+        });
+    }
+    class WebContentsView {
+        webContents = new WebContents();
+        setBounds = vi.fn();
+        setBackgroundColor = vi.fn();
+    }
+    class View {
+        children = [];
+        addChildView(child) {
+            this.children.push(child);
+        }
+        removeChildView(child) {
+            const i = this.children.indexOf(child);
+            if (i >= 0)
+                this.children.splice(i, 1);
+        }
+    }
+    class BrowserWindow extends EmittingStub {
+        destroyed = false;
+        webContents = new WebContents();
+        contentView = new WebContentsView();
+        isDestroyed = () => this.destroyed;
+        getContentSize = () => [1280, 980];
+        setIcon = vi.fn();
+        setTitle = vi.fn();
+        show = vi.fn();
+        showInactive = vi.fn();
+        focus = vi.fn();
+        close = vi.fn();
+        destroy = vi.fn(() => {
+            this.destroyed = true;
+        });
+        loadFile = vi.fn(() => Promise.resolve());
+        loadURL = vi.fn(() => Promise.resolve());
+        static getAllWindows = vi.fn(() => []);
+    }
+    const sessionStub = {
+        fromPartition: vi.fn(() => ({
+            webRequest: {
+                onBeforeSendHeaders: vi.fn(),
+                onHeadersReceived: vi.fn(),
+            },
+            registerPreloadScript: vi.fn(),
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        })),
+        defaultSession: {
+            protocol: { handle: vi.fn(), unhandle: vi.fn() },
+        },
+    };
+    const dialog = {
+        showOpenDialog: vi.fn(() => Promise.resolve({ canceled: true, filePaths: [] })),
+        showMessageBox: vi.fn(() => Promise.resolve({ response: 0 })),
+    };
+    const Menu = {
+        buildFromTemplate: vi.fn((tpl) => ({ template: tpl })),
+        setApplicationMenu: vi.fn(),
+    };
+    const shell = {
+        openExternal: vi.fn(() => Promise.resolve()),
+        openPath: vi.fn(() => Promise.resolve('')),
+    };
+    const nativeImage = {
+        createFromPath: vi.fn(() => ({ isEmpty: () => true })),
+    };
+    const nativeTheme = { ...stubs.makeEmitter(), themeSource: 'system' };
+    const globalShortcut = {
+        register: vi.fn(() => false),
+        unregister: vi.fn(),
+        unregisterAll: vi.fn(),
+    };
+    const webContentsStatic = {
+        fromId: vi.fn(() => null),
+        getAllWebContents: vi.fn(() => []),
+    };
+    const Tray = vi.fn();
+    return {
+        app,
+        ipcMain,
+        BrowserWindow,
+        WebContentsView,
+        BrowserView: WebContentsView,
+        View,
+        webContents: webContentsStatic,
+        session: sessionStub,
+        protocol: { registerSchemesAsPrivileged: vi.fn(), handle: vi.fn(), unhandle: vi.fn() },
+        dialog,
+        Menu,
+        shell,
+        nativeImage,
+        nativeTheme,
+        globalShortcut,
+        Tray,
+        default: {},
+    };
+});
+vi.mock('fs', async () => {
+    const real = await vi.importActual('fs');
+    function existsSync(p) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath)
+            return stubs.getProjectsJson() !== null;
+        if (s.endsWith('/app.json') || s.endsWith('\\app.json')) {
+            const dir = s.replace(/[\\/]app\.json$/, '');
+            return stubs.projectsWithAppJson.has(dir);
+        }
+        return true;
+    }
+    function readFileSync(p, opts) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            const content = stubs.getProjectsJson();
+            if (content === null)
+                throw Object.assign(new Error('ENOENT'), { code: 'ENOENT' });
+            return content;
+        }
+        return real.readFileSync(p, opts);
+    }
+    function writeFileSync(p, data) {
+        const s = String(p);
+        if (s === stubs.projectsJsonPath) {
+            stubs.setProjectsJson(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'));
+        }
+    }
+    const mocked = {
+        ...real,
+        existsSync,
+        readFileSync,
+        writeFileSync,
+        mkdirSync: vi.fn(),
+        statSync: vi.fn(() => ({ isDirectory: () => true, isFile: () => false, size: 0, mtimeMs: 0 })),
+        watch: vi.fn(),
+        realpathSync: vi.fn((p) => p),
+    };
+    return { ...mocked, default: mocked };
+});
+const devkitStubs = vi.hoisted(() => ({
+    sessionClose: vi.fn(() => Promise.resolve()),
+}));
+vi.mock('@dimina-kit/devkit', () => ({
+    openProject: vi.fn(() => Promise.resolve({
+        port: 12345,
+        appInfo: { appId: 'fakeApp' },
+        close: devkitStubs.sessionClose,
+    })),
+}));
+// ── view-manager spy shim ───────────────────────────────────────────────
+// `createDevtoolsBackend` keeps its assembled `instance` in a private
+// closure — the returned `RuntimeBackend` exposes no getter for
+// `instance.context.views`. Wrapping `createViewManager` here (real
+// implementation, just observed) gives the test a handle on the exact
+// `ViewManager` the backend's `assemble` wires up, equivalent to
+// `vi.spyOn(instance.context.views, 'disposeAll')` without needing the
+// backend to leak its internals.
+const viewManagerStubs = vi.hoisted(() => ({
+    createdManagers: [],
+}));
+vi.mock('../services/views/view-manager.js', async (importOriginal) => {
+    const actual = await importOriginal();
+    return {
+        ...actual,
+        createViewManager: (ctx) => {
+            const real = actual.createViewManager(ctx);
+            vi.spyOn(real, 'disposeAll');
+            viewManagerStubs.createdManagers.push(real);
+            return real;
+        },
+    };
+});
+export { stubs, devkitStubs, viewManagerStubs };
+export function registerBackendTestLifecycle() {
+    const state = {};
+    beforeEach(async () => {
+        vi.resetModules();
+        stubs.reset();
+        devkitStubs.sessionClose.mockClear();
+        viewManagerStubs.createdManagers.length = 0;
+        state.electron = await import('electron');
+        ({ createDevtoolsBackend: state.createDevtoolsBackend } = await import('./devtools-backend.js'));
+    });
+    return state;
+}
+/**
+ * Shared setup for the two tests (one in `devtools-backend-before-quit.test.ts`,
+ * one in `devtools-backend-shutdown-race.test.ts`) that need to observe
+ * `assemble()` PAUSED mid-flight, inside a still-pending `config.onSetup`:
+ * builds the backend with a gated `onSetup`, runs `beforeReady`/`assemble`,
+ * and waits until the assembled `ViewManager` is actually reachable (proof
+ * `createDevtoolsRuntime` has progressed past instance construction) before
+ * handing control back — the caller then fires whatever quit-path event it's
+ * testing while `onSetup` is still gated, and is responsible for calling
+ * `releaseOnSetup()` + awaiting `assemblePromise` itself.
+ */
+export async function startAssemblingWithGatedOnSetup(createDevtoolsBackend, extraConfig = {}) {
+    let releaseOnSetup = () => { };
+    const onSetupGate = new Promise((resolve) => {
+        releaseOnSetup = resolve;
+    });
+    const backend = createDevtoolsBackend({
+        ...extraConfig,
+        onSetup: async () => {
+            await onSetupGate;
+        },
+    });
+    backend.beforeReady?.({});
+    const assemblePromise = Promise.resolve(backend.assemble({}));
+    // Let `assemble` progress through `createDevtoolsRuntime` up to (and into)
+    // the pending `onSetup` gate — the instance must exist by then.
+    await vi.waitFor(() => {
+        expect(viewManagerStubs.createdManagers.length).toBeGreaterThan(0);
+    });
+    return { backend, assemblePromise, releaseOnSetup };
+}
+//# sourceMappingURL=devtools-backend-before-quit.harness.js.map

package/dist/main/runtime/devtools-backend.js

@@ -1,5 +1,5 @@
 import { runDevtoolsBootstrap, createDevtoolsRuntime } from '../app/app.js';
-import { registerAppLifecycle } from '../app/lifecycle.js';
+import { isAppQuitting, registerAppLifecycle } from '../app/lifecycle.js';
 /**
  * Adapts the devtools runtime into a {@link RuntimeBackend} the framework
  * (`@dimina-kit/electron-deck`) orchestrates. The framework owns the process
@@ -21,6 +21,15 @@ import { registerAppLifecycle } from '../app/lifecycle.js';
 export function createDevtoolsBackend(config = {}) {
     // Hoisted so `onShutdown` can reach the assembled context (assigned by `assemble`).
     let instance = null;
+    // `assemble`'s own in-flight promise: `instance` is now published EARLY (see
+    // below), before `createDevtoolsRuntime`'s async body — including the host's
+    // `config.onSetup(instance)` and everything after it — has finished running.
+    // `onShutdown` must wait for THIS to settle before disposing: disposing
+    // `instance.context.registry` while `createDevtoolsRuntime` is still adding
+    // entries to that same registry (e.g. the `updateChecker`/`setupMcp` wiring
+    // that runs after `onSetup`) hits `DisposableRegistry.add()`'s "cannot add
+    // to disposed registry" throw instead of a clean teardown.
+    let assembling = null;
     return {
         // The backend builds the devtools main window itself (framework skips its own).
         // Its only construction-time needs are the host preload + `sandbox:false`
@@ -42,15 +51,51 @@ export function createDevtoolsBackend(config = {}) {
         // Setup (post-whenReady): app lifecycle (window-all-closed → quit) + the
         // full devtools assembly.
         assemble: async () => {
-            registerAppLifecycle();
-            instance = await createDevtoolsRuntime(config);
+            // `onBeforeQuit` runs synchronously at Electron's `before-quit` — main
+            // loop still fully healthy, well before `will-quit`'s unawaited
+            // `shutdown()` and any window/WebContentsView destruction. Disposing
+            // the host-scoped views (host-toolbar's WebContentsView + its
+            // MessagePortMain) here, instead of leaving them to `onShutdown`'s
+            // best-effort async teardown, keeps them from surviving into
+            // Chromium's native shutdown sequence, where a late `'destroyed'`
+            // handler closing an already-torn-down MessagePort segfaults natively.
+            // Safe to run again from `onShutdown`'s `instance.dispose()` afterwards
+            // — `views.disposeAll()` and its constituents are dispose-idempotent.
+            registerAppLifecycle(() => instance?.context.views.disposeAll());
+            // `onInstanceCreated` (not the return value) is what assigns `instance`:
+            // `createDevtoolsRuntime` awaits the host's `config.onSetup(instance)`
+            // — which may run arbitrarily long and can itself load the host toolbar
+            // (a live MessagePort) — before returning. Waiting for the return value
+            // would leave `instance` null, and the before-quit hook above a no-op,
+            // for that entire window. Publishing from the callback closes it.
+            assembling = createDevtoolsRuntime(config, (created) => {
+                instance = created;
+                // Quit may have already started (before-quit already fired) before
+                // this instance existed, so the hook above ran with nothing to
+                // dispose. Self-heal: run the same teardown now that there is.
+                if (isAppQuitting())
+                    instance.context.views.disposeAll();
+            }).then(() => { });
+            await assembling;
         },
         // Dispose the devtools context during the framework's deterministic shutdown
         // (app.on('will-quit') → shutdown() → runShutdownCleanup(), awaited once).
         // Without this, the compile session (a child process, torn down by
         // closeProject) and the IPC registry would leak on exit. The framework awaits
         // this hook, so teardown is no longer a best-effort before-quit reach-around.
-        onShutdown: () => instance?.dispose(),
+        //
+        // Waits for `assembling` first: `instance` can be non-null (published
+        // early, above) while `createDevtoolsRuntime`'s own async body — the
+        // host's `onSetup` and everything scheduled after it — is still running
+        // and still adding entries to `instance.context.registry`. Disposing
+        // that registry out from under an in-flight assembly throws instead of
+        // tearing down cleanly (`DisposableRegistry.add` rejects post-dispose).
+        // `.catch()` here: assembly failing is `assemble`'s problem to surface,
+        // not a reason to skip disposing whatever DID get constructed.
+        onShutdown: async () => {
+            await assembling?.catch(() => { });
+            await instance?.dispose();
+        },
     };
 }
 //# sourceMappingURL=devtools-backend.js.map

package/dist/main/services/mcp/server.js

@@ -39,7 +39,6 @@ export function startMcpServer(resolvedCdpPort, mcpPort) {
     // Connect to both targets (non-blocking)
     connectTarget('simulator').catch(() => { });
     connectTarget('workbench').catch(() => { });
-    const server = buildServer();
     const transports = new Map();
     const httpServer = createServer(async (req, res) => {
         const url = new URL(req.url ?? '/', `http://localhost`);
@@ -47,7 +46,30 @@ export function startMcpServer(resolvedCdpPort, mcpPort) {
             const transport = new SSEServerTransport('/message', res);
             transports.set(transport.sessionId, transport);
             res.on('close', () => transports.delete(transport.sessionId));
-            await server.connect(transport);
+            try {
+                // A fresh McpServer PER CONNECTION: the SDK's Protocol is strictly
+                // 1:1 with its transport (`connect()` throws "Already connected to a
+                // transport" if `this._transport` is already set), so reusing one
+                // global server across concurrent SSE clients breaks every
+                // connection after the first. Registration only builds tool-call
+                // closures over already-shared module-level state (target-manager's
+                // CDP connections/listeners) — it has no per-call side effects, so
+                // building N servers is cheap and duplicates nothing.
+                await buildServer().connect(transport);
+            }
+            catch (err) {
+                transports.delete(transport.sessionId);
+                // `connect()` calls `transport.start()` (writes the SSE 200 + headers)
+                // BEFORE it can throw, so a post-start failure here has already sent
+                // headers — writeHead would itself throw. End the response instead so
+                // the client's stream closes cleanly rather than hanging forever with
+                // an open connection nothing will ever write to again.
+                if (!res.headersSent)
+                    res.writeHead(500).end('MCP connect failed');
+                else
+                    res.end();
+                console.error('[MCP] SSE connect failed:', err);
+            }
         }
         else if (req.method === 'POST' && url.pathname === '/message') {
             const sessionId = url.searchParams.get('sessionId') ?? '';

package/dist/main/services/projects/create-project-service.js

@@ -63,9 +63,16 @@ async function materializeTemplate(target, template, name) {
     if (!fs.existsSync(template.source.path)) {
         throw new Error(`Template source missing on disk: ${template.source.path}`);
     }
-    // `recursive: true` makes cpSync mirror the entire tree (files,
-    // subdirs, symlinks). `force: true` mirrors over an empty target.
-    fs.cpSync(template.source.path, target, {
+    // `recursive: true` makes cp mirror the entire tree (files, subdirs,
+    // symlinks). `force: true` mirrors over an empty target. `fs.promises.cp`
+    // (not the sync `fs.cpSync`) deliberately: cpSync's no-filter directory
+    // walk takes Node's native `cpSyncCopyDir` fast path, whose internal
+    // filesystem calls can `abort()` the whole process on certain errors
+    // (long/restricted/non-ASCII paths — nodejs/node#63970) instead of
+    // throwing a catchable JS exception. The async `cp` walks in pure JS and
+    // turns the same failures into a normal rejection this function already
+    // propagates to its IPC-boundary try/catch.
+    await fs.promises.cp(template.source.path, target, {
         recursive: true,
         force: true,
     });

package/dist/main/services/update/github-release-checker.js

@@ -207,6 +207,12 @@ function httpGetText(url, init) {
 function downloadFile(url, dest, token, onProgress) {
     return new Promise((resolve, reject) => {
         const headers = ghHeaders(token);
+        // Awaited before every reject so callers (and tests) that observe the
+        // rejection never race a partial file still being unlinked — fs.unlink's
+        // callback form settles asynchronously, after the promise had already
+        // rejected, which left a truncated/aborted download file on disk for a
+        // window after the caller believed cleanup was done.
+        const cleanup = () => fs.promises.unlink(dest).catch(() => { });
         // GitHub asset downloads redirect to signed S3 URLs; keep following them.
         const attempt = (target, redirectsLeft) => {
             const req = https.get(target, { headers }, (res) => {
@@ -236,11 +242,24 @@ function downloadFile(url, dest, token, onProgress) {
                         onProgress((received / total) * 100);
                     }
                 });
+                // `.pipe()` does not forward source stream errors to the destination —
+                // an aborted/reset connection here would otherwise surface as an
+                // unhandled 'error' event on `res` (crashes the process) instead of
+                // rejecting this promise.
+                res.on('error', async (err) => { out.destroy(); await cleanup(); reject(err); });
                 res.pipe(out);
-                out.on('finish', () => { out.close(); resolve(); });
-                out.on('error', (err) => { fs.unlink(dest, () => { }); reject(err); });
+                out.on('finish', async () => {
+                    out.close();
+                    if (total > 0 && received !== total) {
+                        await cleanup();
+                        reject(new Error(`Downloaded ${received} bytes, expected ${total} — update download was truncated`));
+                        return;
+                    }
+                    resolve();
+                });
+                out.on('error', async (err) => { await cleanup(); reject(err); });
             });
-            req.on('error', (err) => { fs.unlink(dest, () => { }); reject(err); });
+            req.on('error', async (err) => { await cleanup(); reject(err); });
         };
         attempt(url, 5);
     });

package/dist/main/services/update/update-manager.d.ts

@@ -48,7 +48,10 @@ export declare class UpdateManager {
         filePath?: string;
         error?: string;
     }>;
-    install(): void;
+    install(): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
     /**
      * Tear down timers + IPC handlers. Returns a Promise so callers that need
      * a settled cleanup (e.g. workbench registry shutdown, the unit-test

package/dist/main/services/update/update-manager.js

@@ -39,8 +39,21 @@ export class UpdateManager {
             const currentVersion = this.getCurrentVersion();
             const info = await this.checker.checkForUpdates(currentVersion);
             if (info) {
+                // The periodic timer re-runs check() forever (see startPeriodicCheck),
+                // including after the user already downloaded this same update but
+                // before they clicked Install. Only invalidate downloadedPath when the
+                // update identity actually changed — unconditionally nulling it here
+                // would silently no-op a later install() (it's a bare `if (this.downloadedPath)`)
+                // for anyone who takes longer than one check interval to act. Compare
+                // downloadUrl too, not just version: a re-uploaded/replaced asset can
+                // keep the same version string under a different URL, and reusing the
+                // stale downloadedPath would then install bytes that were never
+                // actually verified against this checkForUpdates() result.
+                const isSameUpdate = this.latestUpdate?.version === info.version &&
+                    this.latestUpdate?.downloadUrl === info.downloadUrl;
                 this.latestUpdate = info;
-                this.downloadedPath = null;
+                if (!isSameUpdate)
+                    this.downloadedPath = null;
                 return { hasUpdate: true, info };
             }
             return { hasUpdate: false };
@@ -66,11 +79,23 @@ export class UpdateManager {
             return { success: false, error: String(err) };
         }
     }
-    install() {
-        if (this.downloadedPath) {
-            shell.openPath(this.downloadedPath);
-            app.quit();
+    async install() {
+        if (!this.downloadedPath) {
+            return { success: false, error: 'No update downloaded' };
         }
+        // shell.openPath() resolves (never rejects) with an empty string on
+        // success or an error message on failure — it was previously fired
+        // fire-and-forget immediately followed by app.quit(), so a failure (e.g.
+        // no application associated with the installer) silently closed the app
+        // without ever launching the installer, and the renderer had no way to
+        // know anything went wrong.
+        const failure = await shell.openPath(this.downloadedPath);
+        if (failure) {
+            console.warn('[UpdateManager] install failed:', failure);
+            return { success: false, error: failure };
+        }
+        app.quit();
+        return { success: true };
     }
     /**
      * Tear down timers + IPC handlers. Returns a Promise so callers that need