@@ -0,0 +1,5 @@
+---
+'agent-bundle': patch
+---
+
+Give installed packs the operator `.env` layer that only `agent-bundle mcp run` had: every emitted stdio MCP entry, every hook wrapper that runs plugin code, and the artifact CLI `bin/<name>.mjs` read `<plugin root>/.env` then `.env.local` at launch (the plugin root is the expanded `AGENT_BUNDLE_PLUGIN_ROOT`, else the shell's parent directory), filling only variables the host did not set — host environment and manifest `env` win, `.env.local` beats `.env`, values are never logged, a missing file costs nothing, an unreadable one is skipped. `AGENT_BUNDLE_ENV_FILE` names the file(s) to read instead (platform path delimiter; `none` disables the layer), and `mcp run` hands `--env-file` / `--no-env` down through it so a rehearsal and an installed pack read the same files. The loader is the new plain-Node `agent-bundle/launch-env` module (`applyOperatorEnv`, `parseOperatorEnv`), inlined into the shells without Effect. `agent-bundle doctor` reports whether an installed copy carries `.env` / `.env.local` and how many variables each declares (`AB7331`, informational; a warning when the file cannot be read), never a name or a value. The npm package bin reads no pack file. Fixes #469. (#PR)
@@ -36,7 +36,7 @@ even when no error diagnostic was reported.
 | `AB7010`–`AB7013` | npm prepack inventory, artifact freshness, package bin targets, and release-version agreement. |
 | `AB7200`–`AB7202`, `AB7210`–`AB7211` | Development rebuilds and live host surfaces: rebuild admission and phase failures, development host install sync, and the dev-epoch contract gate (see below). |
 | `AB7xxx` | Project preparation and development rebuilds. |
-| `AB7300`–`AB7330` | Read-only install Doctor: host probes, installed inventory, bundle comparison and registration proof, runtime endpoint health and identity, durable-state inventory, static bytes-at-rest validation, foreign-install detection (`AB7321`; see below), Cursor plugin hook registration / marketplace staging (`AB7322`–`AB7324`; see below), host load refusal (`AB7325`; see below), the Cursor Agent Plugins launch proof (`AB7326`; see below), a disabled Claude install (`AB7327`; see below), and lifecycle receipts and activation states (`AB7328`–`AB7330`; see below). `AB7311` and `AB7325` are also emitted by `build` and `validate --artifact` from the Claude load check (see "Claude Code host validation"). |
+| `AB7300`–`AB7331` | Read-only install Doctor: host probes, installed inventory, bundle comparison and registration proof, runtime endpoint health and identity, durable-state inventory, static bytes-at-rest validation, foreign-install detection (`AB7321`; see below), Cursor plugin hook registration / marketplace staging (`AB7322`–`AB7324`; see below), host load refusal (`AB7325`; see below), the Cursor Agent Plugins launch proof (`AB7326`; see below), a disabled Claude install (`AB7327`; see below), lifecycle receipts and activation states (`AB7328`–`AB7330`; see below), and the operator `.env` layer of an installed pack (`AB7331`; see below). `AB7311` and `AB7325` are also emitted by `build` and `validate --artifact` from the Claude load check (see "Claude Code host validation"). |
 | `AB8200`–`AB8209` | Workbench development runtime routes (`/api/runtime/**`): `AB8200` development runtime provider configuration, load, or lifecycle failure, `AB8201` runtime/session/run not available, `AB8202` invalid route path, `AB8203` invalid request shape, `AB8204` stale runtime generation or MCP session revision (409), `AB8205` runtime request could not be completed, `AB8206` Workbench runtime client failure, `AB8207` Agent Document decoding needs the optional `@agent-bundle/runtime` peer (503), `AB8208` stored Flight could not be decoded as an Agent Document (409), `AB8209` decoded Agent Document over the 16 MiB budget (413) or an invalid document response. |
 | `AB8210`–`AB8214` | Workbench semantic lifecycle replay routes (`/api/lifecycles`, `/api/lifecycles/replays`): `AB8210` invalid path, `AB8211` malformed replay request or native envelope (400, carries the shared validator message), `AB8212` replay unavailable or could not be completed, `AB8213` stale manifest binding (409; the page repairs it with refresh → explicit re-run), `AB8214` replay over the 16 MiB budget (413). |
 | `AB8215`–`AB8218` | Workbench read-only host discovery route. |
@@ -788,6 +788,19 @@ SQLite lock or shared-memory files.
 | --- | --- | --- |
 | `AB7316` | warning | An installed bundle's `state/` directory or one of its `*.sqlite`, `-wal`, or `-shm` files cannot be read with filesystem metadata operations. Repair permissions and rerun Doctor; Doctor never repairs state. |
 
+## Read-only Doctor operator env inventory (`AB7331`)
+
+An installed pack's shells read `<plugin root>/.env` and `.env.local` at
+launch (#469) to fill variables the host did not set. Doctor reports whether
+those files are present and how many variables each declares — never a name
+or a value — so an operator can see that a credential-configured pack is, or
+is not, configured. Absent files are the normal case and produce no
+diagnostic.
+
+| Code | Severity | Trigger |
+| --- | --- | --- |
+| `AB7331` | info / warning | Info: an installed copy (or the `--from` bundle) carries `.env` or `.env.local` at its plugin root; the message names the file and its variable count. Warning: the file exists but cannot be read, so the pack's shells skip it at launch — repair its permissions and rerun Doctor. |
+
 ## Read-only runtime identity introspection (`AB7317`–`AB7318`)
 
 | Code | Severity | Trigger |
 
@@ -1165,6 +1165,22 @@ canonical precedence order (highest wins):
 | 2 | `.env` file layer | The conventional project-root set, or the explicit `--env-file` list in order. Fills gaps only; never beats an exported variable. |
 | 1 (lowest) | Manifest env | Entries declared in the server config plus the injected plugin-root anchor, path tokens expanded. |
 
+Installed packs get the same layer without `mcp run` (#469): every artifact
+shell that runs plugin code — the stdio MCP entry (before its deferred server
+import), the hook wrappers that execute handlers or render standalone, and the
+artifact CLI `bin/<name>.mjs` — applies `agent-bundle/launch-env`
+(`src/launch-env.ts`, plain Node, inlined into the bundle) at startup. It
+reads `<plugin root>/.env` then `.env.local`, where the plugin root is the
+expanded `AGENT_BUNDLE_PLUGIN_ROOT` or the shell's parent directory, or the
+files `AGENT_BUNDLE_ENV_FILE` names (platform-delimited list; `none` disables
+the layer); it fills only variables the host did not set, never logs a value,
+treats a missing file as the normal case and an unreadable one as skipped.
+The dotenv grammar has no `${VAR}` interpolation. Under `mcp run` the plugin
+root is the project root, so the shell's pass is a no-op; `--env-file` and
+`--no-env` are handed down as `AGENT_BUNDLE_ENV_FILE` so the shell follows the
+operator's choice. The npm package bin reads no pack file. Doctor reports the
+presence and variable count of each file (`AB7331`).
+
 ### Durable-state anchors
 
 Under `mcp run` the artifact is an ephemeral build product, so both
 
@@ -68,6 +68,10 @@
       "types": "./dist/meta.d.ts",
       "import": "./dist/meta.js"
     },
+    "./launch-env": {
+      "types": "./dist/launch-env.d.ts",
+      "import": "./dist/launch-env.js"
+    },
     "./mcp-entry": {
       "types": "./dist/mcp-entry.d.ts",
       "import": "./dist/mcp-entry.js"
 
@@ -102,6 +102,7 @@ export default defineConfig({
       'event-project': './src/events/project.ts',
       index: './src/index.ts',
       'install-entry': './src/install-entry.ts',
+      'launch-env': './src/launch-env.ts',
       'lifecycle-render-child': './src/dev/playground/lifecycle-render-child.ts',
       'mcp-apps': './src/mcp-apps.ts',
       'mcp-entry': './src/mcp-entry.ts',
 
@@ -1,6 +1,7 @@
 import type { Diagnostic } from '../core/diagnostics.ts';
 import { dataArrayValues, hasDataKeys, isPlainDataRecord, isRecord, ownDataValue } from '../core/strict-json.ts';
 import { escapeRegExp } from '../core/strings.ts';
+import { operatorEnvImports, operatorEnvStatement } from '../build/launch-env-shell.ts';
 import type { CanonicalAgentEvent } from '../routes/public.ts';
 import {
   canonicalHookEvents,
@@ -633,6 +634,10 @@ const eventRouteHookWrapperSource = (
     : ['const target = artifactTarget;'];
   return [
     "import { dirname, resolve } from 'node:path';",
+    // Only a wrapper that can render in-process needs the operator `.env`
+    // layer (#469): a shared-runtime wrapper forwards the event to the warm
+    // MCP process, which applied the layer itself when it started.
+    ...(standalone ? operatorEnvImports({ importsFileUrlToPath: retiresLineage }) : []),
     ...(standalone ? ["import { Worker } from 'node:worker_threads';"] : []),
     ...(standalone
       ? ["import { agent, available, createAgentRenderDispatcher, resolveStandaloneLineage, runAgentRequest, unavailable } from '@agent-bundle/runtime';"]
@@ -659,6 +664,7 @@ const eventRouteHookWrapperSource = (
     `const fallbackMode = ${JSON.stringify(route.fallback)};`,
     `const timeoutMs = ${String(entry.hook.timeoutMs ?? 5_000)};`,
     "const endpointId = `${artifactEpoch}:${artifactTarget}:${dirname(dirname(resolve(process.argv[1])))}`;",
+    ...(standalone ? [operatorEnvStatement] : []),
     '',
     'const fail = (message) => { throw new Error(`Agent Bundle event route error: ${message}`); };',
     ...(standalone
@@ -794,7 +800,11 @@ const eventRouteHookWrapperSource = (
 
 /** Emits the published Cursor hook wrapper source; see encodeCursorPlaygroundInput for the envelope contract. */
 export const cursorHookWrapperSource = (entry: TargetHookWrapper): string => [
+  ...operatorEnvImports({ importsFileUrlToPath: false }),
   `import * as handlerModule from ${JSON.stringify(entry.hook.source)};`,
+  // The installed pack's operator `.env` layer (#469), applied before the
+  // handler runs; the handler module itself is a static import.
+  operatorEnvStatement,
   'const target = "cursor";',
   `const canonicalEvent = ${JSON.stringify(entry.event)};`,
   `const nativeEvent = ${JSON.stringify(entry.nativeEvent)};`,
@@ -1209,7 +1219,11 @@ export const nativeHookWrapperSource = (
       ]
     : [`const target = ${JSON.stringify(entry.target)};`];
   return [
+    ...operatorEnvImports({ importsFileUrlToPath: false }),
     `import * as handlerModule from ${JSON.stringify(entry.hook.source)};`,
+    // The installed pack's operator `.env` layer (#469), applied before the
+    // handler runs; the handler module itself is a static import.
+    operatorEnvStatement,
     ...targetSource,
     `const canonicalEvent = ${JSON.stringify(entry.event)};`,
     `const nativeEvent = ${JSON.stringify(nativeEvent)};`,
 
@@ -7,11 +7,13 @@ import type { Diagnostic } from '../core/diagnostics.ts';
 import type { NormalizedBinEntry, NormalizedPlugin } from '../core/types.ts';
 import { resolveArtifactDestination } from './emit.ts';
 import { runtimeIgnoredRoot, type CompiledEntry } from './entries.ts';
+import { launchEnvRuntimeSpecifier } from './launch-env-shell.ts';
 import {
   cliEntryRuntimePath,
   cliEntryRuntimeSpecifier,
   generatedCliBinEntrySource,
   generatedRenderedRouteWorkerSource,
+  launchEnvRuntimePath,
 } from './entry-shell.ts';
 import type { RslibEntry, RslibSurfacePlan } from './rslib.ts';
 
@@ -111,7 +113,8 @@ export const cliBinRslibEntries = (
   const cli = generatedCli(entry.bin);
   const workerFile = `${entry.name}-flight.mjs`;
   const entries: RslibEntry[] = [{
-    aliases: { [cliEntryRuntimeSpecifier]: cliEntryRuntimePath() },
+    // The artifact-hosted bin applies the pack's operator `.env` layer (#469).
+    aliases: { [cliEntryRuntimeSpecifier]: cliEntryRuntimePath(), [launchEnvRuntimeSpecifier]: launchEnvRuntimePath() },
     name: `bin-${entry.name}`,
     outputRelativePath: cliBinArtifactPath(entry.name),
     ...(entry.rendered ? { rscManifest: true as const } : {}),
@@ -193,7 +196,7 @@ export const planCliBinsSurface = (
           }),
       })));
     },
-    ignoredSourcePaths: [runtimeIgnoredRoot(cliEntryRuntimePath())],
+    ignoredSourcePaths: [runtimeIgnoredRoot(cliEntryRuntimePath()), launchEnvRuntimePath()],
     logLevel: 'error',
   };
 };
 
@@ -23,8 +23,10 @@ import { stableJson } from '../core/digest.ts';
 import { emitPlanEntries, resolveArtifactDestination } from './emit.ts';
 import { scanEntryExports } from './entry-exports.ts';
 import { deepFreeze } from '../core/freeze.ts';
+import { launchEnvRuntimeSpecifier } from './launch-env-shell.ts';
 import {
   cliEntryRuntimePath,
+  launchEnvRuntimePath,
   cliEntryRuntimeSpecifier,
   generatedExecutableEntrySource,
   generatedRenderedRouteWorkerSource,
@@ -414,6 +416,9 @@ export const planMcpEntriesSurface = async (
       : undefined;
   }));
   const runtimeShell = entryShells.some((shell) => shell !== undefined) ? mcpEntryRuntimePath() : undefined;
+  // The stdio lifecycle shell applies the operator `.env` layer (#469); the
+  // plain-Node module is inlined beside it.
+  const launchEnvRuntime = runtimeShell === undefined ? undefined : launchEnvRuntimePath();
   const eventIpcRuntime = options.eventHooks.length === 0 ? undefined : eventRuntimeModulePath('ipc');
   const eventProjectRuntime = options.eventHooks.length === 0 ? undefined : eventRuntimeModulePath('project');
   const serverRuntime = generatedRouteSources.some((routeSource) => routeSource !== undefined)
@@ -425,6 +430,7 @@ export const planMcpEntriesSurface = async (
       : {
         aliases: {
           [mcpEntryRuntimeSpecifier]: runtimeShell,
+          ...(launchEnvRuntime === undefined ? {} : { [launchEnvRuntimeSpecifier]: launchEnvRuntime }),
           ...(id !== eventHostId || eventIpcRuntime === undefined || eventProjectRuntime === undefined
             ? {}
             : {
@@ -475,6 +481,7 @@ export const planMcpEntriesSurface = async (
       : {
         ignoredSourcePaths: [
           ...(runtimeShell === undefined ? [] : [runtimeShell]),
+          ...(launchEnvRuntime === undefined ? [] : [launchEnvRuntime]),
           ...(eventIpcRuntime === undefined ? [] : [runtimeIgnoredRoot(eventIpcRuntime)]),
           ...(serverRuntime === undefined ? [] : [runtimeIgnoredRoot(serverRuntime)]),
         ],
@@ -549,6 +556,7 @@ export const planHooksSurface = (
   const workerArtifactEpoch = generatedRouteArtifactEpoch(options.plugin);
   const eventIpcRuntime = routeEntries.length === 0 ? undefined : eventRuntimeModulePath('ipc');
   const eventProjectRuntime = routeEntries.length === 0 ? undefined : eventRuntimeModulePath('project');
+  const launchEnvRuntime = launchEnvRuntimePath();
   const workerEntry = standaloneEventRoutes.length === 0
     ? undefined
     : {
@@ -587,14 +595,16 @@ export const planHooksSurface = (
         || entries[index]!.hook.eventRoute?.fallback === 'standalone'
         ? { rscManifest: true as const }
         : {}),
-      ...(entries[index]!.hook.eventRoute === undefined || eventIpcRuntime === undefined
-        ? {}
-        : {
-          aliases: {
+      aliases: {
+        // Every wrapper that runs plugin code applies the operator `.env` layer (#469).
+        [launchEnvRuntimeSpecifier]: launchEnvRuntime,
+        ...(entries[index]!.hook.eventRoute === undefined || eventIpcRuntime === undefined
+          ? {}
+          : {
             [eventIpcRuntimeSpecifier]: eventIpcRuntime,
             ...(eventProjectRuntime === undefined ? {} : { [eventProjectRuntimeSpecifier]: eventProjectRuntime }),
-          },
-        }),
+          }),
+      },
       source: entry.source,
       sourceInputs: entry.sourceInputs,
       virtualSource: entries[index]!.virtualSource
@@ -603,11 +613,10 @@ export const planHooksSurface = (
       })),
       ...(workerEntry === undefined ? [] : [workerEntry]),
     ],
-    ...(eventIpcRuntime === undefined
-      ? {}
-      : {
-        ignoredSourcePaths: [runtimeIgnoredRoot(eventIpcRuntime)],
-      }),
+    ignoredSourcePaths: [
+      launchEnvRuntime,
+      ...(eventIpcRuntime === undefined ? [] : [runtimeIgnoredRoot(eventIpcRuntime)]),
+    ],
     finish: async (evidence) => {
       const evidenceByPath = new Map(evidence.map((entry) => [entry.path, entry.sourceInputs]));
       return Object.freeze(compiled.map((entry, index) => Object.freeze({
 
@@ -2,6 +2,7 @@ import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 import { eventIpcRuntimeSpecifier, eventProjectRuntimeSpecifier } from '../adapters/hook-contract.ts';
+import { operatorEnvImports, operatorEnvStatement } from './launch-env-shell.ts';
 import type { NoticeDeliveryAdvertisement } from '../adapters/notice-delivery.ts';
 import { stableJson } from '../core/digest.ts';
 import type { NormalizedHook, NormalizedNoticeRetentionPolicy, NormalizedStateDefinition } from '../core/types.ts';
@@ -52,17 +53,24 @@ export const mcpEntryRuntimePath = (): string => runtimeModulePath('mcp-entry');
 
 export const mcpServerRuntimePath = (): string => runtimeModulePath('mcp-server-runtime');
 
+/** The on-disk `agent-bundle/launch-env` module (#469), aliased into every artifact shell that applies the operator `.env` layer. */
+export const launchEnvRuntimePath = (): string => runtimeModulePath('launch-env');
+
 /**
  * The generated stdio MCP entry body for a factory-exporting server module:
  * the lifecycle installs the console guard before the consumer module
- * evaluates, so `loadEntry` stays a deferred dynamic import.
+ * evaluates, so `loadEntry` stays a deferred dynamic import — which is also
+ * what lets the operator `.env` layer land before any server code reads
+ * `process.env`.
  */
 export const generatedStdioMcpEntrySource = (options: {
   readonly entrySource: string;
   readonly serverName: string;
 }): string => [
+  ...operatorEnvImports({ importsFileUrlToPath: false }),
   `import { runGeneratedStdioMcpEntry } from ${JSON.stringify(mcpEntryRuntimeSpecifier)};`,
   '',
+  operatorEnvStatement,
   'await runGeneratedStdioMcpEntry({',
   `  loadEntry: () => import(${JSON.stringify(options.entrySource)}),`,
   `  serverName: ${JSON.stringify(options.serverName)},`,
@@ -307,9 +315,19 @@ export const generatedCliBinEntrySource = (options: GeneratedCliBinEntryOptions)
       : "import { available, runAgentRequest, unavailable } from '@agent-bundle/runtime';",
     ...(rendered ? ["import { Worker } from 'node:worker_threads';"] : []),
     ...generatedStateImports(options.state, stateFallback),
+    // The artifact-hosted executable is part of an installed pack, so it
+    // reads the pack's operator `.env` layer (#469); the npm package bin
+    // runs from the operator's own shell and reads none.
+    ...(stateFallback === 'artifact'
+      ? operatorEnvImports({ importsFileUrlToPath: options.state?.lifetime === 'workspace-durable' })
+      : []),
     ...routeImports(commandRoutes),
     ...providerImports(providers),
     '',
+    // Before the state owner opens and before any command runs; route modules
+    // are static imports, so a module-level `process.env` read still sees the
+    // host environment only (documented).
+    ...(stateFallback === 'artifact' ? [operatorEnvStatement] : []),
     ...generatedStateOwner(options.state, stateFallback, options),
     'const processLifetime = { hits: 0, instanceId: crypto.randomUUID(), pid: process.pid };',
     ...providerRegistrySource(providers),
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'agent-bundle': patch
 +---
++
 +Give installed packs the operator `.env` layer that only `agent-bundle mcp run` had: every emitted stdio MCP entry, every hook wrapper that runs plugin code, and the artifact CLI `bin/<name>.mjs` read `<plugin root>/.env` then `.env.local` at launch (the plugin root is the expanded `AGENT_BUNDLE_PLUGIN_ROOT`, else the shell's parent directory), filling only variables the host did not set — host environment and manifest `env` win, `.env.local` beats `.env`, values are never logged, a missing file costs nothing, an unreadable one is skipped. `AGENT_BUNDLE_ENV_FILE` names the file(s) to read instead (platform path delimiter; `none` disables the layer), and `mcp run` hands `--env-file` / `--no-env` down through it so a rehearsal and an installed pack read the same files. The loader is the new plain-Node `agent-bundle/launch-env` module (`applyOperatorEnv`, `parseOperatorEnv`), inlined into the shells without Effect. `agent-bundle doctor` reports whether an installed copy carries `.env` / `.env.local` and how many variables each declares (`AB7331`, informational; a warning when the file cannot be read), never a name or a value. The npm package bin reads no pack file. Fixes #469. (#PR)