@hs-x/cli 0.3.7 → 0.4.0

package/dist/commands/dev.js

@@ -1,7 +1,9 @@
+import { spawn } from 'node:child_process';
 import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, openSync } from 'node:fs';
 import { readFile, readdir, stat } from 'node:fs/promises';
 import { createServer } from 'node:http';
-import { join } from 'node:path';
+import { join, resolve as resolvePath } from 'node:path';
 import * as Args from '@effect/cli/Args';
 import * as Command from '@effect/cli/Command';
 import * as Options from '@effect/cli/Options';
@@ -13,13 +15,20 @@ import { cwdOption, jsonOption, runHandler, runQuarantined } from '../cli/kit.js
 import { formatConfigUrl, loadCliConfig } from '../config.js';
 import { CLI_VERSION } from '../constants.js';
 import { controlPlaneAuthHeaders } from '../control-plane-fetch.js';
+import { selectHubSpotDirectDevAccounts } from '../dev/account-selection.js';
+import { listHubSpotDevComponentCandidates, resolveHubSpotDevComponentSelectors, } from '../dev/component-selection.js';
+import { createManagedDevEventWriter, createManagedDevSession, markManagedDevSessionReady, markManagedDevSessionState, prepareManagedDevSessionRestart, publicManagedDevSession, readManagedDevEvents, readManagedDevSession, reconcileManagedDevSession, setManagedDevSessionPid, stopManagedDevSessionProcess, waitForManagedDevSessionOwner, } from '../dev/managed-session.js';
+import { findListeningProcess, isHubSpotDevPortConflict, stopProcessCommand, terminateProcessGracefully, } from '../dev/port-process.js';
 import { executeCliHttp } from '../effect-http.js';
+import { discoverHubSpotAccounts, exchangePak } from '../hubspot-auth.js';
+import { detectLocalProjectMode, validateHubSpotProject } from '../hubspot-project.js';
 import { LocalProjectPickerCancelled, resolveLocalProject } from '../local-project-picker.js';
 import { requestMutationConsent } from '../mutation-consent.js';
 import { isMachineOutput } from '../output-context.js';
 import { isInteractive, promptConfirm, promptMultiSelect, promptSelect } from '../prompt.js';
 import { createReporter } from '../reporter/index.js';
 import { Cwd } from '../services/cwd.js';
+import { Reporter as ReporterService } from '../services/reporter.js';
 async function hostedHttp(input) {
     const headers = { ...(input.headers ?? {}) };
     let request = HttpClientRequest.make(input.method ?? 'GET')(input.url).pipe(HttpClientRequest.setHeaders(headers));
@@ -35,6 +44,21 @@ function isRecord(value) {
 function isErrnoException(value) {
     return value instanceof Error && typeof value.code === 'string';
 }
+function describeDevSessionFailure(cause) {
+    const error = isRecord(cause) ? cause : undefined;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const status = typeof error?.status === 'number' ? `HTTP ${error.status}` : undefined;
+    const data = isRecord(error?.data) ? error.data : undefined;
+    const responseMessage = typeof data?.message === 'string' ? data.message : undefined;
+    const validationErrors = Array.isArray(error?.validationErrors)
+        ? error.validationErrors.filter((item) => typeof item === 'string')
+        : [];
+    const correlationId = typeof error?.correlationId === 'string' ? `correlation ${error.correlationId}` : undefined;
+    return [...new Set([message, status, responseMessage, ...validationErrors, correlationId])]
+        .filter((item) => Boolean(item))
+        .join(' · ');
+}
+const HUBSPOT_UI_DEV_PORT = 5173;
 function makeDevLogPaint(env, stderr) {
     const isTTY = Boolean(stderr.isTTY);
     const color = isTTY && env.NO_COLOR !== '1';
@@ -179,7 +203,512 @@ async function resolveDefaultPortalId(input) {
     }
     return undefined;
 }
-export async function devCommand({ argv, root, json, }) {
+async function recoverHubSpotDevPort(input) {
+    const listener = await findListeningProcess(HUBSPOT_UI_DEV_PORT);
+    if (!listener)
+        return { kind: 'none' };
+    const summary = `Port ${listener.port} is held by PID ${listener.pid}${listener.command ? ` (${listener.command})` : ''}.`;
+    const recovery = stopProcessCommand(listener.pid);
+    if (input.json) {
+        write(`${JSON.stringify({
+            schema_version: 1,
+            command: 'dev',
+            ok: false,
+            error: {
+                code: 'HSX_E_DEV_PORT_IN_USE',
+                message: summary,
+                process: listener,
+                recovery,
+            },
+        }, null, 2)}\n`);
+        return { kind: 'exit', result: { exitCode: 1 } };
+    }
+    input.reporter.header('HubSpot dev server already running');
+    input.reporter.rows([
+        { key: 'port', value: String(listener.port), status: 'warn' },
+        { key: 'pid', value: String(listener.pid) },
+        ...(listener.cwd ? [{ key: 'directory', value: listener.cwd }] : []),
+        ...(listener.command ? [{ key: 'command', value: listener.command }] : []),
+    ]);
+    if (!isInteractive()) {
+        input.reporter.error('HSX_E_DEV_PORT_IN_USE', summary, {
+            hint: `Stop that exact process with \`${recovery}\`, or rerun in an interactive terminal to confirm and retry automatically.`,
+            docs_url: 'https://hs-x.dev/errors/HSX_E_DEV_PORT_IN_USE',
+        });
+        input.reporter.done(undefined, 1);
+        return { kind: 'exit', result: { exitCode: 1 } };
+    }
+    const confirmed = await promptConfirm({
+        message: `Stop PID ${listener.pid} and retry this dev session?`,
+        default: false,
+    });
+    if (confirmed === undefined) {
+        return { kind: 'exit', result: cancelledResult(input.argv, 'dev') };
+    }
+    if (!confirmed) {
+        input.reporter.info(`Left PID ${listener.pid} running.`);
+        input.reporter.done('Dev session not started', 1);
+        return { kind: 'exit', result: { exitCode: 1 } };
+    }
+    const step = input.reporter.step(`Stopping PID ${listener.pid}`);
+    const stopped = await terminateProcessGracefully(listener.pid);
+    if (!stopped.ok) {
+        step.warn(stopped.message ?? 'could not stop process');
+        input.reporter.error('HSX_E_DEV_PORT_IN_USE', `Could not stop PID ${listener.pid}; it was left running.`, { hint: `Stop it manually with \`${recovery}\`, then retry.` });
+        input.reporter.done(undefined, 1);
+        return { kind: 'exit', result: { exitCode: 1 } };
+    }
+    step.ok('stopped; retrying');
+    return { kind: 'stopped' };
+}
+async function hubSpotDirectDevCommand({ argv, root, json, }) {
+    const reporter = createReporter({ command: 'dev', argv, entry: !json });
+    const profile = resolveFlag(argv, '--profile');
+    const validation = await validateHubSpotProject({ root, ...(profile ? { profile } : {}) });
+    if (!validation.ok) {
+        const result = {
+            ok: false,
+            command: 'dev',
+            mode: 'hubspot-direct',
+            error: 'HubSpot project validation failed.',
+            diagnostics: validation.diagnostics,
+        };
+        if (json)
+            write(`${JSON.stringify(result, null, 2)}\n`);
+        else {
+            reporter.header('HubSpot direct');
+            reporter.rows(validation.diagnostics.map((diagnostic) => ({
+                key: diagnostic.code,
+                value: diagnostic.message,
+                status: diagnostic.severity === 'error' ? 'fail' : 'warn',
+                ...(diagnostic.file ? { detail: diagnostic.file } : {}),
+            })));
+            reporter.done('Validation failed', 1);
+        }
+        return { exitCode: 1 };
+    }
+    const discovered = await discoverHubSpotAccounts(root);
+    const accounts = discovered?.accounts ?? [];
+    const requestedProjectAccount = resolveFlag(argv, '--project-account') ??
+        resolveFlag(argv, '--account') ??
+        resolveFlag(argv, '--portal');
+    const requestedTestingAccount = resolveFlag(argv, '--testing-account');
+    const { projectAccount, testingAccount: selectedTestingAccount } = selectHubSpotDirectDevAccounts({
+        accounts,
+        ...(requestedProjectAccount ? { requestedProjectAccount } : {}),
+        ...(requestedTestingAccount ? { requestedTestingAccount } : {}),
+    });
+    if (requestedProjectAccount && !projectAccount) {
+        const message = `HubSpot project account "${requestedProjectAccount}" is not configured. Run \`hs account list\` or pass a configured --project-account.`;
+        if (json) {
+            write(`${JSON.stringify({
+                schema_version: 1,
+                command: 'dev',
+                ok: false,
+                error: { code: 'HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message },
+            }, null, 2)}\n`);
+        }
+        else {
+            reporter.error('HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message);
+            reporter.done(undefined, 1);
+        }
+        return { exitCode: 1 };
+    }
+    if (!projectAccount) {
+        const message = 'HubSpot-direct dev needs an authenticated HubSpot project account. Run `hs account auth`, select a default with `hs account use`, or pass --project-account.';
+        if (json) {
+            write(`${JSON.stringify({
+                schema_version: 1,
+                command: 'dev',
+                ok: false,
+                error: { code: 'HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message },
+            }, null, 2)}\n`);
+        }
+        else {
+            reporter.error('HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message);
+            reporter.done(undefined, 1);
+        }
+        return { exitCode: 1 };
+    }
+    if (requestedTestingAccount && !selectedTestingAccount) {
+        const message = `HubSpot testing account "${requestedTestingAccount}" is not configured. Run \`hs account list\` or pass a configured --testing-account.`;
+        if (json) {
+            write(`${JSON.stringify({
+                schema_version: 1,
+                command: 'dev',
+                ok: false,
+                error: { code: 'HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message },
+            }, null, 2)}\n`);
+        }
+        else {
+            reporter.error('HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message);
+            reporter.done(undefined, 1);
+        }
+        return { exitCode: 1 };
+    }
+    const testingAccount = selectedTestingAccount ?? projectAccount;
+    if (testingAccount.personalAccessKey) {
+        try {
+            const exchanged = await exchangePak(testingAccount.personalAccessKey);
+            if (exchanged.portalId !== testingAccount.portalId) {
+                throw new Error(`the configured PAK belongs to account ${exchanged.portalId}, not ${testingAccount.portalId}`);
+            }
+        }
+        catch (cause) {
+            const message = `HubSpot testing account ${testingAccount.name} (${testingAccount.portalId}) needs fresh authentication: ${cause instanceof Error ? cause.message : String(cause)} Run \`hs account auth\` for that account, then retry.`;
+            if (json) {
+                write(`${JSON.stringify({
+                    schema_version: 1,
+                    command: 'dev',
+                    ok: false,
+                    error: { code: 'HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message },
+                }, null, 2)}\n`);
+            }
+            else {
+                reporter.error('HSX_E_DEV_SESSION_NO_HUBSPOT_ACCOUNT', message);
+                reporter.done(undefined, 1);
+            }
+            return { exitCode: 1 };
+        }
+    }
+    // Check the fixed HubSpot UI-extension port before translating the project;
+    // otherwise a conflict is discovered only after the comparatively expensive
+    // IR probe/build path has already run.
+    const existingDevServer = await recoverHubSpotDevPort({ argv, json, reporter });
+    if (existingDevServer.kind === 'exit')
+        return existingDevServer.result;
+    const uiExtensionNodes = await probeHubSpotUiNodes({
+        root,
+        portalIdFlag: String(projectAccount.portalId),
+        accountId: undefined,
+        ...(profile ? { profile } : {}),
+    });
+    const requestedComponents = resolveFlags(argv, '--component');
+    const resolvedComponents = resolveHubSpotDevComponentSelectors(uiExtensionNodes?.candidates ?? [], requestedComponents);
+    if (!resolvedComponents.ok) {
+        if (json) {
+            write(`${JSON.stringify({
+                schema_version: 1,
+                command: 'dev',
+                ok: false,
+                error: { code: 'HSX_E_DEV_SESSION_NO_NODES', message: resolvedComponents.message },
+            }, null, 2)}\n`);
+        }
+        else {
+            reporter.error('HSX_E_DEV_SESSION_NO_NODES', resolvedComponents.message);
+            reporter.done(undefined, 1);
+        }
+        return { exitCode: 1 };
+    }
+    let selectedNodeUids = uiExtensionNodes && uiExtensionNodes.candidates.length > 0
+        ? resolvedComponents.uids
+        : undefined;
+    if (requestedComponents.length === 0 &&
+        uiExtensionNodes &&
+        uiExtensionNodes.candidates.length > 1 &&
+        !json &&
+        isInteractive()) {
+        const picked = await promptMultiSelect({
+            message: `Which HubSpot components should run in dev mode? (testing account ${testingAccount.portalId})`,
+            initial: [],
+            minSelected: 1,
+            options: uiExtensionNodes.candidates.map((candidate) => ({
+                value: candidate.uid,
+                label: candidate.label,
+                description: candidate.description,
+            })),
+        });
+        if (picked === undefined)
+            return cancelledResult(argv, 'dev');
+        selectedNodeUids = picked;
+    }
+    let directDevLogStream;
+    if (!json) {
+        const hsxLogPortValue = resolveFlag(argv, '--hsx-log-port') ?? '9099';
+        const hsxLogPort = Number(hsxLogPortValue);
+        if (!Number.isInteger(hsxLogPort) || hsxLogPort < 1 || hsxLogPort > 65535) {
+            const code = 'HSX_E_INPUT_BAD_FIELD';
+            reporter.error(code, `--hsx-log-port must be an integer between 1 and 65535 (got \`${hsxLogPortValue}\`).`, {
+                hint: 'Example: hs-x dev --hsx-log-port 9099',
+                docs_url: `https://hs-x.dev/errors/${code}`,
+            });
+            reporter.done(undefined, 10);
+            return { exitCode: 10 };
+        }
+        const { parseOnlySelectors } = await import('../dev/stream-filter.js');
+        const onlyParsed = parseOnlySelectors(resolveFlags(argv, '--only'));
+        if (!onlyParsed.ok) {
+            const code = 'HSX_E_DEV_BAD_ONLY';
+            reporter.error(code, onlyParsed.message, {
+                hint: 'Selectors: frontend, hubspot, errors, warnings, or free text. Repeat --only to combine.',
+                docs_url: `https://hs-x.dev/errors/${code}`,
+            });
+            reporter.done(undefined, 2);
+            return { exitCode: 2 };
+        }
+        const managedSessionId = resolveFlag(argv, '--managed-session');
+        directDevLogStream = await startHsxDevLogStream({
+            port: hsxLogPort,
+            root,
+            reporter,
+            filter: onlyParsed.filter,
+            ...(managedSessionId ? { managedSessionId } : {}),
+        });
+    }
+    const { startDevSession } = await import('../dev/session-manager.js');
+    const startDirectSession = () => startDevSession({
+        projectAccountId: projectAccount.portalId,
+        testingAccountId: testingAccount.portalId,
+        projectDir: root,
+        ...(selectedNodeUids ? { selectedNodeUids } : {}),
+        ...(profile ? { profile } : {}),
+        ...(directDevLogStream
+            ? {
+                onFrontendLog: (entry) => {
+                    directDevLogStream?.bus.emit({
+                        lane: 'frontend',
+                        level: entry.level,
+                        ts: entry.ts,
+                        msg: entry.msg,
+                        ...(entry.source ? { source: entry.source } : {}),
+                        ...(entry.fields ? { fields: entry.fields } : {}),
+                    });
+                },
+                onBackendLog: (entry) => {
+                    directDevLogStream?.bus.emit({
+                        lane: 'backend',
+                        level: entry.level,
+                        ts: Date.now(),
+                        msg: entry.message,
+                        source: `console.${entry.method}`,
+                    });
+                },
+            }
+            : {}),
+    });
+    let session;
+    let sessionFailure;
+    try {
+        session = await startDirectSession();
+    }
+    catch (initialCause) {
+        sessionFailure = initialCause;
+        if (isHubSpotDevPortConflict(initialCause)) {
+            const recovery = await recoverHubSpotDevPort({ argv, json, reporter });
+            if (recovery.kind === 'exit') {
+                try {
+                    await directDevLogStream?.cleanup();
+                }
+                catch {
+                    // The port-conflict response is already complete.
+                }
+                return recovery.result;
+            }
+            if (recovery.kind === 'stopped') {
+                try {
+                    session = await startDirectSession();
+                    sessionFailure = undefined;
+                }
+                catch (retryCause) {
+                    sessionFailure = retryCause;
+                }
+            }
+        }
+    }
+    if (!session) {
+        if (directDevLogStream) {
+            try {
+                await directDevLogStream.cleanup();
+            }
+            catch {
+                // The dev-session error below is the actionable failure.
+            }
+        }
+        const message = describeDevSessionFailure(sessionFailure);
+        if (json) {
+            write(`${JSON.stringify({
+                schema_version: 1,
+                command: 'dev',
+                ok: false,
+                error: { code: 'HSX_E_DEV_SESSION_REGISTER', message },
+            }, null, 2)}\n`);
+        }
+        else {
+            reporter.error('HSX_E_DEV_SESSION_REGISTER', message);
+            reporter.done(undefined, 1);
+        }
+        return { exitCode: 1 };
+    }
+    const managedSessionId = resolveFlag(argv, '--managed-session');
+    if (managedSessionId) {
+        await markManagedDevSessionReady(managedSessionId, {
+            projectAccountId: projectAccount.portalId,
+            testingAccountId: testingAccount.portalId,
+            components: session.nodeUids,
+            ...(directDevLogStream
+                ? { logPort: Number(resolveFlag(argv, '--hsx-log-port') ?? '9099') }
+                : {}),
+        });
+    }
+    const started = {
+        ok: true,
+        command: 'dev',
+        mode: 'hubspot-direct',
+        portalId: testingAccount.portalId,
+        projectAccountId: projectAccount.portalId,
+        testingAccountId: testingAccount.portalId,
+        sessionId: session.sessionId,
+        components: session.nodeUids,
+        controlPlaneUsed: false,
+        cloudflareUsed: false,
+    };
+    if (json)
+        write(`${JSON.stringify(started, null, 2)}\n`);
+    else {
+        reporter.header(`${projectAccount.name} → ${testingAccount.name}`);
+        reporter.rows([
+            { key: 'mode', value: 'HubSpot direct' },
+            { key: 'project-account', value: `${projectAccount.name} (${projectAccount.portalId})` },
+            { key: 'testing-account', value: `${testingAccount.name} (${testingAccount.portalId})` },
+            { key: 'ui-extensions', value: `session ${session.sessionId}`, status: 'ok' },
+            { key: 'components', value: String(session.nodeUids.length) },
+            ...(directDevLogStream
+                ? [
+                    {
+                        key: 'logs',
+                        value: 'frontend + backend + HubSpot events',
+                        detail: directDevLogStream.url,
+                        status: 'ok',
+                    },
+                ]
+                : []),
+            { key: 'Cloudflare', value: 'not used' },
+            { key: 'HS-X control plane', value: 'not used' },
+        ]);
+        if (!directDevLogStream?.renderer.hasStatusLine())
+            reporter.info('Press Ctrl+C to stop');
+    }
+    const directKeyboard = directDevLogStream
+        ? (await import('../dev/keyboard.js')).attachDevKeyboard({
+            renderer: directDevLogStream.renderer,
+            onQuit: () => process.kill(process.pid, 'SIGINT'),
+        })
+        : undefined;
+    directDevLogStream?.renderer.ready();
+    await new Promise((resolveClose) => {
+        let closing = false;
+        const close = async () => {
+            if (closing)
+                return;
+            closing = true;
+            directKeyboard?.stop();
+            if (managedSessionId) {
+                try {
+                    await markManagedDevSessionState(managedSessionId, 'stopping', undefined, {
+                        expectedPid: process.pid,
+                    });
+                }
+                catch {
+                    // Continue cleanup even if the managed state record is unavailable.
+                }
+            }
+            try {
+                await session.cleanup();
+            }
+            finally {
+                try {
+                    await directDevLogStream?.cleanup();
+                }
+                finally {
+                    if (managedSessionId) {
+                        try {
+                            await markManagedDevSessionState(managedSessionId, 'stopped', undefined, {
+                                expectedPid: process.pid,
+                            });
+                        }
+                        catch {
+                            // The process exit will be reconciled by the next status request.
+                        }
+                    }
+                    resolveClose();
+                }
+            }
+        };
+        process.once('SIGINT', close);
+        process.once('SIGTERM', close);
+    });
+    return { exitCode: 0 };
+}
+const MANAGED_DEV_SUBCOMMANDS = new Set(['start', 'logs', 'stop', 'restart']);
+const KNOWN_DEV_SUBCOMMANDS = new Set([...MANAGED_DEV_SUBCOMMANDS, 'invoke', 'cleanup', 'status']);
+const MANAGED_DEV_LANES = new Set(['frontend', 'backend', 'request', 'hubspot']);
+const MANAGED_DEV_LEVELS = new Set(['debug', 'info', 'warn', 'error']);
+export async function devCommand({ argv, root, json, reporter, }) {
+    const managedSessionId = resolveFlag(argv, '--managed-session');
+    if (managedSessionId) {
+        await waitForManagedDevSessionOwner(managedSessionId);
+        try {
+            const result = await devCommandCore({ argv, root, json: false });
+            if (result.exitCode !== 0) {
+                const current = await readManagedDevSession(managedSessionId);
+                if (current.state === 'starting') {
+                    await markManagedDevSessionState(managedSessionId, 'failed', `hs-x dev exited with code ${result.exitCode} during startup.`, { expectedGeneration: current.generation, expectedPid: process.pid });
+                }
+            }
+            return result;
+        }
+        catch (cause) {
+            const message = cause instanceof Error ? cause.message : String(cause);
+            try {
+                const current = await readManagedDevSession(managedSessionId);
+                if (current.state !== 'stopped' && current.state !== 'failed') {
+                    await markManagedDevSessionState(managedSessionId, 'failed', message, {
+                        expectedPid: process.pid,
+                    });
+                }
+            }
+            catch {
+                // Preserve the original startup failure if the state file is unavailable.
+            }
+            throw cause;
+        }
+    }
+    const subcommand = argv[1];
+    if (subcommand && !subcommand.startsWith('-') && !KNOWN_DEV_SUBCOMMANDS.has(subcommand)) {
+        const outputReporter = reporter ?? createReporter({ command: 'dev', argv });
+        outputReporter.error('HSX_E_INPUT_INVALID', `Unknown dev subcommand "${subcommand}".`, {
+            hint: 'Expected start, logs, stop, restart, invoke, cleanup, or status. Run `hs-x dev --help`.',
+        });
+        outputReporter.done(undefined, 2);
+        return { exitCode: 2 };
+    }
+    if (subcommand &&
+        KNOWN_DEV_SUBCOMMANDS.has(subcommand) &&
+        subcommand !== 'invoke' &&
+        argv[2] !== undefined &&
+        !argv[2].startsWith('-')) {
+        const outputReporter = reporter ?? createReporter({ command: `dev ${subcommand}`, argv });
+        outputReporter.error('HSX_E_INPUT_INVALID', `Unexpected argument "${argv[2]}" after \`hs-x dev ${subcommand}\`.`);
+        outputReporter.done(undefined, 2);
+        return { exitCode: 2 };
+    }
+    const reporterInput = reporter ? { reporter } : {};
+    if (subcommand === 'logs')
+        return managedDevLogsCommand({ argv, json, ...reporterInput });
+    if (subcommand === 'stop')
+        return managedDevStopCommand({ argv, json, ...reporterInput });
+    if (subcommand === 'restart') {
+        return managedDevRestartCommand({ argv, json, ...reporterInput });
+    }
+    if (subcommand === 'status' && resolveFlag(argv, '--session')) {
+        return managedDevStatusCommand({ argv, json, ...reporterInput });
+    }
+    if (subcommand === 'start' || argv.includes('--detach')) {
+        return managedDevStartCommand({ argv, root, json, ...reporterInput });
+    }
+    return devCommandCore({ argv, root, json });
+}
+async function devCommandCore({ argv, root, json, }) {
     if (argv[1] === 'cleanup') {
         return await devCleanupCommand({ argv, json });
     }
@@ -195,7 +724,7 @@ export async function devCommand({ argv, root, json, }) {
                 prompts: { select: promptSelect },
             });
             if (selected && selected.root !== root) {
-                return await devCommand({ argv, root: selected.root, json });
+                return await devCommandCore({ argv, root: selected.root, json });
             }
         }
         catch (error) {
@@ -207,6 +736,9 @@ export async function devCommand({ argv, root, json, }) {
     if (argv[1] === 'invoke') {
         return await devInvokeCommand({ argv, root, json });
     }
+    if ((await detectLocalProjectMode(root)) === 'hubspot-direct') {
+        return await hubSpotDirectDevCommand({ argv, root, json });
+    }
     const portFlag = resolveFlag(argv, '--port');
     const port = Number(portFlag ?? '8787');
     if (!Number.isInteger(port) || port < 1 || port > 65535) {
@@ -665,11 +1197,13 @@ export async function devCommand({ argv, root, json, }) {
         reporter.done(undefined, 2);
         return { exitCode: 2 };
     }
+    const managedLogSessionId = resolveFlag(argv, '--managed-session');
     const devLogStream = await startHsxDevLogStream({
         port: hsxLogPort,
         root,
         reporter,
         filter: onlyParsed.filter,
+        ...(managedLogSessionId ? { managedSessionId: managedLogSessionId } : {}),
     });
     if (devLogStream) {
         const paint = makeDevLogPaint(process.env, process.stderr);
@@ -729,6 +1263,14 @@ export async function devCommand({ argv, root, json, }) {
             }),
         });
     }
+    const managedSessionId = resolveFlag(argv, '--managed-session');
+    if (managedSessionId) {
+        await markManagedDevSessionReady(managedSessionId, {
+            components: selectedUiNodeUids ?? capabilityIds,
+            devPort: port,
+            ...(devLogStream ? { logPort: hsxLogPort } : {}),
+        });
+    }
     // Railed startup checklist: identity header, then one row per surface.
     reporter.header(subject);
     reporter.rows([
@@ -796,8 +1338,22 @@ export async function devCommand({ argv, root, json, }) {
         : undefined;
     devLogStream?.renderer.ready();
     await new Promise((resolveClose) => {
+        let closing = false;
         const close = async () => {
+            if (closing)
+                return;
+            closing = true;
             keyboard?.stop();
+            if (managedSessionId) {
+                try {
+                    await markManagedDevSessionState(managedSessionId, 'stopping', undefined, {
+                        expectedPid: process.pid,
+                    });
+                }
+                catch {
+                    // Continue cleanup even if the managed state record is unavailable.
+                }
+            }
             // Signal-driven shutdown can terminate the Bun process before awaited
             // cleanup settles. Restore temporarily stamped migration sources
             // synchronously first; the remaining network/process cleanup is
@@ -850,13 +1406,615 @@ export async function devCommand({ argv, root, json, }) {
                     // best-effort: sidecar shutdown failures should not block exit.
                 }
             }
-            server.close(() => resolveClose());
+            server.close(async () => {
+                if (managedSessionId) {
+                    try {
+                        await markManagedDevSessionState(managedSessionId, 'stopped', undefined, {
+                            expectedPid: process.pid,
+                        });
+                    }
+                    catch {
+                        // The process exit will be reconciled by the next status request.
+                    }
+                }
+                resolveClose();
+            });
         };
         process.once('SIGINT', close);
         process.once('SIGTERM', close);
     });
     return { exitCode: 0 };
 }
+async function managedDevStartCommand(input) {
+    const reporter = input.reporter ??
+        createReporter({ command: 'dev start', argv: input.argv, entry: !input.json });
+    let waitMs;
+    try {
+        waitMs = parsePositiveSeconds(input.argv, '--wait-seconds', 60) * 1_000;
+    }
+    catch (cause) {
+        return managedDevCommandFailure(reporter, cause, 'HSX_E_INPUT_BAD_FIELD');
+    }
+    const root = resolvePath(input.root);
+    const consent = await requestMutationConsent({
+        yes: input.argv.some((argument) => argument === '--yes' || argument === '-y'),
+        machineOutput: input.json || isMachineOutput(),
+        interactive: isInteractive(),
+        message: `Start an agent-managed background dev session in ${root}?`,
+        confirm: promptConfirm,
+    });
+    if (consent !== 'proceed') {
+        const message = consent === 'require-yes'
+            ? 'Starting a managed dev session in non-interactive or machine-output mode requires --yes.'
+            : 'Start cancelled.';
+        reporter.data({ target: { root } });
+        reporter.error('HSX_E_INPUT_INVALID', message, {
+            hint: 'Review the target root, then rerun `hs-x dev start --yes` with the same dev flags.',
+        });
+        reporter.done(undefined, consent === 'require-yes' ? 2 : 130);
+        return { exitCode: consent === 'require-yes' ? 2 : 130 };
+    }
+    const launchArgv = managedDevLaunchArgv(input.argv);
+    const session = await createManagedDevSession({
+        root,
+        launchArgv,
+    });
+    try {
+        await launchManagedDevChild(session);
+        const result = await waitForManagedDevStartup(session.sessionId, waitMs);
+        const safe = await publicManagedDevSession(result);
+        if (safe.state === 'failed' || safe.state === 'stopped') {
+            reporter.data({ session: safe });
+            reporter.error('HSX_E_DEV_MANAGED_START', safe.error ?? `Managed dev session ${safe.sessionId} stopped before it became ready.`, { hint: `Inspect ${safe.stderrPath} for the complete startup output.` });
+            reporter.done(undefined, 1);
+            return { exitCode: 1 };
+        }
+        renderManagedDevSession(reporter, safe, 'started');
+        reporter.data({
+            session: safe,
+            commands: managedDevSessionCommands(safe.sessionId),
+        });
+        if (safe.state !== 'ready') {
+            reporter.warn('HSX_W_DEV_MANAGED_STARTING', `Managed dev session ${safe.sessionId} is still starting. Check it with \`hs-x dev status --session ${safe.sessionId}\`.`);
+        }
+        else if (!safe.logPort) {
+            reporter.warn('HSX_W_DEV_MANAGED_LOG_STREAM', 'The dev server is ready, but its unified log sidecar is unavailable. Inspect stderrPath and restart with a free --hsx-log-port.');
+        }
+        reporter.done(safe.state === 'ready' ? 'Dev session ready' : 'Dev session still starting');
+        return { exitCode: 0 };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        try {
+            await markManagedDevSessionState(session.sessionId, 'failed', message, {
+                expectedGeneration: session.generation,
+                expectedStates: ['starting'],
+            });
+        }
+        catch {
+            // Keep the launch error as the primary failure.
+        }
+        reporter.error('HSX_E_DEV_MANAGED_START', message, {
+            hint: `Inspect ${session.stderrPath} for startup output.`,
+        });
+        reporter.done(undefined, 1);
+        return { exitCode: 1 };
+    }
+}
+async function managedDevStatusCommand(input) {
+    const reporter = input.reporter ?? createReporter({ command: 'dev status', argv: input.argv });
+    const sessionId = requireManagedSessionId(input.argv, reporter);
+    if (!sessionId)
+        return { exitCode: 2 };
+    try {
+        const safe = await publicManagedDevSession(await reconcileManagedDevSession(sessionId));
+        renderManagedDevSession(reporter, safe, 'status');
+        reporter.data({ session: safe, commands: managedDevSessionCommands(sessionId) });
+        reporter.done();
+        return { exitCode: 0 };
+    }
+    catch (cause) {
+        return managedDevCommandFailure(reporter, cause, 'HSX_E_DEV_MANAGED_SESSION');
+    }
+}
+async function managedDevStopCommand(input) {
+    const reporter = input.reporter ?? createReporter({ command: 'dev stop', argv: input.argv });
+    const sessionId = requireManagedSessionId(input.argv, reporter);
+    if (!sessionId)
+        return { exitCode: 2 };
+    try {
+        const current = await reconcileManagedDevSession(sessionId);
+        const safeCurrent = await publicManagedDevSession(current);
+        renderManagedDevSession(reporter, safeCurrent, 'stop target');
+        if (current.state === 'stopped' || current.state === 'failed') {
+            reporter.data({ session: safeCurrent });
+            reporter.done('Dev session is already stopped');
+            return { exitCode: 0 };
+        }
+        const consent = await requestMutationConsent({
+            yes: input.argv.includes('--yes'),
+            machineOutput: input.json || isMachineOutput(),
+            interactive: isInteractive(),
+            message: `Stop managed dev session ${sessionId} (PID ${current.pid})?`,
+            confirm: promptConfirm,
+        });
+        if (consent !== 'proceed') {
+            const message = consent === 'require-yes'
+                ? 'Stopping a managed dev session in non-interactive or machine-output mode requires --yes.'
+                : 'Stop cancelled.';
+            reporter.data({ session: safeCurrent });
+            reporter.error('HSX_E_INPUT_INVALID', message, {
+                hint: `Review the session above, then run \`hs-x dev stop --session ${sessionId} --yes\`.`,
+            });
+            reporter.done(undefined, consent === 'require-yes' ? 2 : 130);
+            return { exitCode: consent === 'require-yes' ? 2 : 130 };
+        }
+        const stopped = await stopManagedDevSessionProcess(sessionId, {
+            force: input.argv.includes('--force'),
+        });
+        const safe = await publicManagedDevSession(stopped);
+        reporter.data({ session: safe });
+        reporter.step(`Stopped managed dev session ${sessionId}`).ok(`PID ${current.pid}`);
+        reporter.done('Dev session stopped');
+        return { exitCode: 0 };
+    }
+    catch (cause) {
+        return managedDevCommandFailure(reporter, cause, 'HSX_E_DEV_MANAGED_STOP');
+    }
+}
+async function managedDevRestartCommand(input) {
+    const reporter = input.reporter ?? createReporter({ command: 'dev restart', argv: input.argv });
+    const sessionId = requireManagedSessionId(input.argv, reporter);
+    if (!sessionId)
+        return { exitCode: 2 };
+    try {
+        const waitMs = parsePositiveSeconds(input.argv, '--wait-seconds', 60) * 1_000;
+        const current = await reconcileManagedDevSession(sessionId);
+        const safeCurrent = await publicManagedDevSession(current);
+        renderManagedDevSession(reporter, safeCurrent, 'restart target');
+        const consent = await requestMutationConsent({
+            yes: input.argv.includes('--yes'),
+            machineOutput: input.json || isMachineOutput(),
+            interactive: isInteractive(),
+            message: `Restart managed dev session ${sessionId}${safeCurrent.running ? ` (PID ${current.pid})` : ''}?`,
+            confirm: promptConfirm,
+        });
+        if (consent !== 'proceed') {
+            const message = consent === 'require-yes'
+                ? 'Restarting a managed dev session in non-interactive or machine-output mode requires --yes.'
+                : 'Restart cancelled.';
+            reporter.data({ session: safeCurrent });
+            reporter.error('HSX_E_INPUT_INVALID', message, {
+                hint: `Review the session above, then run \`hs-x dev restart --session ${sessionId} --yes\`.`,
+            });
+            reporter.done(undefined, consent === 'require-yes' ? 2 : 130);
+            return { exitCode: consent === 'require-yes' ? 2 : 130 };
+        }
+        const restartBase = safeCurrent.running
+            ? await stopManagedDevSessionProcess(sessionId, { force: input.argv.includes('--force') })
+            : current;
+        const restarting = await prepareManagedDevSessionRestart(sessionId, {
+            expectedGeneration: restartBase.generation,
+            expectedPid: restartBase.pid,
+            expectedStates: [restartBase.state],
+        });
+        await launchManagedDevChild(restarting);
+        const result = await waitForManagedDevStartup(sessionId, waitMs);
+        const safe = await publicManagedDevSession(result);
+        if (safe.state === 'failed' || safe.state === 'stopped') {
+            reporter.data({ session: safe });
+            reporter.error('HSX_E_DEV_MANAGED_RESTART', safe.error ?? `Managed dev session ${sessionId} stopped while restarting.`, { hint: `Inspect ${safe.stderrPath} for the complete restart output.` });
+            reporter.done(undefined, 1);
+            return { exitCode: 1 };
+        }
+        renderManagedDevSession(reporter, safe, 'restarted');
+        reporter.data({ session: safe, commands: managedDevSessionCommands(sessionId) });
+        if (safe.state === 'ready' && !safe.logPort) {
+            reporter.warn('HSX_W_DEV_MANAGED_LOG_STREAM', 'The dev server restarted, but its unified log sidecar is unavailable. Inspect stderrPath and retry with a free --hsx-log-port.');
+        }
+        reporter.done(safe.state === 'ready' ? 'Dev session restarted' : 'Dev session still starting');
+        return { exitCode: 0 };
+    }
+    catch (cause) {
+        return managedDevCommandFailure(reporter, cause, 'HSX_E_DEV_MANAGED_RESTART');
+    }
+}
+async function managedDevLogsCommand(input) {
+    const reporter = input.reporter ?? createReporter({ command: 'dev logs', argv: input.argv });
+    const sessionId = requireManagedSessionId(input.argv, reporter);
+    if (!sessionId)
+        return { exitCode: 2 };
+    if (input.argv.includes('--follow') && input.json) {
+        reporter.error('HSX_E_DEV_LOGS_OUTPUT', '`--follow` is an event stream and cannot be combined with `--json`.', { hint: 'Use `--json-stream` for machine-readable follow mode.' });
+        reporter.done(undefined, 2);
+        return { exitCode: 2 };
+    }
+    try {
+        let session = await reconcileManagedDevSession(sessionId);
+        const cursor = parseNonNegativeInteger(input.argv, '--cursor', 0);
+        const limit = parsePositiveInteger(input.argv, '--limit', 200, 10_000);
+        const filter = parseManagedDevEventFilter(input.argv);
+        if (!input.argv.includes('--follow')) {
+            const result = await readManagedDevEvents({ session, cursor, limit, filter });
+            if (reporter.mode === 'json' || reporter.mode === 'ndjson') {
+                reporter.data({
+                    session_id: sessionId,
+                    cursor,
+                    next_cursor: result.nextCursor,
+                    end_cursor: result.endCursor,
+                    events: result.events,
+                });
+            }
+            else {
+                reporter.header(`${sessionId} · ${result.events.length} event${result.events.length === 1 ? '' : 's'}`);
+                const view = await startManagedDevLogView({ follow: false, filter });
+                try {
+                    for (const match of result.events)
+                        view.emit(match.event);
+                }
+                finally {
+                    view.stop();
+                }
+                reporter.info(`Next cursor: ${result.nextCursor}`);
+            }
+            reporter.done();
+            return { exitCode: 0 };
+        }
+        let nextCursor = cursor;
+        let interrupted = false;
+        let terminalSince;
+        const interrupt = () => {
+            interrupted = true;
+        };
+        process.once('SIGINT', interrupt);
+        process.once('SIGTERM', interrupt);
+        if (reporter.mode !== 'ndjson') {
+            reporter.header(`${sessionId} · following from cursor ${cursor}`);
+        }
+        const followReadFilter = reporter.mode === 'ndjson' ? filter : managedDevFollowReadFilter(filter);
+        let view;
+        try {
+            view =
+                reporter.mode === 'ndjson'
+                    ? undefined
+                    : await startManagedDevLogView({ follow: true, filter, onQuit: interrupt });
+            view?.ready();
+            while (!interrupted) {
+                const previousCursor = nextCursor;
+                const result = await readManagedDevEvents({
+                    session,
+                    cursor: nextCursor,
+                    limit,
+                    ...(followReadFilter ? { filter: followReadFilter } : {}),
+                });
+                for (const match of result.events) {
+                    if (reporter.mode === 'ndjson') {
+                        reporter.event('dev.logs.event', {
+                            session_id: sessionId,
+                            cursor: match.cursor,
+                            event: match.event,
+                        });
+                    }
+                    else {
+                        view?.emit(match.event);
+                    }
+                }
+                nextCursor = result.nextCursor;
+                session = await reconcileManagedDevSession(sessionId);
+                const terminal = session.state === 'stopped' || session.state === 'failed';
+                if (terminal && nextCursor >= result.endCursor) {
+                    terminalSince ??= Date.now();
+                    if (Date.now() - terminalSince >= 1_000)
+                        break;
+                }
+                else {
+                    terminalSince = undefined;
+                }
+                if (nextCursor >= result.endCursor || nextCursor === previousCursor)
+                    await delayMs(250);
+            }
+        }
+        finally {
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', interrupt);
+            view?.stop();
+        }
+        if (reporter.mode === 'ndjson') {
+            reporter.event('dev.logs.cursor', { session_id: sessionId, next_cursor: nextCursor });
+        }
+        else {
+            reporter.info(`Detached at cursor ${nextCursor}`);
+        }
+        reporter.done();
+        return { exitCode: 0 };
+    }
+    catch (cause) {
+        return managedDevCommandFailure(reporter, cause, 'HSX_E_DEV_MANAGED_LOGS');
+    }
+}
+function managedDevLaunchArgv(argv) {
+    const output = [];
+    const orchestrationValueFlags = new Set([
+        '--managed-session',
+        '--session',
+        '--cursor',
+        '--lane',
+        '--level',
+        '--search',
+        '--since',
+        '--limit',
+        '--wait-seconds',
+    ]);
+    const orchestrationBooleanFlags = new Set([
+        '--detach',
+        '--follow',
+        '--json',
+        '--json-stream',
+        '--yes',
+        '-y',
+    ]);
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index];
+        if (!value)
+            continue;
+        if (index === 1 && value === 'start')
+            continue;
+        if (orchestrationBooleanFlags.has(value))
+            continue;
+        if (orchestrationValueFlags.has(value)) {
+            index += 1;
+            continue;
+        }
+        if ([...orchestrationValueFlags].some((flag) => value.startsWith(`${flag}=`)))
+            continue;
+        output.push(value);
+    }
+    return output;
+}
+async function launchManagedDevChild(session) {
+    const entryCandidate = process.argv[1];
+    const entry = entryCandidate ? resolvePath(entryCandidate) : undefined;
+    const entryArgs = entry && existsSync(entry) ? [entry] : [];
+    const stdoutFd = openSync(session.stdoutPath, 'a', 0o600);
+    const stderrFd = openSync(session.stderrPath, 'a', 0o600);
+    try {
+        const child = spawn(process.execPath, [...entryArgs, ...session.launchArgv, '--managed-session', session.sessionId], {
+            cwd: session.root,
+            env: process.env,
+            detached: true,
+            stdio: ['ignore', stdoutFd, stderrFd],
+        });
+        await new Promise((resolveSpawn, rejectSpawn) => {
+            child.once('spawn', resolveSpawn);
+            child.once('error', rejectSpawn);
+        });
+        if (!child.pid)
+            throw new Error('Detached hs-x dev process did not report a PID.');
+        try {
+            await setManagedDevSessionPid(session.sessionId, child.pid, {
+                expectedGeneration: session.generation,
+                expectedPid: 0,
+                expectedStates: ['starting'],
+            });
+        }
+        catch (cause) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // The guarded state update is still the primary failure.
+            }
+            throw cause;
+        }
+        child.unref();
+        return child.pid;
+    }
+    finally {
+        closeSync(stdoutFd);
+        closeSync(stderrFd);
+    }
+}
+async function waitForManagedDevStartup(sessionId, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let session = await reconcileManagedDevSession(sessionId);
+    while (Date.now() < deadline && session.state === 'starting') {
+        await delayMs(100);
+        session = await reconcileManagedDevSession(sessionId);
+    }
+    return session;
+}
+function managedDevSessionCommands(sessionId) {
+    return {
+        logs: `hs-x dev logs --session ${sessionId} --follow`,
+        logs_json: `hs-x dev logs --session ${sessionId} --follow --json-stream`,
+        status: `hs-x dev status --session ${sessionId} --json`,
+        restart: `hs-x dev restart --session ${sessionId} --yes`,
+        stop: `hs-x dev stop --session ${sessionId} --yes`,
+    };
+}
+function renderManagedDevSession(reporter, session, subject) {
+    if (reporter.mode === 'json' || reporter.mode === 'ndjson')
+        return;
+    reporter.header(`${subject} · ${session.sessionId}`);
+    reporter.rows([
+        {
+            key: 'state',
+            value: session.state,
+            status: session.state === 'ready' ? 'ok' : session.state === 'failed' ? 'fail' : 'warn',
+        },
+        { key: 'pid', value: session.pid > 1 ? String(session.pid) : 'not assigned' },
+        { key: 'generation', value: String(session.generation) },
+        { key: 'root', value: session.root },
+        ...(session.projectAccountId
+            ? [{ key: 'project-account', value: String(session.projectAccountId) }]
+            : []),
+        ...(session.testingAccountId
+            ? [{ key: 'testing-account', value: String(session.testingAccountId) }]
+            : []),
+        ...(session.components
+            ? [{ key: 'components', value: session.components.join(', ') || 'none' }]
+            : []),
+        ...(session.logPort ? [{ key: 'log-port', value: String(session.logPort) }] : []),
+    ]);
+    if (session.error)
+        reporter.info(`Last error: ${session.error}`);
+    reporter.info(`Logs: hs-x dev logs --session ${session.sessionId} --follow`);
+}
+function requireManagedSessionId(argv, reporter) {
+    const sessionId = resolveFlag(argv, '--session');
+    if (sessionId)
+        return sessionId;
+    reporter.error('HSX_E_INPUT_INVALID', 'A managed dev session id is required.', {
+        hint: 'Pass the id returned by `hs-x dev start`, for example `--session dev_…`.',
+    });
+    reporter.done(undefined, 2);
+    return undefined;
+}
+function managedDevCommandFailure(reporter, cause, code) {
+    reporter.error(code, cause instanceof Error ? cause.message : String(cause));
+    reporter.done(undefined, 1);
+    return { exitCode: 1 };
+}
+function parseManagedDevEventFilter(argv) {
+    const laneValues = resolveFlags(argv, '--lane');
+    for (const lane of laneValues) {
+        if (!MANAGED_DEV_LANES.has(lane)) {
+            throw new Error(`Unknown --lane "${lane}". Expected frontend, backend, request, or hubspot.`);
+        }
+    }
+    const levelValues = resolveFlags(argv, '--level');
+    for (const level of levelValues) {
+        if (!MANAGED_DEV_LEVELS.has(level)) {
+            throw new Error(`Unknown --level "${level}". Expected debug, info, warn, or error.`);
+        }
+    }
+    const sinceValue = resolveFlag(argv, '--since');
+    const searchValue = resolveFlag(argv, '--search');
+    return {
+        ...(laneValues.length > 0
+            ? { lanes: new Set(laneValues) }
+            : {}),
+        ...(levelValues.length > 0
+            ? { levels: new Set(levelValues) }
+            : {}),
+        ...(searchValue ? { search: searchValue } : {}),
+        ...(sinceValue ? { since: parseManagedSince(sinceValue) } : {}),
+    };
+}
+function parseManagedSince(value) {
+    const relative = /^(\d+)(ms|s|m|h|d)$/.exec(value);
+    if (relative) {
+        const amount = Number(relative[1]);
+        const unit = relative[2];
+        const multiplier = unit === 'ms'
+            ? 1
+            : unit === 's'
+                ? 1_000
+                : unit === 'm'
+                    ? 60_000
+                    : unit === 'h'
+                        ? 3_600_000
+                        : 86_400_000;
+        return Date.now() - amount * multiplier;
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`Invalid --since value "${value}". Use an ISO timestamp or a duration like 30s, 5m, or 2h.`);
+    }
+    return parsed;
+}
+function parseNonNegativeInteger(argv, flag, fallback) {
+    const raw = resolveFlag(argv, flag);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0)
+        throw new Error(`${flag} must be a non-negative integer.`);
+    return value;
+}
+function parsePositiveInteger(argv, flag, fallback, maximum = Number.MAX_SAFE_INTEGER) {
+    const raw = resolveFlag(argv, flag);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1 || value > maximum) {
+        throw new Error(`${flag} must be an integer between 1 and ${maximum}.`);
+    }
+    return value;
+}
+function parsePositiveSeconds(argv, flag, fallback) {
+    return parsePositiveInteger(argv, flag, fallback, 600);
+}
+async function startManagedDevLogView(input) {
+    const [eventBusModule, keyboardModule, formatModule, rendererModule] = await Promise.all([
+        import('../dev/event-bus.js'),
+        import('../dev/keyboard.js'),
+        import('../dev/stream-event-format.js'),
+        import('../dev/stream-renderer.js'),
+    ]);
+    const bus = eventBusModule.createDevEventBus();
+    const renderer = rendererModule.startDevStreamRenderer({
+        bus,
+        filter: managedDevEventFilterToStreamFilter(input.filter),
+        ...(input.follow ? { deferStatus: true } : { isTTY: false }),
+    });
+    const keyboard = input.follow
+        ? keyboardModule.attachDevKeyboard({
+            renderer,
+            onQuit: input.onQuit ?? (() => { }),
+        })
+        : undefined;
+    return {
+        emit(event) {
+            bus.emit(formatModule.managedDevEventToDevEvent(event));
+        },
+        ready() {
+            renderer.ready();
+        },
+        stop() {
+            keyboard?.stop();
+            renderer.stop();
+        },
+    };
+}
+function managedDevEventFilterToStreamFilter(filter) {
+    const levels = filter.levels;
+    const level = levels?.size === 1 && levels.has('error')
+        ? 'error'
+        : levels?.size === 2 && levels.has('warn') && levels.has('error')
+            ? 'warn'
+            : 'all';
+    return {
+        lanes: filter.lanes,
+        level,
+        texts: filter.search ? [filter.search] : [],
+    };
+}
+/**
+ * Human follow mode keeps lane/search/threshold filtering in the renderer so
+ * keyboard controls can widen the retained view. Timestamp and exact level
+ * sets that the threshold model cannot express remain storage-side. Machine
+ * streams never use this split and retain their original cursor/filter path.
+ */
+function managedDevFollowReadFilter(filter) {
+    const levels = filter.levels;
+    const rendererCanRepresentLevels = levels === undefined ||
+        (levels.size === 1 && levels.has('error')) ||
+        (levels.size === 2 && levels.has('warn') && levels.has('error')) ||
+        (levels.size === 4 &&
+            levels.has('debug') &&
+            levels.has('info') &&
+            levels.has('warn') &&
+            levels.has('error'));
+    const readFilter = {
+        ...(filter.since !== undefined ? { since: filter.since } : {}),
+        ...(!rendererCanRepresentLevels && levels ? { levels } : {}),
+    };
+    return Object.keys(readFilter).length > 0 ? readFilter : undefined;
+}
+function delayMs(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 async function startHsxDevLogStream(input) {
     try {
         const [{ createDevEventBus }, { startDevLogServer }, { startDevStreamRenderer }] = await Promise.all([
@@ -872,6 +2030,12 @@ async function startHsxDevLogStream(input) {
             deferStatus: true,
             ...(input.filter ? { filter: input.filter } : {}),
         });
+        const managedEventWriter = input.managedSessionId
+            ? createManagedDevEventWriter(await readManagedDevSession(input.managedSessionId))
+            : undefined;
+        const unsubscribeManagedEvents = managedEventWriter
+            ? bus.subscribe((event) => managedEventWriter.log(event))
+            : undefined;
         // HubSpot-side lane: renders/proxy failures that never reach our Worker
         // only exist in HubSpot's app logs — poll them into the same stream.
         // Missing binding/credentials just means the lane stays off; `hs-x dev`
@@ -903,8 +2067,9 @@ async function startHsxDevLogStream(input) {
             bus,
             async cleanup() {
                 hubspotPoller?.stop();
+                unsubscribeManagedEvents?.();
                 renderer.stop();
-                await server.close();
+                await Promise.all([server.close(), managedEventWriter?.close()]);
             },
         };
     }
@@ -954,8 +2119,9 @@ async function probeHubSpotUiNodes(input) {
             projectSourceDir: pathJoin(input.root, projectConfig.srcDir),
             platformVersion: projectConfig.platformVersion,
             accountId: portalId,
-        }, {});
-        return { uids: Object.keys(ir.intermediateNodesIndexedByUid), portalId };
+        }, input.profile ? { profile: input.profile } : {});
+        const candidates = listHubSpotDevComponentCandidates(ir.intermediateNodesIndexedByUid);
+        return { uids: candidates.map((candidate) => candidate.uid), candidates, portalId };
     }
     catch {
         // IR translate failed — caller falls back to capability-only behavior.
@@ -973,10 +2139,12 @@ async function maybeStartHubSpotDevSession(input) {
     }
     try {
         const { startDevSession } = await import('../dev/session-manager.js');
+        const profile = resolveFlag(input.argv, '--profile');
         const session = await startDevSession({
             accountId: portalId,
             projectDir: input.root,
             selectedNodeUids: input.selectedNodeUids,
+            ...(profile ? { profile } : {}),
         });
         input.reporter
             .step('HubSpot UI-extension session')
@@ -984,7 +2152,7 @@ async function maybeStartHubSpotDevSession(input) {
         return session;
     }
     catch (error) {
-        input.reporter.warn('HSX_W_DEV_HUBSPOT_SESSION_FAILED', `Could not start UI-extension dev session: ${error instanceof Error ? error.message : String(error)}`);
+        input.reporter.warn('HSX_W_DEV_HUBSPOT_SESSION_FAILED', `Could not start UI-extension dev session: ${describeDevSessionFailure(error)}`);
         return undefined;
     }
 }
@@ -1757,11 +2925,11 @@ function write(message) {
 // as a silent `exitWith(code)` (the legacy body renders its own output) so
 // `runHandler` does not re-render.
 //
-// The first positional argument selects the `cleanup` / `status` subcommands
+// The first positional argument selects the managed-session and legacy subcommands
 // the legacy body branches on via `argv[1]`.
 // A positional (not an option) so `hs-x dev cleanup` / `dev status` parse — the
 // legacy body branches on `argv[1]`.
-const devSubcommandArg = Args.text({ name: 'subcommand' }).pipe(Args.withDescription('Optional dev subcommand: invoke | cleanup | status'), Args.optional);
+const devSubcommandArg = Args.text({ name: 'subcommand' }).pipe(Args.withDescription('Optional dev subcommand: start | logs | stop | restart | invoke | cleanup | status'), Args.optional);
 // Second positional: the capability id for `dev invoke <capability-id>`.
 const devTargetArg = Args.text({ name: 'target' }).pipe(Args.withDescription('Capability id for `dev invoke`'), Args.optional);
 const devInputOption = Options.text('input').pipe(Options.optional);
@@ -1772,6 +2940,10 @@ const devRemoteOption = Options.boolean('remote').pipe(Options.withDefault(false
 const devUrlOption = Options.text('url').pipe(Options.optional);
 const portOption = Options.text('port').pipe(Options.optional);
 const portalOption = Options.text('portal').pipe(Options.optional);
+const accountOption = Options.text('account').pipe(Options.optional);
+const projectAccountOption = Options.text('project-account').pipe(Options.optional);
+const testingAccountOption = Options.text('testing-account').pipe(Options.optional);
+const profileOption = Options.text('profile').pipe(Options.withAlias('p'), Options.optional);
 const targetOriginOption = Options.text('target-origin').pipe(Options.optional);
 const telemetryOriginOption = Options.text('telemetry-origin').pipe(Options.optional);
 const accountIdOption = Options.text('account-id').pipe(Options.optional);
@@ -1779,12 +2951,24 @@ const projectIdOption = Options.text('project-id').pipe(Options.optional);
 const developerIdOption = Options.text('developer-id').pipe(Options.optional);
 const userIdOption = Options.text('user-id').pipe(Options.optional);
 const sessionIdOption = Options.text('session-id').pipe(Options.optional);
+const managedSessionOption = Options.text('session').pipe(Options.optional);
+const internalManagedSessionOption = Options.text('managed-session').pipe(Options.optional);
 const ttlSecondsOption = Options.text('ttl-seconds').pipe(Options.optional);
 const hsxLogPortOption = Options.text('hsx-log-port').pipe(Options.optional);
 const controlPlaneUrlOption = Options.text('control-plane-url').pipe(Options.optional);
 const runtimeControlPlaneUrlOption = Options.text('runtime-control-plane-url').pipe(Options.optional);
 const capabilityOption = Options.text('capability').pipe(Options.repeated);
+const componentOption = Options.text('component').pipe(Options.repeated);
 const onlyOption = Options.text('only').pipe(Options.repeated);
+const laneOption = Options.text('lane').pipe(Options.repeated);
+const levelOption = Options.text('level').pipe(Options.repeated);
+const searchOption = Options.text('search').pipe(Options.optional);
+const sinceOption = Options.text('since').pipe(Options.optional);
+const cursorOption = Options.text('cursor').pipe(Options.optional);
+const limitOption = Options.text('limit').pipe(Options.optional);
+const waitSecondsOption = Options.text('wait-seconds').pipe(Options.optional);
+const detachOption = Options.boolean('detach').pipe(Options.withDefault(false));
+const followOption = Options.boolean('follow').pipe(Options.withDefault(false));
 const pickOption = Options.boolean('pick').pipe(Options.withDefault(false));
 const noHubspotOption = Options.boolean('no-hubspot').pipe(Options.withDefault(false));
 const noUiExtensionsOption = Options.boolean('no-ui-extensions').pipe(Options.withDefault(false));
@@ -1803,6 +2987,10 @@ export const devCmd = Command.make('dev', {
     url: devUrlOption,
     port: portOption,
     portal: portalOption,
+    account: accountOption,
+    projectAccount: projectAccountOption,
+    testingAccount: testingAccountOption,
+    profile: profileOption,
     targetOrigin: targetOriginOption,
     telemetryOrigin: telemetryOriginOption,
     accountId: accountIdOption,
@@ -1810,90 +2998,151 @@ export const devCmd = Command.make('dev', {
     developerId: developerIdOption,
     userId: userIdOption,
     sessionId: sessionIdOption,
+    session: managedSessionOption,
+    managedSession: internalManagedSessionOption,
     ttlSeconds: ttlSecondsOption,
     hsxLogPort: hsxLogPortOption,
     controlPlaneUrl: controlPlaneUrlOption,
     runtimeControlPlaneUrl: runtimeControlPlaneUrlOption,
     capability: capabilityOption,
+    component: componentOption,
     only: onlyOption,
+    lane: laneOption,
+    level: levelOption,
+    search: searchOption,
+    since: sinceOption,
+    cursor: cursorOption,
+    limit: limitOption,
+    waitSeconds: waitSecondsOption,
+    detach: detachOption,
+    follow: followOption,
     pick: pickOption,
     noHubspot: noHubspotOption,
     noUiExtensions: noUiExtensionsOption,
     yes: yesOption,
     force: forceOption,
-}, (opts) => runHandler('dev', { json: opts.json }, Effect.gen(function* () {
-    // root: injected cwd, overridden by --cwd.
-    const injectedCwd = yield* Cwd;
-    const root = Option.getOrElse(opts.cwd, () => injectedCwd);
-    // Reconstruct the legacy argv the quarantined body parses (it reads
-    // its flags off argv via `resolveFlag`/`resolveFlags` and branches on
-    // `argv[1]` for the cleanup/status subcommands).
-    const argv = ['dev'];
-    if (Option.isSome(opts.subcommand))
-        argv.push(opts.subcommand.value);
-    if (Option.isSome(opts.target))
-        argv.push(opts.target.value);
-    if (Option.isSome(opts.input))
-        argv.push('--input', opts.input.value);
-    if (Option.isSome(opts.object))
-        argv.push('--object', opts.object.value);
-    if (Option.isSome(opts.install))
-        argv.push('--install', opts.install.value);
-    if (opts.last)
-        argv.push('--last');
-    if (opts.remote)
-        argv.push('--remote');
-    if (Option.isSome(opts.url))
-        argv.push('--url', opts.url.value);
-    if (opts.json)
-        argv.push('--json');
-    if (Option.isSome(opts.port))
-        argv.push('--port', opts.port.value);
-    if (Option.isSome(opts.portal))
-        argv.push('--portal', opts.portal.value);
-    if (Option.isSome(opts.targetOrigin)) {
-        argv.push('--target-origin', opts.targetOrigin.value);
-    }
-    if (Option.isSome(opts.telemetryOrigin)) {
-        argv.push('--telemetry-origin', opts.telemetryOrigin.value);
-    }
-    if (Option.isSome(opts.accountId))
-        argv.push('--account-id', opts.accountId.value);
-    if (Option.isSome(opts.projectId))
-        argv.push('--project-id', opts.projectId.value);
-    if (Option.isSome(opts.developerId)) {
-        argv.push('--developer-id', opts.developerId.value);
-    }
-    if (Option.isSome(opts.userId))
-        argv.push('--user-id', opts.userId.value);
-    if (Option.isSome(opts.sessionId))
-        argv.push('--session-id', opts.sessionId.value);
-    if (Option.isSome(opts.ttlSeconds))
-        argv.push('--ttl-seconds', opts.ttlSeconds.value);
-    if (Option.isSome(opts.hsxLogPort))
-        argv.push('--hsx-log-port', opts.hsxLogPort.value);
-    if (Option.isSome(opts.controlPlaneUrl)) {
-        argv.push('--control-plane-url', opts.controlPlaneUrl.value);
-    }
-    if (Option.isSome(opts.runtimeControlPlaneUrl)) {
-        argv.push('--runtime-control-plane-url', opts.runtimeControlPlaneUrl.value);
-    }
-    for (const capability of opts.capability)
-        argv.push('--capability', capability);
-    for (const only of opts.only)
-        argv.push('--only', only);
-    if (opts.pick)
-        argv.push('--pick');
-    if (opts.noHubspot)
-        argv.push('--no-hubspot');
-    if (opts.noUiExtensions)
-        argv.push('--no-ui-extensions');
-    if (opts.yes)
-        argv.push('--yes');
-    if (opts.force)
-        argv.push('--force');
-    yield* runQuarantined('dev', opts.json, () => devCommand({ argv, root, json: opts.json }));
-})));
+}, (opts) => {
+    const subcommand = Option.isSome(opts.subcommand) ? opts.subcommand.value : undefined;
+    const managedSubcommand = subcommand !== undefined &&
+        (MANAGED_DEV_SUBCOMMANDS.has(subcommand) ||
+            (subcommand === 'status' && Option.isSome(opts.session)));
+    const reportCommand = managedSubcommand ? `dev ${subcommand}` : 'dev';
+    return runHandler(reportCommand, { json: opts.json }, Effect.gen(function* () {
+        const effectReporter = yield* ReporterService;
+        // root: injected cwd, overridden by --cwd.
+        const injectedCwd = yield* Cwd;
+        const root = Option.getOrElse(opts.cwd, () => injectedCwd);
+        // Reconstruct the legacy argv the quarantined body parses (it reads
+        // its flags off argv via `resolveFlag`/`resolveFlags` and branches on
+        // `argv[1]` for the cleanup/status subcommands).
+        const argv = ['dev'];
+        if (Option.isSome(opts.subcommand))
+            argv.push(opts.subcommand.value);
+        if (Option.isSome(opts.target))
+            argv.push(opts.target.value);
+        if (Option.isSome(opts.input))
+            argv.push('--input', opts.input.value);
+        if (Option.isSome(opts.object))
+            argv.push('--object', opts.object.value);
+        if (Option.isSome(opts.install))
+            argv.push('--install', opts.install.value);
+        if (opts.last)
+            argv.push('--last');
+        if (opts.remote)
+            argv.push('--remote');
+        if (Option.isSome(opts.url))
+            argv.push('--url', opts.url.value);
+        if (opts.json)
+            argv.push('--json');
+        if (Option.isSome(opts.port))
+            argv.push('--port', opts.port.value);
+        if (Option.isSome(opts.portal))
+            argv.push('--portal', opts.portal.value);
+        if (Option.isSome(opts.account))
+            argv.push('--account', opts.account.value);
+        if (Option.isSome(opts.projectAccount)) {
+            argv.push('--project-account', opts.projectAccount.value);
+        }
+        if (Option.isSome(opts.testingAccount)) {
+            argv.push('--testing-account', opts.testingAccount.value);
+        }
+        if (Option.isSome(opts.profile))
+            argv.push('--profile', opts.profile.value);
+        if (Option.isSome(opts.targetOrigin)) {
+            argv.push('--target-origin', opts.targetOrigin.value);
+        }
+        if (Option.isSome(opts.telemetryOrigin)) {
+            argv.push('--telemetry-origin', opts.telemetryOrigin.value);
+        }
+        if (Option.isSome(opts.accountId))
+            argv.push('--account-id', opts.accountId.value);
+        if (Option.isSome(opts.projectId))
+            argv.push('--project-id', opts.projectId.value);
+        if (Option.isSome(opts.developerId)) {
+            argv.push('--developer-id', opts.developerId.value);
+        }
+        if (Option.isSome(opts.userId))
+            argv.push('--user-id', opts.userId.value);
+        if (Option.isSome(opts.sessionId))
+            argv.push('--session-id', opts.sessionId.value);
+        if (Option.isSome(opts.session))
+            argv.push('--session', opts.session.value);
+        if (Option.isSome(opts.managedSession)) {
+            argv.push('--managed-session', opts.managedSession.value);
+        }
+        if (Option.isSome(opts.ttlSeconds))
+            argv.push('--ttl-seconds', opts.ttlSeconds.value);
+        if (Option.isSome(opts.hsxLogPort))
+            argv.push('--hsx-log-port', opts.hsxLogPort.value);
+        if (Option.isSome(opts.controlPlaneUrl)) {
+            argv.push('--control-plane-url', opts.controlPlaneUrl.value);
+        }
+        if (Option.isSome(opts.runtimeControlPlaneUrl)) {
+            argv.push('--runtime-control-plane-url', opts.runtimeControlPlaneUrl.value);
+        }
+        for (const capability of opts.capability)
+            argv.push('--capability', capability);
+        for (const component of opts.component)
+            argv.push('--component', component);
+        for (const only of opts.only)
+            argv.push('--only', only);
+        for (const lane of opts.lane)
+            argv.push('--lane', lane);
+        for (const level of opts.level)
+            argv.push('--level', level);
+        if (Option.isSome(opts.search))
+            argv.push('--search', opts.search.value);
+        if (Option.isSome(opts.since))
+            argv.push('--since', opts.since.value);
+        if (Option.isSome(opts.cursor))
+            argv.push('--cursor', opts.cursor.value);
+        if (Option.isSome(opts.limit))
+            argv.push('--limit', opts.limit.value);
+        if (Option.isSome(opts.waitSeconds)) {
+            argv.push('--wait-seconds', opts.waitSeconds.value);
+        }
+        if (opts.detach)
+            argv.push('--detach');
+        if (opts.follow)
+            argv.push('--follow');
+        if (opts.pick)
+            argv.push('--pick');
+        if (opts.noHubspot)
+            argv.push('--no-hubspot');
+        if (opts.noUiExtensions)
+            argv.push('--no-ui-extensions');
+        if (opts.yes)
+            argv.push('--yes');
+        if (opts.force)
+            argv.push('--force');
+        yield* runQuarantined(reportCommand, opts.json, () => devCommand({
+            argv,
+            root,
+            json: opts.json,
+            reporter: effectReporter.implementation,
+        }));
+    }));
+});
 /**
  * `hs-x dev invoke --remote`: dispatch at the DEPLOYED Worker, where install
  * tokens live — handlers using ctx.hubspot run against the real portal. URL
@@ -1910,6 +3159,9 @@ async function devInvokeRemote(args) {
     }
     let url = explicitUrl;
     if (!url) {
+        if (!mapping) {
+            return fail('HSX_E_DEV_UNKNOWN_CAPABILITY', `No capability \`${capabilityId}\` in .hs-x/manifest.json.`);
+        }
         const { resolveCloudflareCredentials } = await import('../cloudflare-kv.js');
         const credentials = resolveCloudflareCredentials(argv);
         const { loadCloudflarePointer } = await import('../cloudflare-pointer.js');