From 1923e155fcf4864f5e36a3a30782071403795588 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 00:16:52 +0000
Subject: [PATCH 1/4] =?UTF-8?q?feat(build):=20agent-bundle=20owns=20the=20?=
 =?UTF-8?q?package=20build=20=E2=80=94=20bin/lib=20config,=20framework=20s?=
 =?UTF-8?q?tdio=20entry=20shell,=20entry=20conventions,=20tools=20hatch,?=
 =?UTF-8?q?=20mcp=20run=20(RFC=20#50=20Phase=201)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One agent-bundle.config.ts now produces the npm package build alongside host
artifacts: bin/lib (or the src/cli.ts / src/index.ts / src/mcp/<id>.ts
conventions) lower onto the internal Rslib synthesis, factory-exporting MCP
entries are wrapped in the framework stdio lifecycle shell (public as
agent-bundle/mcp-entry), tools.rsbuild/tools.rspack is the single bounded
bundler escape hatch, and `agent-bundle mcp run` launches a built stdio server
from the target manifest. audiobook-curator migrates in-PR as proof: drops
rslib.config.ts, tsconfig.build.json, and the bin shim with byte-equivalent
CLI behavior.
---
 .changeset/framework-owned-build.md           |  11 +
 README.md                                     |  57 ++++
 docs/entry-conventions.md                     | 148 +++++++++
 examples/audiobook-curator/README.md          |  42 +--
 .../bin/audiobook-curator.js                  |   7 -
 examples/audiobook-curator/package.json       |  10 +-
 examples/audiobook-curator/rslib.config.ts    |  33 --
 .../audiobook-curator/src/application.tsx     |   4 +-
 examples/audiobook-curator/src/cli-entry.ts   |   3 -
 examples/audiobook-curator/src/mcp-server.ts  |   8 +-
 .../tests/application.test.tsx                |  12 +-
 .../tests/audible-parity.test.ts              |   2 +-
 examples/audiobook-curator/tests/cli.test.ts  |   4 +-
 .../tests/evidence-parity.test.ts             |   2 +-
 .../tests/integrity-audit-parity.test.ts      |   2 +-
 .../tests/media-mutation-parity.test.ts       |   2 +-
 .../tests/real-ffmpeg.test.ts                 |   2 +-
 .../audiobook-curator/tsconfig.build.json     |  10 -
 examples/audiobook-curator/tsconfig.json      |  13 +
 packages/agent-bundle/README.md               |  15 +-
 packages/agent-bundle/package.json            |   4 +
 packages/agent-bundle/rslib.config.ts         |   1 +
 packages/agent-bundle/src/api.ts              |  81 ++++-
 packages/agent-bundle/src/build/build.ts      |  11 +-
 packages/agent-bundle/src/build/entries.ts    |  55 +++-
 .../agent-bundle/src/build/entry-exports.ts   | 156 +++++++++
 .../agent-bundle/src/build/entry-shell.ts     |  70 ++++
 packages/agent-bundle/src/build/mcp-apps.ts   |  83 +++--
 .../agent-bundle/src/build/package-build.ts   | 204 ++++++++++++
 packages/agent-bundle/src/build/rslib.ts      |  89 +++--
 packages/agent-bundle/src/cli.ts              |  20 +-
 packages/agent-bundle/src/config/normalize.ts | 136 +++++++-
 packages/agent-bundle/src/config/validate.ts  | 151 ++++++++-
 .../agent-bundle/src/core/project-context.ts  |  25 ++
 packages/agent-bundle/src/core/types.ts       |  83 +++++
 .../src/dev/artifacts/artifact-service.ts     |   1 +
 .../agent-bundle/src/dev/project-service.ts   |  10 +
 packages/agent-bundle/src/mcp-entry.ts        | 272 +++++++++++++++
 packages/agent-bundle/src/services/mcp-run.ts | 147 +++++++++
 .../agent-bundle/tests/entry-shell.test.ts    |  87 +++++
 packages/agent-bundle/tests/mcp-entry.test.ts | 309 ++++++++++++++++++
 .../agent-bundle/tests/package-build.test.ts  | 278 ++++++++++++++++
 .../tests/package-conventions.test.ts         | 265 +++++++++++++++
 .../tests/packed-consumer.test.ts             |  96 +++++-
 .../agent-bundle/tests/public-api.test.ts     |  13 +
 pnpm-lock.yaml                                |   3 -
 rstest.integration-tests.ts                   |   1 +
 47 files changed, 2863 insertions(+), 175 deletions(-)
 create mode 100644 .changeset/framework-owned-build.md
 create mode 100644 docs/entry-conventions.md
 delete mode 100755 examples/audiobook-curator/bin/audiobook-curator.js
 delete mode 100644 examples/audiobook-curator/rslib.config.ts
 delete mode 100644 examples/audiobook-curator/src/cli-entry.ts
 delete mode 100644 examples/audiobook-curator/tsconfig.build.json
 create mode 100644 examples/audiobook-curator/tsconfig.json
 create mode 100644 packages/agent-bundle/src/build/entry-exports.ts
 create mode 100644 packages/agent-bundle/src/build/entry-shell.ts
 create mode 100644 packages/agent-bundle/src/build/package-build.ts
 create mode 100644 packages/agent-bundle/src/mcp-entry.ts
 create mode 100644 packages/agent-bundle/src/services/mcp-run.ts
 create mode 100644 packages/agent-bundle/tests/entry-shell.test.ts
 create mode 100644 packages/agent-bundle/tests/mcp-entry.test.ts
 create mode 100644 packages/agent-bundle/tests/package-build.test.ts
 create mode 100644 packages/agent-bundle/tests/package-conventions.test.ts

diff --git a/.changeset/framework-owned-build.md b/.changeset/framework-owned-build.md
new file mode 100644
index 000000000..6ecb07027
--- /dev/null
+++ b/.changeset/framework-owned-build.md
@@ -0,0 +1,11 @@
+---
+"agent-bundle": minor
+---
+
+agent-bundle owns the build (RFC #50 Phase 1): one `agent-bundle.config.ts` now produces the npm package build alongside host artifacts, with framework-owned entry lifecycles and one bundler escape hatch.
+
+- `bin` config (or the `src/cli.ts` convention) emits self-executing `dist/bin/<name>.js` bundles with a shebang, executable bit, and a generated `main(argv)` process envelope; artifact Scripts whose module exports `main` receive the same envelope.
+- `lib` config (or the `src/index.ts` convention) emits a single-entry ESM library build with declarations, resolving `typescript` and tsconfig compiler options from the project.
+- MCP server entries that default-export a server factory are wrapped in the new framework stdio lifecycle shell — console-to-stderr guard with raw stdout restored for protocol frames, SIGINT 130 / SIGTERM 143, stdin-EOF exit 0, bounded shutdown race, heartbeat — also public as `agent-bundle/mcp-entry`. Self-connecting entries keep their behavior byte for byte. The `src/mcp/<server-id>.ts` convention supplies the entry for servers naming no `entry`, `command`, or `url`.
+- `tools.rsbuild` / `tools.rspack` is the single blessed bundler escape hatch, merged last into every synthesized config (scripts, MCP entries, hooks, MCP Apps, package build) and still bounded by the artifact invariant assertions.
+- `agent-bundle mcp run --server <name> --target <target>` runs one built stdio server in the foreground, resolving its content-hashed generated entry from the target manifest.
diff --git a/README.md b/README.md
index e666fe8b0..f4a434624 100644
--- a/README.md
+++ b/README.md
@@ -207,6 +207,63 @@ Skills follow the Agent Skills directory layout and may contain references and b
 
 The compiler rejects unsafe output names, unsupported extensions, nonexistent or escaping source paths, unknown targets, and output collisions before it stages an artifact. It does not call Codex, Claude, or another host CLI, and it does not require API keys.
 
+### One config: agent-bundle owns the build
+
+`agent-bundle.config.ts` is the only build configuration a plugin project
+needs — no consumer `rslib.config.ts`, no hand-written bin shims, no
+hand-rolled stdio lifecycles, no launcher scripts. Alongside the host
+artifacts, `agent-bundle build` also produces the node-consumable npm package
+build when a project declares (or conventionally provides) one:
+
+```ts
+export default defineConfig({
+  plugin: { name: 'review-tools', version: '1.0.0' },
+  // npm-facing CLI binaries: dist/bin/<name>.js, self-executing with a
+  // shebang and executable bit; point package.json "bin" straight at it.
+  bin: { 'review-tools': './src/cli.ts' },
+  // Optional npm library output: dist/index.js (+ dist/*.d.ts). The profile
+  // is deliberately thin — one ESM entry, node target, optional dts.
+  lib: { entry: './src/index.ts', dts: true },
+  // THE bundler escape hatch: merged last into every config agent-bundle
+  // synthesizes (scripts, MCP entries, hooks, MCP Apps, bin/lib), still
+  // bounded by the artifact invariant assertions. Consumers never need a
+  // second bundler config file.
+  tools: {
+    rsbuild: { /* Rsbuild environment-config fragment */ },
+    rspack: (config) => { /* mutate the resolved Rspack config */ },
+  },
+});
+```
+
+A `bin` entry that exports `main(argv)` (or a default function) receives the
+generated process envelope: argv forwarding, `await`, and a numeric return
+adopted as the exit code. Artifact `scripts` whose module exports `main` get
+the same envelope; self-executing scripts keep their direct-bundle behavior.
+Generating `lib` declarations resolves `typescript` from the project (install
+it as a devDependency) and reuses the project `tsconfig.json` compiler
+options scoped to the entry's source directory.
+
+Entry-file conventions fill the config when it is silent, and config always
+wins (`bin: false` / `lib: false` opt out): `src/cli.ts` becomes the bin named
+after the plugin, `src/index.ts` becomes the library output, and
+`src/mcp/<server-id>.ts` becomes the stdio entry of a declared MCP server that
+names no `entry`, `command`, or `url`. See
+[docs/entry-conventions.md](docs/entry-conventions.md) for the full contract.
+
+An MCP server entry that **default-exports a server factory** is wrapped in
+the framework-owned stdio lifecycle shell: console-to-stderr protection with
+raw stdout restored for protocol frames, SIGINT/SIGTERM handling (exit 130 /
+143), stdin-EOF detection (exit 0 so the client can respawn), a bounded
+shutdown race against wedged transports, and heartbeat logging. Self-connecting
+entries keep today's behavior byte for byte. The same lifecycle is available
+directly from `agent-bundle/mcp-entry` for hand-rolled entries.
+
+`agent-bundle mcp run --server <name> --target <target> [--artifact <path>]`
+runs one built stdio server in the foreground, resolving its content-hashed
+generated entry from the target manifest — no more parsing `mcp.json` from a
+launcher script. Server state anchored on the plugin-data token persists under
+`.agent-bundle/mcp-run/<target>/<server>`.
+
 ### Adapter-owned extensions
 
 Ordinary projects need no runtime extension key. `AgentBundleConfig` explicitly
diff --git a/docs/entry-conventions.md b/docs/entry-conventions.md
new file mode 100644
index 000000000..7daa2e597
--- /dev/null
+++ b/docs/entry-conventions.md
@@ -0,0 +1,148 @@
+# Entry conventions and the framework-owned package build
+
+agent-bundle is the build product for agent plugins the way Rslib is for
+libraries: one `agent-bundle.config.ts`, one CLI, framework-owned entry
+lifecycles, and a single blessed escape hatch into the bundler. This document
+is the contract for the package build (`bin` / `lib`), the entry-file
+conventions, the generated entry shells, and the `tools` escape hatch.
+
+## The package build
+
+`agent-bundle build` always emits host artifacts. When the project declares
+`bin`/`lib` (or provides them by convention), the CLI build also produces the
+node-consumable package build under `dist/` — the outputs `package.json`
+`bin` and `exports` point at:
+
+| Config | Output | Notes |
+| --- | --- | --- |
+| `bin: { '<name>': './src/cli.ts' }` | `dist/bin/<name>.js` | Self-executing ESM bundle, `#!/usr/bin/env node` shebang, executable bit. |
+| `lib: { entry: './src/index.ts', dts: true }` | `dist/<stem>.js` + `dist/**/*.d.ts` | Single-entry ESM profile, node target, es2022 syntax. |
+
+- The package build runs only for `agent-bundle build` (CLI, or
+  `build({ packageOutputs: true })` through the API). Programmatic artifact
+  operations — temporary artifacts, the dev workbench, evals — never write
+  `dist/`.
+- Outputs are staged and published atomically, and their provenance
+  (bytes, SHA-256, sorted project-relative source inputs) is reported on the
+  build result exactly like artifact files.
+- `dist` is a mandatory-ignored directory: package outputs never enter
+  project source snapshots or skill/asset discovery.
+- An artifact `--output` that overlaps `dist` is rejected (`AB4706`).
+- The `lib` profile is deliberately thin. A package that needs a multi-format
+  library matrix (UMD, multiple entries, per-format tsconfig) has outgrown the
+  profile and genuinely wants Rslib — that is the one case where a second
+  bundler config remains, by choice.
+
+### Declarations
+
+`lib.dts` defaults to `true`. Declaration generation resolves `typescript`
+from the project (add it as a devDependency) and compiles the lib entry's
+source directory as its own program: compiler options come from the project
+`tsconfig.json` (via `extends`), `rootDir` is pinned to the entry's directory,
+and only that subtree is included — test files never fail or pollute the
+package build. Declarations land flat under `dist/`, one `.d.ts` per source
+module.
+
+## Entry-file conventions
+
+Conventions fill the config when it is silent; config always wins. Discovered
+entries carry `provenance.kind: 'conventional'` in the normalized model.
+
+| Convention | Meaning | Opt out |
+| --- | --- | --- |
+| `src/cli.ts` | Package bin named after `plugin.name` (skipped when the name is not a safe output name). | `bin: false` |
+| `src/index.ts` | Library output with declarations. | `lib: false` |
+| `src/mcp/<server-id>.ts` | Stdio entry for the declared MCP server `<server-id>` that names no `entry`, `command`, or `url`. | Declare `entry` explicitly |
+
+Conventions match `.ts` and `.tsx` files exactly.
+
+## Generated entry shells
+
+The framework provides the entry files consumers used to write by hand
+(react-router's provided-entry trick). Every generated shell imports the
+consumer module by absolute path and is bundled through the same Rslib
+synthesis and invariant assertions as all generated executables.
+
+### The executable envelope (bin + Scripts)
+
+A `bin` entry — or an artifact `Script` — whose module exports `main` (or a
+default function for bin entries) receives the generated process envelope:
+
+```ts
+// src/cli.ts — the whole CLI entry a consumer writes
+export const main = async (argv: readonly string[]): Promise<number> => {
+  // ...
+  return 0;
+};
+```
+
+The envelope awaits `main(process.argv.slice(2))`, adopts a numeric return as
+the process exit code, and lets an escaped rejection surface through Node's
+top-level failure path (stack to stderr, exit code 1). Self-executing modules
+(no `main` export) bundle directly, byte for byte — existing Scripts keep
+their behavior.
+
+### The stdio MCP lifecycle shell
+
+An MCP server entry that **default-exports a server factory** is served under
+the framework lifecycle:
+
+```ts
+// src/mcp/curator.ts — the whole stdio entry a consumer writes
+import { createRscMcpServer } from '@agent-bundle/rsc-runtime/plugin';
+import { application } from '../application.js';
+
+export default () => createRscMcpServer(application, 'curator');
+```
+
+The generated shell provides, in order: console-to-stderr redirection before
+the consumer module evaluates, the factory call, raw `process.stdout.write`
+restored for protocol frames, `StdioServerTransport` construction and
+connect, SIGINT → exit 130, SIGTERM → exit 143, stdin EOF → exit 0 (so the
+client can respawn), transport-close → exit 0, a 5-second bounded shutdown
+race against wedged transports, and heartbeat/activity logging on stderr
+(5-minute interval, 60-second activity throttle, labeled with the server
+name).
+
+Self-connecting entries — modules that construct and connect a transport at
+top level without a default export — keep today's behavior byte for byte.
+
+The same lifecycle is public API for hand-rolled entries:
+
+```ts
+import { redirectConsoleToStderr, runStdioServer } from 'agent-bundle/mcp-entry';
+```
+
+Export detection is a static scan of the entry source (comment-, string-, and
+template-safe). The generated shells re-verify the export shape at runtime
+with a clear error.
+
+## `tools` — THE escape hatch
+
+`tools.rsbuild` (an Rsbuild environment-config fragment) and `tools.rspack`
+(an Rspack config object, mutator function, or array — Rslib semantics) merge
+**last** into every bundler config agent-bundle synthesizes: artifact scripts,
+MCP entries, hook wrappers, MCP App views, and the package build. This mirrors
+Rslib's user-config-highest priority and Rspress's `builderConfig` position,
+and it is the reason a consumer never needs a second bundler config file.
+
+The hatch is bounded: the framework invariant hook runs after the consumer's
+`tools.rspack`, and the resolved-config assertions still run after the merge.
+A hatch value that breaks an artifact contract (async chunks, output roots,
+self-containment) fails the build with a hard diagnostic instead of silently
+overriding the contract. The hatch customizes *how code compiles*, never
+*what the artifact promises*.
+
+## `agent-bundle mcp run`
+
+```sh
+agent-bundle mcp run --server <name> --target <target> [--artifact <path>]
+```
+
+Runs one built stdio MCP server in the foreground with inherited stdio: the
+content-hashed generated entry is resolved from the target's MCP manifest
+(the job previously solved with bash launchers parsing `mcp.json`), path
+tokens are resolved through the target adapter, and the child's exit code is
+forwarded (SIGINT/SIGTERM forward to the child). Without `--artifact`, a
+temporary artifact is built first. State anchored on the plugin-data token
+persists under `.agent-bundle/mcp-run/<target>/<server>` in the project root.
diff --git a/examples/audiobook-curator/README.md b/examples/audiobook-curator/README.md
index 562bf9321..010737c73 100644
--- a/examples/audiobook-curator/README.md
+++ b/examples/audiobook-curator/README.md
@@ -24,19 +24,22 @@ pnpm --filter @agent-bundle-example/audiobook-curator build
 Build and globally link the workspace package without a tarball:
 
 ```sh
-pnpm --filter @agent-bundle-example/audiobook-curator build:cli
+pnpm --filter @agent-bundle-example/audiobook-curator build
 cd examples/audiobook-curator
-ln -s "$(pwd)/bin/audiobook-curator.js" ~/.local/bin/audiobook-curator
+ln -s "$(pwd)/dist/bin/audiobook-curator.js" ~/.local/bin/audiobook-curator
 audiobook-curator --help
 ```
 
 Choose any writable directory already on `PATH` in place of `~/.local/bin`.
 This is a direct workspace link; it does not pack or install a tarball.
 
-`build:bundle` writes complete Claude and Codex outputs beneath `artifact/`,
-including each host's plugin metadata, Skill, bundled CLI script, and bundled MCP
-server. The example uses only public `agent-bundle` and
-`@agent-bundle/rsc-runtime` exports with `workspace:*` dependencies.
+One `agent-bundle build` produces everything: complete Claude and Codex
+outputs beneath `artifact/` (each host's plugin metadata, Skill, bundled CLI
+script, and lifecycle-wrapped MCP server) plus the npm package build beneath
+`dist/` (`dist/bin/audiobook-curator.js` for `package.json` `bin`,
+`dist/index.js` and declarations for `exports`). The example uses only public
+`agent-bundle` and `@agent-bundle/rsc-runtime` exports with `workspace:*`
+dependencies.
 
 ## Source layout
 
@@ -52,9 +55,10 @@ server. The example uses only public `agent-bundle` and
   `evidence.ts`, `conversion.ts`, `media-mutation.ts`, `integrity-audit.ts`,
   `curator-core.ts`) over the shared `foundation.ts` and `media-process.ts`
   primitives; `result.tsx` renders every receipt for MCP.
-- `src/cli.ts`, `src/cli-entry.ts`, `src/mcp-server.ts`, and
-  `bin/audiobook-curator.js` are the entry shims for the CLI (test-injectable
-  runner, bundled `<Script>` entry, npm bin) and the stdio MCP server.
+- `src/cli.ts` exports `main`; the framework's generated process envelope
+  turns it into both the bundled `<Script>` artifact entry and the npm bin.
+  `src/mcp-server.ts` default-exports a server factory served under the
+  framework's stdio lifecycle shell. No hand-written entry shims remain.
 
 ## Complete workflow
 
@@ -98,13 +102,13 @@ The completion contract and real-volume checklist are in
 
 ## Maintainer notes
 
-This example carries two bundler configs: `agent-bundle.config.ts` (the
-application, consumed by `agent-bundle build` for the `artifact/` host
-outputs) and `rslib.config.ts` (a hand-written second build producing
-`dist/` for the npm `bin`/`exports`, plus its `tsconfig.build.json`). The
-duplication is a known framework gap — `agent-bundle build` does not yet emit
-a node-consumable package build, so the same CLI is bundled twice from two
-configs. When the framework owns the package build, delete `rslib.config.ts`,
-`tsconfig.build.json`, and the `build:cli` script; `bin/audiobook-curator.js`
-should then point at the framework's output. See the note at the top of
-`rslib.config.ts`.
+This example is the reference consumer of the framework-owned package build
+("one config, agent-bundle owns the build"): `agent-bundle.config.ts` is a
+pure pass-through of the RSC application's config, and the `src/cli.ts` /
+`src/index.ts` conventions provide the npm bin and library outputs under
+`dist/`. The former second bundler config (`rslib.config.ts`), its
+`tsconfig.build.json`, the hand-written `bin/audiobook-curator.js` shim, the
+self-executing `src/cli-entry.ts`, and the dual `build:cli`/`build:bundle`
+script chain were all deleted when the framework took ownership. See
+[`docs/entry-conventions.md`](../../docs/entry-conventions.md) for the
+contract.
diff --git a/examples/audiobook-curator/bin/audiobook-curator.js b/examples/audiobook-curator/bin/audiobook-curator.js
deleted file mode 100755
index a0eee21fe..000000000
--- a/examples/audiobook-curator/bin/audiobook-curator.js
+++ /dev/null
@@ -1,7 +0,0 @@
-#!/usr/bin/env node
-
-import process from 'node:process';
-
-import { main } from '../dist/cli.js';
-
-await main(process.argv.slice(2));
diff --git a/examples/audiobook-curator/package.json b/examples/audiobook-curator/package.json
index b9c00e636..e8643ca2a 100644
--- a/examples/audiobook-curator/package.json
+++ b/examples/audiobook-curator/package.json
@@ -8,12 +8,11 @@
     "node": ">=22.19.0"
   },
   "files": [
-    "bin",
     "dist",
     "README.md"
   ],
   "bin": {
-    "audiobook-curator": "./bin/audiobook-curator.js"
+    "audiobook-curator": "./dist/bin/audiobook-curator.js"
   },
   "exports": {
     ".": {
@@ -22,13 +21,11 @@
     }
   },
   "scripts": {
-    "build": "pnpm build:cli && pnpm build:bundle",
-    "build:bundle": "agent-bundle build --json --output artifact",
-    "build:cli": "rslib build",
+    "build": "agent-bundle build --json --output artifact",
     "check": "pnpm test && pnpm typecheck && pnpm build",
     "dev": "agent-bundle dev",
     "test": "rstest tests",
-    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "validate": "agent-bundle validate --json"
   },
   "dependencies": {
@@ -38,7 +35,6 @@
     "zod": "4.4.3"
   },
   "devDependencies": {
-    "@rslib/core": "0.23.2",
     "@rstest/core": "0.11.10",
     "@types/react": "19.2.18",
     "agent-bundle": "workspace:*"
diff --git a/examples/audiobook-curator/rslib.config.ts b/examples/audiobook-curator/rslib.config.ts
deleted file mode 100644
index 1e0987baa..000000000
--- a/examples/audiobook-curator/rslib.config.ts
+++ /dev/null
@@ -1,33 +0,0 @@
-// FRAMEWORK GAP: this second bundler config exists only because `agent-bundle
-// build` emits host artifacts (artifact/{claude,codex}) but no node-consumable
-// dist/ for the package's own `bin` and `exports`. The CLI is therefore built
-// twice — once here into dist/cli.js for bin/audiobook-curator.js, and once by
-// `agent-bundle build` into artifact/*/scripts/audiobook-curator.mjs — from
-// two configs driving the same bundler family. Once agent-bundle owns the
-// package build ("one config, agent-bundle owns the build"), this file and
-// tsconfig.build.json should be deleted. See the maintainer notes in README.md.
-import { defineConfig } from '@rslib/core';
-
-export default defineConfig({
-  lib: [
-    {
-      bundle: true,
-      dts: true,
-      format: 'esm',
-      syntax: 'es2022',
-    },
-  ],
-  output: {
-    cleanDistPath: true,
-    filenameHash: false,
-    target: 'node',
-  },
-  root: import.meta.dirname,
-  source: {
-    entry: {
-      cli: './src/cli.ts',
-      index: './src/index.ts',
-    },
-    tsconfigPath: './tsconfig.build.json',
-  },
-});
diff --git a/examples/audiobook-curator/src/application.tsx b/examples/audiobook-curator/src/application.tsx
index 6c7a1a157..6278ae6ec 100644
--- a/examples/audiobook-curator/src/application.tsx
+++ b/examples/audiobook-curator/src/application.tsx
@@ -81,7 +81,9 @@ export const createAudiobookCuratorApplication = (
       version="1.0.0"
     >
       <Skill source="./skills/curate-audiobooks" />
-      <Script entry="./src/cli-entry.ts" name="audiobook-curator" />
+      {/* The framework process envelope invokes the exported `main`; no
+          hand-written self-executing entry file is needed. */}
+      <Script entry="./src/cli.ts" name="audiobook-curator" />
       <McpServer entry="./src/mcp-server.ts" name="curator" />
       {definitions.map((definition) => <Operation definition={definition} key={definition.id} />)}
     </AgentBundle>,
diff --git a/examples/audiobook-curator/src/cli-entry.ts b/examples/audiobook-curator/src/cli-entry.ts
deleted file mode 100644
index 61de0e293..000000000
--- a/examples/audiobook-curator/src/cli-entry.ts
+++ /dev/null
@@ -1,3 +0,0 @@
-import { main } from './cli.js';
-
-await main(process.argv.slice(2));
diff --git a/examples/audiobook-curator/src/mcp-server.ts b/examples/audiobook-curator/src/mcp-server.ts
index d814cc600..38e2e3b72 100644
--- a/examples/audiobook-curator/src/mcp-server.ts
+++ b/examples/audiobook-curator/src/mcp-server.ts
@@ -1,8 +1,12 @@
 import { createRscMcpServer } from '@agent-bundle/rsc-runtime/plugin';
-import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
 
 import { audiobookCuratorApplication } from './application.js';
 
 export const createAudiobookCuratorServer = () => createRscMcpServer(audiobookCuratorApplication, 'curator');
 
-await createAudiobookCuratorServer().connect(new StdioServerTransport());
+/**
+ * Default-exported server factory: `agent-bundle build` detects it and wraps
+ * this entry in the framework stdio lifecycle shell (console-to-stderr guard,
+ * SIGINT/SIGTERM handling, stdin-EOF exit, bounded shutdown, heartbeat).
+ */
+export default createAudiobookCuratorServer;
diff --git a/examples/audiobook-curator/tests/application.test.tsx b/examples/audiobook-curator/tests/application.test.tsx
index 623108256..2d76ce7d7 100644
--- a/examples/audiobook-curator/tests/application.test.tsx
+++ b/examples/audiobook-curator/tests/application.test.tsx
@@ -19,7 +19,17 @@ const operations = (): AudiobookCuratorOperations => ({
     generatedAt: '2026-08-26T00:00:00.000Z',
     mutation: false,
     operation: 'audit',
-    probe: { codec: 'aac', durationSeconds: 12, format: 'mov', tags: {} },
+    probe: {
+      bytes: 12,
+      chapters: 0,
+      codec: 'aac',
+      durationSeconds: 12,
+      extension: '.m4b',
+      path: input.file,
+      relativePath: 'book.m4b',
+      sampleRate: 44_100,
+      tags: {},
+    },
     sha256: 'a'.repeat(64),
     sourceChapterMapping: { issues: [], status: 'not-requested' },
     status: 'verified',
diff --git a/examples/audiobook-curator/tests/audible-parity.test.ts b/examples/audiobook-curator/tests/audible-parity.test.ts
index 4c5fe2299..cf5a4fff0 100644
--- a/examples/audiobook-curator/tests/audible-parity.test.ts
+++ b/examples/audiobook-curator/tests/audible-parity.test.ts
@@ -13,7 +13,7 @@ import {
 } from '../src/index.js';
 
 const roots: string[] = [];
-afterEach(async () => Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))));
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))); });
 
 const product = {
   asin: 'B012345678',
diff --git a/examples/audiobook-curator/tests/cli.test.ts b/examples/audiobook-curator/tests/cli.test.ts
index 2db09e8c5..c21c2ca84 100644
--- a/examples/audiobook-curator/tests/cli.test.ts
+++ b/examples/audiobook-curator/tests/cli.test.ts
@@ -24,9 +24,9 @@ describe('audiobook-curator CLI', () => {
     let applied = false;
     const fixture = operations();
     await runCli(['prepare', '/source/book.mp3', '--output', '/curated', '--apply'], {
-      operations: { ...fixture, prepare: async (input) => {
+      operations: { ...fixture, prepare: async (input, options) => {
         applied = input.apply === true;
-        return fixture.prepare(input);
+        return fixture.prepare(input, options);
       } },
       write: () => undefined,
     });
diff --git a/examples/audiobook-curator/tests/evidence-parity.test.ts b/examples/audiobook-curator/tests/evidence-parity.test.ts
index 9709a58db..87d67b237 100644
--- a/examples/audiobook-curator/tests/evidence-parity.test.ts
+++ b/examples/audiobook-curator/tests/evidence-parity.test.ts
@@ -16,7 +16,7 @@ import {
 } from '../src/index.js';
 
 const roots: string[] = [];
-afterEach(async () => Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))));
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))); });
 
 describe('optional identity evidence parity', () => {
   it('keeps the reviewed distributed Whisper sampling sequence', () => {
diff --git a/examples/audiobook-curator/tests/integrity-audit-parity.test.ts b/examples/audiobook-curator/tests/integrity-audit-parity.test.ts
index 18b189497..2ebf0ca4b 100644
--- a/examples/audiobook-curator/tests/integrity-audit-parity.test.ts
+++ b/examples/audiobook-curator/tests/integrity-audit-parity.test.ts
@@ -7,7 +7,7 @@ import { afterEach, describe, expect, it } from '@rstest/core';
 import { auditAudiobookIntegrity, type MediaProcess } from '../src/index.js';
 
 const roots: string[] = [];
-afterEach(async () => Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))));
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))); });
 
 describe('complete audiobook integrity audit', () => {
   it('verifies chapter mapping, file/audio hashes, probe facts, and optional full decode', async () => {
diff --git a/examples/audiobook-curator/tests/media-mutation-parity.test.ts b/examples/audiobook-curator/tests/media-mutation-parity.test.ts
index ae118ba9c..2ee749a28 100644
--- a/examples/audiobook-curator/tests/media-mutation-parity.test.ts
+++ b/examples/audiobook-curator/tests/media-mutation-parity.test.ts
@@ -13,7 +13,7 @@ import {
 } from '../src/index.js';
 
 const roots: string[] = [];
-afterEach(async () => Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))));
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))); });
 
 const fixture = async () => {
   const root = await mkdtemp(join(tmpdir(), 'curator-mutation-'));
diff --git a/examples/audiobook-curator/tests/real-ffmpeg.test.ts b/examples/audiobook-curator/tests/real-ffmpeg.test.ts
index f784a517e..9177971f2 100644
--- a/examples/audiobook-curator/tests/real-ffmpeg.test.ts
+++ b/examples/audiobook-curator/tests/real-ffmpeg.test.ts
@@ -17,7 +17,7 @@ import {
 } from '../src/index.js';
 
 const roots: string[] = [];
-afterEach(async () => Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))));
+afterEach(async () => { await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true }))); });
 
 const sha256 = async (path: string): Promise<string> => createHash('sha256').update(await readFile(path)).digest('hex');
 
diff --git a/examples/audiobook-curator/tsconfig.build.json b/examples/audiobook-curator/tsconfig.build.json
deleted file mode 100644
index 43883341f..000000000
--- a/examples/audiobook-curator/tsconfig.build.json
+++ /dev/null
@@ -1,10 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "./src"
-  },
-  "include": [
-    "src/**/*.ts",
-    "src/**/*.tsx"
-  ]
-}
diff --git a/examples/audiobook-curator/tsconfig.json b/examples/audiobook-curator/tsconfig.json
new file mode 100644
index 000000000..67cbb7fcf
--- /dev/null
+++ b/examples/audiobook-curator/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "jsx": "react-jsx"
+  },
+  "include": [
+    "agent-bundle.config.ts",
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "tests/**/*.ts",
+    "tests/**/*.tsx"
+  ]
+}
diff --git a/packages/agent-bundle/README.md b/packages/agent-bundle/README.md
index fe4465b4e..a5371b0f1 100644
--- a/packages/agent-bundle/README.md
+++ b/packages/agent-bundle/README.md
@@ -43,14 +43,27 @@ plus explicit host-native selectors such as `claude:WebSearch` or `codex:view_im
 contribute only to that host's native matcher. A hook that selects tools must leave every selected
 target with at least one applicable selector, otherwise the build fails.
 
+agent-bundle also owns the npm-facing package build: `bin` entries become self-executing
+`dist/bin/<name>.js` bundles (shebang, executable bit, generated `main(argv)` envelope) and the
+optional `lib` entry becomes `dist/<stem>.js` with declarations (resolving `typescript` from the
+project). The `src/cli.ts`, `src/index.ts`, and `src/mcp/<server-id>.ts` conventions fill these in
+when the config is silent; config always wins and `bin: false` / `lib: false` opt out. MCP server
+entries that default-export a server factory are wrapped in the framework stdio lifecycle shell
+(console-to-stderr guard with raw stdout restored for protocol frames, SIGINT 130 / SIGTERM 143,
+stdin-EOF exit 0, bounded shutdown, heartbeat), also available directly from
+`agent-bundle/mcp-entry`. `tools.rsbuild` / `tools.rspack` is the single bundler escape hatch,
+merged last into every synthesized config and bounded by the artifact invariant assertions. See
+the repository's `docs/entry-conventions.md` for the full contract.
+
 ## Commands
 
 | Command | Purpose |
 | --- | --- |
-| `agent-bundle build` | Build a validated artifact from source. |
+| `agent-bundle build` | Build a validated artifact from source, plus the declared `dist/` package build. |
 | `agent-bundle validate` | Validate project source, or an artifact with `--artifact`. |
 | `agent-bundle inspect` | Inspect normalized targets and adapter plans from source. |
 | `agent-bundle mcp list` / `mcp invoke` | List or invoke one MCP tool from an artifact. |
+| `agent-bundle mcp run` | Run one built stdio MCP server in the foreground, resolving its hashed entry. |
 | `agent-bundle hooks list` / `hooks simulate` | List generated hooks, or run one emitted wrapper. |
 | `agent-bundle eval` | Run deterministic or native Claude/Codex eval suites and record a run. |
 | `agent-bundle dev` | Serve the packaged developer workbench on loopback. |
diff --git a/packages/agent-bundle/package.json b/packages/agent-bundle/package.json
index 945aa9588..38fb15d48 100644
--- a/packages/agent-bundle/package.json
+++ b/packages/agent-bundle/package.json
@@ -56,6 +56,10 @@
     "./mcp-apps": {
       "types": "./dist/mcp-apps.d.ts",
       "import": "./dist/mcp-apps.js"
+    },
+    "./mcp-entry": {
+      "types": "./dist/mcp-entry.d.ts",
+      "import": "./dist/mcp-entry.js"
     }
   },
   "dependencies": {
diff --git a/packages/agent-bundle/rslib.config.ts b/packages/agent-bundle/rslib.config.ts
index aa74a5e05..72c1ad14a 100644
--- a/packages/agent-bundle/rslib.config.ts
+++ b/packages/agent-bundle/rslib.config.ts
@@ -34,6 +34,7 @@ export default defineConfig({
       eval: './src/eval/index.ts',
       index: './src/index.ts',
       'mcp-apps': './src/mcp-apps.ts',
+      'mcp-entry': './src/mcp-entry.ts',
     },
   },
 });
diff --git a/packages/agent-bundle/src/api.ts b/packages/agent-bundle/src/api.ts
index 60a73649a..c0000402d 100644
--- a/packages/agent-bundle/src/api.ts
+++ b/packages/agent-bundle/src/api.ts
@@ -4,7 +4,11 @@ import { join, resolve } from 'node:path';
 import { createDefaultRegistry, TargetRegistry } from './adapters/registry.ts';
 import type { TargetArtifactEntry, TargetHookEntry } from './adapters/types.ts';
 import { build as buildArtifact, type BuildResult } from './build/build.ts';
+import { buildPackageOutputs, type PackageBuildResult } from './build/package-build.ts';
+import { isInsideOrEqual } from './core/paths.ts';
+import { runMcpForeground } from './services/mcp-run.ts';
 export type { BuildResult } from './build/build.ts';
+export type { PackageBuildResult, PackageOutputFile } from './build/package-build.ts';
 export type { ArtifactOutputKind, ArtifactOutputProvenance } from './build/provenance.ts';
 export type { ProjectContext, ProjectSourceInput, ProjectSourceSnapshotInput } from './core/project-context.ts';
 export type {
@@ -219,12 +223,20 @@ export type InspectResult = ReadyInspectResult | InvalidInspectResult;
 
 export interface BuildOptions extends ProjectOptions {
   readonly output?: string;
+  /**
+   * Also produce the framework-owned npm package build (`dist/` bin + lib
+   * outputs) when the project declares or conventionally provides one. The
+   * CLI `build` command always requests this; programmatic artifact
+   * operations (temporary artifacts, dev, evals) never do.
+   */
+  readonly packageOutputs?: boolean;
 }
 
 export interface BuildProjectResult {
   readonly build: BuildResult;
   readonly diagnostics: readonly Diagnostic[];
   readonly model: NormalizedPlugin;
+  readonly packageBuild?: PackageBuildResult;
   readonly projectContext: ProjectContext;
 }
 
@@ -254,6 +266,13 @@ export interface CompareEvalsOptions extends ProjectOptions {
   readonly candidateRunId: string;
 }
 
+export interface RunMcpOptions extends ArtifactOperationOptions {
+  readonly server: string;
+  /** Injectable only to make foreground process behavior deterministic in tests. */
+  readonly spawnProcess?: Parameters<typeof runMcpForeground>[0]['spawnProcess'];
+  readonly target: string;
+}
+
 export interface ListHooksOptions extends ArtifactOperationOptions {
   readonly target?: string;
 }
@@ -431,6 +450,20 @@ export const inspect = async (options: InspectOptions): Promise<InspectResult> =
   });
 };
 
+const assertPackageOutputSources = (
+  packageBuild: PackageBuildResult,
+  projectContext: ProjectContext,
+): void => {
+  const declaredSources = new Set(projectContext.sourceInputs.map((input) => input.path));
+  for (const file of packageBuild.files) {
+    for (const sourceInput of file.sourceInputs) {
+      if (!declaredSources.has(sourceInput)) {
+        throw new Error(`Package output source ${JSON.stringify(sourceInput)} is not declared in the project context.`);
+      }
+    }
+  }
+};
+
 export const build = async (options: BuildOptions): Promise<BuildProjectResult> => {
   const root = resolve(options.root);
   const output = resolveOutput(root, options.output);
@@ -438,6 +471,16 @@ export const build = async (options: BuildOptions): Promise<BuildProjectResult>
   const model = requirePreparedModel(prepared);
   const projectContext = prepared.projectContext;
   if (projectContext === undefined) throw new DiagnosticError(prepared.diagnostics);
+  const packageOutputRoot = model.packageBuild === undefined || options.packageOutputs !== true
+    ? undefined
+    : resolve(prepared.root, model.packageBuild.outputDir);
+  if (packageOutputRoot !== undefined && (isInsideOrEqual(packageOutputRoot, output) || isInsideOrEqual(output, packageOutputRoot))) {
+    throw new DiagnosticError([{
+      code: 'AB4706',
+      message: `Artifact output ${JSON.stringify(output)} overlaps the package build output ${JSON.stringify(packageOutputRoot)}; pass a different --output.`,
+      severity: 'error',
+    }]);
+  }
   log(options.logger, 'artifact.build', { output, root: prepared.root });
   const result = await buildArtifact({
     model,
@@ -445,8 +488,24 @@ export const build = async (options: BuildOptions): Promise<BuildProjectResult>
     projectContext,
     projectRoot: prepared.root,
     registry: prepared.registry,
+    ...(prepared.tools === undefined ? {} : { tools: prepared.tools }),
+  });
+  let packageBuild: PackageBuildResult | undefined;
+  if (packageOutputRoot !== undefined) {
+    packageBuild = await buildPackageOutputs({
+      model,
+      projectRoot: prepared.root,
+      ...(prepared.tools === undefined ? {} : { tools: prepared.tools }),
+    });
+    if (packageBuild !== undefined) assertPackageOutputSources(packageBuild, projectContext);
+  }
+  return Object.freeze({
+    build: result,
+    diagnostics: prepared.diagnostics,
+    model,
+    ...(packageBuild === undefined ? {} : { packageBuild }),
+    projectContext,
   });
-  return Object.freeze({ build: result, diagnostics: prepared.diagnostics, model, projectContext });
 };
 
 /** Every eval refusal reaches a caller as one actionable diagnostic, never a raw service error. */
@@ -586,6 +645,26 @@ export const invokeMcp = async (options: InvokeMcpOptions): Promise<McpInvokeRes
   } satisfies McpInvokeOptions));
 };
 
+/**
+ * Runs one built stdio MCP server in the foreground with inherited stdio,
+ * resolving its content-hashed generated entry from the target manifest.
+ * Server state anchored on the plugin-data token persists under
+ * `.agent-bundle/mcp-run/<target>/<server>` in the project root.
+ */
+export const runMcp = async (options: RunMcpOptions): Promise<number> => {
+  const registry = registryFor(options);
+  const workspaceRoot = resolve(options.root);
+  return temporaryArtifact({ ...options, registry }, async (artifact) => runMcpForeground({
+    artifact,
+    pluginDataRoot: join(workspaceRoot, '.agent-bundle', 'mcp-run', options.target, options.server),
+    registry,
+    server: options.server,
+    ...(options.spawnProcess === undefined ? {} : { spawnProcess: options.spawnProcess }),
+    target: options.target,
+    workspaceRoot,
+  }));
+};
+
 export const listHooks = async (options: ListHooksOptions) => {
   const registry = registryFor(options);
   if (options.target !== undefined && !registry.has(options.target)) {
diff --git a/packages/agent-bundle/src/build/build.ts b/packages/agent-bundle/src/build/build.ts
index b9d7f29dd..0341472e5 100644
--- a/packages/agent-bundle/src/build/build.ts
+++ b/packages/agent-bundle/src/build/build.ts
@@ -7,7 +7,7 @@ import type { TargetRegistry } from '../adapters/registry.ts';
 import type { TargetArtifactEntry, TargetHookEntry } from '../adapters/types.ts';
 import { deduplicateDiagnostics, DiagnosticBag, DiagnosticError, type Diagnostic } from '../core/diagnostics.ts';
 import type { ProjectContext } from '../core/project-context.ts';
-import type { NormalizedPlugin } from '../core/types.ts';
+import type { AgentBundleToolsConfig, NormalizedPlugin } from '../core/types.ts';
 import { assertInside } from '../core/paths.ts';
 import { agentSkillsSchemaRevision } from '../schemas/agent-skills/contract.ts';
 import {
@@ -57,6 +57,8 @@ export interface BuildOptions {
   readonly projectContext: ProjectContext;
   readonly projectRoot: string;
   readonly registry: TargetRegistry;
+  /** The consumer bundler escape hatch, applied to every synthesized config. */
+  readonly tools?: AgentBundleToolsConfig;
 }
 
 interface PlannedTarget {
@@ -271,26 +273,29 @@ export const build = async (options: BuildOptions): Promise<BuildResult> => {
     const compiledHooks: CompiledHookEntry[] = [];
     const compiledMcpApps: CompiledMcpApp[] = [];
     const compiledMcpEntries: CompiledMcpEntry[] = [];
+    const tools = options.tools === undefined ? {} : { tools: options.tools };
     for (const target of stagedTargets) {
       const targetMcpApps = await compileMcpApps(options.model.mcpApps ?? [], {
         cwd: options.projectRoot,
         outDir: target.root,
         target: target.name,
+        ...tools,
       });
       compiledMcpApps.push(...targetMcpApps);
       await emitPlanEntries({ entries: target.entries, root: target.root });
       compiledEntries.push(
         ...(await compileEntries(
           options.model.scripts.filter((script) => script.targets.includes(target.name)),
-          { cwd: options.projectRoot, outDir: target.root },
+          { cwd: options.projectRoot, outDir: target.root, ...tools },
         )),
       );
-      compiledHooks.push(...(await compileHooks(target.hookEntries, { cwd: options.projectRoot, outDir: target.root })));
+      compiledHooks.push(...(await compileHooks(target.hookEntries, { cwd: options.projectRoot, outDir: target.root, ...tools })));
       compiledMcpEntries.push(...(await compileMcpEntries(options.model.mcpServers, {
         apps: targetMcpApps,
         cwd: options.projectRoot,
         outDir: target.root,
         target: target.name,
+        ...tools,
       })));
     }
     const publishedCompiledEntries = Object.freeze(compiledEntries.map((entry) =>
diff --git a/packages/agent-bundle/src/build/entries.ts b/packages/agent-bundle/src/build/entries.ts
index 193965029..920fa3be5 100644
--- a/packages/agent-bundle/src/build/entries.ts
+++ b/packages/agent-bundle/src/build/entries.ts
@@ -2,10 +2,17 @@ import { readFile, stat } from 'node:fs/promises';
 import { extname, relative, resolve } from 'node:path';
 
 import type { TargetHookEntry } from '../adapters/types.ts';
-import type { NormalizedMcpServer, NormalizedScript } from '../core/types.ts';
+import type { AgentBundleToolsConfig, NormalizedMcpServer, NormalizedScript } from '../core/types.ts';
 import { mcpEntryAliasPattern } from '../config/normalize.ts';
 import { stableJson } from '../core/digest.ts';
 import { emitPlanEntries, resolveArtifactDestination } from './emit.ts';
+import { scanEntryExports } from './entry-exports.ts';
+import {
+  generatedExecutableEntrySource,
+  generatedStdioMcpEntrySource,
+  mcpEntryRuntimePath,
+  mcpEntryRuntimeSpecifier,
+} from './entry-shell.ts';
 import type { CompiledMcpApp } from './mcp-apps.ts';
 import type { ArtifactOutputKind } from './provenance.ts';
 import { buildWithRslib } from './rslib.ts';
@@ -67,19 +74,29 @@ export const planCompiledEntries = (
 
 export const compileEntries = async (
   entries: readonly NormalizedScript[],
-  options: { readonly cwd: string; readonly outDir: string },
+  options: { readonly cwd: string; readonly outDir: string; readonly tools?: AgentBundleToolsConfig },
 ): Promise<readonly CompiledEntry[]> => {
   const compiled = planCompiledEntries(entries, options);
   const bundled = compiled.filter((entry) => entry.mode === 'bundle');
   const evidence = await buildWithRslib({
     cwd: options.cwd,
-    entries: bundled.map(({ name, source, sourceInputs }) => ({
-      name,
-      outputRelativePath: `scripts/${name}.mjs`,
-      source,
-      sourceInputs,
+    entries: await Promise.all(bundled.map(async ({ name, source, sourceInputs }) => {
+      // A Script whose module exports `main` receives the framework process
+      // envelope (argv, numeric exit codes); self-executing modules keep
+      // today's direct-bundle behavior byte for byte.
+      const exports = await scanEntryExports(source);
+      return {
+        name,
+        outputRelativePath: `scripts/${name}.mjs`,
+        source,
+        sourceInputs,
+        ...(exports.hasMainExport
+          ? { virtualSource: generatedExecutableEntrySource({ entrySource: source, exportName: 'main' }) }
+          : {}),
+      };
     })),
     outputRoot: options.outDir,
+    ...(options.tools === undefined ? {} : { tools: options.tools }),
   });
   await emitPlanEntries({
     entries: await Promise.all(compiled
@@ -147,6 +164,7 @@ export const compileMcpEntries = async (
     readonly cwd: string;
     readonly outDir: string;
     readonly target: string;
+    readonly tools?: AgentBundleToolsConfig;
   },
 ): Promise<readonly CompiledMcpEntry[]> => {
   const compiled = planCompiledMcpEntries(servers, options);
@@ -167,9 +185,27 @@ export const compileMcpEntries = async (
       '',
     ].join('\n');
   }));
+  // Factory-exporting entries (default export) are wrapped in the framework
+  // stdio lifecycle shell; self-connecting entries keep today's behavior byte
+  // for byte. The shell is aliased onto the local runtime module so emitted
+  // bundles stay self-contained (no residual `agent-bundle` import).
+  const entryShells = await Promise.all(compiled.map(async (entry) =>
+    (await scanEntryExports(entry.source)).hasDefaultExport
+      ? generatedStdioMcpEntrySource({
+        entrySource: entry.source,
+        serverName: entry.id.startsWith('mcp:') ? entry.id.slice('mcp:'.length) : entry.name,
+      })
+      : undefined));
+  const runtimeShell = entryShells.some((shell) => shell !== undefined) ? mcpEntryRuntimePath() : undefined;
   const evidence = await buildWithRslib({
     cwd: options.cwd,
     entries: compiled.map(({ id, name, source, sourceInputs }, index) => ({
+      ...(entryShells[index] === undefined || runtimeShell === undefined
+        ? {}
+        : {
+          aliases: { [mcpEntryRuntimeSpecifier]: runtimeShell },
+          virtualSource: entryShells[index],
+        }),
       name,
       outputRelativePath: `mcp/${name}.mjs`,
       source,
@@ -184,7 +220,9 @@ export const compileMcpEntries = async (
         source: virtualSources[index]!,
       }],
     })),
+    ...(runtimeShell === undefined ? {} : { ignoredSourcePaths: [runtimeShell] }),
     outputRoot: options.outDir,
+    ...(options.tools === undefined ? {} : { tools: options.tools }),
   });
   const evidenceByPath = new Map(evidence.map((entry) => [entry.path, entry.sourceInputs]));
   return Object.freeze(compiled.map((entry) => Object.freeze({
@@ -211,7 +249,7 @@ export const planCompiledHooks = (
 
 export const compileHooks = async (
   entries: readonly TargetHookEntry[],
-  options: { readonly cwd: string; readonly outDir: string },
+  options: { readonly cwd: string; readonly outDir: string; readonly tools?: AgentBundleToolsConfig },
 ): Promise<readonly CompiledHookEntry[]> => {
   const compiled = planCompiledHooks(entries, options);
   const evidence = await buildWithRslib({
@@ -227,6 +265,7 @@ export const compileHooks = async (
       virtualSource: entries[index]!.virtualSource,
     })),
     outputRoot: options.outDir,
+    ...(options.tools === undefined ? {} : { tools: options.tools }),
   });
   const evidenceByPath = new Map(evidence.map((entry) => [entry.path, entry.sourceInputs]));
   return Object.freeze(compiled.map((entry, index) => Object.freeze({
diff --git a/packages/agent-bundle/src/build/entry-exports.ts b/packages/agent-bundle/src/build/entry-exports.ts
new file mode 100644
index 000000000..a7172d5aa
--- /dev/null
+++ b/packages/agent-bundle/src/build/entry-exports.ts
@@ -0,0 +1,156 @@
+import { readFile } from 'node:fs/promises';
+
+/**
+ * Static entry-export detection for TypeScript/JavaScript entry modules. The
+ * generated entry conventions only need two facts — "does this module export
+ * `main`" and "does this module have a default export" — and the sources are
+ * TypeScript, which the JS-only lexers in this package cannot parse. A
+ * comment- and string-stripped scan decides both facts deterministically at
+ * build time; the generated wrappers re-verify the export shape at runtime
+ * with a clear error.
+ */
+export interface EntryExportScan {
+  readonly hasDefaultExport: boolean;
+  readonly hasMainExport: boolean;
+}
+
+/**
+ * Removes comments, string literals, and template literals so export
+ * detection never matches inside them. Template `${}` holes are scanned
+ * recursively enough for detection purposes (nested braces tracked by depth).
+ */
+export const stripCommentsAndStrings = (source: string): string => {
+  let output = '';
+  let index = 0;
+  const length = source.length;
+  // Template-literal nesting: each entry is the brace depth inside a `${}` hole.
+  const templateHoleDepth: number[] = [];
+  let inTemplate = false;
+  // Last significant character, for the division-versus-regex-literal heuristic.
+  let lastCode = '';
+
+  const regexCanFollow = (): boolean =>
+    lastCode === '' || '(,=:[!&|?{};+-*%<>~^'.includes(lastCode) || /\breturn$|\btypeof$|\bcase$/u.test(output.trimEnd());
+
+  while (index < length) {
+    const char = source[index]!;
+    const next = source[index + 1];
+
+    if (inTemplate) {
+      if (char === '\\') {
+        index += 2;
+        continue;
+      }
+      if (char === '`') {
+        inTemplate = false;
+        index += 1;
+        continue;
+      }
+      if (char === '$' && next === '{') {
+        templateHoleDepth.push(0);
+        inTemplate = false;
+        output += ' ';
+        index += 2;
+        continue;
+      }
+      index += 1;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      while (index < length && source[index] !== '\n') index += 1;
+      continue;
+    }
+    if (char === '/' && next === '*') {
+      index += 2;
+      while (index < length && !(source[index] === '*' && source[index + 1] === '/')) index += 1;
+      index += 2;
+      output += ' ';
+      continue;
+    }
+    if (char === '/' && next !== '/' && next !== '*' && regexCanFollow()) {
+      // Regex literal: skip to its unescaped closing slash (character classes
+      // may contain unescaped slashes).
+      index += 1;
+      let inClass = false;
+      while (index < length && (inClass || source[index] !== '/')) {
+        if (source[index] === '\\') index += 1;
+        else if (source[index] === '[') inClass = true;
+        else if (source[index] === ']') inClass = false;
+        index += 1;
+      }
+      index += 1;
+      while (index < length && /[a-z]/iu.test(source[index]!)) index += 1;
+      output += ' ';
+      lastCode = ' ';
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      index += 1;
+      while (index < length && source[index] !== char) {
+        index += source[index] === '\\' ? 2 : 1;
+      }
+      index += 1;
+      output += ' ';
+      continue;
+    }
+    if (char === '`') {
+      inTemplate = true;
+      index += 1;
+      continue;
+    }
+    if (templateHoleDepth.length > 0) {
+      if (char === '{') {
+        templateHoleDepth[templateHoleDepth.length - 1] = templateHoleDepth[templateHoleDepth.length - 1]! + 1;
+      } else if (char === '}') {
+        const depth = templateHoleDepth[templateHoleDepth.length - 1]!;
+        if (depth === 0) {
+          templateHoleDepth.pop();
+          inTemplate = true;
+          index += 1;
+          continue;
+        }
+        templateHoleDepth[templateHoleDepth.length - 1] = depth - 1;
+      }
+    }
+    output += char;
+    if (!/\s/u.test(char)) lastCode = char;
+    index += 1;
+  }
+
+  return output;
+};
+
+const exportBraceClausePattern = /export\s+(?:type\s+)?\{([^}]*)\}/gu;
+
+/** Names exported by one `export { … }` clause, honoring `as` renames. */
+const braceExportNames = (clause: string): readonly string[] => clause
+  .split(',')
+  .map((entry) => entry.trim())
+  .filter((entry) => entry.length > 0)
+  .map((entry) => {
+    const rename = /^(?:\S+)\s+as\s+(\S+)$/u.exec(entry);
+    return rename === null ? entry : rename[1]!;
+  });
+
+export const scanEntryExportsSource = (source: string): EntryExportScan => {
+  const stripped = stripCommentsAndStrings(source);
+  const braceExports = new Set<string>();
+  for (const match of stripped.matchAll(exportBraceClausePattern)) {
+    // Type-only clauses (`export type { … }`) never produce runtime exports.
+    if (/export\s+type\s*\{/u.test(match[0])) continue;
+    for (const name of braceExportNames(match[1]!)) {
+      braceExports.add(name);
+    }
+  }
+
+  const hasDefaultExport =
+    /(?:^|[\s;}])export\s+default\b/u.test(stripped) || braceExports.has('default');
+  const hasMainExport =
+    /(?:^|[\s;}])export\s+(?:async\s+)?(?:const|let|var|function)\s+main\b/u.test(stripped) ||
+    braceExports.has('main');
+  return Object.freeze({ hasDefaultExport, hasMainExport });
+};
+
+export const scanEntryExports = async (source: string): Promise<EntryExportScan> =>
+  scanEntryExportsSource(await readFile(source, 'utf8'));
diff --git a/packages/agent-bundle/src/build/entry-shell.ts b/packages/agent-bundle/src/build/entry-shell.ts
new file mode 100644
index 000000000..6d85e00d3
--- /dev/null
+++ b/packages/agent-bundle/src/build/entry-shell.ts
@@ -0,0 +1,70 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+/**
+ * Generated-entry templates: the framework-provided entry files consumers
+ * would otherwise write by hand (react-router's provided-entry trick). Every
+ * template imports its consumer module by absolute path, exactly like the
+ * generated hook wrappers, and is bundled through the same Rslib synthesis.
+ */
+
+export const mcpEntryRuntimeSpecifier = 'agent-bundle/mcp-entry';
+
+/**
+ * The on-disk location of the `agent-bundle/mcp-entry` runtime module, used
+ * as a bundler alias so generated entries inline the lifecycle instead of
+ * leaving an `agent-bundle` import in the emitted artifact (artifacts must
+ * stay self-contained). From the bundled package this module's URL is
+ * `dist/<bundle>.js` with `mcp-entry.js` as a sibling; from checked-out
+ * sources it is `src/build/entry-shell.ts` with `../mcp-entry.ts`.
+ */
+export const mcpEntryRuntimePath = (): string => {
+  for (const candidate of [
+    new URL('./mcp-entry.js', import.meta.url),
+    new URL('../mcp-entry.ts', import.meta.url),
+  ]) {
+    const path = fileURLToPath(candidate);
+    if (existsSync(path)) return path;
+  }
+  throw new Error('Unable to locate the agent-bundle/mcp-entry runtime module for generated stdio entries.');
+};
+
+/**
+ * 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.
+ */
+export const generatedStdioMcpEntrySource = (options: {
+  readonly entrySource: string;
+  readonly serverName: string;
+}): string => [
+  `import { runGeneratedStdioMcpEntry } from ${JSON.stringify(mcpEntryRuntimeSpecifier)};`,
+  '',
+  'await runGeneratedStdioMcpEntry({',
+  `  loadEntry: () => import(${JSON.stringify(options.entrySource)}),`,
+  `  serverName: ${JSON.stringify(options.serverName)},`,
+  '});',
+  '',
+].join('\n');
+
+/**
+ * The generated process envelope for a `main`- or default-exporting
+ * executable entry (npm bin outputs and artifact Scripts): await the entry
+ * point with argv, adopt a numeric return as the exit code, and let an
+ * escaped rejection surface through Node's top-level failure path (stack to
+ * stderr, exit code 1).
+ */
+export const generatedExecutableEntrySource = (options: {
+  readonly entrySource: string;
+  readonly exportName: 'default' | 'main';
+}): string => [
+  `import * as entry from ${JSON.stringify(options.entrySource)};`,
+  '',
+  `const main = entry[${JSON.stringify(options.exportName)}];`,
+  "if (typeof main !== 'function') {",
+  `  throw new TypeError('Executable entry must export a ${options.exportName} function: ' + ${JSON.stringify(options.entrySource)});`,
+  '}',
+  'const code = await main(process.argv.slice(2));',
+  "if (typeof code === 'number') process.exitCode = code;",
+  '',
+].join('\n');
diff --git a/packages/agent-bundle/src/build/mcp-apps.ts b/packages/agent-bundle/src/build/mcp-apps.ts
index 03b7b2094..3c944ae32 100644
--- a/packages/agent-bundle/src/build/mcp-apps.ts
+++ b/packages/agent-bundle/src/build/mcp-apps.ts
@@ -1,9 +1,9 @@
-import { createRsbuild } from '@rsbuild/core';
+import { createRsbuild, mergeRsbuildConfig } from '@rsbuild/core';
 import { pluginReact } from '@rsbuild/plugin-react';
 import { readFile } from 'node:fs/promises';
 import { extname, resolve } from 'node:path';
 
-import type { NormalizedMcpApp } from '../core/types.ts';
+import type { AgentBundleToolsConfig, NormalizedMcpApp } from '../core/types.ts';
 import { stableJson } from '../core/digest.ts';
 import { listArtifactFiles, resolveArtifactDestination } from './emit.ts';
 import { collectBundledOutputEvidence } from './provenance.ts';
@@ -128,7 +128,12 @@ export const planCompiledMcpApps = (
 
 export const compileMcpApps = async (
   apps: readonly NormalizedMcpApp[],
-  options: { readonly cwd: string; readonly outDir: string; readonly target: string },
+  options: {
+    readonly cwd: string;
+    readonly outDir: string;
+    readonly target: string;
+    readonly tools?: AgentBundleToolsConfig;
+  },
 ): Promise<readonly CompiledMcpApp[]> => {
   const compiled = planCompiledMcpApps(apps, { outDir: options.outDir, target: options.target });
   if (compiled.length === 0) {
@@ -144,40 +149,50 @@ export const compileMcpApps = async (
   });
 
   // One Rsbuild instance with one environment per app compiles every view in
-  // a single parallel run instead of a sequential per-app build loop.
+  // a single parallel run instead of a sequential per-app build loop. The
+  // consumer escape hatch merges over this synthesized profile with the
+  // framework invariant hook appended last; the resolved-config assertions
+  // below bound what the hatch may change.
+  const profile = {
+    environments: Object.fromEntries(sources.map((source) => [source.name, {
+      ...(usesReactSyntax(source.source) ? { plugins: [pluginReact()] } : {}),
+      html: {
+        inject: 'body' as const,
+        ...(source.template === undefined ? {} : { template: source.template }),
+      },
+      source: { entry: { [source.name]: source.source } },
+    }])),
+    logLevel: 'silent' as const,
+    mode: 'production' as const,
+    output: {
+      cleanDistPath: false,
+      dataUriLimit: Number.MAX_SAFE_INTEGER,
+      distPath: { html: 'mcp-apps', root: options.outDir },
+      filename: { css: '[name].css', html: '[name].html', js: '[name].js' },
+      filenameHash: false,
+      inlineScripts: true,
+      inlineStyles: true,
+      legalComments: 'inline' as const,
+      sourceMap: false,
+      target: 'web' as const,
+    },
+    server: { publicDir: false },
+    splitChunks: false,
+  };
   const rsbuild = await createRsbuild({
     cwd: options.cwd,
-    config: {
-      environments: Object.fromEntries(sources.map((source) => [source.name, {
-        ...(usesReactSyntax(source.source) ? { plugins: [pluginReact()] } : {}),
-        html: {
-          inject: 'body' as const,
-          ...(source.template === undefined ? {} : { template: source.template }),
-        },
-        source: { entry: { [source.name]: source.source } },
-      }])),
-      logLevel: 'silent',
-      mode: 'production',
-      output: {
-        cleanDistPath: false,
-        dataUriLimit: Number.MAX_SAFE_INTEGER,
-        distPath: { html: 'mcp-apps', root: options.outDir },
-        filename: { css: '[name].css', html: '[name].html', js: '[name].js' },
-        filenameHash: false,
-        inlineScripts: true,
-        inlineStyles: true,
-        legalComments: 'inline',
-        sourceMap: false,
-        target: 'web',
-      },
-      server: { publicDir: false },
-      splitChunks: false,
-      tools: {
-        rspack: (config) => {
-          config.output.asyncChunks = false;
+    config: mergeRsbuildConfig(
+      profile as never,
+      ...(options.tools?.rsbuild === undefined ? [] : [options.tools.rsbuild as never]),
+      ...(options.tools?.rspack === undefined ? [] : [{ tools: { rspack: options.tools.rspack } } as never]),
+      {
+        tools: {
+          rspack: (config: { output: { asyncChunks?: boolean } }) => {
+            config.output.asyncChunks = false;
+          },
         },
-      },
-    },
+      } as never,
+    ),
   });
   const inspection = await rsbuild.inspectConfig({ mode: 'production' });
   assertResolvedViewConfig(inspection, compiled.map((app) => app.name), options.outDir);
diff --git a/packages/agent-bundle/src/build/package-build.ts b/packages/agent-bundle/src/build/package-build.ts
new file mode 100644
index 000000000..80ea5e056
--- /dev/null
+++ b/packages/agent-bundle/src/build/package-build.ts
@@ -0,0 +1,204 @@
+import { existsSync } from 'node:fs';
+import { chmod, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+
+import type { AgentBundleToolsConfig, NormalizedPlugin } from '../core/types.ts';
+import { assertInside } from '../core/paths.ts';
+import { listArtifactFiles, publishArtifact, resolveArtifactDestination } from './emit.ts';
+import { scanEntryExports } from './entry-exports.ts';
+import { generatedExecutableEntrySource } from './entry-shell.ts';
+import { buildWithRslib, type RslibEntry } from './rslib.ts';
+
+/**
+ * The framework-owned npm package build: `bin` entries become self-executing
+ * `dist/bin/<name>.js` bundles (shebang + executable bit) and the `lib` entry
+ * becomes `dist/<name>.js` (+ bundled `.d.ts`), all through the same Rslib
+ * synthesis, invariant assertions, and staged atomic publication as artifact
+ * executables. This is the build audiobook-curator previously needed a second
+ * bundler config, a tsconfig, and a hand-written bin shim to produce.
+ */
+
+const binShebang = '#!/usr/bin/env node';
+const executableMode = 0o755;
+
+export interface PackageOutputFile {
+  readonly bytes: number;
+  readonly kind: 'bundle' | 'generated';
+  /** Present only for executable outputs. */
+  readonly mode?: number;
+  /** POSIX path relative to the package output root. */
+  readonly path: string;
+  readonly sha256: string;
+  /** Sorted, unique POSIX paths relative to the project root. */
+  readonly sourceInputs: readonly string[];
+}
+
+export interface PackageBuildResult {
+  readonly files: readonly PackageOutputFile[];
+  readonly outputRoot: string;
+}
+
+const toPosixRelative = (root: string, path: string): string =>
+  relative(resolve(root), path).replaceAll('\\', '/');
+
+const relativeSourceInputs = (projectRoot: string, inputs: readonly string[]): readonly string[] =>
+  Object.freeze([...new Set(inputs.map((input) => toPosixRelative(projectRoot, assertInside(projectRoot, input))))]
+    .sort((left, right) => left.localeCompare(right)));
+
+interface PlannedPackageEntry extends RslibEntry {
+  readonly executable: boolean;
+}
+
+/**
+ * Declaration generation compiles the lib entry's source directory as its own
+ * program — the project tsconfig typically also covers tests and config
+ * files, which must never fail or pollute the package build. The synthesized
+ * project extends the project's own `tsconfig.json` (compiler options such as
+ * `jsx` and strictness) and pins `rootDir` so declarations land flat in the
+ * package output, exactly like the dedicated build tsconfig consumers
+ * previously maintained by hand.
+ */
+const synthesizeDtsTsconfig = async (options: {
+  readonly projectRoot: string;
+  readonly sourceDir: string;
+}): Promise<{ readonly cleanup: () => Promise<void>; readonly path: string }> => {
+  // The synthesized project lives under node_modules (mandatory-ignored for
+  // source snapshots) so `types` and other tsconfig lookups resolve against
+  // the project's own installed packages.
+  await mkdir(resolve(options.projectRoot, 'node_modules'), { recursive: true });
+  const root = await mkdtemp(resolve(options.projectRoot, 'node_modules', '.agent-bundle-dts-'));
+  const projectTsconfig = resolve(options.projectRoot, 'tsconfig.json');
+  const path = join(root, 'tsconfig.json');
+  await writeFile(path, `${JSON.stringify({
+    ...(existsSync(projectTsconfig) ? { extends: projectTsconfig } : {}),
+    compilerOptions: { rootDir: options.sourceDir },
+    include: [`${options.sourceDir}/**/*.ts`, `${options.sourceDir}/**/*.tsx`],
+  }, null, 2)}\n`, 'utf8');
+  return {
+    cleanup: () => rm(root, { force: true, recursive: true }),
+    path,
+  };
+};
+
+const planPackageEntries = async (
+  model: NormalizedPlugin,
+  dtsTsconfigPath: string | undefined,
+): Promise<readonly PlannedPackageEntry[]> => {
+  const packageBuild = model.packageBuild;
+  if (packageBuild === undefined) return Object.freeze([]);
+  const entries: PlannedPackageEntry[] = [];
+  for (const bin of packageBuild.bins) {
+    // A bin entry exporting `main` (or a default function) receives the
+    // generated process envelope; a self-executing module bundles directly.
+    const exports = await scanEntryExports(bin.source);
+    const exportName = exports.hasMainExport ? 'main' as const : exports.hasDefaultExport ? 'default' as const : undefined;
+    entries.push({
+      banner: binShebang,
+      executable: true,
+      name: `bin-${bin.name}`,
+      outputRelativePath: `bin/${bin.name}.js`,
+      source: bin.source,
+      sourceInputs: Object.freeze([bin.provenance.sourcePath, bin.source]),
+      ...(exportName === undefined
+        ? {}
+        : { virtualSource: generatedExecutableEntrySource({ entrySource: bin.source, exportName }) }),
+    });
+  }
+  if (packageBuild.lib !== undefined) {
+    const lib = packageBuild.lib;
+    entries.push({
+      dts: lib.dts,
+      executable: false,
+      name: lib.name,
+      outputRelativePath: `${lib.name}.js`,
+      source: lib.source,
+      sourceInputs: Object.freeze([lib.provenance.sourcePath, lib.source]),
+      ...(lib.dts && dtsTsconfigPath !== undefined ? { tsconfigPath: dtsTsconfigPath } : {}),
+    });
+  }
+  return Object.freeze(entries);
+};
+
+/** Maps one emitted `.d.ts` back to the authored module it declares. */
+const declarationSource = (sourceDir: string, declarationPath: string): string | undefined => {
+  const stem = declarationPath.slice(0, -'.d.ts'.length);
+  for (const extension of ['.ts', '.tsx', '.mts']) {
+    const candidate = resolve(sourceDir, `${stem}${extension}`);
+    if (existsSync(candidate)) return candidate;
+  }
+  return undefined;
+};
+
+export const buildPackageOutputs = async (options: {
+  readonly model: NormalizedPlugin;
+  readonly projectRoot: string;
+  readonly tools?: AgentBundleToolsConfig;
+}): Promise<PackageBuildResult | undefined> => {
+  const packageBuild = options.model.packageBuild;
+  if (packageBuild === undefined) return undefined;
+  const projectRoot = resolve(options.projectRoot);
+  const outputRoot = assertInside(projectRoot, resolve(projectRoot, packageBuild.outputDir));
+  const libSourceDir = packageBuild.lib === undefined ? undefined : dirname(packageBuild.lib.source);
+  const dtsTsconfig = packageBuild.lib?.dts === true && libSourceDir !== undefined
+    ? await synthesizeDtsTsconfig({ projectRoot, sourceDir: libSourceDir })
+    : undefined;
+  const entries = await planPackageEntries(options.model, dtsTsconfig?.path);
+  if (entries.length === 0) {
+    await dtsTsconfig?.cleanup();
+    return undefined;
+  }
+
+  const stageParent = dirname(outputRoot);
+  await mkdir(stageParent, { recursive: true });
+  const stageRoot = await mkdtemp(join(stageParent, `.${basename(outputRoot)}.stage-`));
+  try {
+    const evidence = await buildWithRslib({
+      cwd: projectRoot,
+      entries,
+      logLevel: 'error',
+      outputRoot: stageRoot,
+      ...(options.tools === undefined ? {} : { tools: options.tools }),
+    });
+    const evidenceByPath = new Map(evidence.map((entry) => [entry.path, entry.sourceInputs]));
+    await Promise.all(entries
+      .filter((entry) => entry.executable)
+      .map((entry) => chmod(resolveArtifactDestination(stageRoot, entry.outputRelativePath), executableMode)));
+
+    const lib = packageBuild.lib;
+    const files = (await listArtifactFiles(stageRoot)).map((file): PackageOutputFile => {
+      const bundled = evidenceByPath.get(file.path);
+      const declared = lib?.dts === true && libSourceDir !== undefined && file.path.endsWith('.d.ts')
+        ? declarationSource(libSourceDir, file.path) ?? lib.source
+        : undefined;
+      if (bundled === undefined && declared === undefined) {
+        throw new Error(`Package build emitted unexpected output ${JSON.stringify(file.path)}.`);
+      }
+      return {
+        bytes: file.bytes,
+        kind: bundled === undefined ? 'generated' : 'bundle',
+        ...((file.mode & 0o111) === 0 ? {} : { mode: file.mode }),
+        path: file.path,
+        sha256: file.sha256,
+        sourceInputs: relativeSourceInputs(
+          projectRoot,
+          bundled ?? [lib!.provenance.sourcePath, declared!],
+        ),
+      };
+    }).sort((left, right) => left.path.localeCompare(right.path));
+    for (const entry of entries) {
+      if (!files.some((file) => file.path === entry.outputRelativePath)) {
+        throw new Error(`Package build did not emit expected output ${JSON.stringify(entry.outputRelativePath)}.`);
+      }
+    }
+    if (lib?.dts === true && !files.some((file) => file.path === `${lib.name}.d.ts`)) {
+      throw new Error(`Package build did not emit expected declarations ${JSON.stringify(`${lib.name}.d.ts`)}.`);
+    }
+
+    await publishArtifact({ outputRoot, stageRoot });
+    return Object.freeze({ files: Object.freeze(files), outputRoot });
+  } finally {
+    // publishArtifact removes the stage on success; a failed build leaves it.
+    await rm(stageRoot, { force: true, recursive: true });
+    await dtsTsconfig?.cleanup();
+  }
+};
diff --git a/packages/agent-bundle/src/build/rslib.ts b/packages/agent-bundle/src/build/rslib.ts
index 3dcea272b..1dd3ca68a 100644
--- a/packages/agent-bundle/src/build/rslib.ts
+++ b/packages/agent-bundle/src/build/rslib.ts
@@ -1,11 +1,13 @@
 // Rslib re-exports its own rspack; installing @rspack/core separately risks
 // version conflicts (https://rslib.rs/api/javascript-api/core).
-import { createRslib, rspack } from '@rslib/core';
+import { mergeRsbuildConfig } from '@rsbuild/core';
+import { createRslib, rspack, type LibConfig } from '@rslib/core';
 import { readFile, realpath } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isErrno } from '../core/errors.ts';
+import type { AgentBundleToolsConfig } from '../core/types.ts';
 import { collectBundledOutputEvidence, type BundledOutputEvidence } from './provenance.ts';
 
 export interface RslibVirtualModule {
@@ -14,15 +16,24 @@ export interface RslibVirtualModule {
 }
 
 export interface RslibEntry {
+  /** Module specifiers aliased onto existing on-disk modules (e.g. the mcp-entry runtime shell). */
+  readonly aliases?: Readonly<Record<string, string>>;
+  /** Raw JS banner prepended to the emitted bundle (e.g. a bin shebang). */
+  readonly banner?: string;
+  /** Emit type declarations for this entry's program. Defaults to false. */
+  readonly dts?: boolean;
   readonly name: string;
   readonly outputRelativePath: string;
   readonly source: string;
   readonly sourceInputs: readonly string[];
+  /** TypeScript project driving declaration generation and compiler options. */
+  readonly tsconfigPath?: string;
   readonly virtualModules?: readonly RslibVirtualModule[];
   readonly virtualSource?: string;
 }
 
 type RslibInstance = Awaited<ReturnType<typeof createRslib>>;
+type RslibLibConfig = LibConfig;
 
 interface RslibDependencies {
   readonly createRslib?: (options: Parameters<typeof createRslib>[0]) => Promise<Pick<RslibInstance, 'build' | 'inspectConfig'>>;
@@ -62,18 +73,18 @@ const assertExecutableConfig = (
   configs: readonly { readonly output?: { readonly asyncChunks?: boolean; readonly path?: string }; readonly plugins?: readonly unknown[]; readonly target?: false | string | readonly string[] }[],
   outputRoot: string,
 ): void => {
-  const virtualEntries = entries.filter(
-    (entry) => entry.virtualSource !== undefined || (entry.virtualModules?.length ?? 0) > 0,
-  );
   if (configs.length !== entries.length) {
     throw new Error('Rslib did not resolve one environment for every generated executable.');
   }
-  for (const config of configs) {
+  for (const [index, config] of configs.entries()) {
+    const entry = entries[index]!;
     const target = Array.isArray(config.target) ? config.target : [config.target];
     if (config.output?.asyncChunks !== false || config.output.path !== outputRoot || !target.some((value) => value === 'node')) {
       throw new Error('Rslib resolved an invalid generated executable configuration.');
     }
-    if (virtualEntries.length > 0) {
+    const entryHasVirtualModules =
+      entry.virtualSource !== undefined || (entry.virtualModules?.length ?? 0) > 0;
+    if (entryHasVirtualModules) {
       const hasVirtualModule = config.plugins?.some(
         (plugin) => plugin instanceof rspack.experiments.VirtualModulesPlugin,
       );
@@ -87,7 +98,13 @@ const assertExecutableConfig = (
 export const buildWithRslib = async (options: {
   readonly cwd: string;
   readonly entries: readonly RslibEntry[];
+  /** Extra module roots excluded from authored-source evidence (e.g. the aliased runtime shell). */
+  readonly ignoredSourcePaths?: readonly string[];
+  /** 'error' lets declaration-generation failures reach the consumer's terminal. */
+  readonly logLevel?: 'error' | 'silent';
   readonly outputRoot: string;
+  /** The consumer escape hatch, merged last-but-bounded into every synthesized entry. */
+  readonly tools?: AgentBundleToolsConfig;
 }, dependencies: RslibDependencies = {}): Promise<readonly BundledOutputEvidence[]> => {
   if (options.entries.length === 0) {
     return Object.freeze([]);
@@ -97,7 +114,7 @@ export const buildWithRslib = async (options: {
   const rslib = await (dependencies.createRslib ?? createRslib)({
     cwd: options.cwd,
     config: {
-      logLevel: 'silent',
+      logLevel: options.logLevel ?? 'silent',
       lib: options.entries.map((entry) => {
         const virtualSource = entry.virtualSource;
         const virtualModules = (entry.virtualModules ?? []).map((module, index) => ({
@@ -105,11 +122,33 @@ export const buildWithRslib = async (options: {
           path: resolve(options.outputRoot, '.agent-bundle-virtual', `${entry.name}-${index}.mjs`),
         }));
         const hasVirtualModules = virtualSource !== undefined || virtualModules.length > 0;
-        return {
+        const aliases = entry.aliases ?? {};
+        const enforceInvariants = (config: {
+          output: { asyncChunks?: boolean };
+          plugins: unknown[];
+          resolve: { alias?: Record<string, unknown> };
+        }): void => {
+          config.output.asyncChunks = false;
+          if (hasVirtualModules || Object.keys(aliases).length > 0) {
+            config.resolve.alias = {
+              ...config.resolve.alias,
+              ...aliases,
+              ...Object.fromEntries(virtualModules.map((module) => [module.name, module.path])),
+            };
+          }
+          if (hasVirtualModules) {
+            config.plugins.push(new rspack.experiments.VirtualModulesPlugin({
+              ...(virtualSource === undefined ? {} : { [entryAnchor]: virtualSource }),
+              ...Object.fromEntries(virtualModules.map((module) => [module.path, module.source])),
+            }));
+          }
+        };
+        const profile: RslibLibConfig = {
           id: `agent-bundle-${entry.name}`,
           autoExternal: false,
+          ...(entry.banner === undefined ? {} : { banner: { js: entry.banner } }),
           bundle: true,
-          dts: false,
+          dts: entry.dts === true,
           format: 'esm',
           // Copied projects can share one node_modules tree, so a cache keyed
           // by this stable library id would give concurrent builds one lock.
@@ -135,23 +174,18 @@ export const buildWithRslib = async (options: {
             entry: {
               [entry.name]: virtualSource === undefined ? entry.source : entryAnchor,
             },
-          },
-          tools: {
-            rspack: (config) => {
-              config.output.asyncChunks = false;
-              if (hasVirtualModules) {
-                config.resolve.alias = {
-                  ...config.resolve.alias,
-                  ...Object.fromEntries(virtualModules.map((module) => [module.name, module.path])),
-                };
-                config.plugins.push(new rspack.experiments.VirtualModulesPlugin({
-                  ...(virtualSource === undefined ? {} : { [entryAnchor]: virtualSource }),
-                  ...Object.fromEntries(virtualModules.map((module) => [module.path, module.source])),
-                }));
-              }
-            },
+            ...(entry.tsconfigPath === undefined ? {} : { tsconfigPath: entry.tsconfigPath }),
           },
         };
+        // The escape hatch merges over the synthesized profile (Rslib's
+        // "raw user config highest" priority); the invariant enforcer hook is
+        // appended last, and the post-resolution assertions bound the hatch.
+        return mergeRsbuildConfig(
+          profile as never,
+          ...(options.tools?.rsbuild === undefined ? [] : [options.tools.rsbuild as never]),
+          ...(options.tools?.rspack === undefined ? [] : [{ tools: { rspack: options.tools.rspack } } as never]),
+          { tools: { rspack: enforceInvariants } } as never,
+        ) as RslibLibConfig;
       }),
     },
   });
@@ -166,7 +200,12 @@ export const buildWithRslib = async (options: {
         path: entry.outputRelativePath,
         sourceInputs: entry.sourceInputs,
       })),
-      ignoredSourcePaths: [entryAnchor, resolve(options.outputRoot, '.agent-bundle-virtual'), ...dependencyRoots],
+      ignoredSourcePaths: [
+        entryAnchor,
+        resolve(options.outputRoot, '.agent-bundle-virtual'),
+        ...(options.ignoredSourcePaths ?? []),
+        ...dependencyRoots,
+      ],
       projectRoot: options.cwd,
       stats: result.stats,
     });
diff --git a/packages/agent-bundle/src/cli.ts b/packages/agent-bundle/src/cli.ts
index 334b9e94d..691439888 100644
--- a/packages/agent-bundle/src/cli.ts
+++ b/packages/agent-bundle/src/cli.ts
@@ -195,6 +195,9 @@ const writeMachine = (output: Output, result: unknown): void => {
 
 const writeHumanBuild = (output: Output, result: Awaited<ReturnType<typeof build>>): void => {
   output.write(`Built ${result.model.metadata.name} to ${result.build.outputRoot}\n`);
+  if (result.packageBuild !== undefined) {
+    output.write(`Package build (${result.packageBuild.files.length} file(s)) at ${result.packageBuild.outputRoot}\n`);
+  }
 };
 
 const writeHumanInspect = (output: Output, result: Awaited<ReturnType<typeof inspect>>): void => {
@@ -329,7 +332,7 @@ export const runCli = async (
   ).option('--output <path>', 'Artifact output path relative to --root');
   buildCommand.action(async (options: BuildCommandOptions) => {
     const { build } = await import('./api.ts');
-    const result = await build({ ...projectOptions(options), output: options.output });
+    const result = await build({ ...projectOptions(options), output: options.output, packageOutputs: true });
     if (options.json === true) writeMachine(stdout, result);
     else writeHumanBuild(stdout, result);
   });
@@ -451,6 +454,21 @@ export const runCli = async (
     else stdout.write(`Invoked ${options.tool} on ${options.server}\n`);
   });
 
+  const mcpRunCommand = configureArtifactOptions(
+    mcpCommand.command('run').description('Run one stdio MCP server in the foreground from an artifact'),
+    true,
+  ).requiredOption('--server <server>', 'MCP server name');
+  mcpRunCommand.action(async (options: ArtifactCommandOptions & { readonly server: string; readonly target: string }) => {
+    const { runMcp } = await import('./api.ts');
+    // No stdout writes here: with inherited stdio the server owns the
+    // JSON-RPC channel for the whole foreground run.
+    exitCode = await runMcp({
+      ...artifactOptions(options),
+      server: options.server,
+      target: options.target,
+    });
+  });
+
   const hooksCommand = program.command('hooks').description('Inspect and simulate generated hooks');
   const hooksListCommand = configureArtifactOptions(
     hooksCommand.command('list').description('List hooks from one artifact'),
diff --git a/packages/agent-bundle/src/config/normalize.ts b/packages/agent-bundle/src/config/normalize.ts
index 4c63870f9..393e5acba 100644
--- a/packages/agent-bundle/src/config/normalize.ts
+++ b/packages/agent-bundle/src/config/normalize.ts
@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { existsSync, statSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { basename, extname, relative, resolve } from 'node:path';
 
@@ -11,8 +12,11 @@ import {
 } from '../core/runtime.ts';
 import { parseNativeHookToolSelector, pathTokens } from '../core/types.ts';
 import type {
+  AgentBundleBinEntry,
+  AgentBundleConfig,
   AgentBundleHookEntry,
   AgentBundleHookInput,
+  AgentBundleLibEntry,
   AgentBundleMcpApp,
   AgentBundleMcpServer,
   AgentBundleScriptInput,
@@ -21,11 +25,14 @@ import type {
   NativeHookToolSelector,
   NormalizationTargetRegistry,
   NormalizedAsset,
+  NormalizedBinEntry,
   NormalizedConfigExtension,
   NormalizedHook,
+  NormalizedLibEntry,
   NormalizedMcpApp,
   NormalizedMcpServer,
   NormalizedNativeHook,
+  NormalizedPackageBuild,
   NormalizedPlugin,
   NormalizedRuntime,
   NormalizedScript,
@@ -74,6 +81,121 @@ const mcpEntryName = (name: string): string => {
 /** Anchored alias contract for generated target-local MCP entry modules. */
 export const mcpEntryAliasPattern = /^mcp\/(mcp-[a-z0-9-]+-[a-f\d]{8}\.mjs)$/u;
 
+const conventionalEntryExtensions = ['.ts', '.tsx'] as const;
+
+const conventionalEntryAt = (root: string, ...segments: string[]): string | undefined => {
+  const stem = resolve(root, ...segments);
+  for (const extension of conventionalEntryExtensions) {
+    const candidate = `${stem}${extension}`;
+    try {
+      if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+    } catch {
+      // A racing deletion means the convention does not apply.
+    }
+  }
+  return undefined;
+};
+
+/**
+ * The `src/mcp/<server-id>.ts` convention: the stdio entry for a declared MCP
+ * server that names no entry, command, or url. Config always wins — an
+ * explicit `entry` suppresses the lookup entirely.
+ */
+export const conventionalMcpEntrySource = (root: string, serverName: string): string | undefined =>
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u.test(serverName)
+    ? conventionalEntryAt(root, 'src', 'mcp', serverName)
+    : undefined;
+
+const safePackageOutputName = (name: string): boolean =>
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u.test(name);
+
+/**
+ * The framework-owned package build output directory, relative to the project
+ * root. `dist` is one of the mandatory-ignored directory names, so package
+ * outputs never enter project source snapshots or skill/asset discovery.
+ */
+export const packageBuildOutputDir = 'dist';
+
+const normalizeBinEntries = (
+  config: Readonly<AgentBundleConfig>,
+  root: string,
+  configPath: string,
+): readonly NormalizedBinEntry[] => {
+  if (config.bin === false) return [];
+  if (config.bin !== undefined) {
+    return Object.entries(config.bin)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([name, input]) => {
+        const declaration = input as string | AgentBundleBinEntry;
+        const entry = typeof declaration === 'string' ? declaration : declaration.entry;
+        return {
+          id: `bin:${name}`,
+          name,
+          provenance: { kind: 'config' as const, sourcePath: configPath },
+          source: resolve(root, entry),
+        };
+      });
+  }
+  const conventional = conventionalEntryAt(root, 'src', 'cli');
+  if (conventional === undefined || !safePackageOutputName(config.plugin.name)) return [];
+  return [{
+    id: `bin:${config.plugin.name}`,
+    name: config.plugin.name,
+    provenance: { kind: 'conventional' as const, sourcePath: conventional },
+    source: conventional,
+  }];
+};
+
+const normalizeLibEntry = (
+  config: Readonly<AgentBundleConfig>,
+  root: string,
+  configPath: string,
+): NormalizedLibEntry | undefined => {
+  if (config.lib === false) return undefined;
+  if (config.lib !== undefined) {
+    const declaration = config.lib as string | AgentBundleLibEntry;
+    const entry = typeof declaration === 'string' ? declaration : declaration.entry;
+    const source = resolve(root, entry);
+    const name = basename(source, extname(source));
+    return {
+      dts: typeof declaration === 'string' ? true : declaration.dts !== false,
+      id: `lib:${name}`,
+      name,
+      provenance: { kind: 'config', sourcePath: configPath },
+      source,
+    };
+  }
+  const conventional = conventionalEntryAt(root, 'src', 'index');
+  if (conventional === undefined) return undefined;
+  return {
+    dts: true,
+    id: 'lib:index',
+    name: 'index',
+    provenance: { kind: 'conventional', sourcePath: conventional },
+    source: conventional,
+  };
+};
+
+/**
+ * The framework-owned npm package build: explicit `bin`/`lib` config wins,
+ * the `src/cli.ts` and `src/index.ts` conventions fill the gaps, and `false`
+ * opts a project out of a convention entirely.
+ */
+export const normalizePackageBuild = (
+  config: Readonly<AgentBundleConfig>,
+  root: string,
+  configPath: string,
+): NormalizedPackageBuild | undefined => {
+  const bins = normalizeBinEntries(config, root, configPath);
+  const lib = normalizeLibEntry(config, root, configPath);
+  if (bins.length === 0 && lib === undefined) return undefined;
+  return {
+    bins,
+    ...(lib === undefined ? {} : { lib }),
+    outputDir: packageBuildOutputDir,
+  };
+};
+
 const isHookEntryList = (
   input: AgentBundleHookInput,
 ): input is readonly (string | AgentBundleHookEntry)[] => Array.isArray(input);
@@ -214,14 +336,20 @@ const normalizeMcpServer = (
   provenance: SourceProvenance,
 ): NormalizedMcpServer => {
   const targets = sortedUnique(server.targets ?? defaultTargets);
+  const conventionalEntry =
+    server.entry === undefined && server.command === undefined && server.url === undefined
+      ? conventionalMcpEntrySource(root, name)
+      : undefined;
   const common = {
     id: `mcp:${name}`,
     name,
-    provenance: { ...provenance },
+    provenance: conventionalEntry === undefined
+      ? { ...provenance }
+      : { kind: 'conventional' as const, sourcePath: conventionalEntry },
     targets,
   };
 
-  if (server.entry !== undefined) {
+  if (server.entry !== undefined || conventionalEntry !== undefined) {
     const entryName = mcpEntryName(name);
     return {
       ...common,
@@ -229,7 +357,7 @@ const normalizeMcpServer = (
       args: [`mcp/${entryName}`, ...(server.args ?? [])],
       command: 'node',
       cwd: pathTokens.pluginRoot,
-      source: resolve(root, server.entry),
+      source: server.entry === undefined ? conventionalEntry! : resolve(root, server.entry),
       transport: 'stdio',
     };
   }
@@ -533,6 +661,7 @@ export const normalizeProject = async (
   const mcpServers = normalizeMcpServers(loaded, targetNames);
   const scripts = normalizeScripts(loaded, targetNames);
   const assets = normalizeAssets(loaded, discovered, targetNames);
+  const packageBuild = normalizePackageBuild(loaded.config, loaded.context.projectRoot, loaded.configPath);
   const model: NormalizedPlugin = {
     ...(assets.length === 0 ? {} : { assets }),
     ...(loaded.config.marketplace === true ? { marketplace: true as const } : {}),
@@ -548,6 +677,7 @@ export const normalizeProject = async (
     mcpServers,
     hooks: normalizeHooks(loaded, targetNames, registry),
     ...(nativeHooks.length === 0 ? {} : { nativeHooks }),
+    ...(packageBuild === undefined ? {} : { packageBuild }),
     runtime: normalizeRuntime(loaded),
     scripts,
     skills,
diff --git a/packages/agent-bundle/src/config/validate.ts b/packages/agent-bundle/src/config/validate.ts
index 851216245..d459b2a79 100644
--- a/packages/agent-bundle/src/config/validate.ts
+++ b/packages/agent-bundle/src/config/validate.ts
@@ -11,8 +11,10 @@ import {
 } from '../core/runtime.ts';
 import { parseNativeHookToolSelector } from '../core/types.ts';
 import type {
+  AgentBundleBinEntry,
   AgentBundleHookEntry,
   AgentBundleHookInput,
+  AgentBundleLibEntry,
   AgentBundleMcpApp,
   AgentBundleMcpServer,
   AgentBundleScriptInput,
@@ -20,6 +22,7 @@ import type {
   NormalizationTargetRegistry,
   NormalizedPlugin,
 } from '../core/types.ts';
+import { conventionalMcpEntrySource } from './normalize.ts';
 import type { DiscoveredProject } from './discover.ts';
 import type { LoadedConfig } from './load.ts';
 import type { SkillDocument } from './skill.ts';
@@ -411,7 +414,11 @@ const validateMcpApps = (
 ): Diagnostic[] => {
   if (server.apps === undefined) return [];
   const diagnostics: Diagnostic[] = [];
-  if (server.entry === undefined) {
+  const hasLocalEntry = server.entry !== undefined || (
+    server.command === undefined && server.url === undefined &&
+    conventionalMcpEntrySource(loaded.context.projectRoot, name) !== undefined
+  );
+  if (!hasLocalEntry) {
     diagnostics.push(sourceDiagnostic(
       'AB4322',
       `MCP server ${JSON.stringify(name)} can declare Apps only with a local entry.`,
@@ -542,7 +549,19 @@ const validateMcpServer = (
   const command = server.command;
   const url = server.url;
   const variants = [entry, command, url].filter((candidate) => candidate !== undefined);
-  if (variants.length !== 1) {
+  const conventionalEntry = variants.length === 0
+    ? conventionalMcpEntrySource(loaded.context.projectRoot, name)
+    : undefined;
+  if (variants.length !== 1 && conventionalEntry === undefined) {
+    diagnostics.push(sourceDiagnostic(
+      'AB4304',
+      `MCP server ${JSON.stringify(name)} must define exactly one of entry, command, or url, `
+      + `or provide the conventional stdio entry src/mcp/${name}.ts.`,
+      loaded.configPath,
+    ));
+    return diagnostics;
+  }
+  if (variants.length > 1) {
     diagnostics.push(sourceDiagnostic(
       'AB4304',
       `MCP server ${JSON.stringify(name)} must define exactly one of entry, command, or url.`,
@@ -552,10 +571,10 @@ const validateMcpServer = (
   }
   diagnostics.push(...validateStringList(server.targets, 'targets', 'AB4305', loaded));
 
-  if (entry !== undefined) {
-    if (!nonemptyString(entry)) {
+  if (entry !== undefined || conventionalEntry !== undefined) {
+    if (entry !== undefined && !nonemptyString(entry)) {
       diagnostics.push(sourceDiagnostic('AB4306', `MCP server ${JSON.stringify(name)} entry must be a nonempty path.`, loaded.configPath));
-    } else if (!localEntryExists(loaded.context.projectRoot, entry)) {
+    } else if (entry !== undefined && !localEntryExists(loaded.context.projectRoot, entry)) {
       diagnostics.push(sourceDiagnostic('AB4307', `MCP server ${JSON.stringify(name)} entry does not exist.`, loaded.configPath));
     }
     if (server.transport !== undefined && server.transport !== 'stdio') {
@@ -722,6 +741,123 @@ const validateSkill = (skill: SkillDocument): Diagnostic[] => {
   return diagnostics;
 };
 
+const isSafePackageOutputName = (name: string): boolean =>
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u.test(name);
+
+const validatePackageEntryPath = (
+  label: string,
+  entry: unknown,
+  code: { readonly empty: string; readonly extension: string; readonly missing: string; readonly outside: string },
+  loaded: LoadedConfig,
+): Diagnostic[] => {
+  if (!nonemptyString(entry)) {
+    return [sourceDiagnostic(code.empty, `${label} entry must be a nonempty path.`, loaded.configPath)];
+  }
+  const source = resolve(loaded.context.projectRoot, entry);
+  if (!isInside(loaded.context.projectRoot, source)) {
+    return [sourceDiagnostic(code.outside, `${label} entry must resolve inside the project root.`, loaded.configPath)];
+  }
+  const diagnostics: Diagnostic[] = [];
+  if (!bundleScriptExtensions.has(extname(source).toLowerCase())) {
+    diagnostics.push(sourceDiagnostic(code.extension, `${label} entry has an unsupported extension.`, loaded.configPath));
+  }
+  if (!localEntryExists(loaded.context.projectRoot, entry)) {
+    diagnostics.push(sourceDiagnostic(code.missing, `${label} entry must name an existing regular file.`, loaded.configPath));
+  }
+  return diagnostics;
+};
+
+const validateBin = (loaded: LoadedConfig): Diagnostic[] => {
+  const bin = loaded.config.bin;
+  if (bin === undefined || bin === false) return [];
+  if (!isRecord(bin)) {
+    return [sourceDiagnostic('AB4700', 'Bin configuration must be false or an object of bin entries.', loaded.configPath)];
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const [name, rawDeclaration] of Object.entries(bin)) {
+    if (!isSafePackageOutputName(name)) {
+      diagnostics.push(sourceDiagnostic(
+        'AB4701',
+        `Bin name ${JSON.stringify(name)} must be a safe stable output name.`,
+        loaded.configPath,
+      ));
+    }
+    if (typeof rawDeclaration !== 'string' && !isRecord(rawDeclaration)) {
+      diagnostics.push(sourceDiagnostic(
+        'AB4702',
+        `Bin ${JSON.stringify(name)} must be an entry path or an object with an entry path.`,
+        loaded.configPath,
+      ));
+      continue;
+    }
+    const declaration = rawDeclaration as string | AgentBundleBinEntry;
+    diagnostics.push(...validatePackageEntryPath(
+      `Bin ${JSON.stringify(name)}`,
+      typeof declaration === 'string' ? declaration : declaration.entry,
+      { empty: 'AB4702', extension: 'AB4704', missing: 'AB4705', outside: 'AB4703' },
+      loaded,
+    ));
+  }
+  return diagnostics;
+};
+
+const validateLib = (loaded: LoadedConfig): Diagnostic[] => {
+  const lib = loaded.config.lib;
+  if (lib === undefined || lib === false) return [];
+  if (typeof lib !== 'string' && !isRecord(lib)) {
+    return [sourceDiagnostic('AB4710', 'Lib configuration must be false, an entry path, or an object with an entry path.', loaded.configPath)];
+  }
+  const declaration = lib as string | AgentBundleLibEntry;
+  const diagnostics = validatePackageEntryPath(
+    'Lib',
+    typeof declaration === 'string' ? declaration : declaration.entry,
+    { empty: 'AB4711', extension: 'AB4713', missing: 'AB4714', outside: 'AB4712' },
+    loaded,
+  );
+  if (typeof declaration !== 'string' && declaration.dts !== undefined && typeof declaration.dts !== 'boolean') {
+    diagnostics.push(sourceDiagnostic('AB4715', 'Lib dts must be a boolean.', loaded.configPath));
+  }
+  return diagnostics;
+};
+
+const isRspackHatchValue = (value: unknown): boolean =>
+  typeof value === 'function' || isRecord(value);
+
+const validateTools = (loaded: LoadedConfig): Diagnostic[] => {
+  const tools = loaded.config.tools;
+  if (tools === undefined) return [];
+  if (!isRecord(tools)) {
+    return [sourceDiagnostic('AB4720', 'Tools configuration must be an object.', loaded.configPath)];
+  }
+  const diagnostics: Diagnostic[] = [];
+  for (const key of Object.keys(tools)) {
+    if (key !== 'rsbuild' && key !== 'rspack') {
+      diagnostics.push(sourceDiagnostic(
+        'AB4721',
+        `Tools configuration key ${JSON.stringify(key)} is not a supported escape hatch; use rsbuild or rspack.`,
+        loaded.configPath,
+      ));
+    }
+  }
+  const rsbuild = (tools as Record<string, unknown>).rsbuild;
+  if (rsbuild !== undefined && !isRecord(rsbuild)) {
+    diagnostics.push(sourceDiagnostic('AB4722', 'Tools rsbuild must be an Rsbuild environment-config object.', loaded.configPath));
+  }
+  const rspack = (tools as Record<string, unknown>).rspack;
+  if (
+    rspack !== undefined &&
+    !isRspackHatchValue(rspack) &&
+    !(Array.isArray(rspack) && rspack.every(isRspackHatchValue))
+  ) {
+    diagnostics.push(sourceDiagnostic(
+      'AB4723',
+      'Tools rspack must be an Rspack config object, a mutator function, or an array of both.',
+      loaded.configPath,
+    ));
+  }
+  return diagnostics;
+};
+
 export const validateSource = (
   loaded: LoadedConfig,
   discovered: DiscoveredProject,
@@ -775,10 +911,13 @@ export const validateSource = (
   }
 
   diagnostics.push(...validateAssets(loaded));
+  diagnostics.push(...validateBin(loaded));
   diagnostics.push(...validateHooks(loaded, registry));
+  diagnostics.push(...validateLib(loaded));
   diagnostics.push(...validateMcp(loaded));
   diagnostics.push(...validateRuntime(loaded));
   diagnostics.push(...validateScripts(loaded, registry));
+  diagnostics.push(...validateTools(loaded));
 
   return diagnostics;
 };
@@ -812,6 +951,8 @@ export const validateModel = (
     ...(model.mcpApps ?? []),
     ...model.scripts,
     ...(model.assets ?? []),
+    ...(model.packageBuild?.bins ?? []),
+    ...(model.packageBuild?.lib === undefined ? [] : [model.packageBuild.lib]),
   ];
   for (const component of components) {
     const firstSource = ids.get(component.id);
diff --git a/packages/agent-bundle/src/core/project-context.ts b/packages/agent-bundle/src/core/project-context.ts
index eff011abc..502cdeb7d 100644
--- a/packages/agent-bundle/src/core/project-context.ts
+++ b/packages/agent-bundle/src/core/project-context.ts
@@ -115,6 +115,10 @@ const modelPathReferences = (model: NormalizedPlugin): readonly string[] => [
     ...(app.template === undefined ? [] : [app.template]),
   ]),
   ...(model.nativeHooks ?? []).flatMap((hook) => [hook.provenance.sourcePath, hook.source]),
+  ...(model.packageBuild?.bins ?? []).flatMap((bin) => [bin.provenance.sourcePath, bin.source]),
+  ...(model.packageBuild?.lib === undefined
+    ? []
+    : [model.packageBuild.lib.provenance.sourcePath, model.packageBuild.lib.source]),
 ];
 
 const assertModelPathsResolveInsideProject = (root: string, model: NormalizedPlugin): void => {
@@ -190,6 +194,27 @@ export const canonicalizeNormalizedModel = (
           source: canonicalCompilerPath(root, hook.source, 'Native hook source path'),
         })),
       }),
+    ...(detached.packageBuild === undefined
+      ? {}
+      : {
+        packageBuild: {
+          ...detached.packageBuild,
+          bins: detached.packageBuild.bins.map((bin) => ({
+            ...bin,
+            provenance: canonicalProvenance(root, bin.provenance),
+            source: canonicalCompilerPath(root, bin.source, 'Bin entry source path'),
+          })),
+          ...(detached.packageBuild.lib === undefined
+            ? {}
+            : {
+              lib: {
+                ...detached.packageBuild.lib,
+                provenance: canonicalProvenance(root, detached.packageBuild.lib.provenance),
+                source: canonicalCompilerPath(root, detached.packageBuild.lib.source, 'Lib entry source path'),
+              },
+            }),
+        },
+      }),
     scripts: detached.scripts.map((script) => ({
       ...script,
       provenance: canonicalProvenance(root, script.provenance),
diff --git a/packages/agent-bundle/src/core/types.ts b/packages/agent-bundle/src/core/types.ts
index 8595275cf..5b5105b76 100644
--- a/packages/agent-bundle/src/core/types.ts
+++ b/packages/agent-bundle/src/core/types.ts
@@ -1,3 +1,5 @@
+import type { EnvironmentConfig } from '@rsbuild/core';
+
 export interface AgentBundlePluginConfig {
   description?: string;
   name: string;
@@ -98,6 +100,52 @@ export interface AgentBundleScriptEntry {
   targets?: readonly string[];
 }
 
+/** One npm-facing CLI binary compiled into the framework-owned package build. */
+export interface AgentBundleBinEntry {
+  entry: string;
+}
+
+export type AgentBundleBinInput = string | AgentBundleBinEntry;
+
+/**
+ * npm-facing CLI binaries. Key = bin name, value = entry module. `false`
+ * disables the `src/cli.ts` convention. Each entry becomes a self-executing
+ * `dist/bin/<name>.js` bundle (shebang + executable bit) that `package.json`
+ * `bin` can reference directly.
+ */
+export type AgentBundleBinConfig = false | Readonly<Record<string, AgentBundleBinInput>>;
+
+/** The single-entry ESM+dts library profile of the framework-owned package build. */
+export interface AgentBundleLibEntry {
+  /** Emit bundled type declarations next to the library output. Defaults to true. */
+  dts?: boolean;
+  entry: string;
+}
+
+/**
+ * Optional npm library output. `false` disables the `src/index.ts`
+ * convention. The profile is deliberately thin (one ESM entry, node target,
+ * optional dts); packages needing a multi-format matrix have outgrown it and
+ * should use Rslib directly.
+ */
+export type AgentBundleLibConfig = false | string | AgentBundleLibEntry;
+
+/**
+ * THE bundler escape hatch. Both fragments are merged last-but-bounded into
+ * every bundler config agent-bundle synthesizes (artifact scripts, MCP
+ * entries, hooks, MCP Apps, and the package build), mirroring Rslib's
+ * user-config priority and Rspress's `builderConfig` position. The artifact
+ * invariant assertions still run after the merge, so a hatch value that
+ * breaks an artifact contract is a hard diagnostic, never a silent override.
+ * Consumers never need a second bundler config file.
+ */
+export interface AgentBundleToolsConfig {
+  /** Rsbuild environment-config fragment merged after the synthesized profile. */
+  rsbuild?: EnvironmentConfig;
+  /** Rspack config fragment or mutator(s), Rslib `tools.rspack` semantics, applied after `rsbuild`. */
+  rspack?: NonNullable<NonNullable<EnvironmentConfig['tools']>['rspack']>;
+}
+
 export type AgentBundleScriptInput = string | AgentBundleScriptEntry;
 
 export type AgentBundleHookInput =
@@ -116,8 +164,10 @@ export interface AgentBundleDevConfig {
 export interface AgentBundleConfig extends AgentBundleConfigExtensions {
   /** Project-level static files copied byte-for-byte into every target artifact under `assets/`. */
   assets?: string[];
+  bin?: AgentBundleBinConfig;
   dev?: AgentBundleDevConfig;
   hooks?: Partial<Record<CanonicalHookEvent, AgentBundleHookInput>>;
+  lib?: AgentBundleLibConfig;
   marketplace?: boolean;
   mcp?: AgentBundleMcpConfig;
   plugin: AgentBundlePluginConfig;
@@ -125,6 +175,7 @@ export interface AgentBundleConfig extends AgentBundleConfigExtensions {
   scripts?: Readonly<Record<string, AgentBundleScriptInput>>;
   skills?: string[];
   targets?: string[];
+  tools?: AgentBundleToolsConfig;
   [key: string]: unknown;
 }
 
@@ -221,6 +272,32 @@ export interface NormalizedScript {
   readonly targets: readonly string[];
 }
 
+/** One normalized npm-facing CLI binary in the framework-owned package build. */
+export interface NormalizedBinEntry {
+  readonly id: string;
+  readonly name: string;
+  readonly provenance: SourceProvenance;
+  readonly source: string;
+}
+
+/** The normalized single-entry ESM+dts library output of the package build. */
+export interface NormalizedLibEntry {
+  readonly dts: boolean;
+  readonly id: string;
+  /** The output stem: `<name>.js` (+ `<name>.d.ts`) under the package output directory. */
+  readonly name: string;
+  readonly provenance: SourceProvenance;
+  readonly source: string;
+}
+
+/** The node-consumable package build agent-bundle owns alongside target artifacts. */
+export interface NormalizedPackageBuild {
+  readonly bins: readonly NormalizedBinEntry[];
+  readonly lib?: NormalizedLibEntry;
+  /** POSIX path of the package output directory relative to the project root. */
+  readonly outputDir: string;
+}
+
 export interface NormalizedHook {
   readonly event: CanonicalHookEvent;
   readonly id: string;
@@ -274,6 +351,12 @@ export interface NormalizedPlugin {
    */
   readonly mcpApps?: readonly NormalizedMcpApp[];
   readonly nativeHooks?: readonly NormalizedNativeHook[];
+  /**
+   * The framework-owned npm package build (bin + lib outputs). Present only
+   * when configured or discovered by convention; optional so hand-constructed
+   * models predating the package build stay valid.
+   */
+  readonly packageBuild?: NormalizedPackageBuild;
   /** The generated-executable runtime floor selected during normalization. */
   readonly runtime: NormalizedRuntime;
   readonly scripts: readonly NormalizedScript[];
diff --git a/packages/agent-bundle/src/dev/artifacts/artifact-service.ts b/packages/agent-bundle/src/dev/artifacts/artifact-service.ts
index bdd8387bb..619ffe2e2 100644
--- a/packages/agent-bundle/src/dev/artifacts/artifact-service.ts
+++ b/packages/agent-bundle/src/dev/artifacts/artifact-service.ts
@@ -210,6 +210,7 @@ export class ArtifactService {
         projectContext,
         projectRoot: prepared.root,
         registry: prepared.registry,
+        ...(prepared.tools === undefined ? {} : { tools: prepared.tools }),
       });
       const firstValidation = this.#validateArtifact === undefined
         ? await validateArtifactWithSnapshot({
diff --git a/packages/agent-bundle/src/dev/project-service.ts b/packages/agent-bundle/src/dev/project-service.ts
index 4d4e513aa..f651c5b12 100644
--- a/packages/agent-bundle/src/dev/project-service.ts
+++ b/packages/agent-bundle/src/dev/project-service.ts
@@ -22,6 +22,7 @@ import type {
   AgentBundleConfig,
   AgentBundleDevConfig,
   AgentBundleDevRuntimeConfig,
+  AgentBundleToolsConfig,
   NormalizedMcpApp,
   NormalizedMcpServer,
   NormalizedPlugin,
@@ -60,6 +61,8 @@ export interface PreparedProject {
   readonly root: string;
   readonly snapshotSource?: () => Promise<ProjectSourceSnapshot>;
   readonly source: SourceStatus;
+  /** The consumer bundler escape hatch, passed through for build lowering. */
+  readonly tools?: AgentBundleToolsConfig;
 }
 
 export type { ProjectSourceInput, ProjectSourceSnapshotInput } from '../core/project-context.ts';
@@ -489,6 +492,7 @@ const preparedProject = (
   devRuntime?: DevRuntimePreparedProject,
   devRuntimeDiagnostic?: Diagnostic,
   devAgentApiEnabled?: boolean,
+  tools?: AgentBundleToolsConfig,
 ): PreparedProject => Object.freeze({
   configPath,
   ...(devAgentApiEnabled === true ? { devAgentApiEnabled } : {}),
@@ -501,6 +505,7 @@ const preparedProject = (
   registry,
   root,
   source,
+  ...(tools === undefined ? {} : { tools }),
 });
 
 export type ProjectDiagnosticCode = 'AB4500' | 'AB7000' | 'AB7001' | 'AB7002' | 'AB7003' | 'AB7004';
@@ -769,6 +774,10 @@ export class ProjectService {
     if (supplementalMetadataFailure) {
       devRuntimeDiagnostic = sourceDiagnostic('Development runtime MCP App metadata must contain only finite JSON data.', loaded.configPath);
     }
+    const toolsValue = loaded.config.tools;
+    const tools = typeof toolsValue === 'object' && toolsValue !== null && !Array.isArray(toolsValue)
+      ? toolsValue as AgentBundleToolsConfig
+      : undefined;
     return preparedProject(
       loaded.configPath,
       snapshot,
@@ -782,6 +791,7 @@ export class ProjectService {
       devRuntime,
       devRuntimeDiagnostic,
       devAgentApiEnabled,
+      tools,
     );
   }
 }
diff --git a/packages/agent-bundle/src/mcp-entry.ts b/packages/agent-bundle/src/mcp-entry.ts
new file mode 100644
index 000000000..70f354d7c
--- /dev/null
+++ b/packages/agent-bundle/src/mcp-entry.ts
@@ -0,0 +1,272 @@
+/**
+ * The framework-owned stdio MCP entry shell: console-to-stderr protection,
+ * signal handling (SIGINT exits 130, SIGTERM exits 143), stdin-EOF detection
+ * (exit 0 so the client can respawn), a bounded shutdown race against wedged
+ * transports, and heartbeat/activity logging. `agent-bundle build` wraps
+ * every factory-exporting MCP server entry in this lifecycle, and consumers
+ * can import it directly for hand-rolled entries.
+ *
+ * Every value in this module is injectable through structural option types so
+ * the lifecycle is testable with plain-object harnesses; the real
+ * `StdioServerTransport` and MCP server instances satisfy these shapes.
+ */
+
+const defaultHeartbeatIntervalMs = 5 * 60_000;
+const defaultActivityThrottleMs = 60_000;
+const defaultShutdownTimeoutMs = 5_000;
+const defaultHeartbeatName = 'agent-bundle';
+
+type StdoutWrite = typeof process.stdout.write;
+
+export interface StdoutProtocolGuard {
+  /** Hands stdout back to the protocol transport; console.* keeps writing to stderr. */
+  readonly restoreProtocolStdout: () => void;
+}
+
+/**
+ * stdout carries JSON-RPC framing on a stdio server: a stray `console.log`
+ * (or direct `process.stdout.write`) from any imported module would corrupt
+ * the protocol stream. Install this guard before evaluating server modules,
+ * then call `restoreProtocolStdout()` right before serving. Console methods
+ * stay on stderr forever; only the raw `process.stdout.write` is restored
+ * for protocol frames.
+ */
+export const redirectConsoleToStderr = (): StdoutProtocolGuard => {
+  const originalStdoutWrite: StdoutWrite = process.stdout.write.bind(process.stdout) as StdoutWrite;
+  const stderrConsole = new console.Console({ stderr: process.stderr, stdout: process.stderr });
+  const methods = ['debug', 'dir', 'error', 'info', 'log', 'trace', 'warn'] as const;
+  for (const method of methods) {
+    console[method] = stderrConsole[method].bind(stderrConsole) as never;
+  }
+  process.stdout.write = ((chunk: never, encoding?: never, callback?: never) =>
+    process.stderr.write(chunk, encoding, callback)) as StdoutWrite;
+  return Object.freeze({
+    restoreProtocolStdout: (): void => {
+      process.stdout.write = originalStdoutWrite;
+    },
+  });
+};
+
+export interface HeartbeatOptions {
+  readonly activityThrottleMs?: number;
+  readonly intervalMs?: number;
+  /** Log prefix — pass the MCP server name so multi-server logs stay attributable. */
+  readonly name?: string;
+  readonly writeLine: (line: string) => void;
+}
+
+export interface Heartbeat {
+  readonly log: (reason: string) => void;
+  readonly noteActivity: () => void;
+  readonly stop: () => void;
+}
+
+/**
+ * Lightweight liveness logging, stderr only — stdout is the protocol channel.
+ * Logs on a slow interval plus on request activity (throttled), so a silently
+ * stalled server is visible in the client's logs without spamming them.
+ */
+export const createHeartbeat = ({
+  activityThrottleMs = defaultActivityThrottleMs,
+  intervalMs = defaultHeartbeatIntervalMs,
+  name = defaultHeartbeatName,
+  writeLine,
+}: HeartbeatOptions): Heartbeat => {
+  const startedAt = Date.now();
+  let lastActivityAt = startedAt;
+  let lastActivityLogAt = 0;
+
+  const log = (reason: string): void => {
+    const uptimeSeconds = Math.round((Date.now() - startedAt) / 1000);
+    const idleSeconds = Math.round((Date.now() - lastActivityAt) / 1000);
+    writeLine(`[${name}] stdio heartbeat (${reason}) pid=${process.pid} uptime=${uptimeSeconds}s idle=${idleSeconds}s`);
+  };
+
+  const timer = setInterval(() => log('interval'), intervalMs);
+  timer.unref?.();
+
+  return Object.freeze({
+    log,
+    noteActivity: (): void => {
+      lastActivityAt = Date.now();
+      if (lastActivityAt - lastActivityLogAt >= activityThrottleMs) {
+        lastActivityLogAt = lastActivityAt;
+        log('activity');
+      }
+    },
+    stop: (): void => clearInterval(timer),
+  });
+};
+
+export interface LifecycleTransport {
+  close(): Promise<void> | void;
+  onclose?: (() => void) | undefined;
+  onmessage?: ((message: never, extra?: never) => void) | undefined;
+}
+
+export interface LifecycleServer {
+  close(): Promise<void> | void;
+  connect(transport: never): Promise<void>;
+}
+
+export interface LifecycleStdin {
+  off?(event: 'end', listener: () => void): unknown;
+  once?(event: 'end', listener: () => void): unknown;
+}
+
+export interface LifecycleSignalSource {
+  off(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+  on(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+
+export interface RunStdioServerOptions {
+  readonly activityThrottleMs?: number;
+  readonly exit?: (code: number) => void;
+  /** Disables interval/activity heartbeat logging; shutdown behavior is unaffected. */
+  readonly heartbeat?: boolean;
+  readonly heartbeatIntervalMs?: number;
+  readonly server: LifecycleServer;
+  /** Heartbeat log prefix — pass the MCP server name. */
+  readonly serverName?: string;
+  readonly shutdownTimeoutMs?: number;
+  readonly signals?: LifecycleSignalSource;
+  readonly stdin?: LifecycleStdin;
+  readonly transport: LifecycleTransport;
+  readonly writeLine?: (line: string) => void;
+}
+
+export interface StdioServerHandle {
+  readonly heartbeat: Heartbeat;
+  readonly shutdown: (exitCode?: number) => Promise<void>;
+}
+
+/**
+ * Owns the stdio server lifecycle: SIGINT exits 130, SIGTERM exits 143,
+ * stdin EOF and transport close exit 0 promptly (so the client can respawn),
+ * and a wedged transport/server close never hangs shutdown — the closes race
+ * a bounded timer and the process exits unconditionally once it fires.
+ */
+export const runStdioServer = async ({
+  activityThrottleMs,
+  exit = (code) => process.exit(code),
+  heartbeat: heartbeatEnabled = true,
+  heartbeatIntervalMs,
+  server,
+  serverName,
+  shutdownTimeoutMs = defaultShutdownTimeoutMs,
+  signals = process,
+  stdin = process.stdin,
+  transport,
+  writeLine = (line) => void process.stderr.write(`${line}\n`),
+}: RunStdioServerOptions): Promise<StdioServerHandle> => {
+  const heartbeat = createHeartbeat({
+    ...(activityThrottleMs === undefined ? {} : { activityThrottleMs }),
+    ...(heartbeatIntervalMs === undefined ? {} : { intervalMs: heartbeatIntervalMs }),
+    ...(serverName === undefined ? {} : { name: serverName }),
+    writeLine: heartbeatEnabled ? writeLine : () => undefined,
+  });
+
+  // Safety net to keep the event loop alive if the transport stalls without
+  // closing. Unref'd so a dead pipe never keeps the process alive — once
+  // stdin/transport close we exit promptly and let the client respawn.
+  const keepalive = setInterval(() => undefined, 60_000);
+  keepalive.unref?.();
+
+  let shuttingDown = false;
+  const shutdown = async (exitCode = 0): Promise<void> => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+    signals.off('SIGINT', handleSigint);
+    signals.off('SIGTERM', handleSigterm);
+    stdin.off?.('end', handleStdinEnd);
+    clearInterval(keepalive);
+    heartbeat.stop();
+    await Promise.race([
+      Promise.allSettled([
+        Promise.resolve().then(() => transport.close()),
+        Promise.resolve().then(() => server.close()),
+      ]),
+      new Promise((resolve) => setTimeout(resolve, shutdownTimeoutMs)),
+    ]);
+    exit(exitCode);
+  };
+
+  const handleSigint = (): void => {
+    void shutdown(130);
+  };
+  const handleSigterm = (): void => {
+    void shutdown(143);
+  };
+  const handleStdinEnd = (): void => {
+    void shutdown(0);
+  };
+
+  signals.on('SIGINT', handleSigint);
+  signals.on('SIGTERM', handleSigterm);
+  stdin.once?.('end', handleStdinEnd);
+
+  transport.onclose = () => {
+    void shutdown(0);
+  };
+
+  await server.connect(transport as never);
+
+  // server.connect installs transport.onmessage; wrap it so request/tool-call
+  // activity feeds the heartbeat.
+  const originalOnMessage = transport.onmessage;
+  transport.onmessage = (message, extra) => {
+    heartbeat.noteActivity();
+    originalOnMessage?.(message, extra);
+  };
+
+  return Object.freeze({ heartbeat, shutdown });
+};
+
+/** The factory shape a generated stdio entry module default-exports. */
+export type StdioMcpServerFactory = () => LifecycleServer | Promise<LifecycleServer>;
+
+export interface GeneratedStdioMcpEntryModule {
+  readonly default?: unknown;
+}
+
+export interface RunGeneratedStdioMcpEntryOptions {
+  /**
+   * Loads the consumer entry module. Deferred so the console guard is active
+   * before any consumer module side effect can print to the protocol channel.
+   */
+  readonly loadEntry: () => Promise<GeneratedStdioMcpEntryModule>;
+  /** Test seam mirroring {@link RunStdioServerOptions}. */
+  readonly lifecycle?: Omit<RunStdioServerOptions, 'server' | 'serverName' | 'transport'>;
+  readonly serverName: string;
+}
+
+/**
+ * The body of every generated stdio MCP entry: install the stdout guard,
+ * evaluate the consumer module, build the server from its default-exported
+ * factory, hand raw stdout back for protocol frames, and serve under the
+ * managed lifecycle.
+ */
+export const runGeneratedStdioMcpEntry = async (
+  options: RunGeneratedStdioMcpEntryOptions,
+): Promise<StdioServerHandle> => {
+  const guard = redirectConsoleToStderr();
+  const entry = await options.loadEntry();
+  const factory = entry.default;
+  if (typeof factory !== 'function') {
+    throw new TypeError(
+      `Generated stdio entry for MCP server ${JSON.stringify(options.serverName)} must default-export a server factory.`,
+    );
+  }
+  const server = await (factory as StdioMcpServerFactory)();
+  // Deferred so the SDK evaluates under the guard, after the consumer module:
+  // a static import would hoist SDK evaluation ahead of the guard install.
+  const { StdioServerTransport } = await import('@modelcontextprotocol/server/stdio');
+  guard.restoreProtocolStdout();
+  const transport = new StdioServerTransport();
+  return runStdioServer({
+    ...options.lifecycle,
+    server,
+    serverName: options.serverName,
+    transport: transport as LifecycleTransport,
+  });
+};
diff --git a/packages/agent-bundle/src/services/mcp-run.ts b/packages/agent-bundle/src/services/mcp-run.ts
new file mode 100644
index 000000000..b2254820a
--- /dev/null
+++ b/packages/agent-bundle/src/services/mcp-run.ts
@@ -0,0 +1,147 @@
+import { spawn, type ChildProcess } from 'node:child_process';
+import { mkdir, readFile } from 'node:fs/promises';
+import { isAbsolute, resolve } from 'node:path';
+
+import { createDefaultRegistry, type TargetRegistry } from '../adapters/registry.ts';
+import { validateArtifact } from '../build/validate-artifact.ts';
+import { DiagnosticError } from '../core/diagnostics.ts';
+import { assertInside, joinArtifact } from '../core/paths.ts';
+import { parseJsonWithoutDuplicateKeys } from '../core/strict-json.ts';
+import { resolveMcpPathTokens } from './mcp-path-tokens.ts';
+import { readTargetMcpServer, type ModernMcpStdioServer } from './mcp-runtime.ts';
+
+/**
+ * The foreground MCP server runner behind `agent-bundle mcp run`: it resolves
+ * the content-hashed generated entry out of the built target manifest — the
+ * job consumers previously solved with bash launchers parsing `mcp.json` —
+ * and executes it with inherited stdio until the server exits.
+ */
+
+export interface ResolvedMcpStdioLaunch {
+  readonly args: readonly string[];
+  readonly command: string;
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string>>;
+}
+
+export interface ResolveMcpStdioLaunchOptions {
+  readonly artifact: string;
+  /** Durable per-server state root replacing the plugin-data path token. */
+  readonly pluginDataRoot: string;
+  readonly registry?: TargetRegistry;
+  readonly server: string;
+  readonly target: string;
+  readonly workspaceRoot: string;
+}
+
+const resolveContained = (root: string, path: string): string =>
+  isAbsolute(path) ? path : assertInside(root, resolve(root, path));
+
+export const resolveMcpStdioLaunch = async (
+  options: ResolveMcpStdioLaunchOptions,
+): Promise<ResolvedMcpStdioLaunch> => {
+  if (options.server.trim().length === 0) {
+    throw new Error('MCP server name must be nonempty.');
+  }
+  const registry = options.registry ?? createDefaultRegistry();
+  if (!registry.has(options.target) || !registry.supports(options.target, 'mcp')) {
+    throw new Error(`Unsupported MCP target ${JSON.stringify(options.target)}.`);
+  }
+  const runtime = registry.mcpRuntime(options.target);
+  if (runtime === undefined) {
+    throw new Error(`Unsupported MCP target ${JSON.stringify(options.target)}.`);
+  }
+
+  const artifact = resolve(options.artifact);
+  const diagnostics = await validateArtifact({ artifactRoot: artifact, registry });
+  const errors = diagnostics.filter((diagnostic) => diagnostic.severity === 'error');
+  if (errors.length > 0) throw new DiagnosticError(errors);
+
+  const targetRoot = joinArtifact(artifact, options.target);
+  const manifestPath = joinArtifact(targetRoot, runtime.manifestPath);
+  let document: unknown;
+  try {
+    document = parseJsonWithoutDuplicateKeys(await readFile(manifestPath, 'utf8'));
+  } catch {
+    throw new Error(`MCP manifest for target ${JSON.stringify(options.target)} is not valid JSON.`);
+  }
+  const result = readTargetMcpServer(runtime, document, options.server);
+  if (result.status === 'missing') {
+    throw new Error(`Expected exactly one ${options.target} MCP server matching ${JSON.stringify(options.server)}.`);
+  }
+  if (result.status === 'invalid') {
+    throw new Error(`MCP server ${JSON.stringify(options.server)} in target ${JSON.stringify(options.target)} is invalid.`);
+  }
+
+  const resolved = resolveMcpPathTokens({
+    roots: {
+      pluginData: resolve(options.pluginDataRoot),
+      pluginRoot: targetRoot,
+      workspaceRoot: resolve(options.workspaceRoot),
+    },
+    runtime,
+    server: result.server,
+    target: options.target,
+  });
+  if (resolved.kind !== 'stdio') {
+    throw new Error(`MCP server ${JSON.stringify(options.server)} is not a stdio server; only stdio servers can run in the foreground.`);
+  }
+  const stdio = resolved as ModernMcpStdioServer;
+  return Object.freeze({
+    args: Object.freeze([...stdio.args]),
+    command: stdio.command,
+    cwd: stdio.cwd === undefined ? targetRoot : resolveContained(targetRoot, stdio.cwd),
+    env: Object.freeze({ ...stdio.env }),
+  });
+};
+
+export interface RunMcpForegroundOptions extends ResolveMcpStdioLaunchOptions {
+  /** Injectable only to make foreground process behavior deterministic in tests. */
+  readonly spawnProcess?: (
+    command: string,
+    args: readonly string[],
+    options: { readonly cwd: string; readonly env: Readonly<Record<string, string>>; readonly stdio: 'inherit' },
+  ) => ChildProcess;
+}
+
+/**
+ * Resolves the server's generated entry from the built artifact and runs it
+ * in the foreground with inherited stdio. SIGINT/SIGTERM forward to the
+ * child; the child's exit code (or 128 + signal number) is returned.
+ */
+export const runMcpForeground = async (options: RunMcpForegroundOptions): Promise<number> => {
+  const launch = await resolveMcpStdioLaunch(options);
+  await mkdir(resolve(options.pluginDataRoot), { recursive: true });
+  const inheritedEnv = Object.fromEntries(
+    Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+  const spawnProcess = options.spawnProcess ?? ((command, args, spawnOptions) => spawn(command, [...args], spawnOptions));
+  const child = spawnProcess(launch.command, launch.args, {
+    cwd: launch.cwd,
+    env: { ...inheritedEnv, ...launch.env },
+    stdio: 'inherit',
+  });
+
+  const forward = (signal: NodeJS.Signals): void => {
+    child.kill(signal);
+  };
+  const onSigint = (): void => forward('SIGINT');
+  const onSigterm = (): void => forward('SIGTERM');
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', onSigterm);
+  try {
+    return await new Promise<number>((resolveExit, rejectExit) => {
+      child.once('error', rejectExit);
+      child.once('exit', (code, signal) => {
+        if (code !== null) {
+          resolveExit(code);
+          return;
+        }
+        resolveExit(signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+      });
+    });
+  } finally {
+    process.off('SIGINT', onSigint);
+    process.off('SIGTERM', onSigterm);
+  }
+};
diff --git a/packages/agent-bundle/tests/entry-shell.test.ts b/packages/agent-bundle/tests/entry-shell.test.ts
new file mode 100644
index 000000000..7e887fa64
--- /dev/null
+++ b/packages/agent-bundle/tests/entry-shell.test.ts
@@ -0,0 +1,87 @@
+import { access } from 'node:fs/promises';
+
+import { describe, expect, it } from '@rstest/core';
+
+import { scanEntryExportsSource, stripCommentsAndStrings } from '../src/build/entry-exports.ts';
+import {
+  generatedExecutableEntrySource,
+  generatedStdioMcpEntrySource,
+  mcpEntryRuntimePath,
+  mcpEntryRuntimeSpecifier,
+} from '../src/build/entry-shell.ts';
+
+describe('entry export scanning', () => {
+  it('detects declaration-form main exports', () => {
+    expect(scanEntryExportsSource('export const main = async () => 0;')).toEqual({
+      hasDefaultExport: false,
+      hasMainExport: true,
+    });
+    expect(scanEntryExportsSource('export async function main(argv) { return 0; }').hasMainExport).toBe(true);
+    expect(scanEntryExportsSource('export function main() {}').hasMainExport).toBe(true);
+    expect(scanEntryExportsSource('export let main = 1;\n').hasMainExport).toBe(true);
+  });
+
+  it('detects brace-clause exports with renames', () => {
+    expect(scanEntryExportsSource('const run = 1; export { run as main };').hasMainExport).toBe(true);
+    expect(scanEntryExportsSource('const main = 1; export { main };').hasMainExport).toBe(true);
+    expect(scanEntryExportsSource('const main = 1; export { main as other };').hasMainExport).toBe(false);
+    expect(scanEntryExportsSource("export { factory as default } from './server.ts';").hasDefaultExport).toBe(true);
+  });
+
+  it('detects default exports and ignores type-only clauses', () => {
+    expect(scanEntryExportsSource('export default () => ({});').hasDefaultExport).toBe(true);
+    expect(scanEntryExportsSource('const f = 1;\nexport default f;').hasDefaultExport).toBe(true);
+    expect(scanEntryExportsSource("export type { Thing as default } from './types.ts';").hasDefaultExport).toBe(false);
+    expect(scanEntryExportsSource('export type { main } from "./types.ts";').hasMainExport).toBe(false);
+  });
+
+  it('never matches inside comments, strings, or template literals', () => {
+    expect(scanEntryExportsSource('// export default nothing\nconst a = 1;').hasDefaultExport).toBe(false);
+    expect(scanEntryExportsSource('/* export const main = 1 */ const a = 1;').hasMainExport).toBe(false);
+    expect(scanEntryExportsSource("const s = 'export default x';").hasDefaultExport).toBe(false);
+    expect(scanEntryExportsSource('const s = `export const main = ${1}`;').hasMainExport).toBe(false);
+    expect(scanEntryExportsSource('const t = `a ${`b ${1} export default c`} d`;').hasDefaultExport).toBe(false);
+  });
+
+  it('survives regex literals containing slashes', () => {
+    const source = "const re = /https:\\/\\//u; export default re;";
+    expect(scanEntryExportsSource(source).hasDefaultExport).toBe(true);
+    expect(stripCommentsAndStrings('const division = a / b / c; export const main = 1;')).toContain('export const main');
+  });
+
+  it('handles TypeScript syntax the JS lexers cannot parse', () => {
+    const source = [
+      "import type { Widget } from './types.ts';",
+      'export interface CliOptions { readonly write?: (value: string) => void }',
+      'export const main = async (argv: readonly string[]): Promise<void> => {},',
+    ].join('\n');
+    expect(scanEntryExportsSource(source)).toEqual({ hasDefaultExport: false, hasMainExport: true });
+  });
+});
+
+describe('generated entry templates', () => {
+  it('locates the on-disk mcp-entry runtime module for bundler aliasing', async () => {
+    const path = mcpEntryRuntimePath();
+    await expect(access(path)).resolves.toBeUndefined();
+    expect(path.endsWith('mcp-entry.ts') || path.endsWith('mcp-entry.js')).toBe(true);
+  });
+
+  it('generates a stdio entry that defers the consumer import behind the lifecycle', () => {
+    const source = generatedStdioMcpEntrySource({ entrySource: '/proj/src/mcp/curator.ts', serverName: 'curator' });
+    expect(source).toContain(`from ${JSON.stringify(mcpEntryRuntimeSpecifier)}`);
+    expect(source).toContain('loadEntry: () => import("/proj/src/mcp/curator.ts")');
+    expect(source).toContain('serverName: "curator"');
+    // The consumer module must never be statically imported: the console
+    // guard has to activate before its side effects can reach stdout.
+    expect(source).not.toMatch(/^import[^\n]*curator\.ts/mu);
+  });
+
+  it('generates a process envelope that adopts numeric exit codes', () => {
+    const source = generatedExecutableEntrySource({ entrySource: '/proj/src/cli.ts', exportName: 'main' });
+    expect(source).toContain('import * as entry from "/proj/src/cli.ts"');
+    expect(source).toContain('entry["main"]');
+    expect(source).toContain('await main(process.argv.slice(2))');
+    expect(source).toContain("if (typeof code === 'number') process.exitCode = code;");
+    expect(generatedExecutableEntrySource({ entrySource: '/e.ts', exportName: 'default' })).toContain('entry["default"]');
+  });
+});
diff --git a/packages/agent-bundle/tests/mcp-entry.test.ts b/packages/agent-bundle/tests/mcp-entry.test.ts
new file mode 100644
index 000000000..9323cb4b7
--- /dev/null
+++ b/packages/agent-bundle/tests/mcp-entry.test.ts
@@ -0,0 +1,309 @@
+import { describe, expect, it } from '@rstest/core';
+
+import {
+  createHeartbeat,
+  redirectConsoleToStderr,
+  runGeneratedStdioMcpEntry,
+  runStdioServer,
+  type LifecycleServer,
+  type LifecycleSignalSource,
+  type LifecycleStdin,
+  type LifecycleTransport,
+} from '../src/mcp-entry.ts';
+
+const wait = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+interface FakeTransport extends LifecycleTransport {
+  readonly closed: () => number;
+}
+
+const fakeTransport = (close: () => Promise<void> | void = () => undefined): FakeTransport => {
+  let closed = 0;
+  return {
+    close: () => {
+      closed += 1;
+      return close();
+    },
+    closed: () => closed,
+    onclose: undefined,
+    onmessage: undefined,
+  };
+};
+
+interface FakeServer extends LifecycleServer {
+  readonly closed: () => number;
+  readonly connected: () => readonly LifecycleTransport[];
+}
+
+const fakeServer = (): FakeServer => {
+  const connected: LifecycleTransport[] = [];
+  let closed = 0;
+  return {
+    close: () => {
+      closed += 1;
+    },
+    closed: () => closed,
+    connect: async (transport) => {
+      const lifecycleTransport = transport as LifecycleTransport;
+      // The real SDK installs onmessage during connect; the lifecycle wraps it.
+      lifecycleTransport.onmessage = () => undefined;
+      connected.push(lifecycleTransport);
+    },
+    connected: () => connected,
+  };
+};
+
+class FakeSignals implements LifecycleSignalSource {
+  readonly #listeners = new Map<'SIGINT' | 'SIGTERM', Set<() => void>>();
+
+  emit(signal: 'SIGINT' | 'SIGTERM'): void {
+    for (const listener of this.#listeners.get(signal) ?? []) listener();
+  }
+
+  listenerCount(signal: 'SIGINT' | 'SIGTERM'): number {
+    return this.#listeners.get(signal)?.size ?? 0;
+  }
+
+  off(signal: 'SIGINT' | 'SIGTERM', listener: () => void): void {
+    this.#listeners.get(signal)?.delete(listener);
+  }
+
+  on(signal: 'SIGINT' | 'SIGTERM', listener: () => void): void {
+    const listeners = this.#listeners.get(signal) ?? new Set<() => void>();
+    listeners.add(listener);
+    this.#listeners.set(signal, listeners);
+  }
+}
+
+interface FakeStdin extends LifecycleStdin {
+  emitEnd(): void;
+  listenerCount(): number;
+}
+
+const fakeStdin = (): FakeStdin => {
+  const listeners = new Set<() => void>();
+  return {
+    emitEnd: () => {
+      for (const listener of [...listeners]) listener();
+    },
+    listenerCount: () => listeners.size,
+    off: (_event, listener) => listeners.delete(listener),
+    once: (_event, listener) => listeners.add(listener),
+  };
+};
+
+interface Harness {
+  readonly exitCodes: number[];
+  readonly lines: string[];
+  readonly server: FakeServer;
+  readonly signals: FakeSignals;
+  readonly stdin: FakeStdin;
+  readonly transport: FakeTransport;
+}
+
+const startLifecycle = async (
+  overrides: Partial<Parameters<typeof runStdioServer>[0]> = {},
+): Promise<Harness & { readonly handle: Awaited<ReturnType<typeof runStdioServer>> }> => {
+  const harness: Harness = {
+    exitCodes: [],
+    lines: [],
+    server: fakeServer(),
+    signals: new FakeSignals(),
+    stdin: fakeStdin(),
+    transport: fakeTransport(),
+  };
+  const handle = await runStdioServer({
+    exit: (code) => harness.exitCodes.push(code),
+    heartbeat: false,
+    server: harness.server,
+    shutdownTimeoutMs: 100,
+    signals: harness.signals,
+    stdin: harness.stdin,
+    transport: harness.transport,
+    writeLine: (line) => harness.lines.push(line),
+    ...overrides,
+  });
+  return { ...harness, handle };
+};
+
+describe('runStdioServer lifecycle', () => {
+  it('connects the server and wraps onmessage for activity tracking', async () => {
+    const { handle, server, transport } = await startLifecycle();
+    expect(server.connected()).toEqual([transport]);
+    expect(typeof transport.onmessage).toBe('function');
+    await handle.shutdown();
+  });
+
+  it('exits 130 on SIGINT and unregisters every listener', async () => {
+    const { exitCodes, server, signals, stdin, transport } = await startLifecycle();
+    expect(signals.listenerCount('SIGINT')).toBe(1);
+    signals.emit('SIGINT');
+    await wait(10);
+    expect(exitCodes).toEqual([130]);
+    expect(transport.closed()).toBe(1);
+    expect(server.closed()).toBe(1);
+    expect(signals.listenerCount('SIGINT')).toBe(0);
+    expect(signals.listenerCount('SIGTERM')).toBe(0);
+    expect(stdin.listenerCount()).toBe(0);
+  });
+
+  it('exits 143 on SIGTERM', async () => {
+    const { exitCodes, signals } = await startLifecycle();
+    signals.emit('SIGTERM');
+    await wait(10);
+    expect(exitCodes).toEqual([143]);
+  });
+
+  it('exits 0 on stdin EOF so the client can respawn', async () => {
+    const { exitCodes, stdin } = await startLifecycle();
+    stdin.emitEnd();
+    await wait(10);
+    expect(exitCodes).toEqual([0]);
+  });
+
+  it('exits 0 when the transport closes underneath the server', async () => {
+    const { exitCodes, transport } = await startLifecycle();
+    transport.onclose?.();
+    await wait(10);
+    expect(exitCodes).toEqual([0]);
+  });
+
+  it('races a wedged transport close against the bounded shutdown timer', async () => {
+    const wedged = fakeTransport(() => new Promise<void>(() => undefined));
+    const { exitCodes, handle } = await startLifecycle({ shutdownTimeoutMs: 30, transport: wedged });
+    const started = Date.now();
+    await handle.shutdown(9);
+    expect(Date.now() - started).toBeLessThan(5_000);
+    expect(exitCodes).toEqual([9]);
+  });
+
+  it('runs shutdown exactly once across concurrent triggers', async () => {
+    const { exitCodes, handle, server, signals, stdin } = await startLifecycle();
+    signals.emit('SIGINT');
+    signals.emit('SIGTERM');
+    stdin.emitEnd();
+    await handle.shutdown(0);
+    await wait(10);
+    expect(exitCodes).toEqual([130]);
+    expect(server.closed()).toBe(1);
+  });
+});
+
+describe('heartbeat', () => {
+  it('logs on the interval and throttles activity logging', async () => {
+    const lines: string[] = [];
+    const heartbeat = createHeartbeat({
+      activityThrottleMs: 10_000,
+      intervalMs: 20,
+      name: 'curator',
+      writeLine: (line) => lines.push(line),
+    });
+    heartbeat.noteActivity();
+    heartbeat.noteActivity();
+    heartbeat.noteActivity();
+    await wait(70);
+    heartbeat.stop();
+    const activity = lines.filter((line) => line.includes('(activity)'));
+    const interval = lines.filter((line) => line.includes('(interval)'));
+    expect(activity).toHaveLength(1);
+    expect(interval.length).toBeGreaterThanOrEqual(2);
+    expect(lines[0]).toContain('[curator] stdio heartbeat');
+  });
+
+  it('feeds request activity from the wrapped transport onmessage', async () => {
+    const lines: string[] = [];
+    const { handle, transport } = await startLifecycle({
+      heartbeat: true,
+      heartbeatIntervalMs: 60_000,
+      writeLine: (line) => lines.push(line),
+    });
+    (transport.onmessage as (message: never) => void)(undefined as never);
+    expect(lines.some((line) => line.includes('(activity)'))).toBe(true);
+    await handle.shutdown();
+  });
+});
+
+describe('stdout protocol guard', () => {
+  it('redirects console and raw stdout to stderr, then restores stdout only', () => {
+    const originalConsole = { error: console.error, log: console.log };
+    const originalStdoutWrite = process.stdout.write;
+    const originalStderrWrite = process.stderr.write;
+    const stdoutChunks: string[] = [];
+    const stderrChunks: string[] = [];
+    process.stdout.write = ((chunk: string | Uint8Array) => {
+      stdoutChunks.push(String(chunk));
+      return true;
+    }) as typeof process.stdout.write;
+    process.stderr.write = ((chunk: string | Uint8Array) => {
+      stderrChunks.push(String(chunk));
+      return true;
+    }) as typeof process.stderr.write;
+
+    try {
+      const guard = redirectConsoleToStderr();
+      console.log('module side effect');
+      process.stdout.write('stray raw write');
+      expect(stdoutChunks).toEqual([]);
+      expect(stderrChunks.join('')).toContain('module side effect');
+      expect(stderrChunks.join('')).toContain('stray raw write');
+
+      guard.restoreProtocolStdout();
+      process.stdout.write('{"jsonrpc":"2.0"}');
+      console.log('still stderr');
+      expect(stdoutChunks).toEqual(['{"jsonrpc":"2.0"}']);
+      expect(stderrChunks.join('')).toContain('still stderr');
+    } finally {
+      process.stdout.write = originalStdoutWrite;
+      process.stderr.write = originalStderrWrite;
+      console.error = originalConsole.error;
+      console.log = originalConsole.log;
+    }
+  });
+});
+
+describe('runGeneratedStdioMcpEntry', () => {
+  const withGuardedStreams = async (run: () => Promise<void>): Promise<void> => {
+    const originalConsole = {
+      debug: console.debug, dir: console.dir, error: console.error, info: console.info,
+      log: console.log, trace: console.trace, warn: console.warn,
+    };
+    const originalStdoutWrite = process.stdout.write;
+    try {
+      await run();
+    } finally {
+      process.stdout.write = originalStdoutWrite;
+      Object.assign(console, originalConsole);
+    }
+  };
+
+  it('rejects entries whose default export is not a factory', async () => {
+    await withGuardedStreams(async () => {
+      await expect(runGeneratedStdioMcpEntry({
+        loadEntry: async () => ({ default: 42 }),
+        serverName: 'broken',
+      })).rejects.toThrow('must default-export a server factory');
+    });
+  });
+
+  it('builds the server from the factory and serves it under the lifecycle', async () => {
+    await withGuardedStreams(async () => {
+      const server = fakeServer();
+      const exitCodes: number[] = [];
+      const signals = new FakeSignals();
+      const handle = await runGeneratedStdioMcpEntry({
+        lifecycle: {
+          exit: (code) => exitCodes.push(code),
+          heartbeat: false,
+          shutdownTimeoutMs: 50,
+          signals,
+          stdin: fakeStdin(),
+        },
+        loadEntry: async () => ({ default: () => server }),
+        serverName: 'curator',
+      });
+      expect(server.connected()).toHaveLength(1);
+      await handle.shutdown(0);
+      expect(exitCodes).toEqual([0]);
+    });
+  });
+});
diff --git a/packages/agent-bundle/tests/package-build.test.ts b/packages/agent-bundle/tests/package-build.test.ts
new file mode 100644
index 000000000..0fc50af90
--- /dev/null
+++ b/packages/agent-bundle/tests/package-build.test.ts
@@ -0,0 +1,278 @@
+import { execFile as executeFile } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { mkdir, mkdtemp, readFile, realpath, rm, stat, symlink, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { promisify } from 'node:util';
+
+import { afterEach, describe, expect, it } from '@rstest/core';
+
+import { build, runMcp } from '../src/api.ts';
+import { runCli } from '../src/cli.ts';
+
+const execFile = promisify(executeFile);
+const workspaceNodeModules = join(process.cwd(), 'node_modules');
+const roots: string[] = [];
+
+/** Declaration generation resolves `typescript` (and ambient node types) from the consumer project, exactly like a real install. */
+const installTypescriptToolchain = async (root: string): Promise<void> => {
+  await mkdir(join(root, 'node_modules'), { recursive: true });
+  await symlink(join(workspaceNodeModules, 'typescript'), join(root, 'node_modules', 'typescript'), 'dir');
+  await symlink(join(workspaceNodeModules, '@types'), join(root, 'node_modules', '@types'), 'dir');
+};
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true })));
+});
+
+const fixtureRoot = async (files: Readonly<Record<string, string>>): Promise<string> => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), 'agent-bundle-package-build-')));
+  roots.push(root);
+  for (const [path, contents] of Object.entries(files)) {
+    const destination = join(root, path);
+    await mkdir(join(destination, '..'), { recursive: true });
+    await writeFile(destination, contents);
+  }
+  return root;
+};
+
+const conventionFixture = (): Readonly<Record<string, string>> => ({
+  'agent-bundle.config.ts': [
+    'export default {',
+    "  mcp: { servers: { echoer: {} } },",
+    "  plugin: { name: 'package-build-fixture', version: '1.0.0' },",
+    "  targets: ['portable'],",
+    '};',
+    '',
+  ].join('\n'),
+  'package.json': '{"name":"package-build-fixture","type":"module","private":true}\n',
+  'tsconfig.json': JSON.stringify({
+    compilerOptions: {
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      strict: true,
+      target: 'es2022',
+      types: ['node'],
+    },
+  }),
+  'src/cli.ts': [
+    'export const main = async (argv: readonly string[]): Promise<number> => {',
+    "  process.stdout.write(`ran:${argv.join(',')}\\n`);",
+    "  return argv.includes('--fail') ? 3 : 0;",
+    '};',
+    '',
+  ].join('\n'),
+  'src/index.ts': [
+    'export interface Answer { readonly value: number }',
+    'export const answer: Answer = { value: 42 };',
+    '',
+  ].join('\n'),
+  'src/mcp/echoer.ts': [
+    '/** A minimal factory the framework stdio shell can serve. */',
+    'export default () => ({',
+    '  close() {},',
+    '  async connect(transport: { onmessage?: unknown }) { void transport; },',
+    '});',
+    '',
+  ].join('\n'),
+});
+
+describe('framework-owned package build', () => {
+  it('builds bin, lib, and dts outputs from conventions and stays deterministic', async () => {
+    const root = await fixtureRoot(conventionFixture());
+    await installTypescriptToolchain(root);
+    const result = await build({ output: 'artifact', packageOutputs: true, root });
+
+    expect(result.model.packageBuild).toMatchObject({
+      bins: [{ name: 'package-build-fixture', provenance: { kind: 'conventional' } }],
+      lib: { dts: true, name: 'index', provenance: { kind: 'conventional' } },
+    });
+    const packageBuild = result.packageBuild;
+    expect(packageBuild).toBeDefined();
+    expect(packageBuild!.outputRoot).toBe(join(root, 'dist'));
+    const paths = packageBuild!.files.map((file) => file.path);
+    expect(paths).toContain('bin/package-build-fixture.js');
+    expect(paths).toContain('index.js');
+    expect(paths).toContain('index.d.ts');
+    for (const file of packageBuild!.files) {
+      expect(file.sourceInputs).toEqual([...file.sourceInputs].sort((left, right) => left.localeCompare(right)));
+    }
+
+    const binPath = join(root, 'dist', 'bin', 'package-build-fixture.js');
+    const binSource = await readFile(binPath, 'utf8');
+    expect(binSource.startsWith('#!/usr/bin/env node\n')).toBe(true);
+    expect((await stat(binPath)).mode & 0o111).not.toBe(0);
+    await expect(execFile(binPath, ['alpha', 'beta'])).resolves.toMatchObject({ stdout: 'ran:alpha,beta\n' });
+    await expect(execFile(binPath, ['--fail'])).rejects.toMatchObject({ code: 3 });
+
+    const lib = await import(pathToFileURL(join(root, 'dist', 'index.js')).href) as { answer: { value: number } };
+    expect(lib.answer.value).toBe(42);
+    await expect(readFile(join(root, 'dist', 'index.d.ts'), 'utf8')).resolves.toContain('interface Answer');
+
+    const rebuilt = await build({ output: 'artifact', packageOutputs: true, root });
+    expect(rebuilt.packageBuild?.files).toEqual(packageBuild!.files);
+  }, 120_000);
+
+  it('wraps factory-exporting MCP entries in the lifecycle shell and leaves self-connecting entries alone', async () => {
+    const root = await fixtureRoot({
+      ...conventionFixture(),
+      'agent-bundle.config.ts': [
+        'export default {',
+        '  bin: false,',
+        '  lib: false,',
+        '  mcp: { servers: {',
+        '    echoer: {},',
+        "    plain: { entry: './src/plain.ts' },",
+        '  } },',
+        "  plugin: { name: 'package-build-fixture', version: '1.0.0' },",
+        "  targets: ['portable'],",
+        '};',
+        '',
+      ].join('\n'),
+      'src/plain.ts': "process.stderr.write('self-connecting entry ran\\n');\n",
+    });
+    const result = await build({ output: 'artifact', packageOutputs: true, root });
+    expect(result.packageBuild).toBeUndefined();
+
+    const entries = Object.fromEntries(result.build.compiledMcpEntries.map((entry) => [entry.id, entry.output]));
+    const wrapped = await readFile(entries['mcp:echoer']!, 'utf8');
+    const plain = await readFile(entries['mcp:plain']!, 'utf8');
+    expect(wrapped).toContain('stdio heartbeat');
+    expect(wrapped).not.toMatch(/from\s*['"]agent-bundle/u);
+    expect(plain).not.toContain('stdio heartbeat');
+
+    // The lifecycle shell exits 0 on stdin EOF so clients can respawn.
+    const eofRun = await execFile(process.execPath, [entries['mcp:echoer']!], { timeout: 15_000 });
+    expect(eofRun).toMatchObject({ stdout: '' });
+    const plainRun = await execFile(process.execPath, [entries['mcp:plain']!], { timeout: 15_000 });
+    expect(plainRun.stderr).toContain('self-connecting entry ran');
+  }, 120_000);
+
+  it('applies the tools escape hatch after the profile and before the invariant enforcer', async () => {
+    const root = await fixtureRoot({
+      ...conventionFixture(),
+      'agent-bundle.config.ts': [
+        'let sawAsyncChunks;',
+        'export default {',
+        '  lib: false,',
+        "  plugin: { name: 'package-build-fixture', version: '1.0.0' },",
+        "  targets: ['portable'],",
+        '  tools: {',
+        "    rsbuild: { source: { define: { __HATCH_DEFINE__: JSON.stringify('hatched') } } },",
+        '    rspack: (config) => {',
+        '      sawAsyncChunks = config.output.asyncChunks;',
+        '      config.output.asyncChunks = true;',
+        '    },',
+        '  },',
+        '};',
+        '',
+      ].join('\n'),
+      'src/cli.ts': [
+        'declare const __HATCH_DEFINE__: string;',
+        'export const main = async (): Promise<number> => {',
+        '  process.stdout.write(`define:${__HATCH_DEFINE__}\\n`);',
+        '  return 0;',
+        '};',
+        '',
+      ].join('\n'),
+    });
+    const result = await build({ output: 'artifact', packageOutputs: true, root });
+    const binPath = join(root, 'dist', 'bin', 'package-build-fixture.js');
+    // The hatch define reached the bundle, and the framework enforcer ran
+    // after the consumer mutator: the build passed its invariant assertions
+    // even though the mutator flipped asyncChunks back on.
+    await expect(execFile(binPath, [])).resolves.toMatchObject({ stdout: 'define:hatched\n' });
+    expect(result.packageBuild?.files.some((file) => file.path === 'bin/package-build-fixture.js')).toBe(true);
+  }, 120_000);
+
+  it('rejects artifact outputs that overlap the package output directory', async () => {
+    const root = await fixtureRoot(conventionFixture());
+    await expect(build({ output: 'dist', packageOutputs: true, root })).rejects.toThrow(/overlaps the package build output/u);
+    await expect(build({ output: 'dist/artifact', packageOutputs: true, root })).rejects.toThrow(/overlaps the package build output/u);
+  }, 120_000);
+
+  it('keeps programmatic artifact builds free of package outputs', async () => {
+    const root = await fixtureRoot(conventionFixture());
+    const result = await build({ output: 'artifact', root });
+    expect(result.packageBuild).toBeUndefined();
+    await expect(stat(join(root, 'dist'))).rejects.toMatchObject({ code: 'ENOENT' });
+  }, 120_000);
+});
+
+describe('mcp run', () => {
+  it('resolves the hashed generated entry and launches it in the foreground', async () => {
+    const root = await fixtureRoot(conventionFixture());
+    const artifact = join(root, 'artifact');
+    await build({ output: 'artifact', root });
+
+    const launches: { args: readonly string[]; command: string; cwd: string; env: Readonly<Record<string, string>> }[] = [];
+    const child = new EventEmitter() as import('node:child_process').ChildProcess;
+    child.kill = () => true;
+    const exitCode = runMcp({
+      artifact,
+      root,
+      server: 'echoer',
+      spawnProcess: (command, args, options) => {
+        launches.push({ args, command, cwd: options.cwd, env: options.env });
+        queueMicrotask(() => child.emit('exit', 0, null));
+        return child;
+      },
+      target: 'portable',
+    });
+    await expect(exitCode).resolves.toBe(0);
+    expect(launches).toHaveLength(1);
+    expect(launches[0]!.command).toBe('node');
+    expect(launches[0]!.args[0]).toMatch(/mcp-echoer-[a-f\d]{8}\.mjs$/u);
+    expect(launches[0]!.cwd).toBe(join(artifact, 'portable'));
+    await expect(stat(join(launches[0]!.cwd, launches[0]!.args[0]!))).resolves.toMatchObject({});
+  }, 120_000);
+
+  it('runs a built server end to end through the CLI and forwards its exit code', async () => {
+    const root = await fixtureRoot({
+      'agent-bundle.config.ts': [
+        'export default {',
+        "  mcp: { servers: { exiter: { entry: './src/exit.ts' } } },",
+        "  plugin: { name: 'package-build-fixture', version: '1.0.0' },",
+        "  targets: ['portable'],",
+        '};',
+        '',
+      ].join('\n'),
+      'package.json': '{"name":"package-build-fixture","type":"module","private":true}\n',
+      'src/exit.ts': 'process.exitCode = 7;\nexport const marker = true;\n',
+    });
+    await build({ output: 'artifact', root });
+    const exitCode = await runCli([
+      'mcp', 'run',
+      '--root', root,
+      '--artifact', join(root, 'artifact'),
+      '--target', 'portable',
+      '--server', 'exiter',
+    ]);
+    expect(exitCode).toBe(7);
+  }, 120_000);
+
+  it('refuses to run remote servers in the foreground', async () => {
+    const root = await fixtureRoot({
+      'agent-bundle.config.ts': [
+        'export default {',
+        '  mcp: { servers: { remote: {',
+        "    transport: 'streamable-http',",
+        "    url: 'https://mcp.example.test/stream',",
+        '  } } },',
+        "  plugin: { name: 'package-build-fixture', version: '1.0.0' },",
+        "  targets: ['portable'],",
+        '};',
+        '',
+      ].join('\n'),
+      'package.json': '{"name":"package-build-fixture","type":"module","private":true}\n',
+    });
+    await build({ output: 'artifact', root });
+    await expect(runMcp({
+      artifact: join(root, 'artifact'),
+      root,
+      server: 'remote',
+      target: 'portable',
+    })).rejects.toThrow(/not a stdio server/u);
+  }, 120_000);
+});
diff --git a/packages/agent-bundle/tests/package-conventions.test.ts b/packages/agent-bundle/tests/package-conventions.test.ts
new file mode 100644
index 000000000..4078d7f03
--- /dev/null
+++ b/packages/agent-bundle/tests/package-conventions.test.ts
@@ -0,0 +1,265 @@
+import { mkdir, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { afterEach, describe, expect, it } from '@rstest/core';
+
+import {
+  normalizeProject,
+  validateSource,
+  type NormalizationTargetRegistry,
+} from '../src/config/index.ts';
+import { normalizePackageBuild } from '../src/config/normalize.ts';
+import type { AgentBundleConfig } from '../src/core/types.ts';
+import type { LoadedConfig } from '../src/config/load.ts';
+
+const registry: NormalizationTargetRegistry = {
+  configExtensions: () => [],
+  defaultTargetNames: () => ['portable'],
+  has: (name) => ['portable', 'codex', 'claude'].includes(name),
+  supports: () => true,
+};
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { force: true, recursive: true })));
+});
+
+const projectRoot = async (files: Readonly<Record<string, string>>): Promise<string> => {
+  const root = await realpath(await mkdtemp(join(tmpdir(), 'agent-bundle-conventions-')));
+  roots.push(root);
+  for (const [path, contents] of Object.entries(files)) {
+    const destination = join(root, path);
+    await mkdir(join(destination, '..'), { recursive: true });
+    await writeFile(destination, contents);
+  }
+  return root;
+};
+
+const loadedProject = (config: AgentBundleConfig, root: string): LoadedConfig => ({
+  config,
+  configPath: `${root}/agent-bundle.config.ts`,
+  context: {
+    command: 'build',
+    mode: 'production',
+    projectRoot: root,
+    selectedTargets: [],
+  },
+});
+
+describe('package build normalization', () => {
+  it('normalizes explicit bin and lib config with config provenance', async () => {
+    const root = await projectRoot({
+      'src/entry.ts': 'export const main = async () => 0;\n',
+      'src/library.ts': 'export const answer = 42;\n',
+    });
+    const model = await normalizeProject(loadedProject({
+      bin: { 'my-tool': './src/entry.ts', other: { entry: './src/entry.ts' } },
+      lib: { dts: false, entry: './src/library.ts' },
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+
+    expect(model.packageBuild).toEqual({
+      bins: [
+        {
+          id: 'bin:my-tool',
+          name: 'my-tool',
+          provenance: { kind: 'config', sourcePath: `${root}/agent-bundle.config.ts` },
+          source: `${root}/src/entry.ts`,
+        },
+        {
+          id: 'bin:other',
+          name: 'other',
+          provenance: { kind: 'config', sourcePath: `${root}/agent-bundle.config.ts` },
+          source: `${root}/src/entry.ts`,
+        },
+      ],
+      lib: {
+        dts: false,
+        id: 'lib:library',
+        name: 'library',
+        provenance: { kind: 'config', sourcePath: `${root}/agent-bundle.config.ts` },
+        source: `${root}/src/library.ts`,
+      },
+      outputDir: 'dist',
+    });
+  });
+
+  it('defaults lib dts to true for the string form', async () => {
+    const root = await projectRoot({ 'src/index.ts': 'export const a = 1;\n' });
+    const packageBuild = normalizePackageBuild(
+      { lib: './src/index.ts', plugin: { name: 'p', version: '1.0.0' } },
+      root,
+      `${root}/agent-bundle.config.ts`,
+    );
+    expect(packageBuild?.lib).toMatchObject({ dts: true, name: 'index' });
+  });
+
+  it('discovers src/cli.ts and src/index.ts conventions with conventional provenance', async () => {
+    const root = await projectRoot({
+      'src/cli.ts': 'export const main = async () => 0;\n',
+      'src/index.ts': 'export const answer = 42;\n',
+    });
+    const model = await normalizeProject(loadedProject({
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+
+    expect(model.packageBuild).toEqual({
+      bins: [{
+        id: 'bin:review-tools',
+        name: 'review-tools',
+        provenance: { kind: 'conventional', sourcePath: `${root}/src/cli.ts` },
+        source: `${root}/src/cli.ts`,
+      }],
+      lib: {
+        dts: true,
+        id: 'lib:index',
+        name: 'index',
+        provenance: { kind: 'conventional', sourcePath: `${root}/src/index.ts` },
+        source: `${root}/src/index.ts`,
+      },
+      outputDir: 'dist',
+    });
+  });
+
+  it('lets config win over convention and false disable it', async () => {
+    const root = await projectRoot({
+      'src/cli.ts': 'export const main = async () => 0;\n',
+      'src/index.ts': 'export const answer = 42;\n',
+      'src/other.ts': 'export const main = async () => 0;\n',
+    });
+    const explicit = await normalizeProject(loadedProject({
+      bin: { renamed: './src/other.ts' },
+      lib: false,
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(explicit.packageBuild?.bins.map((bin) => bin.name)).toEqual(['renamed']);
+    expect(explicit.packageBuild?.lib).toBeUndefined();
+
+    const disabled = await normalizeProject(loadedProject({
+      bin: false,
+      lib: false,
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(disabled.packageBuild).toBeUndefined();
+  });
+
+  it('skips the bin convention when the plugin name is not a safe output name', async () => {
+    const root = await projectRoot({ 'src/cli.ts': 'export const main = async () => 0;\n' });
+    const model = await normalizeProject(loadedProject({
+      plugin: { name: '@scope/unsafe name', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(model.packageBuild).toBeUndefined();
+  });
+
+  it('leaves projects without package entries untouched', async () => {
+    const root = await projectRoot({});
+    const model = await normalizeProject(loadedProject({
+      plugin: { name: 'plain', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(model.packageBuild).toBeUndefined();
+  });
+});
+
+describe('conventional MCP entries', () => {
+  it('discovers src/mcp/<server-id>.ts for servers naming no entry, command, or url', async () => {
+    const root = await projectRoot({
+      'src/mcp/curator.ts': 'export default () => ({ close() {}, async connect() {} });\n',
+    });
+    const loaded = loadedProject({
+      mcp: { servers: { curator: {} } },
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root);
+
+    expect(validateSource(loaded, { skills: [] }, registry)).toEqual([]);
+    const model = await normalizeProject(loaded, { skills: [] }, registry);
+    expect(model.mcpServers).toEqual([{
+      args: [expect.stringMatching(/^mcp\/mcp-curator-[a-f\d]{8}\.mjs$/u)],
+      command: 'node',
+      cwd: 'agent-bundle:path:plugin-root',
+      id: 'mcp:curator',
+      name: 'curator',
+      provenance: { kind: 'conventional', sourcePath: `${root}/src/mcp/curator.ts` },
+      source: `${root}/src/mcp/curator.ts`,
+      targets: ['portable'],
+      transport: 'stdio',
+    }]);
+  });
+
+  it('lets an explicit entry win over the conventional file', async () => {
+    const root = await projectRoot({
+      'src/explicit.ts': 'export default () => ({});\n',
+      'src/mcp/curator.ts': 'export default () => ({});\n',
+    });
+    const model = await normalizeProject(loadedProject({
+      mcp: { servers: { curator: { entry: './src/explicit.ts' } } },
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(model.mcpServers[0]).toMatchObject({
+      provenance: { kind: 'config' },
+      source: `${root}/src/explicit.ts`,
+    });
+  });
+
+  it('still rejects servers without any entry, command, url, or conventional file', async () => {
+    const root = await projectRoot({});
+    const diagnostics = validateSource(loadedProject({
+      mcp: { servers: { curator: {} } },
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+    expect(diagnostics).toEqual([expect.objectContaining({
+      code: 'AB4304',
+      message: expect.stringContaining('src/mcp/curator.ts'),
+    })]);
+  });
+});
+
+describe('bin, lib, and tools validation', () => {
+  const validated = async (
+    config: Omit<AgentBundleConfig, 'plugin'>,
+    files: Readonly<Record<string, string>> = {},
+  ) => {
+    const root = await projectRoot(files);
+    return validateSource(loadedProject({
+      ...config,
+      plugin: { name: 'review-tools', version: '1.0.0' },
+    }, root), { skills: [] }, registry);
+  };
+
+  it('accepts well-formed bin, lib, and tools configuration', async () => {
+    const diagnostics = await validated({
+      bin: { tool: './src/cli.ts' },
+      lib: { entry: './src/index.ts' },
+      tools: { rsbuild: { output: { legalComments: 'none' } }, rspack: (config: object) => config },
+    }, {
+      'src/cli.ts': 'export const main = async () => 0;\n',
+      'src/index.ts': 'export const a = 1;\n',
+    });
+    expect(diagnostics).toEqual([]);
+  });
+
+  it.each([
+    { code: 'AB4700', config: { bin: 'nope' as never }, label: 'non-object bin' },
+    { code: 'AB4701', config: { bin: { 'bad name': './src/cli.ts' } }, label: 'unsafe bin name' },
+    { code: 'AB4702', config: { bin: { tool: 7 as never } }, label: 'non-path bin declaration' },
+    { code: 'AB4703', config: { bin: { tool: '../outside.ts' } }, label: 'escaping bin entry' },
+    { code: 'AB4704', config: { bin: { tool: './src/cli.sh' } }, label: 'unsupported bin extension' },
+    { code: 'AB4705', config: { bin: { tool: './src/missing.ts' } }, label: 'missing bin entry' },
+    { code: 'AB4710', config: { lib: 7 as never }, label: 'malformed lib' },
+    { code: 'AB4712', config: { lib: '../outside.ts' }, label: 'escaping lib entry' },
+    { code: 'AB4714', config: { lib: './src/missing.ts' }, label: 'missing lib entry' },
+    { code: 'AB4715', config: { lib: { dts: 'yes' as never, entry: './src/index.ts' } }, label: 'non-boolean lib dts' },
+    { code: 'AB4720', config: { tools: 'nope' as never }, label: 'non-object tools' },
+    { code: 'AB4721', config: { tools: { webpack: {} } as never }, label: 'unknown tools key' },
+    { code: 'AB4722', config: { tools: { rsbuild: 7 } as never }, label: 'non-object rsbuild hatch' },
+    { code: 'AB4723', config: { tools: { rspack: 'nope' } as never }, label: 'malformed rspack hatch' },
+  ])('rejects $label with $code', async ({ code, config }) => {
+    const diagnostics = await validated(config, {
+      'src/cli.sh': 'echo hi\n',
+      'src/cli.ts': 'export const main = async () => 0;\n',
+      'src/index.ts': 'export const a = 1;\n',
+    });
+    expect(diagnostics.map((diagnostic) => diagnostic.code)).toContain(code);
+  });
+});
diff --git a/packages/agent-bundle/tests/packed-consumer.test.ts b/packages/agent-bundle/tests/packed-consumer.test.ts
index afac51e29..011deba88 100644
--- a/packages/agent-bundle/tests/packed-consumer.test.ts
+++ b/packages/agent-bundle/tests/packed-consumer.test.ts
@@ -9,6 +9,7 @@ import {
   realpath,
   rm,
   stat,
+  symlink,
   writeFile,
 } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
@@ -280,6 +281,99 @@ it('uses only an installed tarball after source deletion', async () => {
       },
     });
 
+    // The framework-owned package build and generated stdio lifecycle must
+    // work from the installed tarball alone: bin/lib/dts outputs under dist/,
+    // a factory-exporting conventional MCP entry served by the packaged
+    // runtime shell, and foreground resolution of the hashed entry.
+    const frameworkRoot = join(consumerRoot, 'framework-build-project');
+    await mkdir(join(frameworkRoot, 'src', 'mcp'), { recursive: true });
+    await Promise.all([
+      writeFile(join(frameworkRoot, 'package.json'), '{"name":"framework-build-fixture","type":"module","private":true}\n'),
+      writeFile(join(frameworkRoot, 'tsconfig.json'), JSON.stringify({
+        compilerOptions: {
+          module: 'esnext',
+          moduleResolution: 'bundler',
+          strict: true,
+          target: 'es2022',
+          types: ['node'],
+        },
+      })),
+      writeFile(join(frameworkRoot, 'agent-bundle.config.ts'), [
+        'export default {',
+        '  mcp: { servers: { greeter: {} } },',
+        "  plugin: { name: 'framework-build-fixture', version: '1.0.0' },",
+        "  targets: ['portable'],",
+        '};',
+        '',
+      ].join('\n')),
+      writeFile(join(frameworkRoot, 'src', 'cli.ts'), [
+        'export const main = async (argv: readonly string[]): Promise<number> => {',
+        "  process.stdout.write(`packed bin ran:${argv.join(',')}\\n`);",
+        '  return 0;',
+        '};',
+        '',
+      ].join('\n')),
+      writeFile(join(frameworkRoot, 'src', 'index.ts'), [
+        'export interface PackedAnswer { readonly value: number }',
+        'export const packedAnswer: PackedAnswer = { value: 42 };',
+        '',
+      ].join('\n')),
+      writeFile(join(frameworkRoot, 'src', 'mcp', 'greeter.ts'), [
+        "import { McpServer } from '@modelcontextprotocol/server';",
+        '',
+        'export default () => {',
+        "  const server = new McpServer({ name: 'framework-build-fixture', version: '1.0.0' });",
+        "  server.registerTool('greet', { description: 'Greets from the packaged runtime shell.' }, async () => ({",
+        "    content: [{ text: 'hello from the framework shell', type: 'text' }],",
+        '  }));',
+        '  return server;',
+        '};',
+        '',
+      ].join('\n')),
+    ]);
+    await execFile('npm', ['install', '--ignore-scripts', '--no-audit', '--no-fund', tarball], {
+      cwd: frameworkRoot,
+      env: installedEnvironment(),
+    });
+    // Declaration generation resolves typescript and ambient node types from
+    // the consumer project, exactly like a real devDependency install.
+    await Promise.all([
+      symlink(join(workspaceRoot, 'node_modules', 'typescript'), join(frameworkRoot, 'node_modules', 'typescript'), 'dir'),
+      symlink(join(workspaceRoot, 'node_modules', '@types'), join(frameworkRoot, 'node_modules', '@types'), 'dir'),
+    ]);
+    const frameworkCli = join(frameworkRoot, 'node_modules', '.bin', 'agent-bundle');
+    const frameworkArtifact = join(frameworkRoot, 'artifact');
+    await runInstalled(frameworkCli, frameworkRoot, ['build', '--root', frameworkRoot, '--output', frameworkArtifact]);
+
+    const packedBin = join(frameworkRoot, 'dist', 'bin', 'framework-build-fixture.js');
+    expect((await stat(packedBin)).mode & 0o111).not.toBe(0);
+    expect((await readFile(packedBin, 'utf8')).startsWith('#!/usr/bin/env node\n')).toBe(true);
+    await expect(execFile(packedBin, ['alpha'], { cwd: frameworkRoot, env: installedEnvironment() }))
+      .resolves.toMatchObject({ stdout: 'packed bin ran:alpha\n' });
+    const packedLib = await import(pathToFileURL(join(frameworkRoot, 'dist', 'index.js')).href) as {
+      readonly packedAnswer: { readonly value: number };
+    };
+    expect(packedLib.packedAnswer.value).toBe(42);
+    await expect(readFile(join(frameworkRoot, 'dist', 'index.d.ts'), 'utf8')).resolves.toContain('PackedAnswer');
+
+    const greeterManifest = JSON.parse(await readFile(join(frameworkArtifact, 'portable', 'mcp.json'), 'utf8')) as {
+      readonly mcpServers: { readonly greeter: { readonly args: readonly [string, ...string[]] } };
+    };
+    const greeterEntry = join(frameworkArtifact, 'portable', greeterManifest.mcpServers.greeter.args[0]);
+    const greeterBundle = await readFile(greeterEntry, 'utf8');
+    expect(greeterBundle).not.toMatch(agentBundleImport);
+    expect(greeterBundle).toContain('stdio heartbeat');
+    // The packaged lifecycle shell exits 0 on stdin EOF so clients can respawn.
+    await expect(execFile(process.execPath, [greeterEntry], {
+      cwd: frameworkRoot,
+      env: installedEnvironment(),
+      timeout: 30_000,
+    })).resolves.toMatchObject({ stdout: '' });
+    const { stdout: greeterTools } = await runInstalled(frameworkCli, frameworkRoot, [
+      'mcp', 'list', '--json', '--root', frameworkRoot, '--artifact', frameworkArtifact, '--target', 'portable', '--server', 'greeter',
+    ]);
+    expect(JSON.parse(greeterTools)).toMatchObject({ tools: [{ name: 'greet' }] });
+
     const reader = join(projectRoot, 'read-resource.mjs');
     await writeFile(reader, [
       "import { Client } from '@modelcontextprotocol/client';",
@@ -304,4 +398,4 @@ it('uses only an installed tarball after source deletion', async () => {
   } finally {
     await rm(consumerRoot, { force: true, recursive: true });
   }
-}, 120_000);
+}, 240_000);
diff --git a/packages/agent-bundle/tests/public-api.test.ts b/packages/agent-bundle/tests/public-api.test.ts
index 313f0f1eb..e8d27e275 100644
--- a/packages/agent-bundle/tests/public-api.test.ts
+++ b/packages/agent-bundle/tests/public-api.test.ts
@@ -210,6 +210,19 @@ it('keeps bundled config extension types in emitted root declarations', async ()
       join(consumerRoot, 'node_modules', 'ajv'),
       'dir',
     );
+    // The tools escape hatch types the Rsbuild environment-config surface, so
+    // the declaration graph resolves the bundler packages exactly as
+    // installed consumers do (both are runtime dependencies of the package).
+    await symlink(
+      join(agentBundleNodeModules, '@rsbuild'),
+      join(consumerRoot, 'node_modules', '@rsbuild'),
+      'dir',
+    );
+    await symlink(
+      join(agentBundleNodeModules, '@rspack'),
+      join(consumerRoot, 'node_modules', '@rspack'),
+      'dir',
+    );
     await writeFile(join(emittedPackageRoot, 'package.json'), JSON.stringify({
       exports: { '.': { types: './dist/index.d.ts' } },
       name: 'agent-bundle',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9304e3f3a..4b693f03a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -84,9 +84,6 @@ importers:
         specifier: 4.4.3
         version: 4.4.3
     devDependencies:
-      '@rslib/core':
-        specifier: 0.23.2
-        version: 0.23.2(typescript@7.0.2)
       '@rstest/core':
         specifier: 0.11.10
         version: 0.11.10
diff --git a/rstest.integration-tests.ts b/rstest.integration-tests.ts
index cdcf6cb86..495e012d8 100644
--- a/rstest.integration-tests.ts
+++ b/rstest.integration-tests.ts
@@ -34,6 +34,7 @@ export const integrationTestFiles: readonly string[] = [
   'packages/agent-bundle/tests/integration-matrix.test.ts',
   'packages/agent-bundle/tests/mcp-session-service.test.ts',
   'packages/agent-bundle/tests/mcp.test.ts',
+  'packages/agent-bundle/tests/package-build.test.ts',
   'packages/agent-bundle/tests/path-token-resolver.test.ts',
   'packages/agent-bundle/tests/plugin-bundle.test.ts',
   'packages/agent-bundle/tests/public-api.test.ts',

From 273269d1673881a112f5f1fe593bfbc0895e295f Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 01:01:39 +0000
Subject: [PATCH 2/4] test(packed): deliver stdin EOF explicitly to the
 packaged lifecycle-shell entry

execFile never closes the child's stdin pipe, so a real server's transport
held the generated entry alive until the 30s timeout killed it. End the
child's stdin so the EOF path under test actually executes.
---
 packages/agent-bundle/tests/packed-consumer.test.ts | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/agent-bundle/tests/packed-consumer.test.ts b/packages/agent-bundle/tests/packed-consumer.test.ts
index 011deba88..429b159f4 100644
--- a/packages/agent-bundle/tests/packed-consumer.test.ts
+++ b/packages/agent-bundle/tests/packed-consumer.test.ts
@@ -363,12 +363,17 @@ it('uses only an installed tarball after source deletion', async () => {
     const greeterBundle = await readFile(greeterEntry, 'utf8');
     expect(greeterBundle).not.toMatch(agentBundleImport);
     expect(greeterBundle).toContain('stdio heartbeat');
-    // The packaged lifecycle shell exits 0 on stdin EOF so clients can respawn.
-    await expect(execFile(process.execPath, [greeterEntry], {
+    // The packaged lifecycle shell exits 0 on stdin EOF so clients can
+    // respawn. execFile never closes the child's stdin pipe, so deliver the
+    // EOF explicitly — the real server's transport holds the process alive
+    // until it arrives.
+    const greeterRun = execFile(process.execPath, [greeterEntry], {
       cwd: frameworkRoot,
       env: installedEnvironment(),
       timeout: 30_000,
-    })).resolves.toMatchObject({ stdout: '' });
+    });
+    greeterRun.child.stdin?.end();
+    await expect(greeterRun).resolves.toMatchObject({ stdout: '' });
     const { stdout: greeterTools } = await runInstalled(frameworkCli, frameworkRoot, [
       'mcp', 'list', '--json', '--root', frameworkRoot, '--artifact', frameworkArtifact, '--target', 'portable', '--server', 'greeter',
     ]);

From a64bc937197fbd0cca0ad933a201f0b31f40f901 Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 01:22:39 +0000
Subject: [PATCH 3/4] =?UTF-8?q?feat(agent-bundle):=20framework-owned=20bui?=
 =?UTF-8?q?ld=20=E2=80=94=20package=20outputs,=20stdio=20entry=20shell,=20?=
 =?UTF-8?q?entry=20conventions,=20tools=20hatch,=20mcp=20run=20(RFC=20#50?=
 =?UTF-8?q?=20Phase=201)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One agent-bundle.config.ts now produces the npm package build alongside host
artifacts: `bin` entries become self-executing dist/bin/<name>.js bundles
(shebang, exec bit, generated main(argv) envelope) and `lib` becomes a
single-entry ESM build with declarations, both lowered through the existing
buildWithRslib synthesis with its invariant assertions intact. Factory-
exporting MCP server entries are wrapped in the new framework stdio lifecycle
shell (agent-bundle/mcp-entry: console-to-stderr guard with raw stdout
restore, SIGINT 130 / SIGTERM 143, stdin-EOF exit 0, bounded shutdown,
heartbeat). src/cli.ts, src/index.ts, and src/mcp/<server-id>.ts conventions
fill silent config with 'conventional' provenance; config always wins.
tools.rsbuild/tools.rspack is the single bundler escape hatch, merged
last-but-bounded into every synthesized config. `agent-bundle mcp run`
resolves the content-hashed generated entry from the target manifest and runs
it in the foreground.

audiobook-curator migrates in-tree as the reference consumer: rslib.config.ts,
tsconfig.build.json, bin/audiobook-curator.js, src/cli-entry.ts, and the dual
build script chain are deleted; package.json bin/exports now point at the
framework-built dist.

References #50 (Phase 1).
---
 packages/agent-bundle/tests/package-build.test.ts | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/agent-bundle/tests/package-build.test.ts b/packages/agent-bundle/tests/package-build.test.ts
index 0fc50af90..621d5a6ed 100644
--- a/packages/agent-bundle/tests/package-build.test.ts
+++ b/packages/agent-bundle/tests/package-build.test.ts
@@ -143,8 +143,9 @@ describe('framework-owned package build', () => {
     expect(plain).not.toContain('stdio heartbeat');
 
     // The lifecycle shell exits 0 on stdin EOF so clients can respawn.
-    const eofRun = await execFile(process.execPath, [entries['mcp:echoer']!], { timeout: 15_000 });
-    expect(eofRun).toMatchObject({ stdout: '' });
+    const eofRun = execFile(process.execPath, [entries['mcp:echoer']!], { timeout: 15_000 });
+    eofRun.child.stdin?.end();
+    await expect(eofRun).resolves.toMatchObject({ stdout: '' });
     const plainRun = await execFile(process.execPath, [entries['mcp:plain']!], { timeout: 15_000 });
     expect(plainRun.stderr).toContain('self-connecting entry ran');
   }, 120_000);

From 4b8f35dbfc807e9ffed539d996139588f263e33e Mon Sep 17 00:00:00 2001
From: ScriptedAlchemy <zackary.l.jackson@gmail.com>
Date: Mon, 31 Aug 2026 01:28:02 +0000
Subject: [PATCH 4/4] =?UTF-8?q?fix(build):=20address=20review=20=E2=80=94?=
 =?UTF-8?q?=20exclude=20colocated=20tests=20from=20the=20dts=20program,=20?=
 =?UTF-8?q?contain=20MCP=20state=20paths?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The synthesized declaration tsconfig now excludes *.test.*, *.spec.*, and
__tests__ under the lib source directory, so colocated tests can neither fail
`agent-bundle build` nor publish test declarations into dist/. MCP server
names that are not a plain single path segment (e.g. `../shared`) map to a
content-addressed state directory instead of traversing out of
.agent-bundle/mcp-run.
---
 packages/agent-bundle/src/api.ts              |  4 ++--
 .../agent-bundle/src/build/package-build.ts   |  7 ++++++
 packages/agent-bundle/src/services/mcp-run.ts | 12 ++++++++++
 .../agent-bundle/tests/package-build.test.ts  | 22 +++++++++++++++++++
 4 files changed, 43 insertions(+), 2 deletions(-)

diff --git a/packages/agent-bundle/src/api.ts b/packages/agent-bundle/src/api.ts
index c0000402d..be487b509 100644
--- a/packages/agent-bundle/src/api.ts
+++ b/packages/agent-bundle/src/api.ts
@@ -6,7 +6,7 @@ import type { TargetArtifactEntry, TargetHookEntry } from './adapters/types.ts';
 import { build as buildArtifact, type BuildResult } from './build/build.ts';
 import { buildPackageOutputs, type PackageBuildResult } from './build/package-build.ts';
 import { isInsideOrEqual } from './core/paths.ts';
-import { runMcpForeground } from './services/mcp-run.ts';
+import { mcpServerStateDirectory, runMcpForeground } from './services/mcp-run.ts';
 export type { BuildResult } from './build/build.ts';
 export type { PackageBuildResult, PackageOutputFile } from './build/package-build.ts';
 export type { ArtifactOutputKind, ArtifactOutputProvenance } from './build/provenance.ts';
@@ -656,7 +656,7 @@ export const runMcp = async (options: RunMcpOptions): Promise<number> => {
   const workspaceRoot = resolve(options.root);
   return temporaryArtifact({ ...options, registry }, async (artifact) => runMcpForeground({
     artifact,
-    pluginDataRoot: join(workspaceRoot, '.agent-bundle', 'mcp-run', options.target, options.server),
+    pluginDataRoot: join(workspaceRoot, '.agent-bundle', 'mcp-run', options.target, mcpServerStateDirectory(options.server)),
     registry,
     server: options.server,
     ...(options.spawnProcess === undefined ? {} : { spawnProcess: options.spawnProcess }),
diff --git a/packages/agent-bundle/src/build/package-build.ts b/packages/agent-bundle/src/build/package-build.ts
index 80ea5e056..1f3eca285 100644
--- a/packages/agent-bundle/src/build/package-build.ts
+++ b/packages/agent-bundle/src/build/package-build.ts
@@ -72,6 +72,13 @@ const synthesizeDtsTsconfig = async (options: {
   await writeFile(path, `${JSON.stringify({
     ...(existsSync(projectTsconfig) ? { extends: projectTsconfig } : {}),
     compilerOptions: { rootDir: options.sourceDir },
+    // Colocated tests must neither fail the declaration build nor publish
+    // test declarations into the package output.
+    exclude: [
+      `${options.sourceDir}/**/*.test.*`,
+      `${options.sourceDir}/**/*.spec.*`,
+      `${options.sourceDir}/**/__tests__/**`,
+    ],
     include: [`${options.sourceDir}/**/*.ts`, `${options.sourceDir}/**/*.tsx`],
   }, null, 2)}\n`, 'utf8');
   return {
diff --git a/packages/agent-bundle/src/services/mcp-run.ts b/packages/agent-bundle/src/services/mcp-run.ts
index b2254820a..42ebdda2d 100644
--- a/packages/agent-bundle/src/services/mcp-run.ts
+++ b/packages/agent-bundle/src/services/mcp-run.ts
@@ -5,6 +5,7 @@ import { isAbsolute, resolve } from 'node:path';
 import { createDefaultRegistry, type TargetRegistry } from '../adapters/registry.ts';
 import { validateArtifact } from '../build/validate-artifact.ts';
 import { DiagnosticError } from '../core/diagnostics.ts';
+import { sha256Hex } from '../core/digest.ts';
 import { assertInside, joinArtifact } from '../core/paths.ts';
 import { parseJsonWithoutDuplicateKeys } from '../core/strict-json.ts';
 import { resolveMcpPathTokens } from './mcp-path-tokens.ts';
@@ -37,6 +38,17 @@ export interface ResolveMcpStdioLaunchOptions {
 const resolveContained = (root: string, path: string): string =>
   isAbsolute(path) ? path : assertInside(root, resolve(root, path));
 
+const safeStateSegment = /^[a-zA-Z0-9](?:[a-zA-Z0-9._-]*[a-zA-Z0-9])?$/u;
+
+/**
+ * MCP server names are consumer input with no path-shape guarantee: a name
+ * containing separators or leading dots (for example `../shared`) must never
+ * traverse out of the per-server state root. Plain single-segment names pass
+ * through untouched; anything else becomes a content-addressed segment.
+ */
+export const mcpServerStateDirectory = (server: string): string =>
+  safeStateSegment.test(server) ? server : `server-${sha256Hex(server).slice(0, 16)}`;
+
 export const resolveMcpStdioLaunch = async (
   options: ResolveMcpStdioLaunchOptions,
 ): Promise<ResolvedMcpStdioLaunch> => {
diff --git a/packages/agent-bundle/tests/package-build.test.ts b/packages/agent-bundle/tests/package-build.test.ts
index 621d5a6ed..9e136da67 100644
--- a/packages/agent-bundle/tests/package-build.test.ts
+++ b/packages/agent-bundle/tests/package-build.test.ts
@@ -10,6 +10,7 @@ import { afterEach, describe, expect, it } from '@rstest/core';
 
 import { build, runMcp } from '../src/api.ts';
 import { runCli } from '../src/cli.ts';
+import { mcpServerStateDirectory } from '../src/services/mcp-run.ts';
 
 const execFile = promisify(executeFile);
 const workspaceNodeModules = join(process.cwd(), 'node_modules');
@@ -187,6 +188,18 @@ describe('framework-owned package build', () => {
     expect(result.packageBuild?.files.some((file) => file.path === 'bin/package-build-fixture.js')).toBe(true);
   }, 120_000);
 
+  it('keeps colocated tests out of the declaration program and the package output', async () => {
+    const root = await fixtureRoot({
+      ...conventionFixture(),
+      // Would fail the declaration build if the synthesized program included it.
+      'src/answer.test.ts': 'const wrong: number = "not a number";\nvoid wrong;\n',
+    });
+    await installTypescriptToolchain(root);
+    await build({ output: 'artifact', packageOutputs: true, root });
+    await expect(readFile(join(root, 'dist', 'index.d.ts'), 'utf8')).resolves.toContain('interface Answer');
+    await expect(stat(join(root, 'dist', 'answer.test.d.ts'))).rejects.toMatchObject({ code: 'ENOENT' });
+  }, 120_000);
+
   it('rejects artifact outputs that overlap the package output directory', async () => {
     const root = await fixtureRoot(conventionFixture());
     await expect(build({ output: 'dist', packageOutputs: true, root })).rejects.toThrow(/overlaps the package build output/u);
@@ -253,6 +266,15 @@ describe('mcp run', () => {
     expect(exitCode).toBe(7);
   }, 120_000);
 
+  it('contains server state directories to a single safe path segment', () => {
+    expect(mcpServerStateDirectory('greeter')).toBe('greeter');
+    expect(mcpServerStateDirectory('my.server-2')).toBe('my.server-2');
+    for (const hostile of ['../shared', 'a/b', '..', '.hidden', 'trailing.']) {
+      expect(mcpServerStateDirectory(hostile)).toMatch(/^server-[a-f\d]{16}$/u);
+    }
+    expect(mcpServerStateDirectory('../shared')).not.toBe(mcpServerStateDirectory('../other'));
+  });
+
   it('refuses to run remote servers in the foreground', async () => {
     const root = await fixtureRoot({
       'agent-bundle.config.ts': [