@adhdev/daemon-core 0.7.42 → 0.7.44

package/src/cli-adapters/provider-cli-adapter.ts

@@ -64,7 +64,6 @@ export interface CliSessionStatus {
     messages: CliChatMessage[];
     workingDir: string;
     activeModal: { message: string; buttons: string[] } | null;
-    terminalHistory?: string;
 }
 
 /**
@@ -90,7 +89,6 @@ export interface CliScriptInput {
     rawBuffer: string;       // Raw PTY output (with ANSI)
     recentBuffer: string;    // Recent 1000 chars (ANSI-stripped)
     screenText: string;      // Current visible screen snapshot
-    terminalHistory?: string; // Rolling append-only terminal transcript
     messages: CliChatMessage[];  // Previously parsed messages
     partialResponse: string; // Current partial response being generated
 }
@@ -100,7 +98,6 @@ interface TurnParseScope {
     startedAt: number;
     bufferStart: number;
     rawBufferStart: number;
-    terminalHistoryStart: number;
 }
 
 export interface CliProviderModule {
@@ -173,6 +170,51 @@ function sanitizeTerminalText(str: string): string {
     return stripTerminalNoise(stripAnsi(str));
 }
 
+function buildCliSpawnEnv(baseEnv: NodeJS.ProcessEnv, overrides?: Record<string, string>): Record<string, string> {
+    const env: Record<string, string> = {};
+    const source = { ...baseEnv, ...(overrides || {}) } as NodeJS.ProcessEnv;
+
+    for (const [key, value] of Object.entries(source)) {
+        if (typeof value !== 'string') continue;
+        env[key] = value;
+    }
+
+    for (const key of Object.keys(env)) {
+        if (
+            key === 'INIT_CWD'
+            || key === 'NO_COLOR'
+            || key === 'FORCE_COLOR'
+            || key === 'npm_command'
+            || key === 'npm_execpath'
+            || key === 'npm_node_execpath'
+            || key.startsWith('npm_')
+            || key.startsWith('npm_config_')
+            || key.startsWith('npm_package_')
+            || key.startsWith('npm_lifecycle_')
+            || key.startsWith('PNPM_')
+            || key.startsWith('YARN_')
+            || key.startsWith('BUN_')
+        ) {
+            delete env[key];
+        }
+    }
+
+    return env;
+}
+
+function computeTerminalQueryTail(buffer: string): string {
+    const prefixes = ['\x1b[6n', '\x1b[?6n'];
+    const maxLength = prefixes.reduce((n, value) => Math.max(n, value.length), 0) - 1;
+    const start = Math.max(0, buffer.length - maxLength);
+    for (let i = start; i < buffer.length; i++) {
+        const suffix = buffer.slice(i);
+        if (prefixes.some((pattern) => suffix.length < pattern.length && pattern.startsWith(suffix))) {
+            return suffix;
+        }
+    }
+    return '';
+}
+
 function findBinary(name: string): string {
     const isWin = os.platform() === 'win32';
     try {
@@ -284,44 +326,6 @@ function promptLikelyVisible(screenText: string, promptSnippet: string): boolean
     return matched >= required;
 }
 
-function splitHistoryLines(text: string): string[] {
-    return String(text || '')
-        .split('\n')
-        .map(line => line.replace(/\s+$/, ''));
-}
-
-function normalizeHistoryLine(line: string): string {
-    return String(line || '').replace(/\s+/g, ' ').trim();
-}
-
-function mergeTerminalHistory(existing: string, snapshot: string): string {
-    const next = String(snapshot || '').trim();
-    if (!next) return existing;
-    const prev = String(existing || '').trim();
-    if (!prev) return next;
-    if (prev === next || prev.endsWith(next)) return prev;
-
-    const prevLines = splitHistoryLines(prev);
-    const nextLines = splitHistoryLines(next);
-    const prevNorm = prevLines.map(normalizeHistoryLine);
-    const nextNorm = nextLines.map(normalizeHistoryLine);
-
-    const maxOverlap = Math.min(prevLines.length, nextLines.length);
-    for (let overlap = maxOverlap; overlap >= 1; overlap -= 1) {
-        const prevTail = prevNorm.slice(prevNorm.length - overlap);
-        const nextHead = nextNorm.slice(0, overlap);
-        if (prevTail.every((line, index) => line === nextHead[index])) {
-            return [...prevLines, ...nextLines.slice(overlap)].join('\n').trim();
-        }
-    }
-
-    const compactPrev = prevNorm.join('\n');
-    const compactNext = nextNorm.join('\n');
-    if (compactPrev.includes(compactNext)) return prev;
-
-    return `${prev}\n${next}`.trim();
-}
-
 /**
  * Normalize provider.json for auto-implement approval detection.
  * Kept for backward compat with dev-server auto-impl pipeline only.
@@ -390,6 +394,7 @@ export class ProviderCliAdapter implements CliAdapter {
     private pendingOutputParseTimer: NodeJS.Timeout | null = null;
     private ptyOutputBuffer = '';
     private ptyOutputFlushTimer: NodeJS.Timeout | null = null;
+    private pendingTerminalQueryTail = '';
 
  // Server log forwarding
     private serverConn: any = null;
@@ -428,9 +433,7 @@ export class ProviderCliAdapter implements CliAdapter {
     /** Full accumulated raw PTY output (with ANSI) */
     private accumulatedRawBuffer: string = '';
     /** Current visible terminal screen snapshot */
-    private terminalScreen = new TerminalScreen(40, 120);
-    /** Rolling append-only terminal transcript built from screen snapshots */
-    private terminalHistory: string = '';
+    private terminalScreen = new TerminalScreen(30, 100);
     /** Max accumulated buffer size (last 50KB) */
     private static readonly MAX_ACCUMULATED_BUFFER = 50000;
     private currentTurnScope: TurnParseScope | null = null;
@@ -461,23 +464,17 @@ export class ProviderCliAdapter implements CliAdapter {
 
     private buildParseInput(baseMessages: CliChatMessage[], partialResponse: string, scope?: TurnParseScope | null): CliScriptInput {
         const buffer = scope
-            ? (this.sliceFromOffset(this.terminalHistory, scope.terminalHistoryStart)
-                || this.sliceFromOffset(this.accumulatedBuffer, scope.bufferStart)
-                || this.accumulatedBuffer)
+            ? (this.sliceFromOffset(this.accumulatedBuffer, scope.bufferStart) || this.accumulatedBuffer)
             : this.accumulatedBuffer;
         const rawBuffer = scope
             ? (this.sliceFromOffset(this.accumulatedRawBuffer, scope.rawBufferStart) || this.accumulatedRawBuffer)
             : this.accumulatedRawBuffer;
-        const terminalHistory = scope
-            ? (this.sliceFromOffset(this.terminalHistory, scope.terminalHistoryStart) || this.terminalHistory)
-            : this.terminalHistory;
 
         return {
             buffer,
             rawBuffer,
             recentBuffer: buffer.slice(-1000) || this.recentOutputBuffer,
             screenText: this.terminalScreen.getText(),
-            terminalHistory,
             messages: [...baseMessages],
             partialResponse,
         };
@@ -623,13 +620,10 @@ export class ProviderCliAdapter implements CliAdapter {
         }
 
         const ptyOpts = {
-            cols: 120,
-            rows: 40,
+            cols: 100,
+            rows: 30,
             cwd: this.workingDir,
-            env: {
-                ...process.env,
-                ...spawnConfig.env,
-            } as Record<string, string>,
+            env: buildCliSpawnEnv(process.env, spawnConfig.env),
         };
 
         try {
@@ -650,9 +644,8 @@ export class ProviderCliAdapter implements CliAdapter {
         this.ptyProcess.onData((data: string) => {
             if (Date.now() < this.resizeSuppressUntil) return;
 
-            if (data.includes('\x1b[6n') || data.includes('\x1b[?6n')) {
-                // Some TUIs probe cursor position during startup; reply quickly even when batching parsing.
-                this.ptyProcess?.write('\x1b[1;1R');
+            if (!this.ptyProcess?.terminalQueriesHandled) {
+                this.respondToTerminalQueries(data);
             }
 
             this.pendingOutputParseBuffer += data;
@@ -691,8 +684,8 @@ export class ProviderCliAdapter implements CliAdapter {
         this.spawnAt = Date.now();
         this.startupParseGate = true;
         this.startupBuffer = '';
-        this.terminalScreen.reset(40, 120);
-        this.terminalHistory = '';
+        this.terminalScreen.reset(30, 100);
+        this.pendingTerminalQueryTail = '';
         this.currentTurnScope = null;
         this.ready = false;
         await this.ptyProcess.ready;
@@ -704,7 +697,6 @@ export class ProviderCliAdapter implements CliAdapter {
 
     private handleOutput(rawData: string): void {
         this.terminalScreen.write(rawData);
-        this.terminalHistory = mergeTerminalHistory(this.terminalHistory, this.terminalScreen.getText());
         const cleanData = sanitizeTerminalText(rawData);
 
         if (this.isWaitingForResponse && cleanData) {
@@ -1013,7 +1005,6 @@ export class ProviderCliAdapter implements CliAdapter {
             messages: [...this.committedMessages],
             workingDir: this.workingDir,
             activeModal: this.activeModal,
-            terminalHistory: this.terminalHistory,
         };
     }
 
@@ -1032,7 +1023,6 @@ export class ProviderCliAdapter implements CliAdapter {
                 id: parsed.id || 'cli_session',
                 status: parsed.status || this.currentStatus,
                 title: parsed.title || this.cliName,
-                terminalHistory: this.terminalHistory,
                 messages: parsed.messages,
                 activeModal: parsed.activeModal ?? this.activeModal,
             };
@@ -1043,7 +1033,6 @@ export class ProviderCliAdapter implements CliAdapter {
             id: 'cli_session',
             status: this.currentStatus,
             title: this.cliName,
-            terminalHistory: this.terminalHistory,
             messages: messages.slice(-50).map((message, index) => ({
                 id: `msg_${index}`,
                 role: message.role,
@@ -1114,9 +1103,8 @@ export class ProviderCliAdapter implements CliAdapter {
             startedAt: Date.now(),
             bufferStart: this.accumulatedBuffer.length,
             rawBufferStart: this.accumulatedRawBuffer.length,
-            terminalHistoryStart: this.terminalHistory.length,
         };
-        LOG.info('CLI', `[${this.cliType}] sendMessage turn scope buffer=${this.currentTurnScope.bufferStart} raw=${this.currentTurnScope.rawBufferStart} terminal=${this.currentTurnScope.terminalHistoryStart} prompt=${JSON.stringify(text).slice(0, 120)}`);
+        LOG.info('CLI', `[${this.cliType}] sendMessage turn scope buffer=${this.currentTurnScope.bufferStart} raw=${this.currentTurnScope.rawBufferStart} prompt=${JSON.stringify(text).slice(0, 120)}`);
         this.submitRetryUsed = false;
         this.submitRetryPromptSnippet = extractPromptRetrySnippet(text);
         const normalizedPromptSnippet = normalizePromptText(this.submitRetryPromptSnippet);
@@ -1304,6 +1292,7 @@ export class ProviderCliAdapter implements CliAdapter {
         if (this.submitRetryTimer) { clearTimeout(this.submitRetryTimer); this.submitRetryTimer = null; }
         if (this.pendingOutputParseTimer) { clearTimeout(this.pendingOutputParseTimer); this.pendingOutputParseTimer = null; }
         this.pendingOutputParseBuffer = '';
+        this.pendingTerminalQueryTail = '';
         if (this.ptyOutputFlushTimer) { clearTimeout(this.ptyOutputFlushTimer); this.ptyOutputFlushTimer = null; }
         this.ptyOutputBuffer = '';
         if (this.ptyProcess) {
@@ -1326,6 +1315,7 @@ export class ProviderCliAdapter implements CliAdapter {
         if (this.submitRetryTimer) { clearTimeout(this.submitRetryTimer); this.submitRetryTimer = null; }
         if (this.pendingOutputParseTimer) { clearTimeout(this.pendingOutputParseTimer); this.pendingOutputParseTimer = null; }
         this.pendingOutputParseBuffer = '';
+        this.pendingTerminalQueryTail = '';
         if (this.ptyOutputFlushTimer) { clearTimeout(this.ptyOutputFlushTimer); this.ptyOutputFlushTimer = null; }
         this.ptyOutputBuffer = '';
         if (this.ptyProcess) {
@@ -1349,12 +1339,12 @@ export class ProviderCliAdapter implements CliAdapter {
         this.syncMessageViews();
         this.accumulatedBuffer = '';
         this.accumulatedRawBuffer = '';
-        this.terminalHistory = '';
         this.currentTurnScope = null;
         this.submitRetryUsed = false;
         this.submitRetryPromptSnippet = '';
         if (this.pendingOutputParseTimer) { clearTimeout(this.pendingOutputParseTimer); this.pendingOutputParseTimer = null; }
         this.pendingOutputParseBuffer = '';
+        this.pendingTerminalQueryTail = '';
         if (this.ptyOutputFlushTimer) { clearTimeout(this.ptyOutputFlushTimer); this.ptyOutputFlushTimer = null; }
         this.ptyOutputBuffer = '';
         this.terminalScreen.reset();
@@ -1413,7 +1403,6 @@ export class ProviderCliAdapter implements CliAdapter {
             structuredMessages: this.structuredMessages.slice(-20),
             messageCount: this.committedMessages.length,
             screenText: sanitizeTerminalText(this.terminalScreen.getText()).slice(-4000),
-            terminalHistory: this.terminalHistory.slice(-8000),
             currentTurnScope: this.currentTurnScope,
             startupBuffer: this.startupBuffer.slice(-4000),
             recentOutputBuffer: this.recentOutputBuffer.slice(-500),
@@ -1441,4 +1430,24 @@ export class ProviderCliAdapter implements CliAdapter {
             ptyAlive: !!this.ptyProcess,
         };
     }
+
+    private respondToTerminalQueries(data: string): void {
+        if (!this.ptyProcess || !data) return;
+
+        const combined = this.pendingTerminalQueryTail + data;
+        const regex = /\x1b\[(\?)?6n/g;
+        let match: RegExpExecArray | null;
+
+        while ((match = regex.exec(combined)) !== null) {
+            const cursor = this.terminalScreen.getCursorPosition();
+            const row = Math.max(1, (cursor.row | 0) + 1);
+            const col = Math.max(1, (cursor.col | 0) + 1);
+            const response = match[1]
+                ? `\x1b[?${row};${col}R`
+                : `\x1b[${row};${col}R`;
+            this.ptyProcess.write(response);
+        }
+
+        this.pendingTerminalQueryTail = computeTerminalQueryTail(combined);
+    }
 }

package/src/cli-adapters/pty-transport.ts

@@ -37,6 +37,7 @@ export interface PtyRuntimeMetadata {
 export interface PtyRuntimeTransport {
   readonly pid: number;
   readonly ready: Promise<void>;
+  readonly terminalQueriesHandled?: boolean;
   write(data: string): void;
   resize(cols: number, rows: number): void;
   kill(): void;
@@ -53,6 +54,7 @@ export interface PtyTransportFactory {
 
 class NodePtyRuntimeTransport implements PtyRuntimeTransport {
   readonly ready = Promise.resolve();
+  readonly terminalQueriesHandled = false;
 
   constructor(private readonly handle: any) {}
 

package/src/cli-adapters/session-host-transport.ts

@@ -28,6 +28,7 @@ interface SessionHostRuntimeOptions extends SessionHostPtyTransportFactoryOption
 
 class SessionHostRuntimeTransport implements PtyRuntimeTransport {
     readonly ready: Promise<void>;
+    readonly terminalQueriesHandled = true;
 
     private readonly client: SessionHostClient;
     private readonly dataCallbacks = new Set<(data: string) => void>();

package/src/cli-adapters/terminal-backends/ghostty-vt-backend.ts

@@ -8,6 +8,7 @@ type GhosttyVtTerminal = {
     write(data: string | Uint8Array): void;
     resize(cols: number, rows: number): void;
     formatPlainText(options?: { trim?: boolean }): string;
+    getCursorPosition(): { col: number; row: number };
     dispose(): void;
 };
 
@@ -123,6 +124,10 @@ export class GhosttyVtTerminalBackend implements TerminalViewportBackend {
         return this.terminal.formatPlainText({ trim: true }) || '';
     }
 
+    getCursorPosition(): { col: number; row: number } {
+        return this.terminal.getCursorPosition();
+    }
+
     dispose(): void {
         this.terminal.dispose();
     }

package/src/cli-adapters/terminal-backends/types.ts

@@ -13,5 +13,6 @@ export interface TerminalViewportBackend {
     resize(rows: number, cols: number): void;
     write(data: string): void;
     getText(): string;
+    getCursorPosition(): { col: number; row: number };
     dispose(): void;
 }

package/src/cli-adapters/terminal-backends/xterm-backend.ts

@@ -7,6 +7,8 @@ type XtermBufferLine = {
 type XtermBuffer = {
     length: number;
     viewportY: number;
+    cursorX?: number;
+    cursorY?: number;
     getLine(index: number): XtermBufferLine | undefined;
 };
 
@@ -72,6 +74,14 @@ export class XtermTerminalBackend implements TerminalViewportBackend {
         return lines.slice(first, last).join('\n');
     }
 
+    getCursorPosition(): { col: number; row: number } {
+        const buffer = this.terminal.buffer.active;
+        return {
+            col: Math.max(0, buffer.cursorX || 0),
+            row: Math.max(0, buffer.cursorY || 0),
+        };
+    }
+
     dispose(): void {
         this.terminal.dispose();
     }

package/src/cli-adapters/terminal-screen.ts

@@ -106,6 +106,10 @@ export class TerminalScreen {
         return this.terminal.getText();
     }
 
+    getCursorPosition(): { col: number; row: number } {
+        return this.terminal.getCursorPosition();
+    }
+
     dispose(): void {
         this.terminal.dispose();
     }

package/src/commands/router.ts

@@ -26,6 +26,7 @@ import { logCommand } from '../logging/command-log.js';
 import { getRecentLogs, LOG_PATH } from '../logging/logger.js';
 import { buildSessionEntries } from '../status/builders.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
+import { spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
 import * as fs from 'fs';
 
 // ─── Types ───
@@ -315,36 +316,41 @@ export class DaemonCommandRouter {
                     // Check latest version
                     const latest = execSync(`npm view ${pkgName} version`, { encoding: 'utf-8', timeout: 10000 }).trim();
                     LOG.info('Upgrade', `Latest ${pkgName}: v${latest}`);
+                    let currentInstalled: string | null = null;
+                    try {
+                        const currentJson = execSync(`npm ls -g ${pkgName} --depth=0 --json`, {
+                            encoding: 'utf-8',
+                            timeout: 10000,
+                            stdio: ['pipe', 'pipe', 'pipe'],
+                        }).trim();
+                        const parsed = JSON.parse(currentJson);
+                        currentInstalled = parsed?.dependencies?.[pkgName]?.version || null;
+                    } catch {
+                        // ignore ls failures; upgrade can still proceed
+                    }
 
-                    // Install latest (--force ensures native addons are rebuilt cleanly)
-                    execSync(`npm install -g ${pkgName}@latest --force`, {
-                        encoding: 'utf-8',
-                        timeout: 120000,
-                        stdio: ['pipe', 'pipe', 'pipe'],
+                    if (currentInstalled === latest) {
+                        LOG.info('Upgrade', `Already on latest version v${latest}; skipping install`);
+                        return { success: true, upgraded: false, alreadyLatest: true, version: latest };
+                    }
+
+                    spawnDetachedDaemonUpgradeHelper({
+                        packageName: pkgName,
+                        targetVersion: latest,
+                        parentPid: process.pid,
+                        restartArgv: process.argv.slice(1),
+                        cwd: process.cwd(),
+                        sessionHostAppName: process.env.ADHDEV_SESSION_HOST_NAME || 'adhdev',
                     });
-                    LOG.info('Upgrade', `✅ Upgraded to v${latest}`);
+                    LOG.info('Upgrade', `Scheduled detached upgrade to v${latest}`);
 
-                    // Schedule restart after response is sent
+                    // Exit after the command response has been sent so the helper can replace the package cleanly.
                     setTimeout(() => {
-                        LOG.info('Upgrade', 'Restarting daemon with new version...');
-                        // Remove PID file so the new process doesn't see 'already running'
-                        try {
-                            const path = require('path');
-                            const fs = require('fs');
-                            const pidFile = path.join(process.env.HOME || process.env.USERPROFILE || '', '.adhdev', 'daemon.pid');
-                            if (fs.existsSync(pidFile)) fs.unlinkSync(pidFile);
-                        } catch { /* ignore */ }
-                        const { spawn } = require('child_process');
-                        const child = spawn(process.execPath, process.argv.slice(1), {
-                            detached: true,
-                            stdio: 'ignore',
-                            env: { ...process.env },
-                        });
-                        child.unref();
+                        LOG.info('Upgrade', 'Exiting daemon so detached upgrader can continue...');
                         process.exit(0);
                     }, 3000);
 
-                    return { success: true, upgraded: true, version: latest };
+                    return { success: true, upgraded: true, version: latest, restarting: true };
                 } catch (e: any) {
                     LOG.error('Upgrade', `Failed: ${e.message}`);
                     return { success: false, error: e.message };

package/src/commands/upgrade-helper.ts

@@ -0,0 +1,214 @@
+import { execFileSync } from 'child_process';
+import { spawn } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+
+const UPGRADE_HELPER_ENV = 'ADHDEV_DAEMON_UPGRADE_HELPER';
+
+export interface DaemonUpgradeHelperPayload {
+  packageName: string;
+  targetVersion: string;
+  parentPid: number;
+  restartArgv: string[];
+  cwd?: string;
+  sessionHostAppName?: string;
+}
+
+function getUpgradeLogPath(): string {
+  const home = os.homedir();
+  const dir = path.join(home, '.adhdev');
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, 'daemon-upgrade.log');
+}
+
+function appendUpgradeLog(message: string): void {
+  const line = `[${new Date().toISOString()}] ${message}\n`;
+  try {
+    fs.appendFileSync(getUpgradeLogPath(), line, 'utf8');
+  } catch {
+    // noop
+  }
+}
+
+function getNpmExecutable(): string {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
+function killPid(pid: number): boolean {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+    } else {
+      process.kill(pid, 'SIGTERM');
+    }
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForPidExit(pid: number, timeoutMs: number): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      process.kill(pid, 0);
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    } catch {
+      return;
+    }
+  }
+}
+
+function stopSessionHostProcesses(appName: string): void {
+  const pidFile = path.join(os.homedir(), '.adhdev', `${appName}-session-host.pid`);
+  try {
+    if (fs.existsSync(pidFile)) {
+      const pid = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+      if (Number.isFinite(pid)) {
+        killPid(pid);
+      }
+    }
+  } catch {
+    // noop
+  } finally {
+    try {
+      fs.unlinkSync(pidFile);
+    } catch {
+      // noop
+    }
+  }
+
+  if (process.platform !== 'win32') {
+    try {
+      const raw = execFileSync('pgrep', ['-f', 'session-host-daemon'], { encoding: 'utf8' }).trim();
+      for (const line of raw.split('\n')) {
+        const pid = Number.parseInt(line.trim(), 10);
+        if (Number.isFinite(pid)) {
+          killPid(pid);
+        }
+      }
+    } catch {
+      // noop
+    }
+  }
+}
+
+function removeDaemonPidFile(): void {
+  const pidFile = path.join(os.homedir(), '.adhdev', 'daemon.pid');
+  try {
+    fs.unlinkSync(pidFile);
+  } catch {
+    // noop
+  }
+}
+
+function cleanupStaleGlobalInstallDirs(pkgName: string): void {
+  const npmRoot = execFileSync(getNpmExecutable(), ['root', '-g'], { encoding: 'utf8' }).trim();
+  if (!npmRoot) return;
+  const npmPrefix = execFileSync(getNpmExecutable(), ['prefix', '-g'], { encoding: 'utf8' }).trim();
+  const binDir = process.platform === 'win32' ? npmPrefix : path.join(npmPrefix, 'bin');
+  const packageBaseName = pkgName.startsWith('@') ? pkgName.split('/')[1] : pkgName;
+  const binNames = new Set<string>([packageBaseName]);
+  if (pkgName === '@adhdev/daemon-standalone') {
+    binNames.add('adhdev-standalone');
+  }
+
+  if (pkgName.startsWith('@')) {
+    const [scope, name] = pkgName.split('/');
+    const scopeDir = path.join(npmRoot, scope);
+    if (!fs.existsSync(scopeDir)) return;
+    for (const entry of fs.readdirSync(scopeDir)) {
+      if (!entry.startsWith(`.${name}-`)) continue;
+      fs.rmSync(path.join(scopeDir, entry), { recursive: true, force: true });
+      appendUpgradeLog(`Removed stale scoped staging dir: ${path.join(scopeDir, entry)}`);
+    }
+  } else {
+    for (const entry of fs.readdirSync(npmRoot)) {
+      if (!entry.startsWith(`.${pkgName}-`)) continue;
+      fs.rmSync(path.join(npmRoot, entry), { recursive: true, force: true });
+      appendUpgradeLog(`Removed stale staging dir: ${path.join(npmRoot, entry)}`);
+    }
+  }
+
+  if (fs.existsSync(binDir)) {
+    for (const entry of fs.readdirSync(binDir)) {
+      if (![...binNames].some((name) => entry.startsWith(`.${name}-`))) continue;
+      fs.rmSync(path.join(binDir, entry), { recursive: true, force: true });
+      appendUpgradeLog(`Removed stale bin staging entry: ${path.join(binDir, entry)}`);
+    }
+  }
+}
+
+export function spawnDetachedDaemonUpgradeHelper(payload: DaemonUpgradeHelperPayload): void {
+  const env = { ...process.env, [UPGRADE_HELPER_ENV]: JSON.stringify(payload) };
+  const child = spawn(process.execPath, process.argv.slice(1), {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    cwd: payload.cwd || process.cwd(),
+    env,
+  });
+  child.unref();
+}
+
+async function runDaemonUpgradeHelper(payload: DaemonUpgradeHelperPayload): Promise<void> {
+  const restartArgv = Array.isArray(payload.restartArgv) ? payload.restartArgv : [];
+  const sessionHostAppName = payload.sessionHostAppName || process.env.ADHDEV_SESSION_HOST_NAME || 'adhdev';
+  appendUpgradeLog(`Upgrade helper started for ${payload.packageName}@${payload.targetVersion}`);
+
+  if (Number.isFinite(payload.parentPid) && payload.parentPid > 0) {
+    appendUpgradeLog(`Waiting for parent pid ${payload.parentPid} to exit`);
+    await waitForPidExit(payload.parentPid, 15000);
+  }
+
+  stopSessionHostProcesses(sessionHostAppName);
+  removeDaemonPidFile();
+  cleanupStaleGlobalInstallDirs(payload.packageName);
+
+  const spec = `${payload.packageName}@${payload.targetVersion || 'latest'}`;
+  appendUpgradeLog(`Installing ${spec}`);
+  const installOutput = execFileSync(
+    getNpmExecutable(),
+    ['install', '-g', spec, '--force'],
+    {
+      encoding: 'utf8',
+      stdio: 'pipe',
+      maxBuffer: 20 * 1024 * 1024,
+    },
+  );
+  if (installOutput.trim()) {
+    appendUpgradeLog(installOutput.trim());
+  }
+
+  if (restartArgv.length > 0) {
+    const env = { ...process.env };
+    delete env[UPGRADE_HELPER_ENV];
+    appendUpgradeLog(`Restarting daemon with args: ${restartArgv.join(' ')}`);
+    const child = spawn(process.execPath, restartArgv, {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: true,
+      cwd: payload.cwd || process.cwd(),
+      env,
+    });
+    child.unref();
+  } else {
+    appendUpgradeLog('No restart argv provided; upgrade completed without restart');
+  }
+}
+
+export async function maybeRunDaemonUpgradeHelperFromEnv(): Promise<boolean> {
+  const raw = process.env[UPGRADE_HELPER_ENV];
+  if (!raw) return false;
+  delete process.env[UPGRADE_HELPER_ENV];
+
+  try {
+    const payload = JSON.parse(raw) as DaemonUpgradeHelperPayload;
+    await runDaemonUpgradeHelper(payload);
+    process.exit(0);
+  } catch (error: any) {
+    appendUpgradeLog(`Upgrade helper failed: ${error?.stack || error?.message || String(error)}`);
+    process.exit(1);
+  }
+}