proteum 2.2.9 → 2.4.1

package/cli/commands/mcp.ts

@@ -0,0 +1,133 @@
+import cli from '..';
+import { startProteumMachineMcpRouter, startProteumMachineMcpRouterHttp } from '../mcp/router';
+import {
+    ensureMachineMcpDaemonProcess,
+    inspectMachineMcpDaemonRecord,
+    resolveMachineMcpDaemonPort,
+    stopMachineMcpDaemonProcess,
+} from '../runtime/mcpDaemon';
+
+const printJson = (payload: unknown) => {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+};
+
+const printStatus = async () => {
+    const inspection = await inspectMachineMcpDaemonRecord({ cleanStale: true });
+
+    if (cli.args.json === true) {
+        printJson({
+            daemon: inspection
+                ? {
+                      live: inspection.live,
+                      stale: inspection.stale,
+                      invalid: inspection.invalid,
+                      parseError: inspection.parseError,
+                      record: inspection.record,
+                  }
+                : null,
+        });
+        return;
+    }
+
+    if (!inspection?.record || !inspection.live) {
+        console.info('No live Proteum machine MCP daemon found.');
+        return;
+    }
+
+    console.info(
+        [
+            `Proteum machine MCP daemon is running.`,
+            `pid ${inspection.record.pid}`,
+            `mcp ${inspection.record.mcpUrl}`,
+            `health ${inspection.record.healthUrl}`,
+        ].join('\n'),
+    );
+};
+
+const runDaemon = async () => {
+    const existing = await inspectMachineMcpDaemonRecord({ cleanStale: true });
+
+    if (existing?.record && existing.live && existing.record.pid !== process.pid) {
+        if (cli.args.json === true) {
+            printJson({ started: false, daemon: existing.record });
+            return;
+        }
+
+        console.info(`Proteum machine MCP daemon is already running at ${existing.record.mcpUrl} (pid ${existing.record.pid}).`);
+        return;
+    }
+
+    const port = resolveMachineMcpDaemonPort(typeof cli.args.port === 'string' ? cli.args.port : undefined);
+
+    await startProteumMachineMcpRouterHttp({
+        port,
+        version: String(cli.packageJson.version || ''),
+    });
+
+    if (cli.args.json === true) {
+        printJson({
+            started: true,
+            daemon: {
+                pid: process.pid,
+                mcpUrl: `http://127.0.0.1:${port}/mcp`,
+                healthUrl: `http://127.0.0.1:${port}/health`,
+            },
+        });
+    } else {
+        console.info(`Proteum machine MCP daemon started at http://127.0.0.1:${port}/mcp.`);
+    }
+};
+
+const ensureDaemon = async () => {
+    const result = await ensureMachineMcpDaemonProcess({
+        coreRoot: cli.paths.core.root,
+        port: typeof cli.args.port === 'string' ? cli.args.port : undefined,
+    });
+
+    if (cli.args.json === true) {
+        printJson({ started: result.started, daemon: result.inspection.record });
+        return;
+    }
+
+    if (result.inspection.record) {
+        console.info(
+            result.started
+                ? `Proteum machine MCP daemon started at ${result.inspection.record.mcpUrl}.`
+                : `Proteum machine MCP daemon is already running at ${result.inspection.record.mcpUrl}.`,
+        );
+    }
+};
+
+export const run = async () => {
+    if (cli.args.action === 'status') {
+        await printStatus();
+        return;
+    }
+
+    if (cli.args.action === 'stop') {
+        const result = await stopMachineMcpDaemonProcess();
+        if (cli.args.json === true) {
+            printJson({ stopped: result.stopped, daemon: result.inspection?.record || null });
+        } else if (result.stopped) {
+            console.info('Proteum machine MCP daemon stopped.');
+        } else if (result.inspection?.record) {
+            console.info(`Could not stop Proteum machine MCP daemon pid ${result.inspection.record.pid}.`);
+            process.exitCode = 1;
+        }
+        return;
+    }
+
+    if (cli.args.daemon === true) {
+        await runDaemon();
+        return;
+    }
+
+    if (cli.args.stdio !== true && (process.stdout.isTTY || cli.args.json === true)) {
+        await ensureDaemon();
+        return;
+    }
+
+    await startProteumMachineMcpRouter({
+        version: String(cli.packageJson.version || ''),
+    });
+};

package/cli/commands/orient.ts

@@ -7,7 +7,9 @@ import cli from '..';
 import Compiler from '../compiler';
 import { readProteumManifest } from '../compiler/common/proteumManifest';
 import { buildOrientationResponse, type TOrientResponse } from '@common/dev/inspection';
+import { resolveTriggeredInstructionReads } from '@common/dev/mcpPayloads';
 import type { TProteumManifest } from '@common/dev/proteumManifest';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
 
 const normalizeBaseUrl = (value: string) => value.replace(/\/+$/, '');
 const dedupe = <TValue>(values: TValue[]) => [...new Set(values)];
@@ -124,6 +126,7 @@ const renderHuman = (response: TOrientResponse) =>
         ...(response.app.routerPort ? [`- routerPort=${response.app.routerPort}`] : []),
         'Guidance',
         `- agents=${response.guidance.agents}`,
+        `- documentation=${response.guidance.documentation}`,
         `- diagnostics=${response.guidance.diagnostics}`,
         `- optimizations=${response.guidance.optimizations}`,
         `- codingStyle=${response.guidance.codingStyle}`,
@@ -153,6 +156,88 @@ const renderHuman = (response: TOrientResponse) =>
         ...(response.warnings.length === 0 ? ['- none'] : response.warnings.map((warning) => `- ${warning}`)),
     ].join('\n');
 
+const compactOwnerMatch = (match: TOrientResponse['owner']['matches'][number]) => ({
+    kind: match.kind,
+    label: match.label,
+    score: match.score,
+    scope: match.scopeLabel,
+    origin: match.originHint,
+    source: match.source,
+});
+
+const buildInstructionPlan = (response: TOrientResponse) => {
+    const triggered = resolveTriggeredInstructionReads({
+        codingStyle: response.guidance.codingStyle,
+        diagnostics: response.guidance.diagnostics,
+        documentation: response.guidance.documentation,
+        optimizations: response.guidance.optimizations,
+        query: response.normalizedQuery || response.query,
+        rootAgentsFile:
+            response.app.repoRoot !== response.app.appRoot
+                ? path.join(response.app.repoRoot, 'AGENTS.md')
+                : response.guidance.agents,
+    });
+
+    return {
+        mustRead: [
+            ...new Set([
+                response.guidance.agents,
+                ...response.guidance.areaAgents,
+                ...triggered.map((entry) => entry.file),
+            ]),
+        ],
+        triggered,
+        readWhen: [
+            {
+                file: response.guidance.documentation,
+                when: 'Read before non-trivial coding tasks to choose the smallest `/docs` pack and update docs after changes.',
+            },
+            {
+                file: response.guidance.diagnostics,
+                when: 'Read only for raw errors, failing requests, traces, perf regressions, or reproduction work.',
+            },
+            {
+                file: response.guidance.codingStyle,
+                when: 'Read before editing implementation files.',
+            },
+            {
+                file: response.guidance.optimizations,
+                when: 'Read after client-side implementation or when the task explicitly concerns packages, build, runtime, or performance.',
+            },
+        ],
+    };
+};
+
+const printCompactOrient = (response: TOrientResponse) => {
+    const topOwner = response.owner.matches[0];
+    const summary = topOwner
+        ? `${response.query} -> ${topOwner.kind} ${topOwner.label} (${topOwner.scopeLabel})`
+        : `${response.query} -> no manifest owner matched`;
+
+    printAgentResponse({
+        summary,
+        data: {
+            query: response.query,
+            app: response.app,
+            owner: {
+                top: topOwner ? compactOwnerMatch(topOwner) : undefined,
+                matches: compactList(response.owner.matches, 4).map(compactOwnerMatch),
+                totalReturned: response.owner.matches.length,
+            },
+            instructions: buildInstructionPlan(response),
+            connected: {
+                imports: compactList(response.connected.imports, 4),
+                producers: compactList(response.connected.producers, 3),
+                totalImports: response.connected.imports.length,
+                totalProducers: response.connected.producers.length,
+            },
+            warnings: response.warnings,
+        },
+        nextActions: response.nextSteps,
+        fullDetailCommand: `proteum orient ${quoteCommandArgument(response.query)} --full`,
+    });
+};
+
 export const run = async () => {
     const query = typeof cli.args.query === 'string' ? cli.args.query.trim() : '';
     if (!query) throw new UsageError('A query is required. Example: proteum orient /api/Auth/CurrentUser');
@@ -160,10 +245,15 @@ export const run = async () => {
     const manifest = await resolveManifest();
     const response = buildOrientationResponse(manifest, query);
 
-    if (cli.args.json === true) {
-        console.log(JSON.stringify(response, null, 2));
+    if (cli.args.full === true) {
+        printJson(response);
+        return;
+    }
+
+    if (cli.args.human === true) {
+        console.log(renderHuman(response));
         return;
     }
 
-    console.log(renderHuman(response));
+    printCompactOrient(response);
 };

package/cli/commands/perf.ts

@@ -4,6 +4,7 @@ import path from 'path';
 import { UsageError } from 'clipanion';
 
 import cli from '..';
+import { compactList, printAgentResponse, printJson, quoteCommandArgument, truncateForAgent } from '../utils/agentOutput';
 import type {
     TPerfCompareResponse,
     TPerfMemoryResponse,
@@ -102,10 +103,6 @@ const requestJson = async <TResponse>(pathname: string) => {
     );
 };
 
-const printJson = (value: object) => {
-    console.log(JSON.stringify(value, null, 2));
-};
-
 const renderWindow = (label: string, value: { startedAt: string; finishedAt: string; requestCount: number; availableRequestCount: number }) =>
     `${label}=${value.requestCount}/${value.availableRequestCount} traces ${value.startedAt}..${value.finishedAt}`;
 
@@ -180,9 +177,113 @@ const renderRequest = (response: TPerfRequestResponse) =>
               )),
     ].join('\n');
 
+const compactTopLikeRow = (row: TPerfTopResponse['rows'][number]) => ({
+    label: row.label,
+    requestCount: row.requestCount,
+    avgDurationMs: row.avgDurationMs,
+    p95DurationMs: row.p95DurationMs,
+    maxDurationMs: row.maxDurationMs,
+    avgCpuMs: row.avgCpuMs,
+    avgSqlDurationMs: row.avgSqlDurationMs,
+    avgRenderDurationMs: row.avgRenderDurationMs,
+    avgHeapDeltaBytes: row.avgHeapDeltaBytes,
+    slowestRequestId: row.slowestRequestId,
+});
+
+const compactSql = (query: TPerfRequestResponse['request']['hottestSqlQueries'][number]) => ({
+    callerLabel: query.callerLabel,
+    operation: query.operation,
+    model: query.model,
+    fingerprint: query.fingerprint,
+    durationMs: query.durationMs,
+    query: truncateForAgent(query.query, 140),
+});
+
+const printCompactTop = (response: TPerfTopResponse) => {
+    printAgentResponse({
+        summary: `Perf top ${response.groupBy}: ${response.summary.requestCount} requests, ${response.summary.errorCount} errors, p95=${formatDuration(response.summary.p95DurationMs)}`,
+        data: {
+            groupBy: response.groupBy,
+            window: response.window,
+            summary: response.summary,
+            rows: compactList(response.rows, 8).map(compactTopLikeRow),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf top --full',
+    });
+};
+
+const printCompactCompare = (response: TPerfCompareResponse) => {
+    printAgentResponse({
+        summary: `Perf compare ${response.groupBy}: ${response.rows.length} rows`,
+        data: {
+            groupBy: response.groupBy,
+            baseline: response.baseline,
+            target: response.target,
+            rows: compactList(response.rows, 8),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf compare --full',
+    });
+};
+
+const printCompactMemory = (response: TPerfMemoryResponse) => {
+    printAgentResponse({
+        summary: `Perf memory ${response.groupBy}: ${response.rows.length} rows`,
+        data: {
+            groupBy: response.groupBy,
+            window: response.window,
+            rows: compactList(response.rows, 8),
+            totalRows: response.rows.length,
+        },
+        fullDetailCommand: 'proteum perf memory --full',
+    });
+};
+
+const printCompactRequest = (response: TPerfRequestResponse) => {
+    printAgentResponse({
+        summary: `${response.request.requestId}: ${response.request.method} ${response.request.path} total=${formatDuration(response.request.totalDurationMs)} cpu=${formatDuration(response.request.cpuTotalMs)} sql=${formatDuration(response.request.sqlDurationMs)}`,
+        data: {
+            request: {
+                requestId: response.request.requestId,
+                method: response.request.method,
+                path: response.request.path,
+                statusCode: response.request.statusCode,
+                routeLabel: response.request.routeLabel,
+                controllerLabel: response.request.controllerLabel,
+                totalDurationMs: response.request.totalDurationMs,
+                cpuTotalMs: response.request.cpuTotalMs,
+                sqlDurationMs: response.request.sqlDurationMs,
+                callDurationMs: response.request.callDurationMs,
+                renderDurationMs: response.request.renderDurationMs,
+                selfDurationMs: response.request.selfDurationMs,
+                heapDeltaBytes: response.request.heapDeltaBytes,
+            },
+            stages: compactList(response.request.stages, 8),
+            hotCalls: compactList(response.request.hottestCalls, 6),
+            chain: compactList(response.request.chain || [], 8),
+            hotSql: compactList(response.request.hottestSqlQueries, 6).map(compactSql),
+        },
+        nextActions: [
+            {
+                label: 'Diagnose Request',
+                command: `proteum diagnose ${quoteCommandArgument(response.request.path)}`,
+                reason: 'Combine this request with owner, diagnostics, suspects, and logs.',
+            },
+            {
+                label: 'Trace Events',
+                command: `proteum trace show ${quoteCommandArgument(response.request.requestId)} --events`,
+                reason: 'Open raw event detail only if the compact waterfall is insufficient.',
+            },
+        ],
+        fullDetailCommand: `proteum perf request ${quoteCommandArgument(response.request.requestId)} --full`,
+    });
+};
+
 export const run = async () => {
     const action = getAction();
-    const shouldPrintJson = cli.args.json === true;
+    const shouldPrintFull = cli.args.full === true;
+    const shouldPrintHuman = cli.args.human === true;
     const groupBy = typeof cli.args.groupBy === 'string' && cli.args.groupBy ? cli.args.groupBy : 'path';
     const limit =
         typeof cli.args.limit === 'string' && cli.args.limit ? Math.max(1, Number.parseInt(cli.args.limit, 10) || 12) : 12;
@@ -192,12 +293,13 @@ export const run = async () => {
         const response = await requestJson<TPerfTopResponse>(
             `/__proteum/perf/top?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderTop(response));
+        if (shouldPrintHuman) console.log(renderTop(response));
+        else printCompactTop(response);
         return;
     }
 
@@ -212,12 +314,13 @@ export const run = async () => {
                 target: targetWindow,
             }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderCompare(response));
+        if (shouldPrintHuman) console.log(renderCompare(response));
+        else printCompactCompare(response);
         return;
     }
 
@@ -226,12 +329,13 @@ export const run = async () => {
         const response = await requestJson<TPerfMemoryResponse>(
             `/__proteum/perf/memory?${new URLSearchParams({ groupBy, limit: String(limit), since }).toString()}`,
         );
-        if (shouldPrintJson) {
+        if (shouldPrintFull) {
             printJson(response);
             return;
         }
 
-        console.log(renderMemory(response));
+        if (shouldPrintHuman) console.log(renderMemory(response));
+        else printCompactMemory(response);
         return;
     }
 
@@ -241,10 +345,11 @@ export const run = async () => {
     const response = await requestJson<TPerfRequestResponse>(
         `/__proteum/perf/request?${new URLSearchParams({ query: requestTarget }).toString()}`,
     );
-    if (shouldPrintJson) {
+    if (shouldPrintFull) {
         printJson(response);
         return;
     }
 
-    console.log(renderRequest(response));
+    if (shouldPrintHuman) console.log(renderRequest(response));
+    else printCompactRequest(response);
 };

package/cli/commands/runtime.ts

@@ -0,0 +1,234 @@
+import fs from 'fs-extra';
+import got from 'got';
+import path from 'path';
+import { UsageError } from 'clipanion';
+
+import cli from '..';
+import { readProteumManifest } from '../compiler/common/proteumManifest';
+import { listDevSessionInspections, writeMachineDevSessionRecord, type TDevSessionInspection } from '../runtime/devSessions';
+import { inspectDevPort, type TDevPortInspection } from '../runtime/ports';
+import { printAgentResponse, printJson, quoteCommandArgument } from '../utils/agentOutput';
+import type { TDoctorResponse } from '@common/dev/diagnostics';
+import type { TProteumManifest } from '@common/dev/proteumManifest';
+
+type TRuntimeAction = 'status';
+
+const allowedActions = new Set<TRuntimeAction>(['status']);
+
+const getAction = () => {
+    const action = typeof cli.args.action === 'string' && cli.args.action ? cli.args.action : 'status';
+    if (!allowedActions.has(action as TRuntimeAction)) {
+        throw new UsageError(`Unsupported runtime action "${action}". Expected one of: ${[...allowedActions].join(', ')}.`);
+    }
+
+    return action as TRuntimeAction;
+};
+
+const readManifestIfAvailable = (): TProteumManifest | undefined => {
+    const manifestFilepath = path.join(cli.paths.appRoot, '.proteum', 'manifest.json');
+    if (!fs.existsSync(manifestFilepath)) return undefined;
+
+    try {
+        return readProteumManifest(cli.paths.appRoot);
+    } catch {
+        return undefined;
+    }
+};
+
+const getSessionUrl = (inspection: TDevSessionInspection) => {
+    if (!inspection.record) return '';
+    if (inspection.record.publicUrl) return inspection.record.publicUrl.replace(/\/+$/, '');
+    return `http://localhost:${inspection.record.routerPort}`;
+};
+
+const getSessionMcpUrl = (inspection: TDevSessionInspection) => {
+    const sessionUrl = getSessionUrl(inspection);
+    return sessionUrl ? `${sessionUrl}/__proteum/mcp` : '';
+};
+
+const probeDoctor = async (baseUrl: string) => {
+    if (!baseUrl) return { reachable: false, error: 'No dev URL is registered.' };
+
+    try {
+        const response = await got(`${baseUrl}/__proteum/doctor`, {
+            responseType: 'json',
+            retry: { limit: 0 },
+            throwHttpErrors: false,
+            timeout: { request: 1200 },
+        });
+
+        if (response.statusCode >= 400) {
+            return { reachable: false, statusCode: response.statusCode, error: `Doctor returned HTTP ${response.statusCode}.` };
+        }
+
+        const doctor = response.body as TDoctorResponse;
+        return {
+            reachable: true,
+            statusCode: response.statusCode,
+            doctor: doctor.summary,
+        };
+    } catch (error) {
+        return {
+            reachable: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+};
+
+const compactSession = (inspection: TDevSessionInspection) => ({
+    sessionFilePath: inspection.sessionFilePath,
+    live: inspection.live,
+    stale: inspection.stale,
+    invalid: inspection.invalid,
+    parseError: inspection.parseError,
+    pid: inspection.record?.pid,
+    routerPort: inspection.record?.routerPort,
+    publicUrl: inspection.record?.publicUrl,
+    mcpUrl: inspection.record ? getSessionMcpUrl(inspection) : undefined,
+    state: inspection.record?.state,
+    startedAt: inspection.record?.startedAt,
+    updatedAt: inspection.record?.updatedAt,
+});
+
+const createStartDevCommand = (port?: number) =>
+    `proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${port || '<free-port>'}`;
+
+const describePortOwner = (portInspection?: TDevPortInspection) => {
+    if (!portInspection || portInspection.router.available) return '';
+    if (portInspection.router.proteum) {
+        const appLabel =
+            portInspection.router.app?.identifier ||
+            portInspection.router.app?.name ||
+            portInspection.router.app?.appRoot ||
+            'another Proteum app';
+        return `Configured router port ${portInspection.router.port} is already occupied by ${appLabel}.`;
+    }
+
+    return `Configured router port ${portInspection.router.port} is already occupied by a non-Proteum or unrecognized process.`;
+};
+
+const getNextActions = ({
+    health,
+    portInspection,
+    selectedSession,
+}: {
+    health: { reachable: boolean };
+    portInspection?: TDevPortInspection;
+    selectedSession: TDevSessionInspection | undefined;
+}) => {
+    if (!selectedSession?.record || !selectedSession.live) {
+        const portOwner = describePortOwner(portInspection);
+
+        if (portInspection?.router.proteum && portInspection.router.matchesApp) {
+            return [
+                {
+                    label: 'Use Existing Runtime',
+                    command: `proteum diagnose ${quoteCommandArgument('/')} --port ${portInspection.router.port}`,
+                    reason:
+                        'A Proteum runtime for this app already responds on the configured router port, but no tracked session file is live. Do not start a second dev server; use this port for CLI evidence or stop the owning process before starting a tracked session.',
+                },
+            ];
+        }
+
+        const startPort =
+            portInspection && !portInspection.canStartOnConfiguredPort ? portInspection.recommendedPort : portInspection?.router.port;
+
+        return [
+            {
+                label: 'Start Dev',
+                command: createStartDevCommand(startPort),
+                reason: portOwner
+                    ? `${portOwner} Use an alternate free router/HMR port pair; do not probe page bodies to identify port owners.`
+                    : 'Create a tracked dev session before request-time diagnostics.',
+            },
+        ];
+    }
+
+    if (!health.reachable) {
+        return [
+            {
+                label: 'Stop Unreachable Dev',
+                command: `proteum dev stop --session-file ${quoteCommandArgument(selectedSession.sessionFilePath)}`,
+                reason: 'A tracked session exists but the runtime and MCP endpoint are unreachable.',
+            },
+            {
+                label: 'Start Dev',
+                command: createStartDevCommand(portInspection?.recommendedPort),
+                reason: 'Start a fresh tracked session after stopping the unreachable one.',
+            },
+        ];
+    }
+
+    return [
+        {
+            label: 'Diagnose Root',
+            command: `proteum diagnose ${quoteCommandArgument('/')} --port ${selectedSession.record.routerPort}`,
+            reason: 'Use the selected runtime for the smallest request-level diagnostic pass.',
+        },
+    ];
+};
+
+export const run = async () => {
+    const action = getAction();
+    if (action !== 'status') return;
+
+    const manifest = readManifestIfAvailable();
+    const sessions = await listDevSessionInspections({
+        appRoot: cli.paths.appRoot,
+        sessionFilePath: typeof cli.args.sessionFile === 'string' && cli.args.sessionFile ? cli.args.sessionFile : undefined,
+    });
+    const liveSessions = sessions.filter((inspection) => inspection.live && inspection.record);
+    await Promise.allSettled(
+        liveSessions.map((inspection) =>
+            inspection.record ? writeMachineDevSessionRecord(inspection.record) : Promise.resolve(undefined),
+        ),
+    );
+    const selectedSession =
+        liveSessions.find((inspection) => inspection.record?.state === 'ready') || liveSessions[0] || sessions.find((inspection) => inspection.record);
+    const selectedBaseUrl = selectedSession ? getSessionUrl(selectedSession) : '';
+    const health = selectedSession && selectedSession.live ? await probeDoctor(selectedBaseUrl) : { reachable: false, error: 'No live tracked dev session.' };
+    const configuredDevPort = manifest
+        ? await inspectDevPort({
+              appRoot: cli.paths.appRoot,
+              port: manifest.env.resolved.routerPort,
+          })
+        : undefined;
+
+    const payload = {
+        appRoot: cli.paths.appRoot,
+        manifest: manifest
+            ? {
+                  identifier: manifest.app.identity.identifier,
+                  name: manifest.app.identity.name,
+                  routerPort: manifest.env.resolved.routerPort,
+                  diagnostics: {
+                      errors: manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length,
+                      warnings: manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length,
+                  },
+                  counts: {
+                      connectedProjects: manifest.connectedProjects.length,
+                      controllers: manifest.controllers.length,
+                      routes: manifest.routes.client.length + manifest.routes.server.length,
+                  },
+              }
+            : undefined,
+        selected: selectedSession ? compactSession(selectedSession) : undefined,
+        sessions: sessions.map(compactSession),
+        health,
+        configuredDevPort,
+    };
+
+    if (cli.args.full === true) {
+        printJson(payload);
+        return;
+    }
+
+    printAgentResponse({
+        summary: selectedSession
+            ? `${selectedSession.live ? 'live' : 'stale'} dev session on ${selectedSession.record?.routerPort || 'unknown port'}; health=${health.reachable ? 'reachable' : 'unreachable'}`
+            : describePortOwner(configuredDevPort) || 'No tracked Proteum dev session found.',
+        data: payload,
+        nextActions: getNextActions({ health, portInspection: configuredDevPort, selectedSession }),
+        fullDetailCommand: 'proteum runtime status --full',
+    });
+};