@feltdb/core 0.6.9 → 0.6.11

package/dist/cli/commands.js

@@ -7,9 +7,12 @@ import http from 'http';
 import net from 'net';
 import { createRequire } from 'module';
 import { spawn, spawnSync } from 'child_process';
-import { createFeltDB, diffFlowSpec, formatFlowSpec, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
+import { randomBytes } from 'crypto';
+import { createFeltDB, diffFlowSpec, formatFlowSpec, InvestigationLifecycleManager, parseFlowSpec, planFlowSpecMigration, startLocalDevelopmentAuthority, validateFlowSpec } from '@feltdb/core';
 import { discoverWorkspace, ensureWorkspaceGitIgnored, generatePairingToken, persistPairingToken, displayWorkspaceStatus, initializeWorkspace, startPairingDiscoveryServer } from './workspace-integration.js';
-import { detectApplication, discoverApplicationUrl } from './application.js';
+import { applicationUrlCandidate, detectApplication, discoverApplicationUrl } from './application.js';
+import { resolveApplicationLifecycle, startManagedApplication, waitForManagedApplication } from './application-lifecycle.js';
+import { createDevelopmentSession, developmentSessionEnvironment, developmentSessionSummary, transitionDevelopmentSession } from './development-session.js';
 function loadProjectEnvironment(file = path.resolve('.env.local')) {
     if (!fs.existsSync(file))
         return;
@@ -55,6 +58,8 @@ export async function handleCommand(command, args) {
             return handleWorkspace(args);
         case 'dev':
             return handleDev(args);
+        case 'investigations':
+            return handleInvestigations(args);
         case 'build':
             return handleBuild(args);
         case 'check':
@@ -76,6 +81,92 @@ export async function handleCommand(command, args) {
             return handleHelp();
     }
 }
+/**
+ * Inspect the durable investigation store.
+ *
+ * The evidence chain is only useful if a developer can get back to it after
+ * the browser is closed, so it is queryable from the command line.
+ */
+function handleInvestigations(args) {
+    if (args.includes('--help')) {
+        console.log('Usage: feltdb investigations [<investigation-id>] [--json]\n');
+        console.log('List durable runtime investigations, or show one in full.\n');
+        console.log('Options:');
+        console.log('  --json    Emit machine-readable JSON');
+        return;
+    }
+    const store = new InvestigationLifecycleManager(process.cwd());
+    const json = args.includes('--json');
+    const id = args.find(value => !value.startsWith('--'));
+    if (id) {
+        const investigation = store.loadInvestigation(id);
+        if (!investigation)
+            throw new Error(`Investigation not found: ${id}`);
+        if (json) {
+            console.log(JSON.stringify(investigation, null, 2));
+            return;
+        }
+        const observation = investigation.originalObservation;
+        console.log(`\nInvestigation ${investigation.id}`);
+        console.log(`  Workspace:    ${investigation.workspaceId}`);
+        console.log(`  Investigation ${investigation.investigationState}`);
+        console.log(`  Remediation:  ${investigation.remediationState}`);
+        console.log(`  Verification: ${investigation.verificationState}\n`);
+        if (observation) {
+            console.log('Observation');
+            console.log(`  ${observation.method} ${observation.url} -> HTTP ${observation.status}`);
+            console.log(`  ${observation.browser || 'unknown'} / ${observation.runtime || 'unknown'}`
+                + `${observation.durationMs !== undefined ? ` / ${observation.durationMs}ms` : ''}\n`);
+        }
+        if (investigation.evidence?.length) {
+            console.log('Evidence (observed by the runtime)');
+            for (const item of investigation.evidence)
+                console.log(`  [${item.kind}] ${item.statement}`);
+            console.log();
+        }
+        if (investigation.finding) {
+            console.log('Finding (FeltDB analysis, not an observation)');
+            console.log(`  ${investigation.finding.statement}`);
+            console.log(`  confidence: ${investigation.finding.confidence}\n`);
+        }
+        if (investigation.remediation?.changeIdentity) {
+            console.log('Remediation');
+            console.log(`  ${investigation.remediation.changeKind}: ${investigation.remediation.changeIdentity}`);
+            if (investigation.remediation.changedPaths.length) {
+                console.log(`  changed: ${investigation.remediation.changedPaths.join(', ')}`);
+            }
+            console.log();
+        }
+        if (investigation.verificationAttempt) {
+            const attempt = investigation.verificationAttempt;
+            console.log('Verification');
+            console.log(`  ${attempt.result}: ${attempt.summary}`);
+            console.log(`  ${attempt.originalStatus} -> ${attempt.observedStatus ?? 'no matching observation'}\n`);
+        }
+        return;
+    }
+    const investigations = store.listInvestigations();
+    if (json) {
+        console.log(JSON.stringify(investigations, null, 2));
+        return;
+    }
+    if (investigations.length === 0) {
+        console.log('\nNo investigations recorded.');
+        console.log('Run "feltdb dev", exercise the application, and a runtime defect will open one.\n');
+        return;
+    }
+    console.log(`\n${investigations.length} investigation${investigations.length === 1 ? '' : 's'}\n`);
+    for (const investigation of investigations) {
+        const observation = investigation.originalObservation;
+        const summary = observation
+            ? `${observation.method} ${observation.url} -> ${observation.status}`
+            : investigation.observationId;
+        console.log(`  ${investigation.id}  ${investigation.verificationState.padEnd(12)} ${summary}`);
+    }
+    const metrics = store.metrics();
+    console.log(`\n  ${metrics.observations} observations, ${metrics.evidenceRecords} evidence records, `
+        + `${metrics.serializedBytes} bytes, loaded in ${metrics.loadMilliseconds}ms\n`);
+}
 function flowFile(args) {
     const candidate = args.find(value => !value.startsWith('--')) || 'feltdb.flow';
     return path.resolve(candidate);
@@ -414,37 +505,30 @@ async function handleWorkspaceConnect(args) {
     console.log('   This feature will be implemented in the next phase');
     console.log('   (when @feltdb/client workspace APIs are available)\n');
 }
-function runLocalVite(args, waitForExit) {
-    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
-    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
-        cwd: process.cwd(),
-        stdio: 'inherit',
-        env: process.env,
-    });
-    if (!waitForExit)
-        return child;
-    return new Promise((resolve, reject) => {
-        child.once('error', reject);
-        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
-    });
-}
 async function handleDev(args) {
     var _a, _b, _c;
+    const projectDir = process.cwd();
     if (args.includes('--help')) {
-        console.log('Usage: feltdb dev [--app-url URL | --app-port PORT] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('Usage: feltdb dev [--app-url URL] [--studio-port 7701] [--authority-port 7700] [--discovery-port 7799] [--no-open]');
+        console.log('\nOptions:');
+        console.log('  --app-url <url>           Application URL (e.g., http://127.0.0.1:3000)');
+        console.log('  --studio-port <port>      FeltDB Studio port (default: 7701)');
+        console.log('  --authority-port <port>   Authority port (default: 7700)');
+        console.log('  --discovery-port <port>   Pairing discovery port (default: 7799)');
+        console.log('  --application-timeout <ms> Managed application readiness timeout (default: 15000)');
+        console.log('  --no-open                 Do not open Studio in browser');
         return;
     }
     loadProjectEnvironment();
     console.log('🚀 Starting FeltDB development server...\n');
-    const projectDir = process.cwd();
-    const configPath = path.join(projectDir, 'feltdb.config.json');
     // .feltdb/ is reserved local runtime state. Protect it before discovery,
     // initialization, the authority, or pairing can persist anything there.
+    // This runs after `--help` returns, so asking for help never writes anything.
     ensureWorkspaceGitIgnored(projectDir);
+    const configPath = path.join(projectDir, 'feltdb.config.json');
     // Initialize workspace if needed
     let workspace = discoverWorkspace(projectDir);
     if (!workspace) {
-        // Get project name from package.json
         const packageJsonPath = path.join(projectDir, 'package.json');
         let projectId = path.basename(projectDir);
         if (fs.existsSync(packageJsonPath)) {
@@ -460,31 +544,20 @@ async function handleDev(args) {
         console.log(`✨ Initialized Development Workspace`);
         console.log(`   Workspace ID: ${workspace.workspaceId}\n`);
     }
-    // Create feltdb.config.json if it doesn't exist
-    if (!fs.existsSync(configPath)) {
-        const packageJsonPath = path.join(projectDir, 'package.json');
-        let namespace = path.basename(projectDir);
-        if (fs.existsSync(packageJsonPath)) {
-            try {
-                const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
-                namespace = packageJson.name || namespace;
-            }
-            catch {
-                // Use default namespace if package.json parsing fails
-            }
-        }
-        const defaultConfig = {
-            namespace,
-            runtime: 'browser',
-            storage: 'indexeddb',
-            distributed: true,
-            agents: { enabled: false },
-            capabilities: { search: true },
-        };
-        fs.writeFileSync(configPath, JSON.stringify(defaultConfig, null, 2) + '\n');
-        console.log(`✨ Created feltdb.config.json with default configuration\n`);
-    }
-    const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    // Investigation lifecycle manager will be initialized when needed
+    // const investigationManager = new InvestigationLifecycleManager(projectDir);
+    // Existing applications may attach without adopting generated FeltDB source.
+    // Missing developer-owned config is resolved in memory and never written.
+    const configDefaults = {
+        namespace: workspace.projectId,
+        runtime: 'browser',
+        storage: 'indexeddb',
+        distributed: true,
+        applicationUrl: null,
+    };
+    const config = fs.existsSync(configPath)
+        ? { ...configDefaults, ...JSON.parse(fs.readFileSync(configPath, 'utf-8')) }
+        : configDefaults;
     if (config.runtime === 'managed') {
         (_a = process.env).VITE_FELTDB_URL || (_a.VITE_FELTDB_URL = process.env.VITE_FELTDB_MANAGED_URL);
         (_b = process.env).VITE_FELTDB_API_KEY || (_b.VITE_FELTDB_API_KEY = process.env.VITE_FELTDB_MANAGED_API_KEY);
@@ -495,17 +568,16 @@ async function handleDev(args) {
     const runtimeNamespace = config.runtime === 'managed'
         ? process.env.VITE_FELTDB_MANAGED_NAMESPACE || config.namespace
         : config.namespace;
-    const hasAppUrl = args.includes('--app-url');
-    const appUrlArgument = hasAppUrl ? args[args.indexOf('--app-url') + 1] : undefined;
-    if (hasAppUrl && !appUrlArgument)
+    const applicationLifecycle = resolveApplicationLifecycle(config);
+    // Application URL precedence:
+    // 1. --app-url (highest priority)
+    // 2. feltdb.config.json applicationUrl
+    // 3. Deterministically discovered running application
+    // 4. No application (lowest priority - allowed)
+    const hasAppUrlArg = args.includes('--app-url');
+    const appUrlArgument = hasAppUrlArg ? args[args.indexOf('--app-url') + 1] : undefined;
+    if (hasAppUrlArg && !appUrlArgument)
         throw new Error('--app-url requires a URL');
-    const hasAppPort = args.includes('--app-port') || args.includes('--port');
-    const appPortValue = args.includes('--app-port')
-        ? args[args.indexOf('--app-port') + 1]
-        : args.includes('--port') ? args[args.indexOf('--port') + 1] : undefined;
-    if (!hasAppUrl && hasAppPort && !appPortValue)
-        throw new Error('--app-port requires a port');
-    const appPort = appPortValue ? Number(appPortValue) : undefined;
     if (appUrlArgument) {
         try {
             const parsed = new URL(appUrlArgument);
@@ -516,31 +588,54 @@ async function handleDev(args) {
             throw new Error(`Invalid --app-url: ${appUrlArgument}`);
         }
     }
-    if (!hasAppUrl && appPortValue && (!Number.isInteger(appPort) || appPort < 1 || appPort > 65535))
-        throw new Error(`Invalid --app-port: ${appPortValue}`);
-    let discoveredApplication;
-    if (!hasAppUrl && !appPort) {
-        discoveredApplication = await discoverApplicationUrl(projectDir);
-    }
-    else {
+    let appUrl;
+    let detectedApplication;
+    // Priority 1: --app-url takes highest priority
+    if (appUrlArgument) {
+        appUrl = appUrlArgument;
         try {
-            discoveredApplication = { project: detectApplication(projectDir) };
+            detectedApplication = detectApplication(projectDir);
         }
         catch {
-            discoveredApplication = { project: { packageManager: 'npm', framework: 'External' } };
+            detectedApplication = { packageManager: 'npm', framework: 'External', feltDBEnabled: false, feltDBSignals: [] };
+        }
+    }
+    else {
+        // Priority 2: Check feltdb.config.json applicationUrl
+        if (config.applicationUrl) {
+            appUrl = config.applicationUrl;
+            try {
+                detectedApplication = detectApplication(projectDir);
+            }
+            catch {
+                detectedApplication = { packageManager: 'npm', framework: 'External', feltDBEnabled: false, feltDBSignals: [] };
+            }
+        }
+        else {
+            // Priority 3: Try to discover an existing running application
+            if (applicationLifecycle === 'managed') {
+                detectedApplication = detectApplication(projectDir);
+                appUrl = applicationUrlCandidate(detectedApplication);
+            }
+            else {
+                const discovered = await discoverApplicationUrl(projectDir);
+                detectedApplication = discovered.project;
+                appUrl = discovered.url;
+            }
         }
     }
-    const appUrl = appUrlArgument || (appPort ? `http://127.0.0.1:${appPort}` : discoveredApplication.url);
-    if (!appUrl) {
-        throw new Error('No application URL was detected.\nStart your application and run:\n  feltdb dev --app-url http://127.0.0.1:<port>\nOr configure applicationUrl in feltdb.config.json.');
+    if (detectedApplication?.feltDBEnabled) {
+        console.log(`Attaching existing FeltDB application (${detectedApplication.feltDBSignals.join(', ')})\n`);
     }
     const requestedStudioPort = Number(args.includes('--studio-port') ? args[args.indexOf('--studio-port') + 1] || '7701' : '7701');
     const studioPort = String(await availablePort(requestedStudioPort));
     if (studioPort !== String(requestedStudioPort))
-        console.log(`Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.`);
+        console.log(`⚠ Port ${requestedStudioPort} is busy; using ${studioPort} for Studio.\n`);
     process.env.STUDIO_PORT = studioPort;
     let selfHostedStarted = false;
     let localAuthority = null;
+    let managedApplication = null;
+    let developmentSession = null;
     const stopSelfHosted = () => {
         if (selfHostedStarted) {
             spawnSync('docker', ['compose', 'stop', 'feltdb'], { cwd: process.cwd(), stdio: 'ignore' });
@@ -570,62 +665,184 @@ async function handleDev(args) {
         });
         process.env.VITE_FELTDB_URL = localAuthority.endpoint;
     }
+    const authorityUrl = process.env.VITE_FELTDB_URL;
+    if (!authorityUrl)
+        throw new Error('Development session authority URL was not resolved');
+    const discoveryPort = Number(args.includes('--discovery-port') ? args[args.indexOf('--discovery-port') + 1] || '7799' : '7799');
+    developmentSession = createDevelopmentSession({
+        sessionId: `dev_${randomBytes(16).toString('hex')}`,
+        workspaceId: workspace.workspaceId,
+        projectId: workspace.projectId,
+        namespace: runtimeNamespace || config.namespace,
+        runtime: config.runtime,
+        storage: config.storage,
+        lifecycle: applicationLifecycle,
+        authorityUrl,
+        studioUrl: `http://127.0.0.1:${studioPort}`,
+        pairingUrl: `http://127.0.0.1:${discoveryPort}`,
+        applicationUrl: appUrl,
+    });
+    transitionDevelopmentSession(developmentSession, 'STARTING');
     // Generate pairing token for the workspace
     // This enables browsers and IDEs to discover and connect to the workspace
     let pairingToken = null;
     let pairingDiscoveryServer = null;
-    if (workspace) {
-        const token = generatePairingToken();
-        token.workspaceId = workspace.workspaceId;
-        token.endpoint = process.env.VITE_FELTDB_URL;
-        token.authorityEndpoint = token.endpoint;
-        token.namespace = runtimeNamespace || config.namespace;
-        if (!token.endpoint) {
-            throw new Error('Development Workspace pairing requires a FeltDB authority endpoint');
+    try {
+        if (workspace) {
+            const token = generatePairingToken();
+            token.workspaceId = developmentSession.workspaceId;
+            token.endpoint = developmentSession.authorityUrl;
+            token.authorityEndpoint = token.endpoint;
+            token.namespace = developmentSession.namespace;
+            if (!token.endpoint) {
+                throw new Error('Development Workspace pairing requires a FeltDB authority endpoint');
+            }
+            persistPairingToken(process.cwd(), token);
+            pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort, '127.0.0.1', {
+                sessionId: developmentSession.sessionId,
+                workspaceId: developmentSession.workspaceId,
+                namespace: developmentSession.namespace,
+                runtime: developmentSession.runtime,
+                authorityUrl: developmentSession.authorityUrl,
+                applicationUrl: developmentSession.applicationUrl,
+            });
+            const pairingAddress = pairingDiscoveryServer.address();
+            developmentSession.pairingUrl = `http://127.0.0.1:${pairingAddress.port}`;
+            pairingToken = token.token;
         }
-        persistPairingToken(process.cwd(), token);
-        const discoveryPort = Number(args.includes('--discovery-port') ? args[args.indexOf('--discovery-port') + 1] || '7799' : '7799');
-        pairingDiscoveryServer = await startPairingDiscoveryServer(token, discoveryPort);
-        pairingToken = token.token;
     }
-    console.log('FeltDB Dev Server');
-    console.log(`  Authority: ${process.env.VITE_FELTDB_URL}`);
-    console.log(`  Studio:    http://127.0.0.1:${studioPort}`);
-    console.log(`  Pairing:   http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
-    console.log('Application');
-    console.log(`  Framework: ${discoveredApplication.project.framework}`);
-    console.log('  Dev command: (managed externally)');
-    console.log(`  URL:       ${appUrl}`);
-    console.log(`  Namespace: ${config.namespace}`);
-    console.log(`  Runtime:   ${config.runtime}`);
-    console.log(`  Storage:   ${config.storage}`);
-    console.log(`  Distributed: ${config.distributed}`);
-    if (workspace) {
-        console.log(`  Workspace: ${workspace.workspaceId}\n`);
-        console.log(`🔗 Development Workspace`);
-        if (pairingToken) {
-            console.log(`  Pairing Code: ${pairingToken}`);
-            console.log(`  Pairing discovery: http://127.0.0.1:${(pairingDiscoveryServer?.address()).port}`);
-            console.log(`  Clients can use this code to auto-discover the workspace`);
+    catch (error) {
+        transitionDevelopmentSession(developmentSession, 'FAILED');
+        await localAuthority?.close();
+        stopSelfHosted();
+        throw error;
+    }
+    let stopping = null;
+    const stopAll = () => stopping ?? (stopping = (async () => {
+        if (developmentSession && developmentSession.state !== 'STOPPING' && developmentSession.state !== 'STOPPED') {
+            transitionDevelopmentSession(developmentSession, 'STOPPING');
         }
+        await managedApplication?.stop();
+        if (pairingDiscoveryServer?.listening) {
+            await new Promise(resolve => pairingDiscoveryServer.close(() => resolve()));
+        }
+        await localAuthority?.close();
+        stopSelfHosted();
+        if (developmentSession?.state === 'STOPPING')
+            transitionDevelopmentSession(developmentSession, 'STOPPED');
+    })());
+    process.once('exit', () => { void stopAll(); });
+    process.once('SIGINT', async () => { await stopAll(); process.exit(130); });
+    process.once('SIGTERM', async () => { await stopAll(); process.exit(143); });
+    if (applicationLifecycle === 'managed') {
+        try {
+            if (!detectedApplication)
+                detectedApplication = detectApplication(projectDir);
+            if (!appUrl) {
+                throw new Error(`Managed application lifecycle requires an expected application URL from --app-url, feltdb.config.json applicationUrl, FELTDB_APP_URL, or an explicit port in package.json.scripts.dev (workspace: ${workspace.workspaceId}; project: ${projectDir})`);
+            }
+            const timeoutArgument = args.includes('--application-timeout')
+                ? args[args.indexOf('--application-timeout') + 1]
+                : undefined;
+            const applicationTimeoutMs = timeoutArgument === undefined ? 15000 : Number(timeoutArgument);
+            if (!Number.isFinite(applicationTimeoutMs) || applicationTimeoutMs <= 0)
+                throw new Error('--application-timeout must be a positive number of milliseconds');
+            managedApplication = startManagedApplication({
+                projectDir,
+                project: detectedApplication,
+                environment: { ...process.env, ...developmentSessionEnvironment(developmentSession) },
+            });
+            console.log(`Starting managed application: ${managedApplication.command}`);
+            await waitForManagedApplication({ application: managedApplication, expectedUrl: appUrl, timeoutMs: applicationTimeoutMs, workspaceId: workspace.workspaceId, projectDir });
+            console.log(`Managed application ready: ${appUrl}\n`);
+        }
+        catch (error) {
+            transitionDevelopmentSession(developmentSession, 'FAILED');
+            await stopAll();
+            throw error;
+        }
+    }
+    // Output startup information
+    console.log('✨ Development Workspace');
+    if (workspace) {
+        console.log(`   Workspace ID: ${workspace.workspaceId}`);
     }
     console.log();
+    console.log('🔗 Development Workspace');
+    if (pairingToken) {
+        console.log(`   Pairing Code: ${pairingToken}`);
+        console.log(`   Pairing discovery: ${developmentSession.pairingUrl}`);
+    }
+    console.log();
+    console.log('FeltDB Dev Server');
+    console.log(`  Namespace:   ${developmentSession.namespace}`);
+    console.log(`  Runtime:     ${developmentSession.runtime}`);
+    console.log(`  Storage:     ${developmentSession.storage}`);
+    console.log(`  Distributed: ${config.distributed}`);
+    console.log(`  Application: ${applicationLifecycle}`);
+    console.log();
+    if (appUrl) {
+        console.log(`Application: ${appUrl}`);
+        console.log(`Authority: ${developmentSession.authorityUrl}`);
+        console.log();
+        console.log(`Using existing application at ${appUrl}`);
+        console.log(`app=${encodeURIComponent(appUrl)}\n`);
+    }
+    else {
+        console.log('❌ No application URL is configured.\n');
+        console.log('Start your application, then run:\n');
+        console.log('  feltdb dev --app-url http://127.0.0.1:<port>\n');
+        console.log('Or set applicationUrl in feltdb.config.json\n');
+        console.log('FeltDB workspace is ready at:');
+        console.log('Authority: ' + developmentSession.authorityUrl);
+        console.log('Studio:    ' + developmentSession.studioUrl);
+        console.log();
+    }
     const open = !args.includes('--no-open');
-    console.log(`Application: ${appUrl}`);
-    console.log(`Studio:      http://127.0.0.1:${studioPort}\n`);
-    console.log(`Using existing application at ${appUrl}\n`);
-    const stopAll = () => { pairingDiscoveryServer?.close(); void localAuthority?.close(); stopSelfHosted(); };
-    process.once('exit', stopAll);
-    process.once('SIGINT', () => { stopAll(); process.exit(130); });
-    process.once('SIGTERM', () => { stopAll(); process.exit(143); });
-    await handleStudio([
-        '--port', studioPort,
-        '--namespace', runtimeNamespace || 'default',
-        '--runtime', config.runtime || 'browser',
-        '--app-url', appUrl,
-        ...((config.runtime === 'self-hosted' || config.runtime === 'managed') && process.env.VITE_FELTDB_URL ? ['--connect', process.env.VITE_FELTDB_URL] : []),
-        ...(open ? [] : ['--no-open']),
-    ]);
+    try {
+        const studio = handleStudio([
+            '--port', studioPort,
+            '--namespace', developmentSession.namespace,
+            '--runtime', developmentSession.runtime,
+            '--workspace-id', developmentSession.workspaceId,
+            '--session-id', developmentSession.sessionId,
+            '--project-id', developmentSession.projectId,
+            '--authority-url', developmentSession.authorityUrl,
+            '--pairing-url', developmentSession.pairingUrl,
+            '--lifecycle', developmentSession.lifecycle,
+            ...(developmentSession.applicationUrl ? ['--app-url', developmentSession.applicationUrl] : []),
+            ...((developmentSession.runtime === 'self-hosted' || developmentSession.runtime === 'managed') ? ['--connect', developmentSession.authorityUrl] : []),
+            ...(open ? [] : ['--no-open']),
+        ], () => {
+            transitionDevelopmentSession(developmentSession, 'READY');
+            console.log(`\n${developmentSessionSummary(developmentSession)}\n`);
+            transitionDevelopmentSession(developmentSession, 'RUNNING');
+        });
+        if (managedApplication) {
+            await Promise.race([studio, managedApplication.exited.then(exit => {
+                    throw new Error(`Managed application stopped during the development session (command: ${managedApplication.command}; exit: ${exit.code ?? exit.signal})`);
+                })]);
+        }
+        else
+            await studio;
+    }
+    finally {
+        await stopAll();
+    }
+}
+function runLocalVite(args, waitForExit) {
+    const executable = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const child = spawn(executable, ['exec', '--', 'vite', ...args], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        env: process.env,
+    });
+    if (!waitForExit)
+        return child;
+    return new Promise((resolve, reject) => {
+        child.once('error', reject);
+        child.once('exit', code => code === 0 ? resolve() : reject(new Error(`Vite exited with status ${code ?? 'unknown'}`)));
+    });
 }
 async function handleBuild(args) {
     console.log('🔨 Building FeltDB application...\n');
@@ -867,7 +1084,7 @@ async function handleDoctor() {
     }
     console.log('\n✅ System healthy\n');
 }
-async function handleStudio(args) {
+async function handleStudio(args, onReady) {
     const connectUrl = args.includes('--connect')
         ? args[args.indexOf('--connect') + 1]
         : undefined;
@@ -887,6 +1104,19 @@ async function handleStudio(args) {
     const appUrl = args.includes('--app-url')
         ? args[args.indexOf('--app-url') + 1]
         : undefined;
+    const sessionValue = (name) => args.includes(name) ? args[args.indexOf(name) + 1] : undefined;
+    const session = {
+        sessionId: sessionValue('--session-id'),
+        workspaceId: sessionValue('--workspace-id'),
+        projectId: sessionValue('--project-id'),
+        authorityUrl: sessionValue('--authority-url'),
+        pairingUrl: sessionValue('--pairing-url'),
+        lifecycle: sessionValue('--lifecycle'),
+        namespace,
+        runtime,
+        applicationUrl: appUrl,
+        bridgeUrl: sessionValue('--pairing-url'),
+    };
     if (connectUrl) {
         console.log(`Connecting to: ${connectUrl}`);
         console.log(`Remote Studio: http://localhost:${port}\n`);
@@ -897,19 +1127,21 @@ async function handleStudio(args) {
     const require = createRequire(import.meta.url);
     const packageFile = require.resolve('@feltdb/core/package.json');
     const root = path.join(path.dirname(packageFile), 'dist', 'studio-app');
+    if (!fs.existsSync(path.join(root, 'index.html'))) {
+        console.log('⚠️  Studio application artifacts not found.');
+        return;
+    }
     const projectFlow = ['feltdb.flow', ...fs.readdirSync(process.cwd()).filter(value => value.endsWith('.flow'))]
         .map(value => path.resolve(process.cwd(), value))
         .find((value, index, values) => values.indexOf(value) === index && fs.existsSync(value));
-    if (!fs.existsSync(path.join(root, 'index.html')))
-        throw new Error('Studio application artifact is missing; reinstall @feltdb/core');
     const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.json': 'application/json' };
-    const server = http.createServer((request, response) => {
+    const server = http.createServer(async (request, response) => {
         const pathname = decodeURIComponent(new URL(request.url || '/', 'http://localhost').pathname);
         if (pathname === '/_feltdb/config') {
             response.setHeader('Content-Type', 'application/json; charset=utf-8');
             response.setHeader('Cache-Control', 'no-store');
             response.setHeader('Pragma', 'no-cache');
-            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '' }));
+            response.end(JSON.stringify({ token: connectUrl ? process.env.VITE_FELTDB_API_KEY || '' : '', session }));
             return;
         }
         if (pathname === '/_feltdb/project') {
@@ -923,6 +1155,52 @@ async function handleStudio(args) {
             response.end(JSON.stringify({ namespace, filename: path.basename(projectFlow), source: fs.readFileSync(projectFlow, 'utf8') }));
             return;
         }
+        if (pathname === '/_feltdb/runtime') {
+            if (!session.bridgeUrl || !session.sessionId) {
+                response.statusCode = 404;
+                response.end('No development session');
+                return;
+            }
+            try {
+                const upstream = await fetch(`${session.bridgeUrl}/api/v1/development/runtimes?sessionId=${encodeURIComponent(session.sessionId)}`);
+                response.statusCode = upstream.status;
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.setHeader('Cache-Control', 'no-store');
+                response.end(await upstream.text());
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: String(error) }));
+            }
+            return;
+        }
+        if (pathname === '/_feltdb/observations') {
+            if (!session.bridgeUrl || !session.sessionId) {
+                response.statusCode = 404;
+                response.end('No development session');
+                return;
+            }
+            const query = new URL(request.url || '/', 'http://localhost').searchParams;
+            const runtimeInstanceId = query.get('runtimeInstanceId');
+            if (!runtimeInstanceId) {
+                response.statusCode = 400;
+                response.end('runtimeInstanceId is required');
+                return;
+            }
+            const parameters = new URLSearchParams({ sessionId: session.sessionId, limit: query.get('limit') || '100', cursor: query.get('cursor') || '0' });
+            try {
+                const upstream = await fetch(`${session.bridgeUrl}/api/v1/development/runtime/${encodeURIComponent(runtimeInstanceId)}/observations?${parameters}`);
+                response.statusCode = upstream.status;
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.setHeader('Cache-Control', 'no-store');
+                response.end(await upstream.text());
+            }
+            catch (error) {
+                response.statusCode = 503;
+                response.end(JSON.stringify({ error: String(error) }));
+            }
+            return;
+        }
         const requested = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
         const candidate = path.resolve(root, requested);
         const file = candidate.startsWith(`${path.resolve(root)}${path.sep}`) && fs.existsSync(candidate) && fs.statSync(candidate).isFile() ? candidate : path.join(root, 'index.html');
@@ -936,9 +1214,18 @@ async function handleStudio(args) {
         parameters.set('connect', connectUrl);
     if (appUrl)
         parameters.set('app', appUrl);
+    if (session.workspaceId)
+        parameters.set('workspace', session.workspaceId);
+    if (session.sessionId)
+        parameters.set('session', session.sessionId);
+    if (session.authorityUrl)
+        parameters.set('authority', session.authorityUrl);
+    if (session.pairingUrl)
+        parameters.set('pairing', session.pairingUrl);
     const query = `?${parameters.toString()}`;
     const studioUrl = `http://127.0.0.1:${port}/${query}`;
     console.log(`FeltDB Studio ready at ${studioUrl}`);
+    onReady?.();
     console.log('Use Ctrl+C to stop the server.');
     if (open) {
         const command = process.platform === 'darwin' ? ['open', studioUrl] : process.platform === 'win32' ? ['cmd', '/c', 'start', '', studioUrl] : ['xdg-open', studioUrl];
@@ -964,6 +1251,7 @@ Commands:
   connect              Connect to remote FeltDB
   status               Show connection status
   dev                  Start development server
+  investigations       List or show durable runtime investigations
   build                Build FeltDB application
   check                Validate configuration
   inspect              Inspect runtime state