proteum 2.1.6 → 2.1.8

package/AGENTS.md

@@ -26,6 +26,9 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 
 - If the user pastes raw errors without asking for a fix, do not implement changes. List likely causes and, for each one, give probability, why, and how to fix it.
 - After implementing a framework feature or change, do not stop at code edits. Boot both reference apps, exercise the affected flow with Playwright or the smallest real Proteum surface, run the relevant `proteum` diagnostics or perf commands, and confirm there is no meaningful regression in runtime behavior, performance, load size, SEO output, or coding-style expectations before finishing.
+- When starting a long-lived reference app dev server for framework work, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
+- Before retrying a boot on the same app, changing ports, or finishing the task, stop every framework-started dev session with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`.
+- If the task changed the dev workflow itself, verify the final cleanup path with `npx proteum dev list --json` before finishing.
 - When you have finished your work, summarize in one top-level short (up to 100 characters) sentence the changes you made since the beginning of the conversation. Output as "Commit message".
 
 ## Core Changes
@@ -36,6 +39,7 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
   - `/Users/gaetan/Desktop/Projets/unique.domains/website`
 - Inspect how both apps currently use the touched feature, runtime, API, compiler behavior, or generated output before proposing or implementing changes.
 - Keep the developer-facing contract synchronized when framework work changes CLI commands, profiler capabilities, or the `proteum dev` banner. Update the live surfaces together in the same pass: CLI command/help definitions, profiler panels and dev-only endpoints, banner text/examples, and the most relevant agent docs that describe them, especially `AGENTS.md`, `agents/project/AGENTS.md`, `agents/project/diagnostics.md`, and any narrower `agents/project/**/AGENTS.md` file that mentions the changed workflow.
+- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner, while only `proteum dev` clears the interactive terminal before rendering and exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI.
 - Keep core changes aligned with the explicit controller/page architecture in `agents/project/AGENTS.md`.
 - Prefer removing framework magic when the same result can be expressed with explicit contracts, generated code, or typed context.
 - Apply the pruning rules from `agents/project/optimizations.md`, especially for webpack plugins, Babel plugins, aliases, helpers, runtime services, and npm packages that are not meaningfully used by both apps.
@@ -54,9 +58,10 @@ After those optimization concerns, preserve explicit, typed, machine-readable co
 
 Do not stop at static analysis for routing, controllers, generated code, SSR, client runtime, services, webpack, Babel, or emitted assets.
 
-- Run `npx proteum dev --no-cache --port 3xxx` in both reference apps on explicit ports.
+- Run `npx proteum dev --no-cache --replace-existing --session-file var/run/proteum/dev/framework-<app>.json --port 3xxx` in both reference apps on explicit ports.
 - When validating a concrete route, controller path, or failing page on a running dev server, prefer `proteum diagnose <path> --port <port>` first. Use raw `proteum trace ...` output when you need lower-level event detail beyond the diagnose summary.
 - When the issue is latency, CPU, SQL cost, render cost, or memory drift, inspect `proteum perf top`, `proteum perf request`, `proteum perf compare`, or `proteum perf memory` against the running dev server before adding custom instrumentation.
+- When a framework change can affect shipped client code size, run `proteum build --prod --analyze` for static bundle artifacts or `proteum build --prod --analyze --analyze-serve --analyze-port auto` when you need a local analyzer URL.
 - For protected browser or API flows in dev, prefer `npx proteum session <email> --role <role>` to mint a dev auth cookie instead of automating the login UI. Use the login UI only when login itself is the feature under test.
 - For request-time behavior, arm traces with `proteum trace arm --capture deep`, reproduce once, then inspect `proteum trace latest` or `proteum trace show <requestId>`.
 - When the framework-facing workflow itself changed, verify the CLI surface too with `proteum verify framework-change --crosspath-port <port> --product-port <port> --website-port <port>`.

package/README.md

@@ -323,7 +323,7 @@ Proteum ships with a compact CLI focused on the real app lifecycle:
 | `proteum typecheck` | Refresh generated typings, then run TypeScript |
 | `proteum lint` | Run ESLint for the current app |
 | `proteum check` | Refresh, typecheck, and lint in one command |
-| `proteum build --prod` | Produce the production server and client bundles into `bin/` |
+| `proteum build --prod` | Produce the production server and client bundles into `bin/`, with optional static or served bundle analysis |
 | `proteum connect` | Inspect connected-project sources, env, cached contracts, and imported controllers |
 | `proteum doctor` | Inspect manifest diagnostics |
 | `proteum explain` | Explain routes, controllers, services, layouts, conventions, env, and connected projects |
@@ -343,8 +343,12 @@ proteum dev
 proteum refresh
 proteum check
 proteum build --prod
+proteum build --prod --analyze
+proteum build --prod --analyze --analyze-serve --analyze-port auto
 ```
 
+Every human-facing Proteum CLI run prints the welcome banner. `proteum dev` is the only command that clears the interactive terminal before rendering its live session UI, and its banner exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys.
+
 Useful inspection commands:
 
 ```bash

package/agents/project/AGENTS.md

@@ -16,9 +16,13 @@ Coding style source of truth: project-root `CODING_STYLE.md`.
 - Follow project-root `diagnostics.md` for diagnosis, runtime reproduction, temporary instrumentation, error-solving workflow, and verification method selection.
 - For new app or artifact boilerplate, prefer `npx proteum init ...` and `npx proteum create ...` before creating files by hand. Use `--dry-run --json` when an agent needs a machine-readable plan before writing files.
 - After running `npx proteum create ...`, adapt the generated code to the real feature instead of leaving placeholder logic in place.
+- When starting a long-lived dev server for an agent task, prefer `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically later.
+- Do not start a second `proteum dev` server for the same app and port until the earlier tracked session has been stopped or replaced.
 - When framework work changes Proteum CLI commands, profiler panels/features, or the `proteum dev` banners, keep this file, project-root `diagnostics.md`, and any narrower area `AGENTS.md` that mentions the same workflow aligned with the live framework behavior in the same pass.
+- Current CLI banner contract: every human-facing Proteum CLI run prints the welcome banner, while only `proteum dev` clears the interactive terminal before rendering and exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI.
 - Before finishing, double-check the touched files and generated output against the applicable optimization, diagnostics, and coding-style sources: project-root `optimizations.md`, project-root `diagnostics.md`, project-root `CODING_STYLE.md`, and any narrower area `AGENTS.md`.
 - After implementing any feature or behavior change, always verify it on a running app before finishing: start the server, exercise the affected flow with Playwright or the smallest real runtime or `npx proteum` surface, run the relevant diagnostics or perf commands, and confirm there is no meaningful regression in behavior, performance, bundle/load size, SEO output, or coding style.
+- Before finishing a task, stop every `proteum dev` session started during the task and confirm cleanup with `npx proteum dev list --json` or an explicit `npx proteum dev stop --session-file <path>`.
 - When you have finished your work, summarize in one top-level short (up to 100 characters) sentence ALL the changes you made since the beginning of the WHOLE conversation. Output as "Commit message".
 
 ## Project Shape
@@ -98,6 +102,8 @@ Prefer structured CLI surfaces over re-deriving framework facts from source:
 - `npx proteum command ...`
 - `npx proteum session ...`
 - `npx proteum create ... --dry-run --json`
+- `npx proteum dev list --json`
+- `npx proteum dev stop --session-file <path>`
 
 Prefer scaffold commands before hand-writing boilerplate:
 
@@ -224,7 +230,7 @@ Verify at the correct layer:
 - router or plugin changes: verify request context, auth, redirects, metrics, and validation on a running app
 - For trace-first reproduction, session-based auth setup, temporary logs, and post-fix surface checks, follow project-root `diagnostics.md`.
 
-Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
+Useful commands: `npx proteum init <dir> --name <name>`, `npx proteum create <kind> <target>`, `proteum dev`, `proteum dev list --json`, `proteum dev stop --session-file <path>`, `npx proteum refresh`, `npx proteum typecheck`, `npx proteum lint`, `npx proteum check`, `npx proteum build prod`, `npx proteum build --prod --analyze`, `npx proteum build --prod --analyze --analyze-serve --analyze-port auto`, `npx proteum perf top`, `npx proteum perf request <requestId|path>`, `npx proteum perf compare --baseline yesterday --target today`, `npx proteum command <path>`, `npx proteum session <email> --role <role>`.
 
 ## High-Impact Files
 

package/agents/project/diagnostics.md

@@ -12,10 +12,13 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 
 ## Runtime Diagnostics
 
+- For long-lived dev reproductions, start the app with `npx proteum dev --session-file <path> --replace-existing --port <port>` so the session can be listed and stopped deterministically after the repro.
+- Human-facing Proteum CLI runs now print the welcome banner, but only `npx proteum dev` clears the interactive terminal before rendering; keep that in mind when capturing or comparing command logs during diagnosis.
 - For request-time issues in dev, start with `npx proteum diagnose <path> --port <port>` when you have a concrete failing route, page, controller path, or request target. It combines owner lookup, manifest diagnostics, contract diagnostics, matching trace data, and buffered server logs in one pass.
 - For connected-project failures, confirm the consumer app resolves the expected `connect.<Namespace>.source` and `connect.<Namespace>.urlInternal` values, the producer app exposes `GET /api/__proteum/connected/ping`, and the imported controller entries show `scope=connected` in `proteum explain`.
 - Use `npx proteum explain owner <query>` when you need a fast ownership graph for a route, controller path, source file, or generated artifact before reading code.
 - For performance issues or regressions in dev, use `npx proteum perf top --since <window>` to rank hot paths, `npx proteum perf request <requestId|path>` for one request waterfall, `npx proteum perf compare --baseline <window> --target <window>` for regressions, and `npx proteum perf memory --since <window>` for heap or RSS drift.
+- For bundle-size inspection, use `npx proteum build --prod --analyze` to emit `bin/bundle-analysis/client.html` and `client-stats.json`, or add `--analyze-serve --analyze-port auto` when you want a local analyzer URL instead of a static HTML file.
 - For request-time issues in dev, inspect traces before adding logs when the diagnose surface is still too coarse.
 - If a server is already running on the default port from `PORT` or `./.proteum/manifest.json`, inspect existing traces before reproducing the issue.
 - If existing traces are insufficient, arm `npx proteum trace arm --capture deep`, reproduce once, then inspect the new request with `npx proteum trace latest` or `npx proteum trace show <requestId>`.
@@ -47,6 +50,7 @@ This file is the canonical source of truth for diagnostics, temporary instrument
 - For browser regressions, prefer targeted Playwright coverage and inspect failure artifacts such as screenshots, videos, `error-context.md`, and Playwright traces.
 - Treat server startup failures, runtime errors, browser console errors or warnings, and Playwright failures as blocking unless they are clearly unrelated to the change.
 - When the touched surface can affect coding-style enforcement, run the smallest relevant project check such as `npx proteum lint` or `npx proteum check` before finishing.
+- If the task started any long-lived `proteum dev` server, stop it explicitly with `npx proteum dev stop --session-file <path>` or `npx proteum dev stop --all --stale`, then confirm the remaining tracked sessions with `npx proteum dev list --json`.
 - Add `data-testid` when stable selectors are missing instead of relying on brittle text or DOM-shape selectors.
 - If an isolated test misses prerequisite state, run the smallest broader scope that reproduces the real setup.
 - After a fix, re-check traces, rendered HTML, browser console, and server output when those surfaces were part of the original failure.

package/agents/project/optimizations.md

@@ -13,6 +13,7 @@ When tradeoffs exist inside optimization work, optimize in this order:
 ## Bundle Size And Runtime Cost
 
 - Reduce shipped client bundle size and unnecessary runtime code.
+- When you need evidence for a bundle-size regression, run `npx proteum build --prod --analyze` for static artifacts or `npx proteum build --prod --analyze --analyze-serve --analyze-port auto` for a local analyzer URL.
 - Before inventing a new helper, runtime, plugin, abstraction, primitive, parser, formatter, SDK wrapper, or build-time tool, first check whether the repo already depends on a suitable package.
 - If the repo does not already depend on one, search npm before writing a custom implementation.
 - Prefer established, flexible, well-typed, widely adopted, actively maintained packages.

package/cli/bin.js

@@ -2,12 +2,6 @@
 
 const path = require('path');
 
-const clearInteractiveConsole = () => {
-    if (process.stdout.isTTY !== true || process.env.TERM === 'dumb') return;
-
-    process.stdout.write('\x1B[2J\x1B[3J\x1B[H');
-};
-
 /*
     Why this exists (npm i vs npm link difference)
 
@@ -36,8 +30,6 @@ if (!process.env.TS_NODE_IGNORE) {
 process.env.TS_NODE_PROJECT = path.join(__dirname, 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 
-clearInteractiveConsole();
-
 require('ts-node/register/transpile-only');
 
 const { runCli } = require('./index.ts');

package/cli/commands/build.ts

@@ -2,6 +2,8 @@
 - DEPENDANCES
 ----------------------------------*/
 
+import { UsageError } from 'clipanion';
+
 // Core
 import cli from '..';
 import { app } from '../app';
@@ -10,15 +12,23 @@ import { app } from '../app';
 import Compiler from '../compiler';
 import type { TCompileMode } from '../compiler/common';
 import {
+    consumeClientBundleAnalysisServerUrl,
+    getBundleAnalysisMode,
+    getBundleAnalysisServerHost,
+    getBundleAnalysisServerPort,
     getClientBundleAnalysisReportPaths,
+    hasBundleAnalysisServerOverrides,
     waitForClientBundleAnalysisArtifacts,
 } from '../compiler/common/bundleAnalysis';
 import { refreshGeneratedTypings, runAppTypecheck } from '../utils/check';
 import { renderRows } from '../presentation/layout';
 import { renderStep, renderSuccess, renderTitle } from '../presentation/ink';
 
-const allowedBuildArgs = new Set(['prod', 'cache', 'analyze', 'strict']);
+const allowedBuildArgs = new Set(['prod', 'cache', 'analyze', 'analyzeServe', 'strict']);
 type TBuildMultiCompiler = Awaited<ReturnType<Compiler['create']>>;
+type TBuildAnalysisResult =
+    | { mode: 'static'; reportPath: string; statsPath: string }
+    | { mode: 'server'; statsPath: string; url?: string };
 
 /*----------------------------------
 - COMMAND
@@ -30,7 +40,9 @@ function resolveBuildMode(): TCompileMode {
 
     const invalidArgs = enabledArgs.filter((arg) => !allowedBuildArgs.has(arg));
     if (invalidArgs.length > 0)
-        throw new Error(`Unknown build argument(s): ${invalidArgs.join(', ')}. Allowed values: prod, cache, analyze, strict.`);
+        throw new Error(
+            `Unknown build argument(s): ${invalidArgs.join(', ')}. Allowed values: prod, cache, analyze, analyzeServe, strict.`,
+        );
 
     const requestedModes = enabledArgs.filter((arg): arg is TCompileMode => arg === 'prod');
     if (requestedModes.length > 1)
@@ -39,6 +51,19 @@ function resolveBuildMode(): TCompileMode {
     return requestedModes[0] ?? 'prod';
 }
 
+function assertValidBuildAnalyzerArgs() {
+    const analyzeEnabled = cli.args.analyze === true;
+    const analyzeServeEnabled = cli.args.analyzeServe === true;
+
+    if (!analyzeEnabled && (analyzeServeEnabled || hasBundleAnalysisServerOverrides())) {
+        throw new UsageError('Analyzer server flags require `--analyze`.');
+    }
+
+    if (!analyzeServeEnabled && hasBundleAnalysisServerOverrides()) {
+        throw new UsageError('`--analyze-host` and `--analyze-port` require `--analyze-serve`.');
+    }
+}
+
 const closeMultiCompiler = async (multiCompiler: TBuildMultiCompiler) =>
     await new Promise<void>((resolve, reject) => {
         multiCompiler.close((error) => {
@@ -54,7 +79,11 @@ const closeMultiCompiler = async (multiCompiler: TBuildMultiCompiler) =>
 export const run = async (): Promise<void> => {
     const mode = resolveBuildMode();
     const strict = cli.args.strict === true;
-    let analysisArtifacts: { reportPath: string; statsPath: string } | undefined;
+    assertValidBuildAnalyzerArgs();
+
+    const analyze = cli.args.analyze === true;
+    const analysisMode = analyze ? getBundleAnalysisMode() : undefined;
+    let analysisResult: TBuildAnalysisResult | undefined;
 
     console.info(
         [
@@ -69,7 +98,14 @@ export const run = async (): Promise<void> => {
                 { label: 'mode', value: mode },
                 { label: 'strict', value: strict ? 'enabled' : 'disabled' },
                 { label: 'cache', value: cli.args.cache === true ? 'enabled' : 'disabled' },
-                { label: 'analyze', value: cli.args.analyze === true ? 'enabled' : 'disabled' },
+                { label: 'analyze', value: analyze ? 'enabled' : 'disabled' },
+                ...(analyze ? [{ label: 'analyze mode', value: analysisMode || 'static' }] : []),
+                ...(analysisMode === 'server'
+                    ? [
+                          { label: 'analyze host', value: getBundleAnalysisServerHost() },
+                          { label: 'analyze port', value: String(getBundleAnalysisServerPort()) },
+                      ]
+                    : []),
                 { label: 'output', value: 'bin/' },
             ]),
         ].join('\n\n'),
@@ -103,10 +139,11 @@ export const run = async (): Promise<void> => {
                     return;
                 }
 
-                if (cli.args.analyze === true) {
+                if (analysisMode === 'static') {
                     waitForClientBundleAnalysisArtifacts(app, 'bin')
                         .then(() => {
-                            analysisArtifacts = getClientBundleAnalysisReportPaths(app, 'bin');
+                            const { reportPath, statsPath } = getClientBundleAnalysisReportPaths(app, 'bin');
+                            analysisResult = { mode: 'static', reportPath, statsPath };
                             resolve();
                         })
                         .catch(reject);
@@ -125,11 +162,25 @@ export const run = async (): Promise<void> => {
 
     if (buildError) throw buildError;
 
-    if (analysisArtifacts !== undefined) {
+    if (analysisMode === 'server') {
+        const { statsPath } = getClientBundleAnalysisReportPaths(app, 'bin');
+        analysisResult = {
+            mode: 'server',
+            statsPath,
+            url: consumeClientBundleAnalysisServerUrl(),
+        };
+    }
+
+    if (analysisResult !== undefined) {
         console.info(
             renderRows([
-                { label: 'report', value: analysisArtifacts.reportPath },
-                { label: 'stats', value: analysisArtifacts.statsPath },
+                ...(analysisResult.mode === 'static' ? [{ label: 'report', value: analysisResult.reportPath }] : []),
+                ...(analysisResult.mode === 'server'
+                    ? [
+                          { label: 'server', value: analysisResult.url || 'Analyzer server started. See the analyzer log for the URL.' },
+                      ]
+                    : []),
+                { label: 'stats', value: analysisResult.statsPath },
             ]),
         );
     }

package/cli/commands/dev.ts

@@ -23,6 +23,19 @@ import Compiler from '../compiler';
 import { createDevEventServer } from './devEvents';
 import { ensureProjectAgentSymlinks } from '../utils/agents';
 import { renderDevSession, renderServerReadyBanner, renderDevShutdownBanner } from '../presentation/devSession';
+import { clearInteractiveConsole } from '../presentation/welcome';
+import {
+    createDevSessionRecord,
+    inspectDevSessionFile,
+    listDevSessionInspections,
+    removeDevSessionRecord,
+    removeDevSessionRecordSync,
+    resolveDevSessionFilePath,
+    stopDevSessionFile,
+    updateDevSessionRecord,
+    type TDevSessionInspection,
+    type TStopDevSessionResult,
+} from '../runtime/devSessions';
 import { logVerbose } from '../runtime/verbose';
 
 // Core
@@ -51,6 +64,8 @@ const hotReloadableRoots = [() => app.paths.root, () => cli.paths.core.root];
 let cp: ChildProcess | undefined = undefined;
 let devSessionStopping = false;
 let appProcessOperation: Promise<void> = Promise.resolve();
+let currentDevSessionFilePath: string | undefined = undefined;
+let devSessionExitCleanupRegistered = false;
 type TDevWatching = ReturnType<Awaited<ReturnType<Compiler['create']>>['watch']>;
 type TIndexedSourceWatching = { close: () => Promise<void> };
 
@@ -122,6 +137,7 @@ const createIgnoredWatchMatcher = (outputPaths: string[]) => (watchPath: string)
 
     return ignoredWatchPathPatterns.test(normalizedWatchPath);
 };
+
 const getDevAppName = (app: App) =>
     app.identity.web?.fullTitle || app.identity.web?.title || app.identity.name || app.packageJson.name || app.paths.root;
 
@@ -159,6 +175,190 @@ const signalAppProcess = (child: ChildProcess, signal: NodeJS.Signals) => {
     }
 };
 
+const getRequestedSessionFilePath = () =>
+    typeof cli.args.sessionFile === 'string' && cli.args.sessionFile.trim() ? cli.args.sessionFile : undefined;
+
+const getResolvedDevSessionFilePath = () =>
+    resolveDevSessionFilePath({
+        appRoot: app.paths.root,
+        port: app.env.router.port,
+        sessionFilePath: getRequestedSessionFilePath(),
+    });
+
+const registerDevSessionExitCleanup = () => {
+    if (devSessionExitCleanupRegistered) return;
+
+    devSessionExitCleanupRegistered = true;
+    process.once('exit', () => {
+        if (!currentDevSessionFilePath) return;
+        removeDevSessionRecordSync(currentDevSessionFilePath);
+    });
+};
+
+const updateCurrentDevSession = async (patch: { publicUrl?: string; state?: 'starting' | 'ready' }) => {
+    if (!currentDevSessionFilePath) return;
+
+    await updateDevSessionRecord({
+        sessionFilePath: currentDevSessionFilePath,
+        patch,
+    });
+};
+
+const cleanupCurrentDevSession = async () => {
+    if (!currentDevSessionFilePath) return;
+
+    const sessionFilePath = currentDevSessionFilePath;
+    currentDevSessionFilePath = undefined;
+    await removeDevSessionRecord(sessionFilePath);
+};
+
+const describeInspection = (inspection: TDevSessionInspection) => {
+    if (!inspection.record) {
+        return [
+            'stale invalid',
+            inspection.sessionFilePath,
+            inspection.parseError || 'Unreadable session file.',
+        ].join(' | ');
+    }
+
+    const parts = [
+        inspection.live ? 'live' : 'stale',
+        inspection.record.state,
+        `pid ${inspection.record.pid}`,
+        `port ${inspection.record.routerPort}`,
+    ];
+
+    if (inspection.record.publicUrl) parts.push(inspection.record.publicUrl);
+    parts.push(inspection.sessionFilePath);
+
+    return parts.join(' | ');
+};
+
+const describeStopResult = (result: TStopDevSessionResult) => {
+    if (!result.matched) return `missing | ${result.sessionFilePath}`;
+    if (result.invalid)
+        return `removed stale invalid | ${result.sessionFilePath} | ${result.parseError || 'Unreadable session file.'}`;
+    if (result.removed && result.stopped && !result.live) {
+        return [
+            result.pid !== null ? `stopped pid ${result.pid}` : 'stopped',
+            result.routerPort !== null ? `port ${result.routerPort}` : '',
+            result.publicUrl,
+            result.sessionFilePath,
+        ]
+            .filter(Boolean)
+            .join(' | ');
+    }
+
+    return [
+        'failed',
+        result.pid !== null ? `pid ${result.pid}` : '',
+        result.routerPort !== null ? `port ${result.routerPort}` : '',
+        result.publicUrl,
+        result.sessionFilePath,
+    ]
+        .filter(Boolean)
+        .join(' | ');
+};
+
+const printJson = (payload: unknown) => {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+};
+
+const runListCommand = async () => {
+    const inspections = await listDevSessionInspections({
+        appRoot: app.paths.root,
+        sessionFilePath: getRequestedSessionFilePath(),
+    });
+    const filteredInspections = cli.args.stale === true ? inspections.filter((inspection) => inspection.stale) : inspections;
+
+    if (cli.args.json === true) {
+        printJson({
+            appRoot: app.paths.root,
+            sessions: filteredInspections.map((inspection) => ({
+                sessionFilePath: inspection.sessionFilePath,
+                live: inspection.live,
+                stale: inspection.stale,
+                invalid: inspection.invalid,
+                parseError: inspection.parseError,
+                record: inspection.record,
+            })),
+        });
+        return;
+    }
+
+    if (filteredInspections.length === 0) {
+        console.info(`No Proteum dev sessions found for ${app.paths.root}.`);
+        return;
+    }
+
+    console.info(filteredInspections.map(describeInspection).join('\n'));
+};
+
+const runStopCommand = async () => {
+    const stopAll = cli.args.all === true;
+    const filterStale = cli.args.stale === true;
+
+    const targetSessionFilePaths = stopAll
+        ? (await listDevSessionInspections({
+              appRoot: app.paths.root,
+              sessionFilePath: getRequestedSessionFilePath(),
+          }))
+              .filter((inspection) => !filterStale || inspection.stale)
+              .map((inspection) => inspection.sessionFilePath)
+        : [getResolvedDevSessionFilePath()];
+
+    const results = await Promise.all(targetSessionFilePaths.map((sessionFilePath) => stopDevSessionFile(sessionFilePath)));
+    const failedResults = results.filter((result) => result.matched && !result.stopped);
+
+    if (cli.args.json === true) {
+        printJson({ appRoot: app.paths.root, results });
+    } else if (results.length === 0) {
+        console.info(`No Proteum dev sessions matched for ${app.paths.root}.`);
+    } else {
+        console.info(results.map(describeStopResult).join('\n'));
+    }
+
+    if (failedResults.length > 0) {
+        process.exitCode = 1;
+    }
+};
+
+const ensureDevSessionSlot = async () => {
+    const sessionFilePath = getResolvedDevSessionFilePath();
+    const existingInspection = await inspectDevSessionFile(sessionFilePath);
+
+    if (existingInspection?.record && existingInspection.live && existingInspection.record.pid !== process.pid) {
+        if (cli.args.replaceExisting !== true) {
+            throw new Error(
+                `A Proteum dev session is already registered at ${sessionFilePath} (pid ${existingInspection.record.pid}, port ${existingInspection.record.routerPort}). ` +
+                    'Use `proteum dev stop` or restart with `proteum dev --replace-existing`.',
+            );
+        }
+
+        const stopResult = await stopDevSessionFile(sessionFilePath);
+        if (!stopResult.stopped) {
+            throw new Error(`Could not stop the existing Proteum dev session registered at ${sessionFilePath}.`);
+        }
+    } else if (existingInspection) {
+        await stopDevSessionFile(sessionFilePath);
+    }
+
+    currentDevSessionFilePath = sessionFilePath;
+    registerDevSessionExitCleanup();
+    await fs.ensureDir(path.dirname(sessionFilePath));
+    await fs.writeJson(
+        sessionFilePath,
+        createDevSessionRecord({
+            appRoot: app.paths.root,
+            port: app.env.router.port,
+            sessionFilePath,
+        }),
+        { spaces: 2 },
+    );
+
+    logVerbose(`Registered Proteum dev session at ${sessionFilePath}.`);
+};
+
 async function startApp(app: App) {
     await runSerializedAppProcessOperation(async () => {
         if (devSessionStopping) return;
@@ -166,6 +366,7 @@ async function startApp(app: App) {
         await stopAppInternal('Restart asked');
         if (devSessionStopping) return;
 
+        await updateCurrentDevSession({ state: 'starting', publicUrl: '' });
         logVerbose('Launching new server ...');
         cp = spawn('node', ['--preserve-symlinks', app.outputPath('dev') + '/server.js'], {
             // stdin, stdout, stderr
@@ -174,14 +375,24 @@ async function startApp(app: App) {
         });
 
         const child = cp;
+        let childReady = false;
+
+        child.on('exit', (code, signal) => {
+            const isCurrentChild = cp === child;
+            if (isCurrentChild) cp = undefined;
+            if (!isCurrentChild || devSessionStopping || childReady) return;
 
-        child.on('exit', () => {
-            if (cp === child) cp = undefined;
+            console.error(
+                `Proteum dev server exited before reporting ready.${code !== null ? ` Exit code: ${code}.` : ''}${signal ? ` Signal: ${signal}.` : ''}`,
+            );
+            process.exit(code && code !== 0 ? code : 1);
         });
 
         child.on('message', (message: unknown) => {
             if (isServerReadyMessage(message)) {
+                childReady = true;
                 void (async () => {
+                    await updateCurrentDevSession({ publicUrl: message.publicUrl, state: 'ready' });
                     console.info(
                         await renderServerReadyBanner({
                             appName: getDevAppName(app),
@@ -342,12 +553,11 @@ const createIndexedSourceWatching = ({
     };
 };
 
-/*----------------------------------
-- MAIN PROCESS
-----------------------------------*/
-export const run = async () => {
+const runDevLoop = async () => {
     devSessionStopping = false;
+    clearInteractiveConsole();
     ensureProjectAgentSymlinks({ appRoot: app.paths.root, coreRoot: cli.paths.core.root });
+    await ensureDevSessionSlot();
 
     const devEventServer = await createDevEventServer(app.env.router.port + 1);
     app.devEventPort = devEventServer.port;
@@ -463,6 +673,7 @@ export const run = async () => {
             await stopApp(reason);
             await cleanupPersistedDevTraces(app);
             await devEventServer.close();
+            await cleanupCurrentDevSession();
             console.info(await renderDevShutdownBanner());
         })();
 
@@ -499,3 +710,22 @@ export const run = async () => {
     process.once('SIGTERM', () => exitAfterShutdown('SIGTERM', 0));
     process.once('SIGHUP', () => exitAfterShutdown('SIGHUP', 0));
 };
+
+/*----------------------------------
+- MAIN PROCESS
+----------------------------------*/
+export const run = async () => {
+    const action = typeof cli.args.action === 'string' ? cli.args.action : 'start';
+
+    if (action === 'list') {
+        await runListCommand();
+        return;
+    }
+
+    if (action === 'stop') {
+        await runStopCommand();
+        return;
+    }
+
+    await runDevLoop();
+};

package/cli/compiler/artifacts/manifest.ts

@@ -5,6 +5,7 @@ import app from '../../app';
 import cli from '../..';
 import { inspectProteumEnv } from '../../../common/env/proteumEnv';
 import { reservedRouteSetupKeys, routeSetupOptionKeys } from '../../../common/router/pageSetup';
+import { getProjectInstructionGitignoreEntries } from '../../utils/agents';
 import {
     TProteumManifest,
     TProteumManifestCommand,
@@ -39,6 +40,10 @@ const collectManifestDiagnostics = ({
     routes: TProteumManifest['routes'];
 }) => {
     const diagnostics: TProteumManifestDiagnostic[] = [];
+    const expectedGitignoreEntries = [
+        ...requiredGitignoreEntries,
+        ...getProjectInstructionGitignoreEntries({ coreRoot: cli.paths.core.root }),
+    ];
 
     const pushDiagnostic = (diagnostic: TProteumManifestDiagnostic) => {
         diagnostics.push(diagnostic);
@@ -224,7 +229,7 @@ const collectManifestDiagnostics = ({
         pushDiagnostic({
             level: 'warning',
             code: 'app.gitignore-missing',
-            message: `Missing .gitignore. Proteum generated output should ignore ${requiredGitignoreEntries.join(', ')}.`,
+            message: `Missing .gitignore. Proteum-managed paths should ignore ${expectedGitignoreEntries.join(', ')}.`,
             filepath: gitignoreFilepath,
         });
     } else {
@@ -236,14 +241,14 @@ const collectManifestDiagnostics = ({
                 .map(normalizeGitignoreEntry),
         );
 
-        for (const requiredEntry of requiredGitignoreEntries) {
+        for (const requiredEntry of expectedGitignoreEntries) {
             const normalizedRequiredEntry = normalizeGitignoreEntry(requiredEntry);
             if (entries.has(normalizedRequiredEntry)) continue;
 
             pushDiagnostic({
                 level: 'warning',
                 code: 'app.gitignore-generated-entry-missing',
-                message: `Add "${requiredEntry}" to .gitignore so Proteum generated output stays untracked.`,
+                message: `Add "${requiredEntry}" to .gitignore so Proteum-managed paths stay untracked.`,
                 filepath: gitignoreFilepath,
             });
         }