proteum 2.5.22 → 2.5.23

package/AGENTS.md

@@ -65,7 +65,7 @@ npx prisma migrate dev --config ./prisma.config.ts --name <migration name>
 - 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.
 - Proteum MCP contract: `proteum mcp` is the machine-scope router agents register once, and `proteum dev` exposes each app runtime at `/__proteum/mcp`. `proteum dev` ensures one managed machine MCP daemon is running; do not start a second managed daemon. Agents should start with MCP `workflow_start` using `cwd` or a known `projectId`; ambiguous routing or offline app candidates use `project_resolve { cwd }`, and follow-up live app tools require the returned `projectId`. Dev-hosted app tools are already rooted to their own runtime. Keep MCP tools/resources compact, typed, capped, paginated for full trace detail, and read-only unless a future task explicitly expands the mutation contract. The database diagnostic exception is still read-only: MCP `db_query` and CLI `proteum db query` allow one capped `SELECT`, `SHOW`, or `EXPLAIN` statement only and return rows plus elapsed milliseconds. MCP payloads are compact single-line `proteum-mcp-v1` JSON, not pretty-printed human output. Do not implement MCP tools as thin CLI process wrappers when the data is available through manifest readers, tracked sessions, or dev runtime registries.
 - Keep the same-system trace contract explicit when request instrumentation changes: `TRACE_*` controls the retained dev trace store plus the trace/perf CLI, dev-only HTTP endpoints, and bottom profiler, while `ENABLE_PROFILER` enables the reduced request-local `request.profiling` snapshot and `request.finished` hook payload without retaining finished requests globally unless dev trace is also enabled.
-- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins.
+- Current CLI banner contract: only the bare `proteum build` and bare `proteum dev` commands print the welcome banner and include the active Proteum installation method. Any extra argument or option skips the welcome banner. Terminal `proteum mcp` may print a compact central MCP ready banner when it starts or reuses the managed daemon. Only `proteum dev` clears the interactive terminal before rendering, exposes `CTRL+R` reload plus `CTRL+C` shutdown hotkeys in its session UI, and reports connected app names plus successful connected `/ping` checks in the ready banner. Every `proteum dev` start ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files before the dev loop begins, except for apps whose `proteum.config.ts` sets `agentInstructions: false` (hand-owned instructions; a monorepo root is managed only when no app opted out).
 - 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.

package/README.md

@@ -206,7 +206,7 @@ An agent — or you — can ask the framework directly:
 
 - **One MCP entry point.** `proteum mcp` runs a machine-scope router; `proteum dev` exposes each app at `/__proteum/mcp`. An agent calls `workflow_start`, gets a stable `projectId`, and routes every follow-up read to the right app.
 - **Token-efficient output.** Diagnostics default to compact `proteum-agent-v1` JSON — decision-ready summaries first, raw detail only behind `--full`, `--manifest`, or `--events`.
-- **Generated instruction files.** `proteum configure agents` writes managed `AGENTS.md` / `CLAUDE.md` instruction routers, kept in sync on every `proteum dev` start.
+- **Generated instruction files.** `proteum configure agents` writes managed `AGENTS.md` / `CLAUDE.md` instruction routers, kept in sync on every `proteum dev` start. Projects that write their own instructions set `agentInstructions: false` in `proteum.config.ts` and Proteum leaves them alone.
 - **Auth without UI automation.** `proteum session <email> --role ADMIN` mints a dev session (token + Playwright-ready cookie) so agents and E2E suites skip the login flow.
 
 > Full agent contract: [docs/mcp.md](docs/mcp.md), [docs/diagnostics.md](docs/diagnostics.md), and [docs/agent-routing.md](docs/agent-routing.md).

package/cli/commands/configure.ts

@@ -18,6 +18,7 @@ import {
     configureProjectAgentInstructions,
     findLikelyRepoRoot,
     isInsideDirectory,
+    isProjectAgentInstructionsEnabled,
     resolveCanonicalPath,
     type TConfigureMonorepoProjectAgentInstructionsResult,
     type TConfigureProjectAgentInstructionsResult,
@@ -143,6 +144,9 @@ const renderConfigureMonorepoResultSections = (result: TConfigureMonorepoProject
         appRoot: result.monorepoRoot,
     });
 
+const agentInstructionsDisabledMessage = (root: string) =>
+    `Agent instructions are hand-owned in ${root}: \`agentInstructions: false\` is set in proteum.config.ts, so \`proteum configure agents\` does nothing. Remove that setting to let Proteum manage them again.`;
+
 /*----------------------------------
 - COMMAND
 ----------------------------------*/
@@ -162,6 +166,8 @@ export const runConfigureAgentsWizard = async ({
 } = {}) => {
     assertProteumAppRoot(appRoot);
 
+    if (!isProjectAgentInstructionsEnabled(appRoot)) throw new UsageError(agentInstructionsDisabledMessage(appRoot));
+
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
     }
@@ -241,6 +247,10 @@ export const runConfigureAgentsMonorepoWizard = async ({
     if (appRoots.length === 0) throw new UsageError(`No Proteum app roots were found under ${monorepoRoot}.`);
     for (const appRoot of appRoots) assertProteumAppRoot(appRoot);
 
+    if (appRoots.every((appRoot) => !isProjectAgentInstructionsEnabled(appRoot))) {
+        throw new UsageError(agentInstructionsDisabledMessage(monorepoRoot));
+    }
+
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         throw new UsageError('`proteum configure agents` is interactive and requires a TTY.');
     }

package/cli/commands/dev.ts

@@ -199,6 +199,9 @@ const ensureProjectAgentInstructions = async () => {
         dryRun: true,
         monorepoRoot,
     });
+    // `agentInstructions: false`: the project owns its instruction files, so dev must not rewrite them.
+    if (preview.disabled) return;
+
     const overwriteBlockedPaths = await promptBlockedAgentInstructionOverwrites(preview.blocked);
 
     const result = configureProjectAgentInstructions({

package/cli/compiler/artifacts/manifest.ts

@@ -331,6 +331,7 @@ export const writeCurrentProteumManifest = ({
                               ]),
                           )
                         : undefined,
+                ...(app.setup.agentInstructions === false ? { agentInstructions: false } : {}),
             },
         },
         conventions: {

package/cli/mcp/router.ts

@@ -295,13 +295,47 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         return client;
     };
 
-    const closeClient = async (record: TMachineDevSessionRecord) => {
+    // Removes a client only if the cache still holds that same instance, so a failing call cannot
+    // close the fresh client that a parallel call just opened after a dev server restart.
+    const evictClient = async (record: TMachineDevSessionRecord, client: TDevMcpClient) => {
         const key = cacheKey(record);
-        const client = clients.get(key);
-        clients.delete(key);
-        if (client) await client.close().catch(() => undefined);
+        if (clients.get(key) === client) clients.delete(key);
+        await client.close().catch(() => undefined);
     };
 
+    /**
+     * Calls a tool on the app's dev MCP, retrying once with a fresh client when the cached one fails.
+     * A dev server restart drops its MCP sessions, and the cached client then gets "initialize the
+     * Proteum MCP session" on its next call. Only a cached client can be stale; a brand-new client
+     * failing means the app is down or booting, so it is not retried.
+     */
+    const callDevTool = async (record: TMachineDevSessionRecord, request: { arguments: Record<string, unknown>; name: string }) => {
+        const cached = clients.get(cacheKey(record));
+        const client = cached || (await getClient(record));
+
+        try {
+            return await client.callTool(request);
+        } catch (error) {
+            await evictClient(record, client);
+            if (!cached) throw error;
+
+            const freshClient = await getClient(record);
+            try {
+                return await freshClient.callTool(request);
+            } catch (retryError) {
+                await evictClient(record, freshClient);
+                throw retryError;
+            }
+        }
+    };
+
+    const devMcpUnreachableResult = (record: TMachineDevSessionRecord, error: unknown) =>
+        errorToolResult(`Could not reach Proteum dev MCP for ${record.projectId}.`, {
+            error: error instanceof Error ? error.message : String(error),
+            mcpUrl: record.mcpUrl,
+            projectId: record.projectId,
+        });
+
     const closeAllClients = async () => {
         const cachedClients = [...clients.values()];
         clients.clear();
@@ -446,23 +480,18 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
         const resolution = await resolveProject(input.projectId);
         if (!resolution.record) return resolution.error;
 
+        let result: CallToolResult;
         try {
-            const client = await getClient(resolution.record);
-            const result = await client.callTool({
+            result = await callDevTool(resolution.record, {
                 arguments: stripProjectRouting(input),
                 name,
             });
-
-            if (name === 'runtime_status' || name === 'doctor') return augmentForwardedPayload(result, resolution.record);
-            return result;
         } catch (error) {
-            await closeClient(resolution.record);
-            return errorToolResult(`Could not reach Proteum dev MCP for ${resolution.record.projectId}.`, {
-                error: error instanceof Error ? error.message : String(error),
-                mcpUrl: resolution.record.mcpUrl,
-                projectId: resolution.record.projectId,
-            });
+            return devMcpUnreachableResult(resolution.record, error);
         }
+
+        if (name === 'runtime_status' || name === 'doctor') return augmentForwardedPayload(result, resolution.record);
+        return result;
     };
 
     const createOfflineWorkflowStartResult = async (offline: TOfflineProject, input: Record<string, unknown>) => {
@@ -572,13 +601,18 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
             return jsonToolResult(createWorktreeBootstrapMcpBlockResponse(bootstrapStatus, compactProject(record)), true);
         }
 
+        let result: CallToolResult;
         try {
-            const client = await getClient(record);
-            const result = await client.callTool({
+            result = await callDevTool(record, {
                 arguments: stripProjectRouting(input),
                 name: 'workflow_start',
             });
+        } catch (error) {
+            return devMcpUnreachableResult(record, error);
+        }
 
+        // Payload and preflight failures are not connection failures: they must not evict a healthy client.
+        try {
             if (result.content[0]?.type !== 'text') return result;
 
             const payload = JSON.parse(result.content[0].text);
@@ -620,8 +654,7 @@ export const createProteumMachineMcpServer = ({ createDevMcpClient, version }: T
                 nextActions: dedupeNextActions([...preflight.nextActions, ...(routedNextActions || [])]),
             });
         } catch (error) {
-            await closeClient(record);
-            return errorToolResult(`Could not reach Proteum dev MCP for ${record.projectId}.`, {
+            return errorToolResult(`Could not read the workflow_start payload from ${record.projectId}.`, {
                 error: error instanceof Error ? error.message : String(error),
                 mcpUrl: record.mcpUrl,
                 projectId: record.projectId,

package/cli/presentation/commands.ts

@@ -135,6 +135,7 @@ export const proteumCommands: Record<TProteumCommandName, TProteumCommandDoc> =
             'Every generated `CLAUDE.md` is a sibling symlink pointing to `AGENTS.md`.',
             'Every managed instruction file contains a `# Proteum Instructions` section with the full embedded Proteum project instruction corpus.',
             'Existing content outside `# Proteum Instructions` is preserved. Directories and foreign symlinks are replaced only after confirmation.',
+            'An app with `agentInstructions: false` in `proteum.config.ts` owns its instruction files: configure refuses to run for it, `proteum dev` leaves them alone, and a monorepo root is managed only when no app opted out.',
         ],
         status: 'experimental',
     },

package/cli/presentation/help.ts

@@ -139,7 +139,7 @@ export const renderCliOverview = async ({
                     indent: '  ',
                     nextIndent: '  ',
                 }),
-                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files.', {
+                wrapText('Before the dev loop starts, `proteum dev` ensures tracked instruction files contain the current managed `# Proteum Instructions` section and `CLAUDE.md` symlinks point to sibling `AGENTS.md` files, unless `proteum.config.ts` sets `agentInstructions: false`, in which case the project owns those files and dev leaves them untouched.', {
                     indent: '  ',
                     nextIndent: '  ',
                 }),

package/cli/utils/agents.ts

@@ -5,6 +5,7 @@
 // Npm
 import fs from 'fs-extra';
 import path from 'path';
+import { loadApplicationSetupConfig, resolveSetupConfigFilepath } from '../../common/applicationConfigLoader';
 import { logVerbose } from '../runtime/verbose';
 import { createStartDevCommand, findProteumAppRootsUnder, readProteumAppRootSummary } from './appRoots';
 
@@ -55,6 +56,8 @@ type TEnsureInstructionFilesResult = {
 
 export type TConfigureProjectAgentInstructionsResult = {
     appRoot: string;
+    /** True when `agentInstructions: false` made Proteum leave every instruction file alone. */
+    disabled?: boolean;
     blocked: string[];
     created: string[];
     monorepoRoot?: string;
@@ -142,6 +145,25 @@ const projectInstructionGitignoreBlockEnd = '# End Proteum-managed instruction f
 - PUBLIC API
 ----------------------------------*/
 
+/**
+ * Whether Proteum manages the agent instruction files of an app.
+ * An app opts out with `agentInstructions: false` in `proteum.config.ts` when it owns
+ * its instructions by hand; without a readable config the historical default (managed) applies.
+ */
+export function isProjectAgentInstructionsEnabled(appRoot: string) {
+    if (!fs.existsSync(resolveSetupConfigFilepath(appRoot))) return true;
+
+    return loadApplicationSetupConfig(appRoot).agentInstructions !== false;
+}
+
+/**
+ * Monorepo root files are shared by every app, so Proteum only writes them when no app opted out:
+ * one hand-owned app is enough to make the shared root hand-owned too.
+ */
+export function isMonorepoAgentInstructionsEnabled(monorepoRoot: string) {
+    return findProteumAppRootsUnder(monorepoRoot).every((appRoot) => isProjectAgentInstructionsEnabled(appRoot));
+}
+
 export function configureProjectAgentInstructions({
     appRoot,
     coreRoot,
@@ -170,6 +192,19 @@ export function configureProjectAgentInstructions({
         updated: [],
         updatedGitignores: [],
     };
+    const manageAppInstructions = includeAppInstructions && isProjectAgentInstructionsEnabled(normalizedAppRoot);
+    const manageRootInstructions =
+        includeRootInstructions &&
+        mode === 'monorepo' &&
+        normalizedMonorepoRoot !== undefined &&
+        isMonorepoAgentInstructionsEnabled(normalizedMonorepoRoot);
+
+    // Return before rendering or the dry-run preview: both touch the file system (the preview creates test folders).
+    if (!manageAppInstructions && !manageRootInstructions) {
+        result.disabled = true;
+        return result;
+    }
+
     const appEmbeddedInstructions = renderEmbeddedProjectInstructions({
         appRoot: normalizedAppRoot,
         coreRoot,
@@ -177,7 +212,7 @@ export function configureProjectAgentInstructions({
         monorepoRoot: normalizedMonorepoRoot,
     });
     const rootEmbeddedInstructions =
-        mode === 'monorepo'
+        mode === 'monorepo' && normalizedMonorepoRoot
             ? renderEmbeddedProjectInstructions({
                   appRoot: normalizedAppRoot,
                   coreRoot,
@@ -188,7 +223,7 @@ export function configureProjectAgentInstructions({
               })
             : appEmbeddedInstructions;
 
-    if (includeRootInstructions && mode === 'monorepo' && normalizedMonorepoRoot) {
+    if (manageRootInstructions && normalizedMonorepoRoot) {
         result.monorepoRoot = normalizedMonorepoRoot;
 
         const rootInstructions = getRootAgentInstructionDefinitions();
@@ -209,7 +244,7 @@ export function configureProjectAgentInstructions({
             result.updatedGitignores.push(path.join(normalizedMonorepoRoot, '.gitignore'));
     }
 
-    if (includeAppInstructions) {
+    if (manageAppInstructions) {
         const appInstructions = getAppAgentInstructionDefinitions({ mode });
         const appFiles = ensureInstructionFiles(
             normalizedAppRoot,

package/common/applicationConfig.ts

@@ -30,6 +30,11 @@ export type TApplicationIdentityConfig = {
 export type TApplicationSetupConfig = {
     transpile?: string[];
     connect?: TConnectedProjectsConfig;
+    /**
+     * Set to `false` when the project owns its agent instruction files by hand.
+     * Proteum then never writes AGENTS.md, CLAUDE.md or the routed instruction copies.
+     */
+    agentInstructions?: boolean;
 };
 
 export type TVerificationCheckScope = 'targeted' | 'area' | 'full' | 'static';
@@ -317,9 +322,14 @@ export const normalizeApplicationSetupConfig = (
         throw new Error(`Invalid setup config in ${filepath}. Use "transpile" instead of "transpileModules".`);
     }
 
+    if (value.agentInstructions !== undefined && typeof value.agentInstructions !== 'boolean') {
+        throw new Error(`Invalid setup config in ${filepath}. "agentInstructions" must be a boolean.`);
+    }
+
     return {
         transpile: normalizeTranspileConfig(value.transpile),
         connect: normalizeConnectedProjectsConfig(value.connect),
+        ...(value.agentInstructions === undefined ? {} : { agentInstructions: value.agentInstructions }),
     };
 };
 

package/common/dev/inspection.ts

@@ -780,6 +780,28 @@ const resolveGuidance = ({
     manifest: TProteumManifest;
     ownerFilepath?: string;
 }) => {
+    // `agentInstructions: false`: the project owns one hand-written CLAUDE.md and deleted the routed
+    // copies, so every guidance slot points at it instead of Proteum's bundled fallbacks.
+    if (manifest.app.setup.agentInstructions === false) {
+        const claudeInstructions = resolveGuidanceFile({
+            appRoot: manifest.app.root,
+            fallbackFilepath: joinPath(manifest.app.root, 'CLAUDE.md'),
+            relativePath: 'CLAUDE.md',
+        }).filepath;
+
+        return {
+            guidance: {
+                agents: claudeInstructions,
+                documentation: claudeInstructions,
+                diagnostics: claudeInstructions,
+                optimizations: claudeInstructions,
+                codingStyle: claudeInstructions,
+                areaAgents: [],
+            } satisfies TOrientGuidance,
+            warnings: [] as string[],
+        };
+    }
+
     const fallbackRoot = joinPath(manifest.app.coreRoot, 'agents', 'project');
     const warnings: string[] = [];
     const agents = resolveGuidanceFile({

package/common/dev/mcpPayloads.ts

@@ -919,6 +919,15 @@ const createSelectedInstruction = (file: string, reason: string) => ({
     reason,
 });
 
+// This module also runs inside the bundled dev server, where the TypeScript config loader is not
+// available, so the opt-out is read from the config source text instead of evaluating it.
+const readsProteumManagedInstructions = (appRoot: string) => {
+    if (fs === undefined || path === undefined) return true;
+    const setupFilepath = path.join(appRoot, 'proteum.config.ts');
+    if (!fileExists(setupFilepath)) return true;
+    return !/\bagentInstructions\s*:\s*false\b/.test(fs.readFileSync(setupFilepath, 'utf8'));
+};
+
 export const resolveInstructionRouting = ({
     appRoot,
     query = '',
@@ -930,6 +939,26 @@ export const resolveInstructionRouting = ({
     const repoRoot = findLikelyRepoRoot(appRoot);
     const selected = new Map<string, ReturnType<typeof createSelectedInstruction>>();
     const readWhen: Array<{ file?: string; when: string }> = [];
+
+    // `agentInstructions: false`: the routed AGENTS.md copies no longer exist; route to the hand-owned CLAUDE.md.
+    if (!readsProteumManagedInstructions(appRoot)) {
+        const claudeFile = resolveDocumentFile({ appRoot, repoRoot, relativeFilepath: 'CLAUDE.md' });
+        if (claudeFile && fileExists(claudeFile)) {
+            selected.set(claudeFile, createSelectedInstruction(claudeFile, 'Project-owned agent instructions.'));
+        }
+        const selectedFiles = [...selected.values()];
+        return createMcpPayload({
+            summary: `${selectedFiles.length} instruction files selected for ${normalizedQuery || 'current app'}`,
+            data: {
+                query: normalizedQuery,
+                appRoot,
+                repoRoot,
+                selected: selectedFiles,
+                readWhen,
+                fullReadPolicy: fullInstructionReadPolicy,
+            },
+        });
+    }
     const addInstruction = (relativeFilepath: string, reason: string, preferAppRoot = true) => {
         if (path === undefined) return;
         const roots = preferAppRoot ? [appRoot, repoRoot] : [repoRoot, appRoot];

package/common/dev/proteumManifest.ts

@@ -123,6 +123,7 @@ export type TProteumManifest = {
         setup: {
             transpile?: string[];
             connect?: Record<string, { source?: string; urlInternal?: string }>;
+            agentInstructions?: boolean;
         };
     };
     conventions: {

package/docs/agent-routing.md

@@ -138,3 +138,7 @@ The result confirms the intended routing:
 - use `workflow_start` to collapse project resolution, fresh-copy readiness, runtime status, instruction previews, owner summary, and first next actions into one read
 - use machine MCP with `projectId` for repeated runtime reads against an already running app
 - use `instructions_resolve` to refresh routing instead of rereading full instruction files
+
+## Hand-Owned Instructions
+
+A project that writes its own agent instructions sets `agentInstructions: false` in each app's `proteum.config.ts`. Proteum then never writes `AGENTS.md`, `CLAUDE.md` or the routed instruction copies for that app: `proteum dev` skips the sync, `proteum configure agents` refuses to run, and a monorepo root is managed only when no app opted out. MCP `workflow_start` and `instructions_resolve` route such apps to their `CLAUDE.md`, and orientation guidance points there instead of Proteum's bundled fallbacks.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "proteum",
 	"description": "LLM-first Opinionated Typescript Framework for web applications.",
-	"version": "2.5.22",
+	"version": "2.5.23",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/scripts/update-codex-agents.ts

@@ -31,5 +31,6 @@ for (const projectRoot of projectRoots) {
     }
 
     console.log(`[update-codex-agents] Syncing project Codex assets in ${projectRoot}`);
-    configureProjectAgentInstructions({ appRoot: projectRoot, coreRoot: proteumRoot });
+    const result = configureProjectAgentInstructions({ appRoot: projectRoot, coreRoot: proteumRoot });
+    if (result.disabled) console.warn(`[update-codex-agents] Skipped ${projectRoot}: agentInstructions is false.`);
 }

package/tests/agents-utils.test.cjs

@@ -11,6 +11,7 @@ require('ts-node/register/transpile-only');
 const {
     configureMonorepoProjectAgentInstructions,
     configureProjectAgentInstructions,
+    isProjectAgentInstructionsEnabled,
     resolveProjectAgentMonorepoRoot,
 } = require('../cli/utils/agents.ts');
 
@@ -581,3 +582,64 @@ test('configure reports blocked paths unless overwrite is allowed', () => {
     assert.equal(fs.lstatSync(blockedPath).isFile(), true);
     assert.match(fs.readFileSync(blockedPath, 'utf8'), /## Source: CODING_STYLE\.md/);
 });
+
+const createSetupAppFixture = (appRoot, setupConfig = 'export default {};\n') => {
+    fs.mkdirSync(path.join(appRoot, 'client'), { recursive: true });
+    fs.mkdirSync(path.join(appRoot, 'server'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), setupConfig);
+};
+
+test('agentInstructions defaults to managed and reads the opt-out from proteum.config.ts', () => {
+    const managedRoot = makeTempRoot();
+    const optedOutRoot = makeTempRoot();
+    const invalidRoot = makeTempRoot();
+
+    createSetupAppFixture(managedRoot);
+    createSetupAppFixture(optedOutRoot, 'export default { agentInstructions: false };\n');
+    createSetupAppFixture(invalidRoot, "export default { agentInstructions: 'no' };\n");
+
+    assert.equal(isProjectAgentInstructionsEnabled(makeTempRoot()), true);
+    assert.equal(isProjectAgentInstructionsEnabled(managedRoot), true);
+    assert.equal(isProjectAgentInstructionsEnabled(optedOutRoot), false);
+    assert.throws(() => isProjectAgentInstructionsEnabled(invalidRoot), /"agentInstructions" must be a boolean/);
+});
+
+test('an opted-out standalone app keeps its hand-owned instruction files untouched', () => {
+    const coreRoot = createCoreFixture();
+    const appRoot = makeTempRoot();
+
+    createSetupAppFixture(appRoot, 'export default { agentInstructions: false };\n');
+    writeFile(path.join(appRoot, 'CLAUDE.md'), '# Hand-owned\n');
+
+    const preview = configureProjectAgentInstructions({ appRoot, coreRoot, dryRun: true });
+    const result = configureProjectAgentInstructions({ appRoot, coreRoot });
+
+    assert.equal(preview.disabled, true);
+    assert.equal(result.disabled, true);
+    assert.deepEqual([result.created, result.updated, result.blocked], [[], [], []]);
+    assert.equal(pathEntryExists(path.join(appRoot, 'AGENTS.md')), false);
+    assert.equal(pathEntryExists(path.join(appRoot, 'tests')), false);
+    assert.equal(fs.readFileSync(path.join(appRoot, 'CLAUDE.md'), 'utf8'), '# Hand-owned\n');
+});
+
+test('one opted-out app makes the shared monorepo root hand-owned', () => {
+    const coreRoot = createCoreFixture();
+    const monorepoRoot = makeTempRoot();
+    const productRoot = path.join(monorepoRoot, 'apps', 'product');
+    const websiteRoot = path.join(monorepoRoot, 'apps', 'website');
+
+    fs.mkdirSync(path.join(monorepoRoot, '.git'));
+    createSetupAppFixture(productRoot, 'export default { agentInstructions: false };\n');
+    createSetupAppFixture(websiteRoot);
+
+    const productResult = configureProjectAgentInstructions({ appRoot: productRoot, coreRoot, monorepoRoot });
+    const websiteResult = configureProjectAgentInstructions({ appRoot: websiteRoot, coreRoot, monorepoRoot });
+
+    assert.equal(productResult.disabled, true);
+    assert.equal(websiteResult.disabled, undefined);
+    assert.equal(pathEntryExists(path.join(monorepoRoot, 'AGENTS.md')), false);
+    assert.equal(pathEntryExists(path.join(productRoot, 'AGENTS.md')), false);
+    assert.equal(pathEntryExists(path.join(websiteRoot, 'AGENTS.md')), true);
+});

package/tests/mcp.test.cjs

@@ -769,6 +769,100 @@ test('machine MCP router forwards app tools without leaking projectId', async (t
     assert.equal(closeCount, 1);
 });
 
+const setupReconnectRouter = async (t, { failFreshClient }) => {
+    const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-reconnect-'));
+    t.onTestFinished(() => {
+        if (previousRegistryDir === undefined) delete process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+        else process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = previousRegistryDir;
+    });
+
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-reconnect-app-'));
+    const machineRecord = await writeMachineDevSessionRecord({
+        ...createDevSessionRecord({
+            appRoot,
+            port: 3104,
+            sessionFilePath: path.join(appRoot, 'var/run/proteum/dev/3104.json'),
+        }),
+        publicUrl: 'http://localhost:3104',
+        state: 'ready',
+    });
+    const staleSessionError = new Error(
+        'Streamable HTTP error: Error POSTing to endpoint: Bad Request: initialize the Proteum MCP session before sending tool or resource requests.',
+    );
+    const createdClients = [];
+    const server = createProteumMachineMcpServer({
+        createDevMcpClient: async () => {
+            const clientIndex = createdClients.length + 1;
+            const devClient = {
+                calls: 0,
+                closeCount: 0,
+                callTool: async () => {
+                    devClient.calls += 1;
+                    // Client 1 answers once, then the dev server restarts and forgets its session.
+                    if (clientIndex === 1 && devClient.calls > 1) throw staleSessionError;
+                    if (clientIndex > 1 && failFreshClient) throw staleSessionError;
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: JSON.stringify({ ok: true, format: 'proteum-mcp-v1', summary: `client ${clientIndex}`, data: {} }),
+                            },
+                        ],
+                    };
+                },
+                close: async () => {
+                    devClient.closeCount += 1;
+                },
+            };
+            createdClients.push(devClient);
+            return devClient;
+        },
+        version: 'test',
+    });
+    const client = new Client({ name: 'machine-mcp-reconnect-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const callLogs = async () =>
+        await client.callTool({ name: 'logs_tail', arguments: { projectId: machineRecord.projectId } });
+
+    return { callLogs, client, createdClients, server };
+};
+
+test('machine MCP router reconnects once when a dev server restart invalidated the cached session', async (t) => {
+    const { callLogs, client, createdClients, server } = await setupReconnectRouter(t, { failFreshClient: false });
+
+    const first = await callLogs();
+    const second = await callLogs();
+
+    assert.match(first.content[0].text, /client 1/);
+    assert.equal(second.isError, undefined);
+    assert.match(second.content[0].text, /client 2/);
+    assert.equal(createdClients.length, 2);
+    assert.equal(createdClients[0].closeCount, 1);
+
+    await client.close();
+    await server.close();
+});
+
+test('machine MCP router retries a stale session exactly once before reporting the dev MCP unreachable', async (t) => {
+    const { callLogs, client, createdClients, server } = await setupReconnectRouter(t, { failFreshClient: true });
+
+    await callLogs();
+    const second = await callLogs();
+
+    assert.equal(second.isError, true);
+    assert.match(second.content[0].text, /Could not reach Proteum dev MCP/);
+    assert.equal(createdClients.length, 2);
+    assert.equal(createdClients[1].closeCount, 1);
+
+    await client.close();
+    await server.close();
+});
+
 test('machine MCP router resolves projects by cwd and bootstraps workflow without duplicate discovery', async (t) => {
     const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-workflow-router-'));