proteum 2.3.0 → 2.4.2

package/cli/runtime/ports.ts

@@ -0,0 +1,151 @@
+import net from 'net';
+import path from 'path';
+
+import fs from 'fs-extra';
+import got from 'got';
+
+export type TProteumRuntimePortProbe = {
+    app?: {
+        appRoot?: string;
+        identifier?: string;
+        name?: string;
+    };
+    available: boolean;
+    error?: string;
+    listening: boolean;
+    matchesApp: boolean;
+    port: number;
+    proteum: boolean;
+    publicUrl: string;
+    statusCode?: number;
+};
+
+export type TDevPortInspection = {
+    canStartOnConfiguredPort: boolean;
+    hmr: {
+        available: boolean;
+        port: number;
+    };
+    recommendedPort?: number;
+    router: TProteumRuntimePortProbe;
+};
+
+const normalizePath = (value: string) => {
+    const resolved = path.resolve(value);
+
+    try {
+        return path.normalize(fs.realpathSync(resolved));
+    } catch {
+        return path.normalize(resolved);
+    }
+};
+
+export const isTcpPortAvailable = async (port: number) =>
+    await new Promise<boolean>((resolve) => {
+        const server = net.createServer();
+
+        server.once('error', () => {
+            resolve(false);
+        });
+
+        server.once('listening', () => {
+            server.close(() => resolve(true));
+        });
+
+        server.listen(port, '127.0.0.1');
+    });
+
+export const areTcpPortsAvailable = async (ports: number[]) => {
+    const availability = await Promise.all(ports.map((port) => isTcpPortAvailable(port)));
+    return availability.every(Boolean);
+};
+
+export const findAvailableDevPort = async (startPort: number, { maxOffset = 30 }: { maxOffset?: number } = {}) => {
+    const normalizedStartPort = Math.max(1, Math.floor(startPort));
+
+    for (let port = normalizedStartPort; port <= normalizedStartPort + maxOffset; port += 1) {
+        if (await areTcpPortsAvailable([port, port + 1])) return port;
+    }
+
+    return undefined;
+};
+
+export const probeProteumRuntimePort = async ({
+    appRoot,
+    port,
+}: {
+    appRoot: string;
+    port: number;
+}): Promise<TProteumRuntimePortProbe> => {
+    const publicUrl = `http://localhost:${port}`;
+    const available = await isTcpPortAvailable(port);
+
+    if (available) {
+        return {
+            available: true,
+            listening: false,
+            matchesApp: false,
+            port,
+            proteum: false,
+            publicUrl,
+        };
+    }
+
+    try {
+        const response = await got(`http://127.0.0.1:${port}/__proteum/explain?section=app`, {
+            responseType: 'json',
+            retry: { limit: 0 },
+            throwHttpErrors: false,
+            timeout: { request: 700 },
+        });
+        const body = response.body as { app?: { root?: unknown; identity?: { identifier?: unknown; name?: unknown } } };
+        const root = typeof body.app?.root === 'string' ? body.app.root : undefined;
+        const identifier = typeof body.app?.identity?.identifier === 'string' ? body.app.identity.identifier : undefined;
+        const name = typeof body.app?.identity?.name === 'string' ? body.app.identity.name : undefined;
+        const proteum = response.statusCode < 400 && Boolean(root || identifier || name);
+
+        return {
+            app: proteum ? { appRoot: root, identifier, name } : undefined,
+            available: false,
+            error: proteum ? undefined : `Proteum explain endpoint returned HTTP ${response.statusCode}.`,
+            listening: true,
+            matchesApp: Boolean(root && normalizePath(root) === normalizePath(appRoot)),
+            port,
+            proteum,
+            publicUrl,
+            statusCode: response.statusCode,
+        };
+    } catch (error) {
+        return {
+            available: false,
+            error: error instanceof Error ? error.message : String(error),
+            listening: true,
+            matchesApp: false,
+            port,
+            proteum: false,
+            publicUrl,
+        };
+    }
+};
+
+export const inspectDevPort = async ({
+    appRoot,
+    port,
+}: {
+    appRoot: string;
+    port: number;
+}): Promise<TDevPortInspection> => {
+    const router = await probeProteumRuntimePort({ appRoot, port });
+    const hmr = {
+        port: port + 1,
+        available: await isTcpPortAvailable(port + 1),
+    };
+    const canStartOnConfiguredPort = router.available && hmr.available;
+
+    return {
+        canStartOnConfiguredPort,
+        hmr,
+        recommendedPort: canStartOnConfiguredPort ? port : await findAvailableDevPort(port + 1),
+        router,
+    };
+};

package/cli/utils/agents.ts

@@ -6,12 +6,13 @@
 import fs from 'fs-extra';
 import path from 'path';
 import { logVerbose } from '../runtime/verbose';
+import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSummary } from './appRoots';
 
 /*----------------------------------
 - TYPES
 ----------------------------------*/
 
-type TProjectInstructionArgs = { coreRoot: string };
+type TProjectInstructionArgs = { appRoot?: string; coreRoot: string; includeMonorepoRegistry?: boolean; monorepoRoot?: string };
 type TConfigureProjectAgentInstructionsArgs = {
     appRoot: string;
     coreRoot: string;
@@ -61,6 +62,7 @@ const managedInstructionSectionEnd = '<!-- proteum-instructions:end -->';
 const managedInstructionSectionIntro = 'This section is managed by `proteum configure agents`.';
 
 const sharedRootDocumentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: 'DOCUMENTATION.md', content: 'source' },
     { projectPath: 'CODING_STYLE.md', content: 'source' },
     { projectPath: 'diagnostics.md', content: 'source' },
     { projectPath: 'optimizations.md', content: 'source' },
@@ -73,7 +75,8 @@ const sharedAppAreaAgentInstructionDefinitions: TAgentInstructionDefinition[] =
     { projectPath: path.join('server', 'routes', 'AGENTS.md'), content: 'source' },
 ];
 
-const sharedE2eAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+const sharedTestAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
+    { projectPath: path.join('tests', 'AGENTS.md'), ensureParentDir: true, content: 'source' },
     { projectPath: path.join('tests', 'e2e', 'AGENTS.md'), ensureParentDir: true, content: 'source' },
     { projectPath: path.join('tests', 'e2e', 'REAL_WORLD_JOURNEY_TESTS.md'), ensureParentDir: true, content: 'source' },
 ];
@@ -82,7 +85,7 @@ const standaloneAppAgentInstructionDefinitions: TAgentInstructionDefinition[] =
     { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
     ...sharedAppAreaAgentInstructionDefinitions,
-    ...sharedE2eAgentInstructionDefinitions,
+    ...sharedTestAgentInstructionDefinitions,
 ];
 
 const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
@@ -93,7 +96,7 @@ const monorepoAppAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
 const monorepoRootAgentInstructionDefinitions: TAgentInstructionDefinition[] = [
     { projectPath: 'AGENTS.md', content: 'router' },
     ...sharedRootDocumentInstructionDefinitions,
-    ...sharedE2eAgentInstructionDefinitions,
+    ...sharedTestAgentInstructionDefinitions,
 ];
 
 const legacyProjectInstructionGitignoreBlockStart = '# Proteum-managed instruction symlinks';
@@ -130,7 +133,20 @@ export function configureProjectAgentInstructions({
         updated: [],
         updatedGitignores: [],
     };
-    const embeddedInstructions = renderEmbeddedProjectInstructions({ coreRoot });
+    const appEmbeddedInstructions = renderEmbeddedProjectInstructions({
+        appRoot: normalizedAppRoot,
+        coreRoot,
+        monorepoRoot: normalizedMonorepoRoot,
+    });
+    const rootEmbeddedInstructions =
+        mode === 'monorepo'
+            ? renderEmbeddedProjectInstructions({
+                  appRoot: normalizedAppRoot,
+                  coreRoot,
+                  includeMonorepoRegistry: true,
+                  monorepoRoot: normalizedMonorepoRoot,
+              })
+            : appEmbeddedInstructions;
 
     if (mode === 'monorepo' && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
@@ -141,7 +157,7 @@ export function configureProjectAgentInstructions({
             rootInstructions,
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
-            embeddedInstructions,
+            rootEmbeddedInstructions,
             {
                 dryRun,
                 overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
@@ -159,7 +175,7 @@ export function configureProjectAgentInstructions({
         appInstructions,
         '[agents]',
         path.join(coreRoot, 'agents', 'project'),
-        embeddedInstructions,
+        appEmbeddedInstructions,
         {
             dryRun,
             overwriteBlockedPaths: normalizedOverwriteBlockedPaths,
@@ -170,7 +186,7 @@ export function configureProjectAgentInstructions({
     if (mode === 'monorepo') {
         const retiredAppRootFiles = removeManagedInstructionFiles(
             normalizedAppRoot,
-            [...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions],
+            [...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions],
             '[agents]',
             path.join(coreRoot, 'agents', 'project'),
             {
@@ -182,7 +198,7 @@ export function configureProjectAgentInstructions({
 
     const appGitignoreCleanupInstructions =
         mode === 'monorepo'
-            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedE2eAgentInstructionDefinitions]
+            ? [...appInstructions, ...sharedRootDocumentInstructionDefinitions, ...sharedTestAgentInstructionDefinitions]
             : appInstructions;
 
     if (
@@ -544,7 +560,41 @@ function renderSingleProjectInstruction({
     return lines.join('\n');
 }
 
-function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs) {
+function renderMonorepoAppRegistry({
+    appRoot,
+    monorepoRoot,
+}: {
+    appRoot?: string;
+    monorepoRoot?: string;
+}) {
+    if (!monorepoRoot || !appRoot || path.resolve(monorepoRoot) === path.resolve(appRoot)) return [];
+
+    const appRoots = findProteumAppRootsUnder(monorepoRoot);
+    if (appRoots.length === 0) return [];
+
+    const summaries = appRoots.map((candidate) => readProteumAppRootSummary(candidate, monorepoRoot));
+
+    return [
+        '## Known Proteum Apps',
+        '',
+        'This is a monorepo root wrapper. Do not start `npx proteum dev` from this root; start it from one app root below.',
+        '',
+        ...summaries.map((summary) => {
+            const marker = path.resolve(summary.appRoot) === path.resolve(appRoot) ? ' (current configured app)' : '';
+            const port = summary.manifest?.routerPort ? `, default port ${summary.manifest.routerPort}` : '';
+            const command = createStartDevCommand({
+                appRoot: summary.appRoot,
+                baseRoot: monorepoRoot,
+                port: summary.manifest?.routerPort,
+            });
+
+            return `- ${summary.relativeAppRoot || summary.appRoot}${marker}${port}: ${command}`;
+        }),
+        '',
+    ];
+}
+
+function renderEmbeddedProjectInstructions({ appRoot, coreRoot, includeMonorepoRegistry = false, monorepoRoot }: TProjectInstructionArgs) {
     const agentSourceRoot = path.join(coreRoot, 'agents', 'project');
     if (!fs.existsSync(agentSourceRoot)) throw new Error(`Missing project instruction source root: ${agentSourceRoot}`);
 
@@ -556,36 +606,63 @@ function renderEmbeddedProjectInstructions({ coreRoot }: TProjectInstructionArgs
         '',
         '## Agent Routing Contract',
         '',
-        'Proteum CLI commands are optimized for agents. Do not load the whole instruction corpus up front.',
+        'Proteum CLI and MCP outputs are optimized for agents. Do not load the whole instruction corpus up front.',
         '',
-        '1. Start ambiguous, generated, connected, route, controller, file, or error work with `npx proteum orient <query>`.',
-        '2. Read only the files returned in `mustRead` plus the conditional docs that match the current task.',
-        '3. Use `npx proteum runtime status` before starting a dev server, so an existing tracked session can be reused.',
-        '4. Use `npx proteum diagnose <target>` for request-time issues before raw trace, perf, browser, or broad source search.',
-        '5. Use `--full`, `--manifest`, or `--events` only when a compact CLI response says the omitted detail is needed.',
+        'Detailed Proteum contracts are intentionally split into the files listed in the routing table below. They are not deleted; load only the file that matches the current task, or use MCP `workflow_start` / `instructions_resolve { projectId }` to get the routed set.',
         '',
+        '1. When a Proteum MCP client is available, call MCP `workflow_start` first. Pass `cwd` when `projectId` is not known, or pass the stable `projectId` from `projects_list` when it is known.',
+        '2. Use the `projectId` returned by live `workflow_start` for every follow-up app-bound MCP tool. If `workflow_start` is ambiguous or returns offline candidates, call MCP `project_resolve { cwd }`, select the intended app root, follow its port-inspected next action when needed, then retry `workflow_start`.',
+        '3. After `projectId` is selected, use MCP `runtime_status`, `orient`, `instructions_resolve`, `explain_summary`, `route_candidates`, `doctor`, `diagnose`, `trace_show`, `perf_request`, `logs_tail`, and `db_query` for read-only runtime, owner, instruction, route, trace, perf, log, and database reads.',
+        '4. Do not run CLI equivalents after a successful MCP result for the same read. Do not run broad source searches for route/page/controller ownership after `workflow_start`, `orient`, or `explain_summary` already returned the owner.',
+        '5. Treat selected instruction previews returned by MCP as the instruction source for read-only discovery and diagnostics. Read full files only before edits or git writes, when the returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
+        '6. Use `npx proteum runtime status` before starting a dev server only when MCP runtime status is unavailable, so an existing tracked session can be reused and the configured router/HMR ports can be checked without probing page bodies. If it says health is unreachable, do not run `diagnose`, `trace`, or `perf`; stop/repair/start the dev session first.',
+        '7. During `npx proteum dev`, Proteum ensures one managed machine MCP daemon is running and routes app-bound reads to the read-only runtime endpoint at `/__proteum/mcp` instead of spawning equivalent CLI diagnostics.',
+        '8. If machine MCP routing fails, run `npx proteum mcp status` and `npx proteum runtime status`; if no live session exists, use the exact next action from MCP offline routing or runtime status instead of assuming the manifest default port. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server.',
+        '9. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not start a second dev server in the same worktree or a second managed MCP daemon. Then retry MCP `workflow_start`.',
+        '10. Use MCP `diagnose { projectId, path }` for request-time issues before raw trace, perf, browser, or broad source search; use `npx proteum diagnose <target>` only as fallback or final terminal evidence.',
+        '11. Use `route_candidates`, `explain_summary`, or `npx proteum explain owner <query>` to pick routes. Do not run `npx proteum explain --routes --full` unless compact route/owner tools explicitly cannot answer the raw route-array question.',
+        '12. Use `--full`, `--manifest`, `--events`, or MCP `detail: "full"` only when compact output says the omitted detail is needed.',
+        '',
+        'CLI remains the reproducible surface for `dev`, `build`, `check`, `verify`, migrations, and final command evidence. MCP remains read-only and returns compact `proteum-mcp-v1` JSON.',
+        '',
+        ...(includeMonorepoRegistry ? renderMonorepoAppRegistry({ appRoot, monorepoRoot }) : []),
         '## Always-On Safety',
         '',
         '- Never edit generated files under `.proteum`.',
         '- Never create or edit Prisma migration files manually.',
         '- Never run schema-mutating SQL such as `ALTER TABLE`, `CREATE TABLE`, `DROP TABLE`, or `CREATE INDEX`.',
+        '- For read-only SQL diagnosis, use MCP `db_query` or `npx proteum db query "<sql>"`; only one capped `SELECT`, `SHOW`, or `EXPLAIN` statement is allowed.',
         '- If `schema.prisma` changes, ask the user to run `npx prisma migrate dev --config ./prisma.config.ts --name <migration name>` and wait for `continue` before validation.',
+        '- For production changes, add or update focused unit tests for touched behavior when applicable, targeting 100% meaningful coverage for changed production paths.',
         '- Do not run `git restore` or `git reset`.',
         '- Keep `proteum dev` sessions tracked with explicit session files and do not replace another live session.',
         '',
+        '## Triggered Instruction Reads',
+        '',
+        'Keep this root file as a router. MCP-selected previews are enough for read-only discovery and diagnostics. Read the referenced full instruction file only before edits or git writes, when `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.',
+        '',
+        '- Git lifecycle (`commit`, `and commit`, `stage`, `push`, `PR`, pull request): read Root contract fallback before any git write.',
+        '- Before finishing production code changes: read Root contract fallback, `CODING_STYLE.md`, `tests/AGENTS.md`, and any touched area `AGENTS.md`.',
+        '- Runtime-visible, request-time, router, SSR, browser, or controller behavior: read Root contract fallback and `diagnostics.md` for verification routing.',
+        '- Non-trivial feature, product, business-rule, UX, copy, or docs changes: read `DOCUMENTATION.md` before editing.',
+        '- Implementation edits: read `CODING_STYLE.md` before editing, plus the matching area file from the routing table.',
+        '',
         '## Routing Table',
         '',
+        '- Non-trivial coding tasks, feature docs, product intent, acceptance criteria, or docs updates: read `DOCUMENTATION.md`.',
         '- Raw errors, failing requests, traces, perf, or reproduction: read `diagnostics.md`.',
         '- Implementation edits: read `CODING_STYLE.md` before editing.',
         '- Client files or pages: read `client/AGENTS.md`; for page route/data/render work also read `client/pages/AGENTS.md`.',
         '- Server services: read `server/services/AGENTS.md`.',
         '- Manual server routes: read `server/routes/AGENTS.md`.',
-        '- E2E work: read `tests/e2e/AGENTS.md` and `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`.',
+        '- Unit tests, integration tests, or test-area work: read `tests/AGENTS.md`.',
+        '- E2E work: read `tests/AGENTS.md`, `tests/e2e/AGENTS.md`, and `tests/e2e/REAL_WORLD_JOURNEY_TESTS.md`.',
         '- Package, runtime, build, or client-performance decisions: read `optimizations.md` after implementation or when explicitly optimizing.',
         '',
         '## Canonical Source Map',
         '',
         `- Root contract fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'AGENTS.md'))}`,
+        `- Documentation fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'DOCUMENTATION.md'))}`,
         `- Diagnostics fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'diagnostics.md'))}`,
         `- Optimization fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'optimizations.md'))}`,
         `- Coding style fallback: ${normalizeProjectPathForGitignore(path.join(coreRoot, 'agents', 'project', 'CODING_STYLE.md'))}`,

package/cli/utils/appRoots.ts

@@ -0,0 +1,232 @@
+import fs from 'fs-extra';
+import path from 'path';
+import type { Dirent } from 'fs';
+
+import { readProteumManifest, type TProteumManifest } from '../compiler/common/proteumManifest';
+
+export type TProteumAppRootSummary = {
+    appRoot: string;
+    hasManifest: boolean;
+    manifest?: {
+        counts: {
+            connectedProjects: number;
+            controllers: number;
+            routes: number;
+        };
+        diagnostics: {
+            errors: number;
+            warnings: number;
+        };
+        identifier: string;
+        name: string;
+        routerPort: number;
+    };
+    manifestError?: string;
+    packageManager: 'npm' | 'pnpm' | 'yarn' | 'unknown';
+    relativeAppRoot?: string;
+};
+
+const proteumAppRootRequiredEntries = ['package.json', 'identity.config.ts', 'proteum.config.ts', 'client', 'server'];
+const ignoredSearchDirectories = new Set([
+    '.cache',
+    '.git',
+    '.proteum',
+    'bin',
+    'coverage',
+    'dev',
+    'node_modules',
+    'playwright-report',
+    'test-results',
+    'var',
+]);
+
+const resolveExistingPath = (value: string) => {
+    const resolved = path.resolve(value);
+
+    try {
+        return fs.realpathSync(resolved);
+    } catch {
+        return resolved;
+    }
+};
+
+const pathEntryExists = (filepath: string) => {
+    try {
+        fs.lstatSync(filepath);
+        return true;
+    } catch {
+        return false;
+    }
+};
+
+const isDirectory = (filepath: string) => {
+    try {
+        return fs.statSync(filepath).isDirectory();
+    } catch {
+        return false;
+    }
+};
+
+const resolveSearchRoot = (value: string) => {
+    const resolved = resolveExistingPath(value);
+    if (isDirectory(resolved)) return resolved;
+    return path.dirname(resolved);
+};
+
+export const isProteumAppRoot = (workdir: string) =>
+    proteumAppRootRequiredEntries.every((entry) => pathEntryExists(path.join(workdir, entry)));
+
+export const findNearestProteumAppRoot = (startPath: string) => {
+    let currentPath = resolveSearchRoot(startPath);
+
+    while (true) {
+        if (isProteumAppRoot(currentPath)) return currentPath;
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return undefined;
+        currentPath = parentPath;
+    }
+};
+
+export const findProteumAppRootsUnder = (root: string, { maxDepth = 5 }: { maxDepth?: number } = {}) => {
+    const searchRoot = resolveSearchRoot(root);
+    const appRoots: string[] = [];
+    const seen = new Set<string>();
+
+    const visit = (directory: string, depth: number) => {
+        const canonicalDirectory = resolveExistingPath(directory);
+        if (seen.has(canonicalDirectory)) return;
+        seen.add(canonicalDirectory);
+
+        if (isProteumAppRoot(canonicalDirectory)) {
+            appRoots.push(canonicalDirectory);
+            return;
+        }
+
+        if (depth >= maxDepth) return;
+
+        let entries: Dirent[];
+        try {
+            entries = fs.readdirSync(canonicalDirectory, { withFileTypes: true });
+        } catch {
+            return;
+        }
+
+        for (const entry of entries) {
+            if (!entry.isDirectory()) continue;
+            if (ignoredSearchDirectories.has(entry.name)) continue;
+            visit(path.join(canonicalDirectory, entry.name), depth + 1);
+        }
+    };
+
+    visit(searchRoot, 0);
+
+    return appRoots.sort((left, right) => left.localeCompare(right));
+};
+
+const findPackageManager = (appRoot: string): TProteumAppRootSummary['packageManager'] => {
+    let currentPath = path.resolve(appRoot);
+
+    while (true) {
+        if (pathEntryExists(path.join(currentPath, 'package-lock.json'))) return 'npm';
+        if (pathEntryExists(path.join(currentPath, 'pnpm-lock.yaml'))) return 'pnpm';
+        if (pathEntryExists(path.join(currentPath, 'yarn.lock'))) return 'yarn';
+
+        if (pathEntryExists(path.join(currentPath, '.git'))) return 'unknown';
+
+        const parentPath = path.dirname(currentPath);
+        if (parentPath === currentPath) return 'unknown';
+        currentPath = parentPath;
+    }
+};
+
+const summarizeManifest = (manifest: TProteumManifest): NonNullable<TProteumAppRootSummary['manifest']> => {
+    const errors = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'error').length;
+    const warnings = manifest.diagnostics.filter((diagnostic) => diagnostic.level === 'warning').length;
+
+    return {
+        counts: {
+            connectedProjects: manifest.connectedProjects.length,
+            controllers: manifest.controllers.length,
+            routes: manifest.routes.client.length + manifest.routes.server.length,
+        },
+        diagnostics: { errors, warnings },
+        identifier: manifest.app.identity.identifier,
+        name: manifest.app.identity.name,
+        routerPort: manifest.env.resolved.routerPort,
+    };
+};
+
+export const readProteumAppRootSummary = (appRoot: string, baseRoot?: string): TProteumAppRootSummary => {
+    const normalizedAppRoot = resolveExistingPath(appRoot);
+    const relativeAppRoot = baseRoot ? path.relative(resolveExistingPath(baseRoot), normalizedAppRoot) || '.' : undefined;
+    const summary: TProteumAppRootSummary = {
+        appRoot: normalizedAppRoot,
+        hasManifest: false,
+        packageManager: findPackageManager(normalizedAppRoot),
+        relativeAppRoot,
+    };
+
+    try {
+        const manifest = readProteumManifest(normalizedAppRoot);
+        summary.hasManifest = true;
+        summary.manifest = summarizeManifest(manifest);
+    } catch (error) {
+        summary.manifestError = error instanceof Error ? error.message : String(error);
+    }
+
+    return summary;
+};
+
+export const resolveProteumAppRootContext = (cwd: string) => {
+    const normalizedCwd = resolveSearchRoot(cwd);
+    const nearestAppRoot = findNearestProteumAppRoot(normalizedCwd);
+    const appRoots = nearestAppRoot ? [nearestAppRoot] : findProteumAppRootsUnder(normalizedCwd);
+
+    return {
+        cwd: normalizedCwd,
+        isAppRoot: nearestAppRoot === normalizedCwd,
+        isWrapper: !nearestAppRoot && appRoots.length > 0,
+        nearestAppRoot,
+        appRoots,
+        appCandidates: appRoots.map((appRoot) => readProteumAppRootSummary(appRoot, normalizedCwd)),
+    };
+};
+
+export const quoteShellPath = (value: string) => JSON.stringify(value);
+
+const createAppScopedCommand = ({
+    appRoot,
+    baseRoot,
+    command,
+}: {
+    appRoot: string;
+    baseRoot?: string;
+    command: string;
+}) => {
+    const relativeAppRoot = baseRoot ? path.relative(resolveExistingPath(baseRoot), resolveExistingPath(appRoot)) || '.' : '';
+
+    if (!relativeAppRoot || relativeAppRoot === '.') return command;
+    return `cd ${quoteShellPath(relativeAppRoot)} && ${command}`;
+};
+
+export const createStartDevCommand = ({
+    appRoot,
+    baseRoot,
+    port,
+}: {
+    appRoot: string;
+    baseRoot?: string;
+    port?: number;
+}) => {
+    const command = `npx proteum dev --session-file var/run/proteum/dev/agents/<task>.json --port ${port || '<free-port>'}`;
+
+    return createAppScopedCommand({ appRoot, baseRoot, command });
+};
+
+export const createRuntimeStatusCommand = ({ appRoot, baseRoot }: { appRoot: string; baseRoot?: string }) =>
+    createAppScopedCommand({
+        appRoot,
+        baseRoot,
+        command: 'npx proteum runtime status',
+    });