proteum 2.5.3 → 2.5.5

package/cli/runtime/worktreeBootstrap.ts

@@ -23,6 +23,13 @@ export type TWorktreeBootstrapMarker = {
         copied: boolean;
         copiedAt?: string;
         present: boolean;
+        root?: {
+            copied: boolean;
+            copiedAt?: string;
+            filepath: string;
+            present: boolean;
+            source?: string;
+        };
         source?: string;
     };
     packageLockHash?: string;
@@ -84,6 +91,11 @@ type TWorktreeBootstrapInputs = {
     packageLockHash?: string;
     proteumConfigHash?: string;
     proteumVersion: string;
+    rootEnv?: {
+        filepath: string;
+        present: boolean;
+        required: boolean;
+    };
 };
 
 type TRunCaptureResult = {
@@ -159,6 +171,32 @@ const findVisibleDirectory = (startPath: string, directoryName: string) => {
     }
 };
 
+const readJsonFile = (filepath: string) => {
+    try {
+        return fs.readJSONSync(filepath) as Record<string, unknown>;
+    } catch {
+        return {};
+    }
+};
+
+const hasWorkspaceRootTooling = (workspaceRoot: string) => {
+    if (fs.existsSync(path.join(workspaceRoot, 'prisma.config.ts'))) return true;
+
+    const packageJson = readJsonFile(path.join(workspaceRoot, 'package.json'));
+    return Array.isArray(packageJson.workspaces);
+};
+
+const resolveWorkspaceRootEnv = (appRoot: string) => {
+    const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    if (!packageLockFilepath) return undefined;
+
+    const workspaceRoot = path.dirname(packageLockFilepath);
+    if (workspaceRoot === normalizePath(appRoot)) return undefined;
+    if (!hasWorkspaceRootTooling(workspaceRoot)) return undefined;
+
+    return path.join(workspaceRoot, '.env');
+};
+
 const hashFile = (filepath: string | undefined) => {
     if (!filepath || !fs.existsSync(filepath)) return undefined;
 
@@ -177,6 +215,7 @@ const readMarker = (markerFilepath: string) => {
 
 const readInputs = (appRoot: string, proteumVersion: string): TWorktreeBootstrapInputs => {
     const packageLockFilepath = findNearestExistingPath(appRoot, 'package-lock.json');
+    const rootEnvFilepath = resolveWorkspaceRootEnv(appRoot);
 
     return {
         agentsHash: hashFile(path.join(appRoot, 'AGENTS.md')),
@@ -186,6 +225,13 @@ const readInputs = (appRoot: string, proteumVersion: string): TWorktreeBootstrap
         packageLockHash: hashFile(packageLockFilepath),
         proteumConfigHash: hashFile(path.join(appRoot, 'proteum.config.ts')),
         proteumVersion,
+        rootEnv: rootEnvFilepath
+            ? {
+                  filepath: rootEnvFilepath,
+                  present: fs.existsSync(rootEnvFilepath),
+                  required: true,
+              }
+            : undefined,
     };
 };
 
@@ -217,6 +263,8 @@ const collectStaleReasons = ({
     if (marker.agentsHash !== inputs.agentsHash)
         reasons.push({ code: 'worktree-bootstrap/agents-changed', message: 'AGENTS.md changed since bootstrap.' });
     if (!inputs.envPresent) reasons.push({ code: 'worktree-bootstrap/env-missing', message: '.env is missing.' });
+    if (inputs.rootEnv?.required && !inputs.rootEnv.present)
+        reasons.push({ code: 'worktree-bootstrap/root-env-missing', message: 'Workspace root .env is missing.' });
     if (!inputs.manifestPresent)
         reasons.push({ code: 'worktree-bootstrap/manifest-missing', message: '.proteum/manifest.json is missing.' });
     if (!inputs.nodeModulesPresent && !dependenciesWereIntentionallySkipped(marker, inputs))
@@ -309,18 +357,63 @@ const resolveDependencyAction = ({
     return 'up-to-date';
 };
 
+const resolveSourceRootEnv = (source: string) => {
+    const sourceWorkspaceRootEnv = resolveWorkspaceRootEnv(source);
+    if (sourceWorkspaceRootEnv && fs.existsSync(sourceWorkspaceRootEnv)) return sourceWorkspaceRootEnv;
+
+    const sourceEnvFilepath = path.join(path.resolve(source), '.env');
+    return fs.existsSync(sourceEnvFilepath) ? sourceEnvFilepath : undefined;
+};
+
 const requireSourceEnvWhenNeeded = ({ appRoot, source }: { appRoot: string; source?: string }) => {
     const envFilepath = path.join(appRoot, '.env');
-    if (fs.existsSync(envFilepath)) return { copied: false, present: true, source: undefined };
+    const rootEnvFilepath = resolveWorkspaceRootEnv(appRoot);
+    let copied = false;
+    let copiedAt: string | undefined;
+    let sourceForEnv: string | undefined;
 
-    if (!source) throw new Error('This worktree is missing .env. Pass --source <app-root> with a readable source .env.');
+    if (!fs.existsSync(envFilepath)) {
+        if (!source) throw new Error('This worktree is missing .env. Pass --source <app-root> with a readable source .env.');
 
-    const sourceEnvFilepath = path.join(path.resolve(source), '.env');
-    if (!fs.existsSync(sourceEnvFilepath)) throw new Error(`Source .env does not exist: ${sourceEnvFilepath}`);
+        const sourceEnvFilepath = path.join(path.resolve(source), '.env');
+        if (!fs.existsSync(sourceEnvFilepath)) throw new Error(`Source .env does not exist: ${sourceEnvFilepath}`);
 
-    fs.copyFileSync(sourceEnvFilepath, envFilepath);
+        fs.copyFileSync(sourceEnvFilepath, envFilepath);
+        copied = true;
+        copiedAt = nowIso();
+        sourceForEnv = path.resolve(source);
+    }
 
-    return { copied: true, copiedAt: nowIso(), present: true, source: path.resolve(source) };
+    const root: TWorktreeBootstrapMarker['env']['root'] | undefined = rootEnvFilepath
+        ? {
+              copied: false,
+              filepath: rootEnvFilepath,
+              present: fs.existsSync(rootEnvFilepath),
+          }
+        : undefined;
+
+    if (root && !root.present) {
+        if (!source) throw new Error('This worktree is missing workspace root .env. Pass --source <app-root> with a readable source .env.');
+
+        const sourceRootEnvFilepath = resolveSourceRootEnv(source);
+        if (!sourceRootEnvFilepath) {
+            throw new Error(`Source workspace root .env does not exist and source app .env is missing: ${path.resolve(source)}`);
+        }
+
+        fs.copyFileSync(sourceRootEnvFilepath, root.filepath);
+        root.copied = true;
+        root.copiedAt = nowIso();
+        root.present = true;
+        root.source = sourceRootEnvFilepath;
+    }
+
+    return {
+        copied,
+        ...(copiedAt ? { copiedAt } : {}),
+        present: fs.existsSync(envFilepath),
+        ...(root ? { root } : {}),
+        ...(sourceForEnv ? { source: sourceForEnv } : {}),
+    };
 };
 
 const writeMarker = (appRoot: string, marker: TWorktreeBootstrapMarker) => {

package/docs/agent-routing.md

@@ -66,9 +66,9 @@ Use MCP for repeated reads when a client is available:
 proteum mcp
 ```
 
-The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
+The machine router discovers live `proteum dev` sessions and offline Proteum app roots under a cwd. `proteum dev` ensures one managed machine MCP daemon is running; terminal `proteum mcp` starts or reuses that daemon and prints a compact central MCP banner with the HTTP client URL, while MCP clients can use stdio. Agents should call MCP `workflow_start` with `cwd` or a known `projectId`, use `project_resolve { cwd }` when routing is ambiguous or offline, resolve any returned `data.readiness.state="blocked"` fresh-copy setup actions, and pass the returned live `projectId` to every follow-up app-bound MCP tool. Offline candidates include readiness and port-inspected next actions, so agents should follow those instead of guessing the manifest default port. The router forwards to the selected dev-hosted `/__proteum/mcp` endpoint and strips routing fields before the app sees the call.
 
-If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's next action from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
+If machine MCP routing returns offline candidates, choose the intended app root and follow that candidate's readiness and next actions from the app root, not from the monorepo wrapper. In `/.codex/worktrees/`, if `workflow_start` returns a worktree bootstrap block, run `npx proteum worktree init --source <source-app-root>` or the returned `--refresh` command before any runtime read. If machine MCP routing fails, run `proteum mcp status` and `proteum runtime status` from the intended app root; if no live session exists, use the exact Start Dev next action from runtime status so occupied router/HMR ports are avoided. If the same app already responds on the configured port without live tracking, use or repair that runtime instead of starting another server. Do not `curl` normal page routes to identify which app owns a port; use runtime status or Proteum dev-only endpoints. If a live session exists but runtime/MCP is unreachable, stop the listed session file first, then start dev again. Do not run diagnose, trace, or perf reads while runtime health is unreachable. Do not start a second dev server in the same worktree, and do not start a second managed MCP daemon. Then retry MCP `workflow_start`.
 
 Prefer CLI over MCP when the result must be reproducible as a shell command, part of verification, or copied into CI/debug instructions.
 
@@ -135,6 +135,6 @@ The latest Product `/domains` benchmark used routed instructions plus the compac
 The result confirms the intended routing:
 
 - use CLI for reproducible verification and final command evidence
-- use `workflow_start` to collapse project resolution, runtime status, instruction previews, owner summary, and first next actions into one read
+- 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

package/docs/diagnostics.md

@@ -112,9 +112,9 @@ Default compact command output follows this shape:
 
 `proteum runtime status` emits the current app manifest summary, tracked dev sessions, selected live session, MCP URL, health status, configured router/HMR port inspection, and a suggested next command. Use it before starting another dev server, and use its Start Dev command instead of probing page bodies when the default port is occupied. If it reports that the same app already responds on the configured port without a live tracked session, use or repair that runtime instead of starting a second server.
 
-Inside `/.codex/worktrees/`, `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` require a fresh `.proteum/worktree-bootstrap.json`. If the marker is missing, run `npx proteum worktree init --source <source-app-root>`. If hashes, `.env`, `.proteum/manifest.json`, `node_modules`, or the Proteum version are stale, run the returned `npx proteum worktree init --source <source-app-root> --refresh` command. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor diagnostics, and MCP output.
+Inside `/.codex/worktrees/`, `proteum dev`, `proteum refresh`, `proteum runtime status`, `proteum verify`, and MCP `workflow_start` require a fresh `.proteum/worktree-bootstrap.json`. If the marker is missing, run `npx proteum worktree init --source <source-app-root>`. If hashes, app `.env`, workspace-root `.env` for monorepos with root tooling, `.proteum/manifest.json`, `node_modules`, or the Proteum version are stale, run the returned `npx proteum worktree init --source <source-app-root> --refresh` command. `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` bypasses the block but remains visible in runtime status, doctor diagnostics, and MCP output.
 
-During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's port-inspected next action when needed, then pass the selected live `projectId` to follow-up app-bound tools.
+During `proteum dev`, `/__proteum/mcp` exposes compact `workflow_start`, `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_*`, `perf_*`, and `logs_tail` tools without spawning CLI commands for each repeated read. `proteum dev` also ensures one managed machine `proteum mcp` daemon is running. Through the machine router, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, use `project_resolve { cwd }`, follow the selected app root's fresh-copy readiness and port-inspected next actions when needed, then pass the selected live `projectId` to follow-up app-bound tools. `workflow_start` returns `data.readiness` with read-only setup checks for `.env`, dependencies, generated manifest state, connected producers, Prisma/client readiness, redacted database URL shape, and local database TCP reachability.
 
 MCP tool/resource output follows compact single-line `proteum-mcp-v1` JSON:
 
@@ -251,7 +251,7 @@ Treat these as framework contract failures first. The fix usually belongs at the
 
 For AI coding agents or automation:
 
-1. When MCP is available, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, start dev from that app root when needed, then retry with the selected stable live `projectId`.
+1. When MCP is available, call `workflow_start` with `cwd` or a known `projectId`; if routing is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, select the intended app root, resolve any returned `data.readiness.state="blocked"` setup actions, start dev from that app root when needed, then retry with the selected stable live `projectId`.
 2. Use the returned `projectId` for MCP `runtime_status`, `orient`, `instructions_resolve`, `route_candidates`, `explain_summary`, `doctor`, `diagnose`, `trace_show`, `perf_request`, and `logs_tail` read-only runtime, owner, route, instruction, trace, perf, and log reads.
 3. Do not run CLI equivalents after a successful MCP result for the same read, and do not run broad source searches for ownership MCP already returned. Use CLI for fallback, `dev`, `build`, `check`, `verify`, migrations, E2E, and final terminal evidence.
 4. Use selected instruction previews for read-only discovery and diagnostics; read full files only before edits or git writes, when returned `fullRead`/`fullReadPolicy` requires it, or when the preview is insufficient.

package/docs/mcp.md

@@ -28,7 +28,7 @@ The router is read-only. It does not start or stop dev servers, mutate files, re
 Use this flow:
 
 1. Call MCP `workflow_start` with `cwd` or a known `projectId`.
-2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
+2. If the result is ambiguous or returns offline app candidates, call `project_resolve { cwd }`, pick the intended app root, resolve any returned `data.readiness.state="blocked"` setup actions, start exactly one `proteum dev` server from that app root when needed, then retry `workflow_start`.
 3. Pass the returned live `projectId` to every follow-up app-bound MCP call.
 4. After an MCP read succeeds, do not run the equivalent CLI command or broad source search for the same state; keep CLI for fallback, validation, and final terminal evidence.
 
@@ -47,7 +47,7 @@ Example tool calls:
 {"tool":"db_query","arguments":{"projectId":"prj_0123abcd4567","sql":"SELECT id, email FROM User LIMIT 5","limit":5}}
 ```
 
-`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
+`workflow_start` is the only app-bound bootstrap tool that may resolve from `cwd` when `projectId` is not known. It may return offline app candidates when no matching dev server is running yet. Its machine-router response includes `data.readiness`, a read-only fresh-copy preflight covering app/root `.env` files, dependency install root and package manager, generated Proteum manifest state, local connected producer apps, Prisma schema/client readiness, redacted database URL shape, and local TCP database reachability when the host is local. The preflight adds exact setup commands where safe, such as copying `.env.example`, installing dependencies, running `npx proteum refresh`, generating Prisma Client, checking Prisma migration status, preflighting connected producer apps, and starting `proteum dev` on a checked port. Other app-bound tools require a live `projectId`; if they omit it, the router returns a compact error that tells the agent to call `projects_list` or `project_resolve`. There is no single-project fallback, because wrong-project reads are worse than an explicit routing retry.
 
 When the selected app root is inside `/.codex/worktrees/`, `workflow_start` first checks `.proteum/worktree-bootstrap.json`. If the marker is missing or stale, it returns `ok: false` with a single next action such as `npx proteum worktree init --source <source-app-root>` or the same command with `--refresh`. The router does not forward to the app MCP endpoint until bootstrap is complete, unless `PROTEUM_ALLOW_UNBOOTSTRAPPED_WORKTREE=1` is set; bypasses remain visible in MCP, `runtime status`, and `doctor`.
 
@@ -79,9 +79,10 @@ If machine MCP routing fails:
 1. Run `proteum mcp status`.
 2. Run `proteum runtime status` from the intended app root. If you are in a monorepo wrapper, use the returned app candidates and exact next action instead of starting dev from the wrapper.
 3. If the app root is inside `/.codex/worktrees/` and runtime status or workflow start reports missing/stale bootstrap, run `proteum worktree init --source <source-app-root>` or the returned `--refresh` command first.
-4. If no live app session exists, use the exact Start Dev next action returned by runtime status. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
-5. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
-6. Retry MCP `workflow_start` and use the returned `projectId`.
+4. If `workflow_start` returns `data.readiness.state="blocked"`, run or resolve the readiness setup actions before starting dev.
+5. If no live app session exists, use the exact Start Dev next action returned by runtime status or `workflow_start`. It checks the configured router/HMR ports and suggests an alternate free port when the manifest default is occupied.
+6. If a live session exists but runtime/MCP is unreachable, stop the listed session file with `proteum dev stop --session-file <path>`, then start dev again.
+7. Retry MCP `workflow_start` and use the returned `projectId`.
 
 Offline `project_resolve` and `workflow_start` candidates also inspect configured router/HMR ports before returning `nextAction`. If the configured port already serves the same app but no live machine project is registered, the next action is runtime tracking repair, not starting a second dev server.
 
@@ -122,7 +123,7 @@ App-bound tools require `projectId` when called through `proteum mcp`:
 
 | Tool | Purpose |
 | --- | --- |
-| `workflow_start` | One-call bootstrap with resolved project, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
+| `workflow_start` | One-call bootstrap with resolved project, fresh-copy readiness, runtime, selected instruction previews, owner summary, doctor summaries, duplicate-avoidance rules, and next actions |
 | `runtime_status` | Manifest summary, selected runtime, tracked sessions, health, and MCP URL |
 | `orient` | Owner, instruction routing, connected boundaries, and next actions |
 | `instructions_resolve` | Selected instruction files for a query, with short previews and full-read policy |

package/docs/request-tracing.md

@@ -33,7 +33,7 @@ proteum perf memory --since 1h --group-by controller
 
 Default trace output is compact `proteum-agent-v1` JSON with counts, failed calls, error events, hot calls, and hot SQL. Use `--events` or `--full` only when raw event details, payload summaries, or SQL text are needed.
 
-When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates or unreachable runtime health, start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
+When an MCP client is available, call `workflow_start` with `cwd` or a known `projectId`, then use the returned live `projectId` with MCP `trace_latest`, `trace_show`, `perf_top`, and `perf_request` for repeated reads against the same running app. If `workflow_start` returns offline app candidates, `data.readiness.state="blocked"`, or unreachable runtime health, resolve the readiness setup actions and start or repair exactly one `proteum dev` server from the intended app root before trace or perf reads. Keep the CLI commands for reproducible terminal evidence and final verification logs.
 
 Before reproducing a bug or starting a new test pass:
 

package/package.json

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

package/tests/mcp.test.cjs

@@ -99,8 +99,53 @@ const createManifest = (appRoot, overrides = {}) => ({
 
 const writeProteumAppFixture = (appRoot, manifestOverrides = {}) => {
     writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture"}\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(
+        path.join(appRoot, '.env'),
+        [
+            'ENV_NAME=local',
+            'ENV_PROFILE=dev',
+            `PORT=${manifestOverrides.routerPort || 3104}`,
+            `URL=http://localhost:${manifestOverrides.routerPort || 3104}`,
+            `URL_INTERNAL=http://localhost:${manifestOverrides.routerPort || 3104}`,
+            '',
+        ].join('\n'),
+    );
+    fs.mkdirSync(path.join(appRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Client\n');
+    writeFile(path.join(appRoot, 'client', 'pages', 'AGENTS.md'), '# Pages\n');
+    writeFile(path.join(appRoot, 'server', 'AGENTS.md'), '# Server\n');
+    writeFile(path.join(appRoot, 'server', 'routes', 'AGENTS.md'), '# Routes\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# App\n');
+    writeFile(path.join(appRoot, 'diagnostics.md'), '# Diagnostics\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), JSON.stringify(createManifest(appRoot, manifestOverrides), null, 2));
+};
+
+const writeFreshCopyFixture = (appRoot, manifestOverrides = {}) => {
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fresh-copy"}\n');
+    writeFile(path.join(appRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(
+        path.join(appRoot, '.env.example'),
+        [
+            'ENV_NAME=local',
+            'ENV_PROFILE=dev',
+            'PORT=3020',
+            'URL=http://localhost:3020',
+            'URL_INTERNAL=http://localhost:3020',
+            'DATABASE_URL=mysql://user:pass@localhost:3306/app',
+            '',
+        ].join('\n'),
+    );
     writeFile(path.join(appRoot, 'identity.config.ts'), 'export default {};\n');
     writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(
+        path.join(appRoot, 'prisma', 'schema.prisma'),
+        ['generator client {', '  provider = "prisma-client-js"', '  output = "../var/prisma"', '}', '', 'datasource db {', '  provider = "mysql"', '}'].join(
+            '\n',
+        ),
+    );
     writeFile(path.join(appRoot, 'client', 'AGENTS.md'), '# Client\n');
     writeFile(path.join(appRoot, 'client', 'pages', 'AGENTS.md'), '# Pages\n');
     writeFile(path.join(appRoot, 'server', 'AGENTS.md'), '# Server\n');
@@ -700,7 +745,10 @@ test('machine MCP router resolves projects by cwd and bootstraps workflow withou
     assert.equal(forwardedCall.name, 'workflow_start');
     assert.deepEqual(forwardedCall.arguments, { route: '/domains', task: 'read-only runtime health pass' });
     assert.equal(workflowPayload.data.project.projectId, productMachineRecord.projectId);
-    assert.equal(workflowPayload.nextActions[0].toolArgs.projectId, productMachineRecord.projectId);
+    assert.equal(
+        workflowPayload.nextActions.find((action) => action.tool === 'diagnose').toolArgs.projectId,
+        productMachineRecord.projectId,
+    );
 
     await client.close();
     await server.close();
@@ -785,6 +833,55 @@ test('machine MCP router resolves offline monorepo app candidates before dev is
     await server.close();
 });
 
+test('machine MCP workflow_start reports fresh-copy setup blockers before dev start', async (t) => {
+    const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+    const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-fresh-copy-registry-'));
+    process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = registryDir;
+    t.onTestFinished(() => {
+        if (previousRegistryDir === undefined) delete process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
+        else process.env.PROTEUM_MACHINE_DEV_SESSION_DIR = previousRegistryDir;
+    });
+
+    const repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-fresh-copy-'));
+    const appRoot = path.join(repoRoot, 'apps', 'product');
+    writeFreshCopyFixture(appRoot, {
+        identifier: 'FreshCopyApp',
+        name: 'Fresh Copy',
+        routerPort: 3022,
+    });
+
+    const server = createProteumMachineMcpServer({ version: 'test' });
+    const client = new Client({ name: 'machine-mcp-test', version: '1.0.0' });
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+    await server.connect(serverTransport);
+    await client.connect(clientTransport);
+
+    const workflow = await client.callTool({
+        name: 'workflow_start',
+        arguments: { cwd: appRoot, task: 'prepare fresh copy' },
+    });
+    const payload = JSON.parse(workflow.content[0].text);
+    const actionLabels = payload.nextActions.map((action) => action.label);
+
+    assert.equal(payload.ok, true);
+    assert.equal(payload.data.readiness.state, 'blocked');
+    assert.equal(payload.data.readiness.env.app.present, false);
+    assert.equal(payload.data.readiness.dependencies.nodeModulesPresent, false);
+    assert.equal(payload.data.readiness.database.detected, true);
+    assert.equal(payload.data.readiness.database.generatedClientPresent, false);
+    assert.equal(actionLabels.includes('Copy App Env Example'), true);
+    assert.equal(actionLabels.includes('Install Dependencies'), true);
+    assert.equal(actionLabels.includes('Generate Prisma Client'), true);
+    assert.equal(actionLabels.includes('Start Dev'), true);
+    assert.match(payload.nextActions.find((action) => action.label === 'Install Dependencies').command, /npm install/);
+    assert.match(payload.nextActions.find((action) => action.label === 'Generate Prisma Client').command, /prisma generate/);
+    assert.doesNotMatch(workflow.content[0].text, /mysql:\/\/user:pass/);
+
+    await client.close();
+    await server.close();
+});
+
 test('machine MCP workflow_start blocks offline unbootstrapped Codex worktrees', async (t) => {
     const previousRegistryDir = process.env.PROTEUM_MACHINE_DEV_SESSION_DIR;
     const registryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-machine-worktree-offline-'));

package/tests/worktree-bootstrap.test.cjs

@@ -153,6 +153,81 @@ test('worktree bootstrap requires a source env only when .env is missing', async
     assert.equal(result.status.blocking, false);
 });
 
+test('worktree bootstrap copies workspace root env for monorepo root tooling', async () => {
+    const targetRepoRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-monorepo-')), '.codex', 'worktrees', 'fixture-repo');
+    const appRoot = path.join(targetRepoRoot, 'apps', 'product');
+    const sourceRepoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-source-repo-'));
+    const sourceAppRoot = path.join(sourceRepoRoot, 'apps', 'product');
+
+    writeFile(path.join(targetRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(targetRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(targetRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    fs.mkdirSync(path.join(targetRepoRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture-product"}\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), '{"version":10}\n');
+
+    writeFile(path.join(sourceRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(sourceRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(sourceRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    writeFile(path.join(sourceRepoRoot, '.env'), 'DATABASE_URL=postgres://root\n');
+    writeFile(path.join(sourceAppRoot, '.env'), 'PORT=3021\n');
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        source: sourceAppRoot,
+    });
+
+    assert.equal(fs.readFileSync(path.join(appRoot, '.env'), 'utf8'), 'PORT=3021\n');
+    assert.equal(fs.readFileSync(path.join(targetRepoRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://root\n');
+    assert.equal(result.marker.env.root.present, true);
+    assert.equal(result.marker.env.root.copied, true);
+    assert.equal(result.status.blocking, false);
+});
+
+test('worktree bootstrap falls back to source app env for missing workspace root env', async () => {
+    const targetRepoRoot = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-root-env-fallback-')), '.codex', 'worktrees', 'fixture-repo');
+    const appRoot = path.join(targetRepoRoot, 'apps', 'api');
+    const sourceRepoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'proteum-worktree-source-repo-fallback-'));
+    const sourceAppRoot = path.join(sourceRepoRoot, 'apps', 'api');
+
+    writeFile(path.join(targetRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(targetRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(targetRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    fs.mkdirSync(path.join(targetRepoRoot, 'node_modules'), { recursive: true });
+    writeFile(path.join(appRoot, 'package.json'), '{"name":"fixture-api"}\n');
+    writeFile(path.join(appRoot, 'proteum.config.ts'), 'export default {};\n');
+    writeFile(path.join(appRoot, 'AGENTS.md'), '# Agents\n');
+    writeFile(path.join(appRoot, '.proteum', 'manifest.json'), '{"version":10}\n');
+
+    writeFile(path.join(sourceRepoRoot, 'package.json'), '{"workspaces":["apps/*"]}\n');
+    writeFile(path.join(sourceRepoRoot, 'package-lock.json'), '{"lockfileVersion":3}\n');
+    writeFile(path.join(sourceRepoRoot, 'prisma.config.ts'), 'export default {};\n');
+    writeFile(path.join(sourceAppRoot, '.env'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+
+    const result = await runWorktreeBootstrapInit({
+        appRoot,
+        coreRoot,
+        proteumVersion: 'test',
+        runDependencies: noOpDeps,
+        runRefresh: noOpRefresh,
+        runRuntimeStatus: noOpRuntime,
+        source: sourceAppRoot,
+    });
+
+    assert.equal(fs.readFileSync(path.join(appRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+    assert.equal(fs.readFileSync(path.join(targetRepoRoot, '.env'), 'utf8'), 'DATABASE_URL=postgres://app\nPORT=3022\n');
+    assert.equal(result.marker.env.root.present, true);
+    assert.equal(result.marker.env.root.source, path.join(sourceAppRoot, '.env'));
+    assert.equal(result.status.blocking, false);
+});
+
 test('worktree bootstrap detects missing env manifest node_modules and version changes', async () => {
     const appRoot = createCodexAppRoot();
     writeBootstrapFixture(appRoot);