proteum 2.5.23 → 2.5.25

package/common/dev/inspection.ts

@@ -780,14 +780,23 @@ 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.
+    // `agentInstructions: false`: the project owns one hand-written instruction file and deleted the
+    // routed copies, so every guidance slot points at it instead of Proteum's bundled fallbacks.
+    // Claude Code reads CLAUDE.md when it exists and AGENTS.md otherwise; follow the same order.
     if (manifest.app.setup.agentInstructions === false) {
-        const claudeInstructions = resolveGuidanceFile({
+        const claudeFile = resolveGuidanceFile({
             appRoot: manifest.app.root,
-            fallbackFilepath: joinPath(manifest.app.root, 'CLAUDE.md'),
+            fallbackFilepath: '',
             relativePath: 'CLAUDE.md',
-        }).filepath;
+        });
+        const claudeInstructions =
+            claudeFile.warning === undefined
+                ? claudeFile.filepath
+                : resolveGuidanceFile({
+                      appRoot: manifest.app.root,
+                      fallbackFilepath: joinPath(manifest.app.root, 'AGENTS.md'),
+                      relativePath: 'AGENTS.md',
+                  }).filepath;
 
         return {
             guidance: {

package/common/dev/mcpPayloads.ts

@@ -940,12 +940,13 @@ export const resolveInstructionRouting = ({
     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.
+    // `agentInstructions: false`: the routed copies no longer exist; route to the hand-owned file the
+    // agent actually loads (Claude Code reads CLAUDE.md when it exists and AGENTS.md otherwise).
     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 ownedFile = ['CLAUDE.md', 'AGENTS.md']
+            .map((relativeFilepath) => resolveDocumentFile({ appRoot, repoRoot, relativeFilepath }))
+            .find((filepath) => filepath !== undefined && fileExists(filepath));
+        if (ownedFile) selected.set(ownedFile, createSelectedInstruction(ownedFile, 'Project-owned agent instructions.'));
         const selectedFiles = [...selected.values()];
         return createMcpPayload({
             summary: `${selectedFiles.length} instruction files selected for ${normalizedQuery || 'current app'}`,

package/docs/agent-routing.md

@@ -141,4 +141,4 @@ The result confirms the intended routing:
 
 ## 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.
+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 hand-owned instruction file (`CLAUDE.md` when it exists, else `AGENTS.md`, the order Claude Code reads them in), 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.23",
+	"version": "2.5.25",
 	"author": "Gaetan Le Gac (https://github.com/gaetanlegac)",
 	"repository": "git://github.com/gaetanlegac/proteum.git",
 	"license": "MIT",

package/server/services/router/http/index.ts

@@ -125,6 +125,12 @@ const createContentSecurityPolicy = (config: Config['csp']): TContentSecurityPol
 
 const connectedProjectBootRetryCount = 10;
 const connectedProjectBootRetryDelayMs = 5_000;
+/**
+ * How long `cleanup()` waits for in-flight responses before force-closing their sockets.
+ * Kept under the host's drain window (Railway `drainingSeconds: 20` on the Unique Domains
+ * services), so the process exits on its own terms instead of being killed mid-response.
+ */
+export const httpDrainDeadlineMs = 10_000;
 
 const wait = async (durationMs: number) =>
     await new Promise<void>((resolve) => {
@@ -588,8 +594,25 @@ export default class HttpServer<TRouter extends TServerRouter = TServerRouter> {
         });
     }
 
+    /**
+     * Stop accepting connections and wait for in-flight responses before the process exits.
+     * `server/index.ts` calls `process.exit(0)` as soon as this resolves, so an unawaited
+     * `close()` cut every response still being written. The wait is bounded because a
+     * keep-alive or streaming client can hold a socket open indefinitely.
+     */
     public async cleanup() {
-        this.http.close();
+        await new Promise<void>((resolve) => {
+            const deadline = setTimeout(() => {
+                this.http.closeAllConnections();
+                resolve();
+            }, httpDrainDeadlineMs);
+            this.http.close(() => {
+                clearTimeout(deadline);
+                resolve();
+            });
+            // Idle keep-alive sockets would otherwise hold `close()` open until the deadline.
+            this.http.closeIdleConnections();
+        });
     }
 
     private registerDevTraceRoutes(routes: express.Express) {

package/tests/http-server-cleanup.test.cjs

@@ -0,0 +1,115 @@
+const assert = require('node:assert/strict');
+const Module = require('node:module');
+const path = require('node:path');
+
+const coreRoot = path.join(__dirname, '..');
+require('module-alias').addAliases({
+    '@client': path.join(coreRoot, 'client'),
+    '@common': path.join(coreRoot, 'common'),
+    '@server': path.join(coreRoot, 'server'),
+});
+process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
+process.env.TS_NODE_TRANSPILE_ONLY = '1';
+require('ts-node/register/transpile-only');
+
+// The app container reads the app's proteum.config.ts at import; the HTTP server only needs it at runtime.
+const httpServerModulePath = path.join(coreRoot, 'server/services/router/http/index.ts');
+const originalLoad = Module._load;
+Module._load = function patchedLoad(request, parent, isMain) {
+    if (parent?.filename === httpServerModulePath && request === '@server/app/container') {
+        return { __esModule: true, default: {} };
+    }
+
+    return originalLoad.call(this, request, parent, isMain);
+};
+
+let HttpServer;
+let httpDrainDeadlineMs;
+try {
+    ({ default: HttpServer, httpDrainDeadlineMs } = require('../server/services/router/http/index.ts'));
+} finally {
+    Module._load = originalLoad;
+}
+
+/** A real HttpServer wired to a fake app, with its node server swapped for a recorder. */
+const createDrainingServer = () => {
+    const hooks = {};
+    const app = {
+        env: { name: 'local' },
+        on: (name, callback) => {
+            hooks[name] = callback;
+        },
+    };
+    const server = new HttpServer({ domain: 'localhost', port: 0, ssl: false }, { app });
+
+    const calls = [];
+    let closeCallback;
+    server.http = {
+        close: (callback) => {
+            calls.push('close');
+            closeCallback = callback;
+        },
+        closeIdleConnections: () => calls.push('closeIdleConnections'),
+        closeAllConnections: () => calls.push('closeAllConnections'),
+    };
+
+    let settled = false;
+    const runCleanupHook = () => {
+        const drained = hooks.cleanup();
+        void drained.then(() => {
+            settled = true;
+        });
+        return drained;
+    };
+
+    return { calls, runCleanupHook, isSettled: () => settled, finishClose: () => closeCallback() };
+};
+
+const flushMicrotasks = async () => {
+    for (let index = 0; index < 5; index++) await Promise.resolve();
+};
+
+afterEach(() => {
+    vi.useRealTimers();
+});
+
+test('http server cleanup waits for close and clears the drain deadline', async () => {
+    vi.useFakeTimers();
+    const server = createDrainingServer();
+
+    const drained = server.runCleanupHook();
+    await flushMicrotasks();
+
+    assert.equal(server.isSettled(), false, 'cleanup must not resolve while responses are still in flight');
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+    assert.equal(vi.getTimerCount(), 1);
+
+    server.finishClose();
+    await drained;
+
+    assert.equal(server.isSettled(), true);
+    assert.equal(vi.getTimerCount(), 0, 'the drain deadline must be cleared once close() calls back');
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+});
+
+test('http server cleanup force-closes connections when the drain deadline passes', async () => {
+    vi.useFakeTimers();
+    const server = createDrainingServer();
+
+    const drained = server.runCleanupHook();
+
+    await vi.advanceTimersByTimeAsync(httpDrainDeadlineMs - 1);
+    assert.equal(server.isSettled(), false);
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections']);
+
+    await vi.advanceTimersByTimeAsync(1);
+    await drained;
+
+    assert.equal(server.isSettled(), true);
+    assert.deepEqual(server.calls, ['close', 'closeIdleConnections', 'closeAllConnections']);
+});
+
+test('http server drain deadline stays under the 20 second host drain window', () => {
+    assert.equal(httpDrainDeadlineMs, 10_000);
+    assert.ok(httpDrainDeadlineMs < 20_000);
+});

package/tests/inspection.test.cjs

@@ -6,7 +6,7 @@ process.env.TS_NODE_PROJECT = path.join(coreRoot, 'cli', 'tsconfig.json');
 process.env.TS_NODE_TRANSPILE_ONLY = '1';
 require('ts-node/register/transpile-only');
 
-const { explainOwner } = require('../common/dev/inspection.ts');
+const { buildOrientationResponse, explainOwner } = require('../common/dev/inspection.ts');
 
 const createRoute = (routePath, filepath) => ({
     chunkFilepath: filepath,
@@ -64,3 +64,21 @@ test('root owner lookup returns only the literal root route when present', () =>
     assert.equal(matches.length, 1);
     assert.equal(matches[0].label, '/');
 });
+
+test('orientation guidance of an opted-out app points at its hand-owned instruction file', () => {
+    const fs = require('node:fs');
+    const os = require('node:os');
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-owned-guidance-'));
+    fs.mkdirSync(path.join(appRoot, '.git'));
+    fs.writeFileSync(path.join(appRoot, 'AGENTS.md'), '# Owned\n');
+    const manifest = createManifest([]);
+    manifest.app = { coreRoot, root: appRoot, identity: { identifier: 'OwnedApp', name: 'Owned App' }, setup: { agentInstructions: false } };
+
+    const agentsOnly = buildOrientationResponse(manifest, '/').guidance;
+    assert.equal(agentsOnly.agents, path.join(appRoot, 'AGENTS.md'));
+    assert.equal(agentsOnly.documentation, path.join(appRoot, 'AGENTS.md'));
+    assert.deepEqual(agentsOnly.areaAgents, []);
+
+    fs.writeFileSync(path.join(appRoot, 'CLAUDE.md'), '# Owned for Claude\n');
+    assert.equal(buildOrientationResponse(manifest, '/').guidance.agents, path.join(appRoot, 'CLAUDE.md'));
+});

package/tests/mcp.test.cjs

@@ -156,6 +156,23 @@ const writeFreshCopyFixture = (appRoot, manifestOverrides = {}) => {
     writeFile(path.join(appRoot, '.proteum', 'manifest.json'), JSON.stringify(createManifest(appRoot, manifestOverrides), null, 2));
 };
 
+test('instruction routing sends an opted-out app to its hand-owned instruction file', () => {
+    const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-owned-'));
+
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default { agentInstructions: false };\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Owned\n');
+    writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Stale routed copy\n');
+
+    const agentsOnly = resolveInstructionRouting({ appRoot, query: 'client/pages/domain.tsx' });
+    assert.deepEqual(agentsOnly.data.selected.map((entry) => path.relative(appRoot, entry.file)), ['AGENTS.md']);
+    assert.deepEqual(agentsOnly.data.readWhen, []);
+
+    // Claude Code reads CLAUDE.md first when both exist, so routing follows it.
+    writeFile(path.join(appRoot, 'CLAUDE.md'), '# Owned for Claude\n');
+    const withClaude = resolveInstructionRouting({ appRoot, query: 'client/pages/domain.tsx' });
+    assert.deepEqual(withClaude.data.selected.map((entry) => path.relative(appRoot, entry.file)), ['CLAUDE.md']);
+});
+
 test('instruction routing returns compact selected files for a page query', () => {
     const appRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-mcp-app-'));