@adhdev/daemon-core 0.7.5 → 0.7.7

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

@@ -1,95 +1,82 @@
 /**
- * PTY screen snapshot backed by xterm's parser.
+ * PTY screen snapshot abstraction.
  *
- * Claude Code and similar CLIs use a real terminal UI. A handwritten ANSI
- * parser quickly drifts from reality, so we reuse xterm's terminal model and
- * expose only the current visible viewport as plain text for provider scripts.
+ * We currently keep xterm as the default parser/model because it is already
+ * proven in production, but the surface is now backend-agnostic so we can
+ * swap in libghostty-vt once a native Node binding is available.
  */
 
-type XtermBufferLine = {
-    translateToString(trimRight?: boolean): string;
-};
+import { GhosttyVtTerminalBackend, isGhosttyVtBackendAvailable, resolveTerminalBackendPreference } from './terminal-backends/ghostty-vt-backend.js';
+import type {
+    TerminalViewportBackend,
+    TerminalViewportBackendKind,
+    TerminalViewportBackendOptions,
+    TerminalViewportBackendPreference,
+} from './terminal-backends/types.js';
+import { XtermTerminalBackend } from './terminal-backends/xterm-backend.js';
 
-type XtermBuffer = {
-    length: number;
-    viewportY: number;
-    getLine(index: number): XtermBufferLine | undefined;
-};
+const DEFAULT_SCROLLBACK = 2000;
 
-type XtermTerminal = {
-    buffer: { active: XtermBuffer };
-    write(data: string, callback?: () => void): void;
-    resize(cols: number, rows: number): void;
-    dispose(): void;
-};
-
-let TerminalCtor: (new (options: { cols: number; rows: number; scrollback: number }) => XtermTerminal) | null = null;
+function createTerminalBackend(
+    options: TerminalViewportBackendOptions,
+    preference: TerminalViewportBackendPreference,
+): TerminalViewportBackend {
+    if (preference === 'ghostty-vt') {
+        return new GhosttyVtTerminalBackend(options);
+    }
 
-function loadTerminalCtor(): new (options: { cols: number; rows: number; scrollback: number }) => XtermTerminal {
-    if (!TerminalCtor) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires
-        const mod = require('@xterm/xterm');
-        TerminalCtor = mod.Terminal || mod.default?.Terminal || mod.default;
-        if (!TerminalCtor) {
-            throw new Error('@xterm/xterm Terminal export not found');
-        }
+    if (preference === 'auto' && isGhosttyVtBackendAvailable()) {
+        return new GhosttyVtTerminalBackend(options);
     }
-    return TerminalCtor;
+
+    return new XtermTerminalBackend(options);
 }
 
 export class TerminalScreen {
+    readonly backendKind: TerminalViewportBackendKind;
     private rows: number;
     private cols: number;
-    private terminal: XtermTerminal;
+    private readonly preference: TerminalViewportBackendPreference;
+    private terminal: TerminalViewportBackend;
 
     constructor(rows = 40, cols = 120) {
         this.rows = Math.max(1, rows | 0);
         this.cols = Math.max(1, cols | 0);
-        this.terminal = this.createTerminal();
+        this.preference = resolveTerminalBackendPreference();
+        this.terminal = this.createBackend();
+        this.backendKind = this.terminal.kind;
     }
 
     reset(rows = this.rows, cols = this.cols): void {
         this.rows = Math.max(1, rows | 0);
         this.cols = Math.max(1, cols | 0);
         this.terminal.dispose();
-        this.terminal = this.createTerminal();
+        this.terminal = this.createBackend();
     }
 
     resize(rows: number, cols: number): void {
         this.rows = Math.max(1, rows | 0);
         this.cols = Math.max(1, cols | 0);
-        this.terminal.resize(this.cols, this.rows);
+        this.terminal.resize(this.rows, this.cols);
     }
 
     write(data: string): void {
-        if (!data) return;
         this.terminal.write(data);
     }
 
     getText(): string {
-        const buffer = this.terminal.buffer.active;
-        const start = Math.max(0, buffer.viewportY || 0);
-        const end = Math.max(start, Math.min(buffer.length || 0, start + this.rows));
-        const lines: string[] = [];
-
-        for (let i = start; i < end; i++) {
-            const line = buffer.getLine(i);
-            lines.push(line ? line.translateToString(true) : '');
-        }
+        return this.terminal.getText();
+    }
 
-        let first = 0;
-        let last = lines.length;
-        while (first < last && !lines[first]?.trim()) first++;
-        while (last > first && !lines[last - 1]?.trim()) last--;
-        return lines.slice(first, last).join('\n');
+    dispose(): void {
+        this.terminal.dispose();
     }
 
-    private createTerminal(): XtermTerminal {
-        const Terminal = loadTerminalCtor();
-        return new Terminal({
+    private createBackend(): TerminalViewportBackend {
+        return createTerminalBackend({
             cols: this.cols,
             rows: this.rows,
-            scrollback: 2000,
-        });
+            scrollback: DEFAULT_SCROLLBACK,
+        }, this.preference);
     }
 }

package/src/commands/cli-manager.ts

@@ -19,6 +19,7 @@ import { AcpProviderInstance } from '../providers/acp-provider-instance.js';
 import type { ProviderInstanceManager } from '../providers/provider-instance-manager.js';
 import { ProviderLoader } from '../providers/provider-loader.js';
 import type { CliAdapter } from '../cli-adapter-types.js';
+import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import type { SessionRegistry } from '../sessions/registry.js';
 import { LOG } from '../logging/logger.js';
 
@@ -35,10 +36,32 @@ export interface CliManagerDeps {
  /** InstanceManager — register in CLI unified status */
     getInstanceManager(): ProviderInstanceManager | null;
     getSessionRegistry?(): SessionRegistry | null;
+    createPtyTransportFactory?: (params: CliTransportFactoryParams) => PtyTransportFactory | null;
+    listHostedCliRuntimes?: () => Promise<HostedCliRuntimeDescriptor[]>;
 }
 
 type CommandResult = { success: boolean;[key: string]: unknown };
 
+export interface CliTransportFactoryParams {
+    runtimeId: string;
+    providerType: string;
+    workspace: string;
+    cliArgs?: string[];
+    attachExisting?: boolean;
+}
+
+export interface HostedCliRuntimeDescriptor {
+    runtimeId: string;
+    runtimeKey?: string;
+    displayName?: string;
+    workspaceLabel?: string;
+    lifecycle?: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed' | 'interrupted';
+    recoveryState?: string | null;
+    cliType: string;
+    workspace: string;
+    cliArgs?: string[];
+}
+
 // ─── DaemonCliManager ────────────────────────────
 
 export class DaemonCliManager {
@@ -77,7 +100,29 @@ export class DaemonCliManager {
         }
     }
 
-    private createAdapter(cliType: string, workingDir: string, cliArgs?: string[]): CliAdapter {
+    private getTransportFactory(
+        runtimeId: string,
+        providerType: string,
+        workspace: string,
+        cliArgs?: string[],
+        attachExisting = false,
+    ): PtyTransportFactory | undefined {
+        return this.deps.createPtyTransportFactory?.({
+            runtimeId,
+            providerType,
+            workspace,
+            cliArgs,
+            attachExisting,
+        }) || undefined;
+    }
+
+    private createAdapter(
+        cliType: string,
+        workingDir: string,
+        cliArgs: string[] | undefined,
+        runtimeId: string,
+        attachExisting = false,
+    ): CliAdapter {
  // cliType normalize (Resolve alias)
         const normalizedType = this.providerLoader.resolveAlias(cliType);
 
@@ -86,12 +131,80 @@ export class DaemonCliManager {
         if (provider && provider.category === 'cli' && provider.patterns && provider.spawn) {
             console.log(chalk.cyan(`  📦 Using provider: ${provider.name} (${provider.type})`));
             const resolvedProvider = this.providerLoader.resolve(normalizedType) || provider;
-            return new ProviderCliAdapter(resolvedProvider as any, workingDir, cliArgs);
+            const transportFactory = this.getTransportFactory(runtimeId, normalizedType, workingDir, cliArgs, attachExisting);
+            return new ProviderCliAdapter(resolvedProvider as any, workingDir, cliArgs, transportFactory);
         }
 
         throw new Error(`No CLI provider found for '${cliType}'. Create a provider.js in providers/cli/${cliType}/`);
     }
 
+    private startCliExitMonitor(key: string, cliType: string): void {
+        const sessionRegistry = this.deps.getSessionRegistry?.() || null;
+        const instanceManager = this.deps.getInstanceManager();
+        const checkStopped = setInterval(() => {
+            try {
+                const adapter = this.adapters.get(key);
+                if (!adapter) { clearInterval(checkStopped); return; }
+                const status = adapter.getStatus?.();
+                if (status?.status === 'stopped' || status?.status === 'error') {
+                    clearInterval(checkStopped);
+                    setTimeout(() => {
+                        if (this.adapters.has(key)) {
+                            this.adapters.delete(key);
+                            this.deps.removeAgentTracking(key);
+                            sessionRegistry?.unregisterByInstanceKey(key);
+                            instanceManager?.removeInstance(key);
+                            LOG.info('CLI', `🧹 Auto-cleaned ${status.status} CLI: ${cliType}`);
+                            this.deps.onStatusChange();
+                        }
+                    }, 5000);
+                }
+            } catch { /* ignore */ }
+        }, 3000);
+    }
+
+    private async registerCliInstance(
+        key: string,
+        normalizedType: string,
+        cliType: string,
+        resolvedDir: string,
+        cliArgs: string[] | undefined,
+        provider: any,
+        settings: Record<string, any>,
+        attachExisting = false,
+    ): Promise<void> {
+        const instanceManager = this.deps.getInstanceManager();
+        const sessionRegistry = this.deps.getSessionRegistry?.() || null;
+        if (!instanceManager) throw new Error('InstanceManager not available');
+        const transportFactory = this.getTransportFactory(key, normalizedType, resolvedDir, cliArgs, attachExisting);
+        const cliInstance = new CliProviderInstance(provider, resolvedDir, cliArgs, key, transportFactory);
+        try {
+            await instanceManager.addInstance(key, cliInstance, {
+                serverConn: this.deps.getServerConn(),
+                settings,
+                onPtyData: (data: string) => {
+                    this.deps.getP2p()?.broadcastPtyOutput(cliInstance.instanceId, data);
+                },
+            });
+            sessionRegistry?.register({
+                sessionId: cliInstance.instanceId,
+                parentSessionId: null,
+                providerType: normalizedType,
+                providerCategory: 'cli',
+                transport: 'pty',
+                adapterKey: key,
+                instanceKey: key,
+            });
+        } catch (spawnErr: any) {
+            LOG.error('CLI', `[${cliType}] Spawn failed: ${spawnErr?.message}`);
+            instanceManager.removeInstance(key);
+            throw new Error(`Failed to start ${provider.displayName || provider.name || cliType}: ${spawnErr?.message}`);
+        }
+
+        this.adapters.set(key, cliInstance.getAdapter() as any);
+        this.startCliExitMonitor(key, cliType);
+    }
+
  // ─── Session start/management ──────────────────────────────
 
     async startSession(cliType: string, workingDir: string, cliArgs?: string[], initialModel?: string): Promise<void> {
@@ -197,59 +310,20 @@ export class DaemonCliManager {
         const instanceManager = this.deps.getInstanceManager();
         if (provider && instanceManager) {
             const resolvedProvider = this.providerLoader.resolve(cliType, { version: cliInfo.version }) || provider;
-            const cliInstance = new CliProviderInstance(resolvedProvider, resolvedDir, cliArgs, key);
-            try {
-                await instanceManager.addInstance(key, cliInstance, {
-                    serverConn: this.deps.getServerConn(),
-                    settings: {},
-                    onPtyData: (data: string) => {
-                        this.deps.getP2p()?.broadcastPtyOutput(cliInstance.instanceId, data);
-                    },
-                });
-                sessionRegistry?.register({
-                    sessionId: cliInstance.instanceId,
-                    parentSessionId: null,
-                    providerType: normalizedType,
-                    providerCategory: 'cli',
-                    transport: 'pty',
-                    adapterKey: key,
-                    instanceKey: key,
-                });
-            } catch (spawnErr: any) {
-                // Spawn failed — cleanup and propagate error
-                LOG.error('CLI', `[${cliType}] Spawn failed: ${spawnErr?.message}`);
-                instanceManager.removeInstance(key);
-                throw new Error(`Failed to start ${cliInfo.displayName}: ${spawnErr?.message}`);
-            }
-
- // Keep adapter ref too (backward compat — write, resize etc)
-            this.adapters.set(key, cliInstance.getAdapter() as any);
+            await this.registerCliInstance(
+                key,
+                normalizedType,
+                cliType,
+                resolvedDir,
+                cliArgs,
+                resolvedProvider,
+                {},
+                false,
+            );
             console.log(chalk.green(`  ✓ CLI started: ${cliInfo.displayName} v${cliInfo.version || 'unknown'} in ${resolvedDir}`));
-
-            // Monitor for stopped/error → auto-cleanup
-            const checkStopped = setInterval(() => {
-                try {
-                    const adapter = this.adapters.get(key);
-                    if (!adapter) { clearInterval(checkStopped); return; }
-                    const status = adapter.getStatus?.();
-                    if (status?.status === 'stopped' || status?.status === 'error') {
-                        clearInterval(checkStopped);
-                        setTimeout(() => {
-                            if (this.adapters.has(key)) {
-                                this.adapters.delete(key);
-                                this.deps.removeAgentTracking(key);
-                                sessionRegistry?.unregisterByInstanceKey(key);
-                                instanceManager.removeInstance(key);
-                                LOG.info('CLI', `🧹 Auto-cleaned ${status.status} CLI: ${cliType}`);
-                                this.deps.onStatusChange();
-                            }
-                        }, 5000);
-                    }
-                } catch { /* ignore */ }
-            }, 3000);
         } else {
  // Fallback: InstanceManager without directly adapter manage
-            const adapter = this.createAdapter(cliType, resolvedDir, cliArgs);
+            const adapter = this.createAdapter(cliType, resolvedDir, cliArgs, key, false);
             try {
                 await adapter.spawn();
             } catch (spawnErr: any) {
@@ -292,10 +366,18 @@ export class DaemonCliManager {
     }
 
     async stopSession(key: string): Promise<void> {
+        return this.stopSessionWithMode(key, 'hard');
+    }
+
+    async stopSessionWithMode(key: string, mode: 'hard' | 'save'): Promise<void> {
         const adapter = this.adapters.get(key);
         if (adapter) {
             try {
-                adapter.shutdown();
+                if (mode === 'save' && typeof adapter.saveAndStop === 'function') {
+                    await adapter.saveAndStop();
+                } else {
+                    adapter.shutdown();
+                }
             } catch (e: any) {
                 LOG.warn('CLI', `Shutdown error for ${adapter.cliType}: ${e?.message} (force-cleaning)`);
             }
@@ -324,6 +406,52 @@ export class DaemonCliManager {
         this.adapters.clear();
     }
 
+    detachAll(): void {
+        for (const adapter of this.adapters.values()) {
+            if (typeof adapter.detach === 'function') adapter.detach();
+            else adapter.shutdown();
+        }
+        this.adapters.clear();
+    }
+
+    async restoreHostedSessions(records?: HostedCliRuntimeDescriptor[]): Promise<number> {
+        const instanceManager = this.deps.getInstanceManager();
+        if (!instanceManager) return 0;
+        const sessions = records || await this.deps.listHostedCliRuntimes?.() || [];
+        let restored = 0;
+
+        for (const record of sessions) {
+            if (!record?.runtimeId || !record?.cliType || !record?.workspace) continue;
+            if (this.adapters.has(record.runtimeId) || instanceManager.getInstance(record.runtimeId)) continue;
+            const normalizedType = this.providerLoader.resolveAlias(record.cliType);
+            const providerMeta = this.providerLoader.getMeta(normalizedType);
+            if (!providerMeta || providerMeta.category !== 'cli') continue;
+
+            const resolvedProvider = this.providerLoader.resolve(normalizedType) || providerMeta;
+            try {
+                await this.registerCliInstance(
+                    record.runtimeId,
+                    normalizedType,
+                    record.cliType,
+                    record.workspace,
+                    record.cliArgs,
+                    resolvedProvider,
+                    {},
+                    true,
+                );
+                restored += 1;
+                LOG.info('CLI', `♻ Restored hosted runtime: ${record.runtimeKey || record.runtimeId} (${record.displayName || record.workspace})`);
+            } catch (error: any) {
+                LOG.warn('CLI', `Failed to restore hosted runtime ${record.runtimeId}: ${error?.message || error}`);
+            }
+        }
+
+        if (restored > 0) {
+            this.deps.onStatusChange();
+        }
+        return restored;
+    }
+
  // ─── Adapter search ─────────────────────────────
 
  /**
@@ -406,15 +534,16 @@ export class DaemonCliManager {
             case 'stop_cli': {
                 const cliType = args?.cliType;
                 const dir = args?.dir || '';
+                const mode = args?.mode === 'save' ? 'save' : 'hard';
                 if (!cliType) throw new Error('cliType required');
  // UUID session target based search priority
                 const found = this.findAdapter(cliType, { instanceKey: args?.targetSessionId, dir });
                 if (found) {
-                    await this.stopSession(found.key);
+                    await this.stopSessionWithMode(found.key, mode);
                 } else {
                     console.log(chalk.yellow(`  ⚠ No adapter found for ${cliType}`));
                 }
-                return { success: true, cliType, dir, stopped: true };
+                return { success: true, cliType, dir, stopped: true, mode };
             }
             case 'restart_session': {
                 const cliType = args?.cliType || args?.agentType || args?.ideType;

package/src/config/config.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ADHDev Launcher — Configuration
+ *
+ * Manages launcher config, server connection tokens, and user preferences.
+ */
+import type { WorkspaceEntry } from './workspaces.js';
+import type { WorkspaceActivityEntry } from './workspace-activity.js';
+export type { WorkspaceEntry } from './workspaces.js';
+export type { WorkspaceActivityEntry } from './workspace-activity.js';
+export interface ADHDevConfig {
+    serverUrl: string;
+    apiToken: string | null;
+    connectionToken: string | null;
+    selectedIde: string | null;
+    configuredIdes: string[];
+    installedExtensions: string[];
+    autoConnect: boolean;
+    /**
+     * @deprecated Not read at runtime. Notification preferences are now managed by:
+     * - Web UI layer: useNotificationPrefs (localStorage)
+     * - Daemon layer: per-provider settings (approvalAlert, longGeneratingAlert)
+     * Kept for backward config compat — will be removed in v0.7+.
+     */
+    notifications: boolean;
+    userEmail: string | null;
+    userName: string | null;
+    setupCompleted: boolean;
+    setupDate: string | null;
+    configuredCLIs: string[];
+    enabledIdes: string[];
+    recentCliWorkspaces: string[];
+    /** Saved workspaces for IDE/CLI/ACP launch (daemon-local) */
+    workspaces?: WorkspaceEntry[];
+    /** Default workspace id (from workspaces[]) — never used implicitly for launch */
+    defaultWorkspaceId?: string | null;
+    /** Recently used workspaces (IDE / CLI / ACP / default) for quick resume */
+    recentWorkspaceActivity?: WorkspaceActivityEntry[];
+    machineNickname: string | null;
+    /**
+     * Stable local machine ID (prefix: `mach_`) — generated locally on first run.
+     * Used as daemon instance key (`daemon_<machineId>`) and in status reports.
+     * NOT the same as the server-side D1 `machines.id` — see `registeredMachineId`.
+     */
+    machineId?: string;
+    machineSecret?: string | null;
+    /**
+     * Server-side D1 `machines.id` — the row ID assigned when daemon registers via
+     * `POST /cli/complete`. Corresponds to `machineId` in server DO context
+     * (`DaemonConnection.machineId`, `StatusContext.machineId`).
+     *
+     * Naming differs from server-side `machineId` to avoid confusion with the local
+     * `config.machineId` (mach_ prefix) which is a different value.
+     *
+     * @deprecated Legacy bridge field — will be removed after 2026-04-06.
+     * Modern auth flow uses `machineSecret` (adm_) to identify machines.
+     */
+    registeredMachineId?: string;
+    cliHistory: CliHistoryEntry[];
+    providerSettings: Record<string, Record<string, any>>;
+    ideSettings: Record<string, {
+        extensions?: Record<string, {
+            enabled: boolean;
+        }>;
+    }>;
+    disableUpstream?: boolean;
+    providerDir?: string;
+}
+export interface CliHistoryEntry {
+    category?: 'ide' | 'cli' | 'acp';
+    cliType: string;
+    dir: string;
+    cliArgs?: string[];
+    workspace?: string;
+    newWindow?: boolean;
+    model?: string;
+    timestamp: number;
+    label?: string;
+}
+export declare function generateMachineId(): string;
+export declare function isStableMachineId(machineId?: string | null): boolean;
+/**
+ * Get the config directory path
+ */
+export declare function getConfigDir(): string;
+/**
+ * Load configuration from disk
+ */
+export declare function loadConfig(): ADHDevConfig;
+/**
+ * Save configuration to disk
+ */
+export declare function saveConfig(config: ADHDevConfig): void;
+/**
+ * Update specific config fields
+ */
+export declare function updateConfig(updates: Partial<ADHDevConfig>): ADHDevConfig;
+/**
+ * Mark setup as completed
+ */
+export declare function markSetupComplete(ideId: string | string[], extensions: string[]): ADHDevConfig;
+/**
+ * Check if setup has been completed before
+ */
+export declare function isSetupComplete(): boolean;
+/**
+ * Reset configuration
+ */
+export declare function resetConfig(): void;
+/**
+ * Generate a connection token for server authentication
+ */
+export declare function generateConnectionToken(): string;
+/**
+ * Add launch to history (max 20, dedup by category+type+dir+args+workspace+model)
+ */
+export declare function addCliHistory(entry: Omit<CliHistoryEntry, 'timestamp'>): void;

package/src/config/workspace-activity.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Recent workspace activity — quick "pick up where you left off" (daemon-local).
+ */
+import type { ADHDevConfig } from './config.js';
+export interface WorkspaceActivityEntry {
+    path: string;
+    lastUsedAt: number;
+    /** `active` legacy — same meaning as default */
+    kind?: 'ide' | 'cli' | 'acp' | 'default' | 'active';
+    /** IDE id or CLI/ACP provider type */
+    agentType?: string;
+}
+export declare function normWorkspacePath(p: string): string;
+/**
+ * Append or bump a path to the front of recent activity (returns new config object).
+ */
+export declare function appendWorkspaceActivity(config: ADHDevConfig, rawPath: string, meta?: {
+    kind?: WorkspaceActivityEntry['kind'];
+    agentType?: string;
+}): ADHDevConfig;
+export declare function getWorkspaceActivity(config: ADHDevConfig, limit?: number): WorkspaceActivityEntry[];
+export declare function removeActivityForPath(config: ADHDevConfig, rawPath: string): ADHDevConfig;

package/src/config/workspaces.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Saved workspaces — shared by IDE launch, CLI, ACP (daemon-local).
+ */
+import type { ADHDevConfig } from './config.js';
+export interface WorkspaceEntry {
+    id: string;
+    path: string;
+    label?: string;
+    addedAt: number;
+}
+export declare function expandPath(p: string): string;
+export declare function validateWorkspacePath(absPath: string): {
+    ok: true;
+} | {
+    ok: false;
+    error: string;
+};
+/** Default workspace label from path */
+export declare function defaultWorkspaceLabel(absPath: string): string;
+/**
+ * Ensure config.workspaces exists; seed from recentCliWorkspaces once (same paths).
+ */
+export declare function migrateWorkspacesFromRecent(config: ADHDevConfig): ADHDevConfig;
+export declare function getDefaultWorkspacePath(config: ADHDevConfig): string | null;
+export declare function getWorkspaceState(config: ADHDevConfig): {
+    workspaces: WorkspaceEntry[];
+    defaultWorkspaceId: string | null;
+    defaultWorkspacePath: string | null;
+};
+export type LaunchDirectorySource = 'dir' | 'workspaceId' | 'defaultWorkspace' | 'home';
+export type ResolveLaunchDirectoryResult = {
+    ok: true;
+    path: string;
+    source: LaunchDirectorySource;
+} | {
+    ok: false;
+    code: 'WORKSPACE_LAUNCH_CONTEXT_REQUIRED';
+    message: string;
+};
+/**
+ * Resolve cwd for CLI/ACP. No implicit default workspace or home — caller must pass
+ * useDefaultWorkspace or useHome (or an explicit dir / workspaceId).
+ */
+export declare function resolveLaunchDirectory(args: {
+    dir?: string;
+    workspaceId?: string;
+    useDefaultWorkspace?: boolean;
+    useHome?: boolean;
+} | undefined, config: ADHDevConfig): ResolveLaunchDirectoryResult;
+/**
+ * IDE folder from explicit args only (`workspace`, `workspaceId`, or `useDefaultWorkspace: true`).
+ */
+export declare function resolveIdeWorkspaceFromArgs(args: {
+    workspace?: string;
+    workspaceId?: string;
+    useDefaultWorkspace?: boolean;
+} | undefined, config: ADHDevConfig): string | undefined;
+/**
+ * IDE launch folder — same saved workspaces + default as CLI/ACP.
+ * After explicit `workspace` / `workspaceId` / `useDefaultWorkspace: true`, falls back to
+ * config default workspace when set. Pass `useDefaultWorkspace: false` to open IDE without that folder.
+ */
+export declare function resolveIdeLaunchWorkspace(args: {
+    workspace?: string;
+    workspaceId?: string;
+    useDefaultWorkspace?: boolean;
+} | undefined, config: ADHDevConfig): string | undefined;
+export declare function findWorkspaceByPath(config: ADHDevConfig, rawPath: string): WorkspaceEntry | undefined;
+export declare function addWorkspaceEntry(config: ADHDevConfig, rawPath: string, label?: string): {
+    config: ADHDevConfig;
+    entry: WorkspaceEntry;
+} | {
+    error: string;
+};
+export declare function removeWorkspaceEntry(config: ADHDevConfig, id: string): {
+    config: ADHDevConfig;
+} | {
+    error: string;
+};
+export declare function setDefaultWorkspaceId(config: ADHDevConfig, id: string | null): {
+    config: ADHDevConfig;
+} | {
+    error: string;
+};