@adhdev/daemon-core 0.8.25 → 0.8.28

package/src/commands/router.ts

@@ -14,6 +14,7 @@ import { registerExtensionProviders } from '../cdp/setup.js';
 import { DaemonCommandHandler } from './handler.js';
 import { DaemonCliManager } from './cli-manager.js';
 import { supportsExplicitSessionResume } from './cli-manager.js';
+import type { HostedCliRuntimeDescriptor } from './cli-manager.js';
 import type { ProviderLoader } from '../providers/provider-loader.js';
 import type { ProviderInstanceManager } from '../providers/provider-instance-manager.js';
 import { launchWithCdp, killIdeProcess, isIdeRunning } from '../launch.js';
@@ -35,6 +36,18 @@ import * as fs from 'fs';
 
 // ─── Types ───
 
+export interface SessionHostControlPlane {
+    getDiagnostics(payload?: { includeSessions?: boolean; limit?: number }): Promise<any>;
+    listSessions(): Promise<any[]>;
+    stopSession(sessionId: string): Promise<any>;
+    resumeSession(sessionId: string): Promise<any>;
+    restartSession(sessionId: string): Promise<any>;
+    sendSignal(sessionId: string, signal: string): Promise<any>;
+    forceDetachClient(sessionId: string, clientId: string): Promise<any>;
+    acquireWrite(payload: { sessionId: string; clientId: string; ownerType: 'agent' | 'user'; force?: boolean }): Promise<any>;
+    releaseWrite(payload: { sessionId: string; clientId: string }): Promise<any>;
+}
+
 export interface CommandRouterDeps {
     commandHandler: DaemonCommandHandler;
     cliManager: DaemonCliManager;
@@ -56,6 +69,8 @@ export interface CommandRouterDeps {
     getCdpLogFn?: (ideType: string) => (msg: string) => void;
     /** Package name for upgrade detection ('adhdev' or '@adhdev/daemon-standalone') */
     packageName?: string;
+    /** Session host control plane */
+    sessionHostControl?: SessionHostControlPlane | null;
 }
 
 export interface CommandRouterResult {
@@ -70,6 +85,30 @@ const CHAT_COMMANDS = [
 ];
 const READ_DEBUG_ENABLED = process.argv.includes('--dev') || process.env.ADHDEV_READ_DEBUG === '1';
 
+function toHostedCliRuntimeDescriptor(record: any): HostedCliRuntimeDescriptor | null {
+    if (!record || typeof record !== 'object') return null;
+    const runtimeId = typeof record.sessionId === 'string' ? record.sessionId : '';
+    const cliType = typeof record.providerType === 'string' ? record.providerType : '';
+    const workspace = typeof record.workspace === 'string' ? record.workspace : '';
+    if (!runtimeId || !cliType || !workspace) return null;
+    return {
+        runtimeId,
+        runtimeKey: typeof record.runtimeKey === 'string' ? record.runtimeKey : undefined,
+        displayName: typeof record.displayName === 'string' ? record.displayName : undefined,
+        workspaceLabel: typeof record.workspaceLabel === 'string' ? record.workspaceLabel : undefined,
+        lifecycle: typeof record.lifecycle === 'string' ? record.lifecycle as HostedCliRuntimeDescriptor['lifecycle'] : undefined,
+        recoveryState: typeof record.meta?.runtimeRecoveryState === 'string'
+            ? String(record.meta.runtimeRecoveryState)
+            : null,
+        cliType,
+        workspace,
+        cliArgs: Array.isArray(record.meta?.cliArgs) ? record.meta.cliArgs as string[] : [],
+        providerSessionId: typeof record.meta?.providerSessionId === 'string'
+            ? String(record.meta.providerSessionId)
+            : undefined,
+    };
+}
+
 export class DaemonCommandRouter {
     private deps: CommandRouterDeps;
 
@@ -159,6 +198,99 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'session_host_get_diagnostics': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const diagnostics = await this.deps.sessionHostControl.getDiagnostics({
+                    includeSessions: args?.includeSessions !== false,
+                    limit: Number(args?.limit) || undefined,
+                });
+                return { success: true, diagnostics };
+            }
+
+            case 'session_host_list_sessions': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessions = await this.deps.sessionHostControl.listSessions();
+                return { success: true, sessions };
+            }
+
+            case 'session_host_stop_session': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                const record = await this.deps.sessionHostControl.stopSession(sessionId);
+                return { success: true, record };
+            }
+
+            case 'session_host_resume_session': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                const record = await this.deps.sessionHostControl.resumeSession(sessionId);
+                const hosted = toHostedCliRuntimeDescriptor(record);
+                if (hosted) {
+                    await this.deps.cliManager.restoreHostedSessions([hosted]);
+                }
+                return { success: true, record };
+            }
+
+            case 'session_host_restart_session': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                const record = await this.deps.sessionHostControl.restartSession(sessionId);
+                const hosted = toHostedCliRuntimeDescriptor(record);
+                if (hosted) {
+                    await this.deps.cliManager.restoreHostedSessions([hosted]);
+                }
+                return { success: true, record };
+            }
+
+            case 'session_host_send_signal': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                const signal = typeof args?.signal === 'string' ? args.signal : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                if (!signal) return { success: false, error: 'signal required' };
+                const record = await this.deps.sessionHostControl.sendSignal(sessionId, signal);
+                return { success: true, record };
+            }
+
+            case 'session_host_force_detach_client': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                if (!clientId) return { success: false, error: 'clientId required' };
+                const record = await this.deps.sessionHostControl.forceDetachClient(sessionId, clientId);
+                return { success: true, record };
+            }
+
+            case 'session_host_acquire_write': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+                const ownerType = args?.ownerType === 'agent' ? 'agent' : 'user';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                if (!clientId) return { success: false, error: 'clientId required' };
+                const record = await this.deps.sessionHostControl.acquireWrite({
+                    sessionId,
+                    clientId,
+                    ownerType,
+                    force: args?.force !== false,
+                });
+                return { success: true, record };
+            }
+
+            case 'session_host_release_write': {
+                if (!this.deps.sessionHostControl) return { success: false, error: 'Session host control unavailable' };
+                const sessionId = typeof args?.sessionId === 'string' ? args.sessionId : '';
+                const clientId = typeof args?.clientId === 'string' ? args.clientId : '';
+                if (!sessionId) return { success: false, error: 'sessionId required' };
+                if (!clientId) return { success: false, error: 'clientId required' };
+                const record = await this.deps.sessionHostControl.releaseWrite({ sessionId, clientId });
+                return { success: true, record };
+            }
+
             case 'list_saved_sessions': {
                 const providerType = typeof args?.providerType === 'string'
                     ? args.providerType.trim()
@@ -233,6 +365,11 @@ export class DaemonCommandRouter {
                 if (!ideType) throw new Error('ideType required');
                 const killProcess = args?.killProcess !== false; // default true
                 await this.stopIde(ideType, killProcess);
+                try {
+                    const results = await detectIDEs(this.deps.providerLoader);
+                    this.deps.detectedIdes.value = results;
+                    this.deps.providerLoader.setIdeDetectionResults(results, true);
+                } catch { /* ignore detection refresh errors */ }
                 return { success: true, ideType, stopped: true, processKilled: killProcess };
             }
 
@@ -283,6 +420,11 @@ export class DaemonCommandRouter {
                     }
                 }
                 this.deps.onIdeConnected?.();
+                try {
+                    const results = await detectIDEs(this.deps.providerLoader);
+                    this.deps.detectedIdes.value = results;
+                    this.deps.providerLoader.setIdeDetectionResults(results, true);
+                } catch { /* ignore detection refresh errors */ }
                 if (result.success && resolvedWorkspace) {
                     try {
                         const next = appendRecentActivity(loadState(), {
@@ -309,8 +451,9 @@ export class DaemonCommandRouter {
 
             // ─── Detect IDEs ───
             case 'detect_ides': {
-                const results = await detectIDEs();
+                const results = await detectIDEs(this.deps.providerLoader);
                 this.deps.detectedIdes.value = results;
+                this.deps.providerLoader.setIdeDetectionResults(results, true);
                 return { success: true, detectedInfo: results };
             }
 

package/src/commands/stream-commands.ts

@@ -76,7 +76,7 @@ export function handleGetProviderSettings(h: CommandHelpers, args: any): Command
     return { success: true, settings: allSettings, values: allValues };
 }
 
-export function handleSetProviderSetting(h: CommandHelpers, args: any): CommandResult {
+export async function handleSetProviderSetting(h: CommandHelpers, args: any): Promise<CommandResult> {
     const loader = h.ctx.providerLoader as ProviderLoader | undefined;
     const { providerType, key, value } = args || {};
     if (!providerType || !key || value === undefined) {
@@ -89,6 +89,7 @@ export function handleSetProviderSetting(h: CommandHelpers, args: any): CommandR
             const updated = h.ctx.instanceManager.updateInstanceSettings(providerType, allSettings);
             LOG.info('Command', `[set_provider_setting] ${providerType}.${key}=${JSON.stringify(value)} → ${updated} instance(s) updated`);
         }
+        await h.ctx.onProviderSettingChanged?.(providerType, key, value);
         return { success: true, providerType, key, value };
     }
     return { success: false, error: `Failed to set ${providerType}.${key} — invalid key, value, or not a public setting` };
@@ -133,7 +134,7 @@ function getCliScriptCommand(payload: any): { type: string; text?: string } | nu
 
     const command = payload.command;
     if (!command || typeof command !== 'object') return null;
-    if (command.type !== 'send_message') return null;
+    if (command.type !== 'send_message' && command.type !== 'pty_write') return null;
 
     const text = typeof command.text === 'string'
         ? command.text.trim()
@@ -141,7 +142,7 @@ function getCliScriptCommand(payload: any): { type: string; text?: string } | nu
             ? command.message.trim()
             : '';
     if (!text) return null;
-    return { type: 'send_message', text };
+    return { type: command.type, text };
 }
 
 function applyProviderPatch(h: CommandHelpers, args: any, payload: any): void {
@@ -191,6 +192,8 @@ async function executeProviderScript(h: CommandHelpers, args: any, scriptName: s
             const cliCommand = getCliScriptCommand(parsed.payload);
             if (cliCommand?.type === 'send_message' && cliCommand.text) {
                 await adapter.sendMessage(cliCommand.text);
+            } else if (cliCommand?.type === 'pty_write' && cliCommand.text && adapter.writeRaw) {
+                adapter.writeRaw(cliCommand.text + '\r');
             }
             applyProviderPatch(h, args, parsed.payload);
             return { success: true, ...(parsed.payload && typeof parsed.payload === 'object' ? parsed.payload : { result: parsed.payload }) };

package/src/detection/cli-detector.ts

@@ -9,6 +9,8 @@
 
 import { exec } from 'child_process';
 import * as os from 'os';
+import * as path from 'path';
+import { existsSync } from 'fs';
 import type { ProviderLoader } from '../providers/provider-loader.js';
 
 export interface CLIInfo {
@@ -28,6 +30,33 @@ function parseVersion(raw: string): string {
     return match ? match[1] : raw.split('\n')[0].slice(0, 100);
 }
 
+function shellQuote(value: string): string {
+    if (/^[a-zA-Z0-9_./:@%+=,-]+$/.test(value)) return value;
+    return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
+}
+
+function expandHome(value: string): string {
+    const trimmed = value.trim();
+    if (!trimmed.startsWith('~')) return trimmed;
+    return path.join(os.homedir(), trimmed.slice(1));
+}
+
+function isExplicitCommandPath(command: string): boolean {
+    const trimmed = command.trim();
+    return path.isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\') || trimmed.startsWith('~');
+}
+
+function resolveCommandPath(command: string): string | null {
+    const trimmed = command.trim();
+    if (!trimmed) return null;
+    if (isExplicitCommandPath(trimmed)) {
+        const expanded = expandHome(trimmed);
+        const candidate = path.isAbsolute(expanded) ? expanded : path.resolve(expanded);
+        return existsSync(candidate) ? candidate : null;
+    }
+    return null;
+}
+
 /** Run a shell command with timeout, returning stdout or null on failure */
 function execAsync(cmd: string, timeoutMs = 5000): Promise<string | null> {
     return new Promise((resolve) => {
@@ -47,9 +76,13 @@ function execAsync(cmd: string, timeoutMs = 5000): Promise<string | null> {
  * Detect all CLI/ACP agents (parallel)
  * @param providerLoader ProviderLoader instance (dynamic list creation)
  */
-export async function detectCLIs(providerLoader?: ProviderLoader): Promise<CLIInfo[]> {
+export async function detectCLIs(
+    providerLoader?: ProviderLoader,
+    options?: { includeVersion?: boolean },
+): Promise<CLIInfo[]> {
     const platform = os.platform();
     const whichCmd = platform === 'win32' ? 'where' : 'which';
+    const includeVersion = options?.includeVersion !== false;
 
     // Provider-based dynamic list creation, fallback is empty array
     const cliList = providerLoader
@@ -60,28 +93,31 @@ export async function detectCLIs(providerLoader?: ProviderLoader): Promise<CLIIn
     const results = await Promise.all(
         cliList.map(async (cli): Promise<CLIInfo> => {
             try {
-                const pathResult = await execAsync(`${whichCmd} ${cli.command}`);
+                const explicitPath = resolveCommandPath(cli.command);
+                const pathResult = explicitPath || await execAsync(`${whichCmd} ${shellQuote(cli.command)}`);
                 if (!pathResult) return { ...cli, installed: false };
 
-                const firstPath = pathResult.split('\n')[0];
+                const firstPath = explicitPath || pathResult.split('\n')[0];
 
                 // Get version (parallel with other checks)
                 let version: string | undefined;
-                try {
+                if (includeVersion) {
                     const versionCommands = [
+                        `"${firstPath}" --version`,
+                        `"${firstPath}" -V`,
+                        `"${firstPath}" -v`,
                         cli.versionCommand,
-                        `${cli.command} --version`,
-                        `${cli.command} -V`,
-                        `${cli.command} -v`,
                     ].filter((v): v is string => !!v);
-                    for (const versionCommand of versionCommands) {
-                        const versionResult = await execAsync(versionCommand, 3000);
-                        if (versionResult) {
-                            version = parseVersion(versionResult);
-                            break;
+                    try {
+                        for (const versionCommand of versionCommands) {
+                            const versionResult = await execAsync(versionCommand, 3000);
+                            if (versionResult) {
+                                version = parseVersion(versionResult);
+                                break;
+                            }
                         }
-                    }
-                } catch { }
+                    } catch { }
+                }
 
                 return { ...cli, installed: true, version, path: firstPath };
             } catch {
@@ -94,7 +130,11 @@ export async function detectCLIs(providerLoader?: ProviderLoader): Promise<CLIIn
 }
 
 /** Detect specific CLI — only probes the one requested provider */
-export async function detectCLI(cliId: string, providerLoader?: ProviderLoader): Promise<CLIInfo | null> {
+export async function detectCLI(
+    cliId: string,
+    providerLoader?: ProviderLoader,
+    options?: { includeVersion?: boolean },
+): Promise<CLIInfo | null> {
     const resolvedId = providerLoader ? providerLoader.resolveAlias(cliId) : cliId;
 
     if (providerLoader) {
@@ -104,25 +144,28 @@ export async function detectCLI(cliId: string, providerLoader?: ProviderLoader):
             const platform = os.platform();
             const whichCmd = platform === 'win32' ? 'where' : 'which';
             try {
-                const pathResult = await execAsync(`${whichCmd} ${target.command}`);
+                const explicitPath = resolveCommandPath(target.command);
+                const pathResult = explicitPath || await execAsync(`${whichCmd} ${shellQuote(target.command)}`);
                 if (!pathResult) return null;
-                const firstPath = pathResult.split('\n')[0];
+                const firstPath = explicitPath || pathResult.split('\n')[0];
                 let version: string | undefined;
-                try {
+                if (options?.includeVersion !== false) {
                     const versionCommands = [
+                        `"${firstPath}" --version`,
+                        `"${firstPath}" -V`,
+                        `"${firstPath}" -v`,
                         target.versionCommand,
-                        `${target.command} --version`,
-                        `${target.command} -V`,
-                        `${target.command} -v`,
                     ].filter((v): v is string => !!v);
-                    for (const versionCommand of versionCommands) {
-                        const versionResult = await execAsync(versionCommand, 3000);
-                        if (versionResult) {
-                            version = parseVersion(versionResult);
-                            break;
+                    try {
+                        for (const versionCommand of versionCommands) {
+                            const versionResult = await execAsync(versionCommand, 3000);
+                            if (versionResult) {
+                                version = parseVersion(versionResult);
+                                break;
+                            }
                         }
-                    }
-                } catch { }
+                    } catch { }
+                }
                 return { ...target, installed: true, version, path: firstPath };
             } catch {
                 return null;
@@ -131,6 +174,6 @@ export async function detectCLI(cliId: string, providerLoader?: ProviderLoader):
     }
 
     // Fallback: full scan for unknown provider IDs
-    const all = await detectCLIs(providerLoader);
+    const all = await detectCLIs(providerLoader, options);
     return all.find((c) => c.id === resolvedId && c.installed) || null;
 }

package/src/detection/ide-detector.ts

@@ -10,6 +10,8 @@
 import { execSync } from 'child_process';
 import { existsSync } from 'fs';
 import { platform, homedir } from 'os';
+import * as path from 'path';
+import type { ProviderLoader } from '../providers/provider-loader.js';
 
 // ─── Types ──────────────────────────────────────
 
@@ -62,9 +64,18 @@ function getMergedDefinitions(): IDEDefinition[] {
 }
 
 function findCliCommand(command: string): string | null {
+    const trimmed = String(command || '').trim();
+    if (!trimmed) return null;
+    if (path.isAbsolute(trimmed) || trimmed.includes('/') || trimmed.includes('\\') || trimmed.startsWith('~')) {
+        const candidate = trimmed.startsWith('~')
+            ? path.join(homedir(), trimmed.slice(1))
+            : trimmed;
+        const resolved = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+        return existsSync(resolved) ? resolved : null;
+    }
     try {
         const result = execSync(
-            platform() === 'win32' ? `where ${command}` : `which ${command}`,
+            platform() === 'win32' ? `where ${trimmed}` : `which ${trimmed}`,
             { encoding: 'utf-8', timeout: 5000, stdio: ['pipe', 'pipe', 'pipe'] }
         ).trim();
         return result.split('\n')[0] || null;
@@ -89,27 +100,29 @@ function getIdeVersion(cliCommand: string): string | null {
 function checkPathExists(paths: string[]): string | null {
     const home = homedir();
     for (const p of paths) {
-        if (p.includes('*')) {
+        const normalized = p.startsWith('~')
+            ? path.join(home, p.slice(1))
+            : p;
+        if (normalized.includes('*')) {
             // Wildcard expansion: replace `*` with the current user's home folder name
             // e.g. "C:\Users\*\AppData\..." → "C:\Users\vilmi\AppData\..."
             const username = home.split(/[\\/]/).pop() || '';
-            const resolved = p.replace('*', username);
+            const resolved = normalized.replace('*', username);
             if (existsSync(resolved)) return resolved;
         } else {
-            if (existsSync(p)) return p;
+            if (existsSync(normalized)) return normalized;
         }
     }
     return null;
 }
 
-export async function detectIDEs(): Promise<IDEInfo[]> {
+export async function detectIDEs(providerLoader?: ProviderLoader): Promise<IDEInfo[]> {
     const os = platform() as 'darwin' | 'win32' | 'linux';
     const results: IDEInfo[] = [];
 
     for (const def of getMergedDefinitions()) {
-        const cliPath = findCliCommand(def.cli);
-        const appPath = checkPathExists(def.paths[os] || []);
-        const installed = !!(cliPath || appPath);
+        const cliPath = findCliCommand(providerLoader?.getIdeCliCommand(def.id, def.cli) || def.cli);
+        const appPath = checkPathExists(providerLoader?.getIdePathCandidates(def.id, def.paths[os] || []) || []);
 
         let resolvedCli = cliPath;
 
@@ -136,6 +149,9 @@ export async function detectIDEs(): Promise<IDEInfo[]> {
             }
         }
 
+        const installed = os === 'darwin'
+            ? !!(resolvedCli || appPath)
+            : !!resolvedCli;
         const version = resolvedCli ? getIdeVersion(resolvedCli) : null;
 
         results.push({

package/src/launch.ts

@@ -310,7 +310,7 @@ export async function launchWithCdp(options: LaunchOptions = {}): Promise<Launch
 
  // 1. IDE determine
     let targetIde: IDEInfo | undefined;
-    const ides = await detectIDEs();
+    const ides = await detectIDEs(getProviderLoader());
 
     if (options.ideId) {
         targetIde = ides.find(i => i.id === options.ideId && i.installed);

package/src/providers/acp-provider-instance.ts

@@ -327,8 +327,9 @@ export class AcpProviderInstance implements ProviderInstance {
  // Find configId for this category
         const opt = this.configOptions.find(c => c.category === category);
         if (!opt) {
-            this.log.warn(`[${this.type}] No config option for category: ${category}`);
-            return;
+            const message = `[${this.type}] No config option for category: ${category}`;
+            this.log.warn(message);
+            throw new Error(message);
         }
 
  // Static config mode: update selection and restart process
@@ -343,8 +344,9 @@ export class AcpProviderInstance implements ProviderInstance {
         }
 
         if (!this.connection || !this.sessionId) {
-            this.log.warn(`[${this.type}] Cannot set config: no active connection/session`);
-            return;
+            const message = `[${this.type}] Cannot set config: no active connection/session`;
+            this.log.warn(message);
+            throw new Error(message);
         }
 
         try {
@@ -361,7 +363,9 @@ export class AcpProviderInstance implements ProviderInstance {
             if (result?.configOptions) this.parseConfigOptions(result.configOptions);
             this.log.info(`[${this.type}] Config ${category} set to: ${value} | response: ${JSON.stringify(result)?.slice(0, 300)}`);
         } catch (e: any) {
-            this.log.warn(`[${this.type}] set_config_option failed: ${e?.message}`);
+            const message = e?.message || 'Unknown ACP config error';
+            this.log.warn(`[${this.type}] set_config_option failed: ${message}`);
+            throw new Error(message);
         }
     }
 
@@ -380,8 +384,9 @@ export class AcpProviderInstance implements ProviderInstance {
         }
 
         if (!this.connection || !this.sessionId) {
-            this.log.warn(`[${this.type}] Cannot set mode: no active connection/session`);
-            return;
+            const message = `[${this.type}] Cannot set mode: no active connection/session`;
+            this.log.warn(message);
+            throw new Error(message);
         }
 
         try {
@@ -392,7 +397,9 @@ export class AcpProviderInstance implements ProviderInstance {
             this.currentMode = modeId;
             this.log.info(`[${this.type}] Mode set to: ${modeId}`);
         } catch (e: any) {
-            this.log.warn(`[${this.type}] set_mode failed: ${e?.message}`);
+            const message = e?.message || 'Unknown ACP mode error';
+            this.log.warn(`[${this.type}] set_mode failed: ${message}`);
+            throw new Error(message);
         }
     }
 
@@ -447,7 +454,9 @@ export class AcpProviderInstance implements ProviderInstance {
             throw new Error(`[ACP:${this.type}] No spawn config defined`);
         }
 
-        const command = spawnConfig.command;
+        const command = typeof this.settings.executablePath === 'string' && this.settings.executablePath.trim()
+            ? this.settings.executablePath.trim()
+            : spawnConfig.command;
  // Static config: create args via spawnArgBuilder (when provider defines it)
         let baseArgs = spawnConfig.args || [];
         if (this.provider.spawnArgBuilder && Object.keys(this.selectedConfig).length > 0) {
@@ -822,7 +831,7 @@ export class AcpProviderInstance implements ProviderInstance {
 
     private permissionResolvers: ((approved: boolean) => void)[] = [];
 
-    private async resolvePermission(approved: boolean): Promise<void> {
+    async resolvePermission(approved: boolean): Promise<void> {
         const resolver = this.permissionResolvers.shift();
         if (resolver) {
             resolver(approved);

package/src/providers/cli-provider-instance.ts

@@ -14,7 +14,7 @@ import type { ProviderModule } from './contracts.js';
 import type { ProviderInstance, ProviderState, ProviderEvent, InstanceContext } from './provider-instance.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
-import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
+import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import { StatusMonitor } from './status-monitor.js';
 import { ChatHistoryWriter, readChatHistory } from '../config/chat-history.js';
 import { LOG } from '../logging/logger.js';
@@ -133,6 +133,7 @@ export class CliProviderInstance implements ProviderInstance {
 
  // PTY spawn
         await this.adapter.spawn();
+        this.maybeAppendRuntimeRecoveryMessage(this.adapter.getRuntimeMetadata());
         if (this.providerSessionId) {
             const restoredHistory = readChatHistory(this.type, 0, 200, this.providerSessionId);
             if (restoredHistory.messages.length > 0) {
@@ -246,6 +247,7 @@ export class CliProviderInstance implements ProviderInstance {
             this.promoteProviderSessionId(parsedProviderSessionId);
         }
         const runtime = this.adapter.getRuntimeMetadata();
+        this.maybeAppendRuntimeRecoveryMessage(runtime);
         const parsedMessages = Array.isArray(parsedStatus?.messages) ? parsedStatus.messages : [];
         const controlValues = extractProviderControlValues(this.provider.controls, parsedStatus);
         if (controlValues) {
@@ -603,6 +605,32 @@ export class CliProviderInstance implements ProviderInstance {
         return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
     }
 
+    private maybeAppendRuntimeRecoveryMessage(runtime: PtyRuntimeMetadata | null): void {
+        if (!runtime?.restoredFromStorage || !runtime.runtimeId) return;
+
+        const recoveryState = String(runtime.recoveryState || '').trim();
+        if (!recoveryState) return;
+
+        let content = '';
+        if (recoveryState === 'auto_resumed') {
+            content = 'Session host restored this CLI after restart and reattached it from a saved snapshot.';
+        } else if (recoveryState === 'resume_failed') {
+            const errorSuffix = runtime.recoveryError ? ` Resume failed: ${runtime.recoveryError}` : '';
+            content = `Session host found this CLI after restart, but automatic resume failed.${errorSuffix}`;
+        } else if (recoveryState === 'host_restart_interrupted') {
+            content = 'Session host found this CLI in interrupted state after restart and is attempting to resume it.';
+        } else if (recoveryState === 'orphan_snapshot') {
+            content = 'Session host restored the last snapshot for this CLI, but the original runtime was not resumed automatically.';
+        } else {
+            content = `Session host restored this CLI after restart (${recoveryState}).`;
+        }
+
+        this.appendRuntimeSystemMessage(
+            content,
+            `runtime_recovery:${runtime.runtimeId}:${recoveryState}`,
+        );
+    }
+
     private appendRuntimeSystemMessage(content: string, dedupKey: string, receivedAt = Date.now()): void {
         const normalizedContent = String(content || '').trim();
         if (!normalizedContent) return;