From a5b88ad82a60c2460a7c71361569b8e9a6871d87 Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 27 Jul 2026 10:07:21 -0400
Subject: [PATCH] Add shared parallel spector scenario compiler
 (@azure-tools/spector-runner)

Add a shared, parallel spector scenario compiler in the new
@azure-tools/spector-runner package, plus a wrapper-free CLI with a
declarative spector.config.yaml (specsRoot/outputDir/compileConfig +
postCompile/postCompileDeclarations hooks, selectable via
--phase all|compile|declarations) and a defineConfig module mode for
emitters needing more. Move the Go, TypeScript and Python regenerators
onto this one parallel-compile + reporting + lifecycle engine; output is
byte-identical to the previous per-emitter drivers.

Fixes #5022
---
 ...r-scenario-compiler-2026-07-24-11-00-00.md |   9 +
 .../instructions/typespec-ts.instructions.md  |  64 ++--
 packages/spector-runner/README.md             | 199 ++++++++++
 packages/spector-runner/cmd/spector-runner.js |  13 +
 packages/spector-runner/package.json          |   8 +
 .../spector-runner/schema/spector-config.tsp  |  34 ++
 packages/spector-runner/src/cli.ts            | 195 ++++++++++
 packages/spector-runner/src/compiler.ts       | 260 +++++++++++++
 packages/spector-runner/src/concurrency.ts    |  52 +++
 packages/spector-runner/src/config.ts         | 176 +++++++++
 packages/spector-runner/src/hooks.ts          | 116 ++++++
 packages/spector-runner/src/index.ts          |  22 ++
 packages/spector-runner/src/loader.ts         |  43 ++-
 packages/spector-runner/src/run.ts            | 186 +++++++++
 packages/spector-runner/src/task-runner.ts    |  48 +++
 packages/spector-runner/src/types.ts          |  43 ++-
 packages/spector-runner/test/cli.test.ts      |  43 +++
 packages/spector-runner/test/compiler.test.ts | 161 ++++++++
 packages/spector-runner/test/config.test.ts   | 122 ++++++
 packages/spector-runner/test/hooks.test.ts    |  67 ++++
 packages/spector-runner/test/loader.test.ts   |  38 ++
 packages/spector-runner/test/run.test.ts      | 206 ++++++++++
 .../.scripts/azure-rest-api-specs.json        |   2 +-
 packages/typespec-go/.scripts/go-test.js      |   2 +-
 packages/typespec-go/.scripts/lint-go.js      |   2 +-
 packages/typespec-go/.scripts/semaphore.js    | 104 -----
 .../.scripts/spector-runner.config.js         | 183 +++++++++
 .../.scripts/sync-azure-rest-api-specs.js     |   2 +-
 packages/typespec-go/.scripts/tspcompile.js   | 284 --------------
 packages/typespec-go/.scripts/tspconfig.yaml  |   2 +-
 packages/typespec-go/package.json             |   2 +-
 .../eng/scripts/ci/regenerate.ts              | 120 ++++--
 packages/typespec-ts/package.json             |   6 +-
 packages/typespec-ts/spector.config.yaml      |  22 ++
 .../test/commands/emit-declarations.ts        | 174 +++++++++
 .../typespec-ts/test/commands/gen-spector.js  |  71 ----
 .../typespec-ts/test/commands/post-compile.js |  55 +++
 packages/typespec-ts/test/commands/run.ts     | 355 ------------------
 pnpm-lock.yaml                                |   3 +
 39 files changed, 2606 insertions(+), 888 deletions(-)
 create mode 100644 .chronus/changes/spector-scenario-compiler-2026-07-24-11-00-00.md
 create mode 100755 packages/spector-runner/cmd/spector-runner.js
 create mode 100644 packages/spector-runner/src/cli.ts
 create mode 100644 packages/spector-runner/src/compiler.ts
 create mode 100644 packages/spector-runner/src/concurrency.ts
 create mode 100644 packages/spector-runner/src/config.ts
 create mode 100644 packages/spector-runner/src/hooks.ts
 create mode 100644 packages/spector-runner/src/run.ts
 create mode 100644 packages/spector-runner/src/task-runner.ts
 create mode 100644 packages/spector-runner/test/cli.test.ts
 create mode 100644 packages/spector-runner/test/compiler.test.ts
 create mode 100644 packages/spector-runner/test/config.test.ts
 create mode 100644 packages/spector-runner/test/hooks.test.ts
 create mode 100644 packages/spector-runner/test/run.test.ts
 delete mode 100644 packages/typespec-go/.scripts/semaphore.js
 create mode 100644 packages/typespec-go/.scripts/spector-runner.config.js
 delete mode 100644 packages/typespec-go/.scripts/tspcompile.js
 create mode 100644 packages/typespec-ts/test/commands/emit-declarations.ts
 delete mode 100644 packages/typespec-ts/test/commands/gen-spector.js
 create mode 100644 packages/typespec-ts/test/commands/post-compile.js
 delete mode 100644 packages/typespec-ts/test/commands/run.ts

diff --git a/.chronus/changes/spector-scenario-compiler-2026-07-24-11-00-00.md b/.chronus/changes/spector-scenario-compiler-2026-07-24-11-00-00.md
new file mode 100644
index 0000000000..503fe9a76a
--- /dev/null
+++ b/.chronus/changes/spector-scenario-compiler-2026-07-24-11-00-00.md
@@ -0,0 +1,9 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-go"
+  - "@azure-tools/typespec-ts"
+  - "@azure-tools/typespec-python"
+---
+
+Add a shared, parallel spector scenario compiler to the `@azure-tools/spector-runner` package, plus a wrapper-free `spector-runner` CLI with a declarative config + hook system, and move the Go, TypeScript (`@azure-tools/typespec-ts`) and Python (`@azure-tools/typespec-python`) regenerators onto it. `compileScenarios` spawns one `tsp compile` subprocess per scenario (up to N at a time, N = CPU count by default) and reports progress through a `TaskRunner`/`runWithConcurrency`/`=== Summary ===` engine shared with `@typespec/tsp-integration`, so the two can be merged later. The `spector-runner` CLI (and its `runSpectorRunner`/`buildScenarios` programmatic API) builds every scenario in one or more `spector.config.yaml` files and compiles them in parallel for a given emitter — driven entirely by flags (`--config`, `--specs-root`, `--emit`, `--output-dir`, `--option`, `--cwd`, ...). The `spector.config.yaml` schema can itself declare the output layout (`specsRoot`, `outputDir`, `compileConfig`) and per-instance lifecycle hooks (`hooks.postCompile`, `hooks.postCompileDeclarations`) as shell commands, selectable with `--phase all|compile|declarations`; hook commands receive `SPECTOR_OUTPUT_DIR`/`SPECTOR_SPEC_PATH`/`SPECTOR_SPEC_NAME`/`SPECTOR_PHASE`. This lets the TypeScript regenerator drop its bespoke driver/config JS entirely: `pnpm generate-tsp-only` is now just `spector-runner --config spector.config.yaml`, with two short hook scripts for the client post-processing and the api-extractor declarations phase. For emitters that need more (extra spec roots, local specs, cross-cutting pre/post steps), a `spector-runner.config.{js,ts}` module (`defineConfig`) declares the whole run — `scenarios` plus `preRun`/`postScenario`/`postRun` hooks — and the CLI drives it end-to-end via `--config-file` (or `runConfig`/`loadConfigFile` programmatically). This lets the per-emitter regenerators shrink (Go and TS now run entirely through the bare CLI; Python keeps only its upstream-synced option tables + flavor/baseline setup in a `--config-file` module). A `CompileScenario` may also set a per-scenario `cwd` (used by the TS regenerator, whose committed per-output `tspconfig.yaml` is resolved relative to each output folder). The Go, TS and Python regenerators now share this one parallel-compile + reporting + lifecycle engine; output is byte-identical to the previous per-emitter drivers.
diff --git a/.github/instructions/typespec-ts.instructions.md b/.github/instructions/typespec-ts.instructions.md
index 0167551cc8..1e0d772a19 100644
--- a/.github/instructions/typespec-ts.instructions.md
+++ b/.github/instructions/typespec-ts.instructions.md
@@ -71,18 +71,25 @@ Integration (spector) tests generate real clients from specs, then assert on the
    though the rest of `test/integration/` is gone). It also copies assets to `./temp/assets`.
    It is a cross-platform Node script (`test/commands/copy-typespec.ts`) and runs the same
    on Windows, macOS, and Linux.
-2. `test/commands/gen-spector.js` picks the `azureModularTsps` list from
-   `test/commands/spector-list.js` (the only spec set) and runs `test/commands/run.ts`
-   for each entry, emitting into `test/azure-modular-integration/generated/<outputPath>`.
+2. `spector-runner --config spector.config.yaml` (the shared
+   `@azure-tools/spector-runner` CLI) reads the opt-in spec list from
+   `spector.config.yaml` and compiles each in parallel, emitting into
+   `test/azure-modular-integration/generated/<outputPath>`. Each spec compiles
+   using the committed `tspconfig.yaml` in its output folder (which names the
+   emitter + per-package options), then the config's per-instance hooks run.
    Generation is split into two phases via `--phase` (default `all` runs both):
-   - `--phase=client` emits the `src/*.ts` sources the tests import. It compiles via
-     `node <@typespec/compiler>/cmd/tsp.js compile` (resolved once per process) rather
-     than `npx tsp`, which avoids ~5 s/spec of npx re-resolution while keeping one fresh
-     subprocess per compile.
-   - `--phase=declarations` emits the tracked `src/index.d.ts` baseline (tsc `.d.ts` +
-     api-extractor rollup). Only `check:tree` consumes these, so the e2e script
-     `generate-and-run` runs the vitest suite in parallel with the
-     declaration regen, keeping the (slow) api-extractor work off the test critical path.
+   - `--phase compile` emits the `src/*.ts` sources the tests import (one fresh
+     `tsp compile` subprocess per spec), then runs the `postCompile` hook
+     (`test/commands/post-compile.js`) to write each package's `.gitignore` and a
+     self-contained test `tsconfig.json`.
+   - `--phase declarations` runs the `postCompileDeclarations` hook
+     (`test/commands/emit-declarations.ts`) per spec — tsc `.d.ts` +
+     api-extractor rollup into the tracked `src/index.d.ts` — **without
+     recompiling**. Only `check:tree` consumes these, so the e2e script
+     `generate-and-run` runs the vitest suite in parallel with the declaration
+     regen, keeping the (slow) api-extractor work off the test critical path.
+   Each hook is a short script that reads `SPECTOR_OUTPUT_DIR` (the spec's output
+   folder); the shared CLI sets it per instance.
 3. The vitest `integration-azure-modular` project then runs the `*.test.ts` assertions.
 
 `pnpm regen-test-baselines` (alias of `generate-tsp-only`, which runs both phases)
@@ -94,9 +101,9 @@ Each generated package writes a `.gitignore` that ignores everything except
 `src/index.d.ts`, `.gitignore`, and `tspconfig.yaml`. So a generated folder is full of
 files on disk (`src/*.ts`, `types/`, `temp/`), but git only tracks the rolled-up
 `src/index.d.ts` (produced by the api-extractor "dtsRollup" pass in the `declarations`
-phase of `run.ts`). The `client` phase rewrites `src/` and therefore _removes_
-`src/index.d.ts`; the `declarations` phase restores it byte-for-byte — so both phases
-must run before `check:tree`.
+phase, `test/commands/emit-declarations.ts`). The `compile` phase rewrites `src/` and
+therefore _removes_ `src/index.d.ts`; the `declarations` phase restores it byte-for-byte
+— so both phases must run before `check:tree`.
 
 ## CI: `e2e-test` job in `.github/workflows/ci-typescript.yml`
 
@@ -109,18 +116,21 @@ So a baseline that doesn't match freshly generated output (changed, missing, or
 ## Gotchas
 
 - **Command scripts run on `node`, not `tsx`.** The `test/commands/*` scripts (including
-  `copy:typespec`, `gen-spector.js`, `check:tree`, and `gen:scenario-suites`) are executed
-  directly with `node`, which strips TypeScript types natively — this requires **Node >=
-  22.18**. When adding or editing one: import sibling `.ts` files with an explicit `.ts`
-  specifier (node does not remap `.js` -> `.ts` the way tsx did), and use `import type` for
-  type-only names from CommonJS deps such as `typescript` (`CompilerOptions`) and
-  `@microsoft/api-extractor` (`IExtractorConfigPrepareOptions`) — otherwise node tries to
-  load them as runtime named exports and throws. `copy:typespec` is cross-platform, so the
-  old Windows workaround (replicating Unix `rm`/`cp` by hand) is no longer needed.
+  `copy:typespec`, `check:tree`, `post-compile.js`, `emit-declarations.ts`, and
+  `gen:scenario-suites`) are executed directly with `node`, which strips TypeScript types
+  natively — this requires **Node >= 22.18**. When adding or editing one: import sibling
+  `.ts` files with an explicit `.ts` specifier (node does not remap `.js` -> `.ts` the way
+  tsx did), and use `import type` for type-only names from CommonJS deps such as
+  `typescript` (`CompilerOptions`) and `@microsoft/api-extractor`
+  (`IExtractorConfigPrepareOptions`) — otherwise node tries to load them as runtime named
+  exports and throws. The spector hooks are invoked by the shared `spector-runner` CLI as
+  shell commands (see `hooks` in `spector.config.yaml`); each reads `SPECTOR_OUTPUT_DIR`.
+  `copy:typespec` is cross-platform, so the old Windows workaround (replicating Unix
+  `rm`/`cp` by hand) is no longer needed.
 - **Never `git add -A` after regenerating baselines.** The api-extractor rollup step can
   intermittently fail to (re)write `src/index.d.ts` for a few specs (concurrent workers in
-  gen-spector share an api-extractor temp workspace per package). The folder still
-  regenerates, but the tracked rollup goes missing — which `git add -A` silently stages as
-  a deletion. Review `git status` for _unexpected_ deletions/additions and stage baseline
-  changes by explicit path before committing. If a baseline went missing this way, restore
-  it from the previous commit rather than re-deleting it.
+  the `declarations` phase share an api-extractor temp workspace per package). The folder
+  still regenerates, but the tracked rollup goes missing — which `git add -A` silently
+  stages as a deletion. Review `git status` for _unexpected_ deletions/additions and stage
+  baseline changes by explicit path before committing. If a baseline went missing this way,
+  restore it from the previous commit rather than re-deleting it.
diff --git a/packages/spector-runner/README.md b/packages/spector-runner/README.md
index 08b93eebd1..627f2c7cce 100644
--- a/packages/spector-runner/README.md
+++ b/packages/spector-runner/README.md
@@ -44,3 +44,202 @@ for (const { path, options } of resolveSpecs(config)) {
   // compile `path` with `options`
 }
 ```
+
+## Compiling scenarios
+
+`compileScenarios` builds a set of scenarios in parallel by spawning one
+`tsp compile` subprocess per scenario (up to `jobs` at a time, defaulting to the
+number of CPUs). It resolves the local `tsp` CLI from `cwd`, reports progress
+through a `TaskRunner` (shared with `@typespec/tsp-integration`), and prints a
+`=== Summary ===` block at the end.
+
+```ts
+import { compileScenarios, resolveSpecEntrypoint } from "@azure-tools/spector-runner";
+
+const scenarios = resolveSpecs(config).map(({ path, options }) => ({
+  name: path,
+  entrypoint: resolveSpecEntrypoint(specsRoot, path),
+  emit: ["@azure-tools/typespec-go"],
+  options: { "@azure-tools/typespec-go": options },
+}));
+
+const summary = await compileScenarios(scenarios, {
+  jobs: 8,
+  cwd: emitterPackageRoot, // where `tsp` and the emitter are installed
+  config: "path/to/stub/tspconfig.yaml", // optional: passed as --config to every compile
+  onScenarioComplete: (result) => {
+    // per-scenario post-processing (runs after each subprocess exits)
+  },
+});
+
+console.log(`${summary.succeeded}/${summary.results.length} succeeded`);
+```
+
+`resolveSpecEntrypoint` maps a config spec-path key to its entry file (an
+explicit `.tsp` key, otherwise `client.tsp` preferred over `main.tsp`).
+
+Each `CompileScenario` may set a per-scenario `cwd`, overriding the run-wide
+`cwd` for that one compile. Use it when scenarios must run in their own output
+folder — e.g. the TypeScript regenerator, where every generated folder ships a
+committed `tspconfig.yaml` resolved relative to it (`--config tspconfig.yaml`).
+The `tsp` CLI is still located from the run-wide `cwd`.
+
+`TaskRunner` and `runWithConcurrency` are also exported for reuse.
+
+The Go (`typespec-go/.scripts/spector-runner.config.js`), TypeScript
+(`typespec-ts/test/commands/spector-runner.config.js`) and Python
+(`typespec-python/eng/scripts/ci/regenerate.ts`) regenerators all drive their
+spec compilation through this engine — see [Config files & hooks](#config-files--hooks).
+
+## `spector-runner` CLI
+
+For the common case you don't need any wrapper script — the `spector-runner`
+bin builds every scenario in a `spector.config.yaml` and compiles them in
+parallel for a given emitter:
+
+```bash
+spector-runner \
+  --config path/to/spector.config.yaml \
+  --specs-root path/to/specs \
+  --emit . \
+  --output-dir "generated/{parentDir}/{options.module}"
+```
+
+Key flags (see `spector-runner --help` for the full list):
+
+- **`--config <path>`** — a `spector.config.yaml` (repeatable to merge several).
+- **`--specs-root <dir>`** — root the spec-path keys are relative to. Defaults to
+  the config's `specsRoot`.
+- **`--emit, --emitter <e>`** — emitter package name or path (`.` for the local
+  package; repeatable). Path-like values are resolved and their `package.json`
+  `name` is used to namespace options. Optional when the config sets
+  `compileConfig` (the emitter then comes from each committed `tspconfig.yaml`).
+- **`--output-dir <template>`** — `emitter-output-dir` template. Placeholders:
+  `{path}` (spec key), `{dir}` (its directory, `.tsp` stripped), `{parentDir}`
+  (`{dir}` minus its last segment), `{outputPath}` (the `outputPath` option,
+  defaulting to `{path}`) and `{options.NAME}` (a spec option value). Defaults to
+  the config's `outputDir`.
+- **`--option <key=value>`** — default emitter option (repeatable); per-spec
+  config options override these by key.
+- **`--tspconfig <path>`** — stub `tspconfig.yaml` passed as `--config` to every
+  compile (prevents option bleed from an upstream config next to the specs).
+- **`--phase <all|compile|declarations>`** — which lifecycle phase(s) to run when
+  the config declares [hooks](#hooks-in-spectorconfigyaml). Default `all`.
+- **`--cwd <dir>`** — directory to run compiles/hooks in and resolve the local
+  `tsp` CLI + emitter. Defaults to `process.cwd()`.
+- **`--jobs <n>`**, **`--filter <regex>`**, **`--verbose`**.
+
+The same logic is available programmatically as `runSpectorRunner` (and the
+lower-level `buildScenarios`), which additionally accept `extraScenarios` and an
+`onScenarioComplete` hook so an emitter can add its own local specs and
+post-processing on top of the config-driven ones:
+
+```ts
+import { runSpectorRunner } from "@azure-tools/spector-runner";
+
+const summary = await runSpectorRunner({
+  config: ["http.spector.config.yaml", "azure.spector.config.yaml"],
+  specsRoot,
+  emit: ["."],
+  outputDir: "test/http-specs/{parentDir}/{options.module}",
+  cwd: emitterPackageRoot,
+  extraScenarios: [...emitterLocalSpecs],
+  onScenarioComplete: ({ scenario, success }) => {
+    // metadata patch / cleanup
+  },
+});
+```
+
+## Hooks in `spector.config.yaml`
+
+For the common case an emitter needs no wrapper module at all: declare the
+output layout and per-instance pre/post steps directly in `spector.config.yaml`
+and drive it with the bare CLI. Each spec compiles using the committed
+`tspconfig.yaml` in its output folder, then the hooks run.
+
+```yaml
+# spector.config.yaml
+specsRoot: temp/specs # default for --specs-root
+outputDir: generated/{outputPath} # {outputPath} = the outputPath option, defaulting to the spec key
+compileConfig: tspconfig.yaml # compile using this committed config inside each output folder
+
+hooks:
+  # A shell command run once per spec. SPECTOR_OUTPUT_DIR points at the output
+  # folder; SPECTOR_SPEC_PATH / SPECTOR_SPEC_NAME / SPECTOR_PHASE are also set.
+  postCompile: node ./scripts/post-compile.js
+  postCompileDeclarations: node ./scripts/emit-declarations.ts
+
+specs:
+  routes: true
+  versioning/removed:
+    - { options: { outputPath: versioning/removed/v1 } }
+    - { options: { outputPath: versioning/removed/v2 } }
+```
+
+```bash
+spector-runner --config spector.config.yaml --phase all
+```
+
+- **`compileConfig`** — when set, each compile runs with its output folder as the
+  cwd and this file as `--config`, so the emitter and per-package options come
+  from the committed config (no synthesized `--emit`/`--option`). Requires
+  `outputDir` to locate each folder.
+- **`hooks.postCompile`** — runs after each successful compile (the `compile` and
+  `all` phases). Keep it a short, reusable script that reads `SPECTOR_OUTPUT_DIR`.
+- **`hooks.postCompileDeclarations`** — runs per spec in the `declarations` phase
+  (and at the end of `all`) **without recompiling**, for a follow-up build step
+  over already-generated sources.
+- **`--phase <all|compile|declarations>`** — pick which phase(s) to run. This lets
+  a heavy declarations pass overlap with, say, an integration-test run:
+
+  ```jsonc
+  "generate-and-run": "npm run gen:client && concurrently \"npm run test\" \"npm run gen:declarations\"",
+  "gen:client": "spector-runner --config spector.config.yaml --phase compile",
+  "gen:declarations": "spector-runner --config spector.config.yaml --phase declarations",
+  ```
+
+## Config files & hooks
+
+Emitters that need more than one spec root, local specs, or pre/post steps can
+declare the **whole run** in a `spector-runner.config.{js,ts}` module instead of
+a bespoke driver script. The `spector-runner` CLI loads it with `--config-file`
+and runs it end-to-end: `preRun` → all scenarios compiled in parallel →
+`postRun`, with `postScenario` after each compile.
+
+```bash
+spector-runner --config-file .scripts/spector-runner.config.js [--filter <regex>] [--jobs <n>] [--verbose]
+```
+
+```js
+import { defineConfig, buildScenarios } from "@azure-tools/spector-runner";
+
+export default defineConfig({
+  cwd: emitterPackageRoot,
+  jobs: 8,
+  tspconfig: ".scripts/tspconfig.yaml", // stub --config for every compile
+
+  // Either an array or a builder invoked with the run context. Compose several
+  // spec roots by calling buildScenarios more than once and concatenating.
+  scenarios: (ctx) => [
+    ...buildScenarios({ config: "spector.config.http.yaml", specsRoot: httpSpecs, emit: ["."], outputDir }),
+    ...buildScenarios({ config: "spector.config.azure.yaml", specsRoot: azureSpecs, emit: ["."], outputDir }),
+    ...localSpecs, // hand-built CompileScenario[]
+  ],
+
+  // Lifecycle hooks (all optional, all awaited):
+  preRun: (ctx) => syncExternalSpecs(),                 // one-time setup: sync/clone/clean
+  postScenario: (result, ctx) => patchOrCleanup(result), // per-scenario post-processing
+  postRun: (summary, ctx) => rollUpDeclarations(),      // follow-up step (not a tsp compile)
+});
+```
+
+Hook and builder context (`RunHookContext`): `{ cwd, jobs, verbose, filter }` —
+already reflecting CLI overrides, so a builder can skip work or a `preRun` can
+adapt when the run is filtered. The CLI `--filter <regex>` filters the built
+scenarios by `name` centrally.
+
+`defineConfig` is an identity helper for type-checking/completion. `runConfig`
+runs a config programmatically (`runConfig(config, { jobs, cwd, verbose, filter })`),
+and `loadConfigFile(path)` imports a config module — useful when a `.ts` config
+must run through `tsx` (e.g. the Python regenerator, whose config imports its
+upstream-synced option tables).
diff --git a/packages/spector-runner/cmd/spector-runner.js b/packages/spector-runner/cmd/spector-runner.js
new file mode 100755
index 0000000000..9e5f9b051e
--- /dev/null
+++ b/packages/spector-runner/cmd/spector-runner.js
@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+/* eslint-disable no-console */
+import { main } from "../dist/src/cli.js";
+
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+  },
+);
diff --git a/packages/spector-runner/package.json b/packages/spector-runner/package.json
index 5d3d6ae5ea..6f6a55a112 100644
--- a/packages/spector-runner/package.json
+++ b/packages/spector-runner/package.json
@@ -18,6 +18,9 @@
   },
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "bin": {
+    "spector-runner": "./cmd/spector-runner.js"
+  },
   "exports": {
     ".": {
       "import": "./dist/src/index.js"
@@ -25,6 +28,7 @@
     "./schema": "./schema/dist/SpectorConfig.json"
   },
   "files": [
+    "cmd/**",
     "dist/**",
     "!dist/test/**",
     "schema/dist/SpectorConfig.json"
@@ -41,8 +45,12 @@
     "test:ci": "vitest run --coverage --reporter=junit --reporter=default"
   },
   "dependencies": {
+    "picocolors": "catalog:",
     "yaml": "catalog:"
   },
+  "peerDependencies": {
+    "@typespec/compiler": "workspace:^"
+  },
   "devDependencies": {
     "@typespec/compiler": "workspace:^",
     "@typespec/json-schema": "workspace:^",
diff --git a/packages/spector-runner/schema/spector-config.tsp b/packages/spector-runner/schema/spector-config.tsp
index 1a5dfde971..c67abb6fcb 100644
--- a/packages/spector-runner/schema/spector-config.tsp
+++ b/packages/spector-runner/schema/spector-config.tsp
@@ -14,6 +14,40 @@ using JsonSchema;
 model SpectorConfig {
   /** Map of spec path (relative to the specs root) to a selection. */
   specs: Record<SpecSelection>;
+
+  /** Root the spec-path keys are relative to (a `--specs-root` default). */
+  specsRoot?: string;
+
+  /**
+   * Template for each spec's output folder, resolved against the run cwd.
+   * Placeholders: `{path}`, `{dir}`, `{parentDir}`, `{outputPath}` (the
+   * `outputPath` option, defaulting to `{path}`) and `{options.NAME}`.
+   */
+  outputDir?: string;
+
+  /**
+   * Filename of a committed `tspconfig.yaml` inside each spec's output folder.
+   * When set, every compile runs with that folder as its cwd and this file as
+   * `--config`, so the emitter and per-package options come from the committed
+   * config (no synthesized `--emit`/`--option`).
+   */
+  compileConfig?: string;
+
+  /** Per-instance lifecycle hooks (shell commands). */
+  hooks?: SpectorHooks;
+}
+
+/**
+ * Per-instance lifecycle hooks, each a shell command run once per selected
+ * spec. The scenario details are exposed via `SPECTOR_OUTPUT_DIR`,
+ * `SPECTOR_SPEC_PATH`, `SPECTOR_SPEC_NAME` and `SPECTOR_PHASE` env vars.
+ */
+model SpectorHooks {
+  /** Runs after each successful `tsp compile` (the `compile`/`all` phases). */
+  postCompile?: string;
+
+  /** Runs per spec in the `declarations` phase (and end of `all`), no recompile. */
+  postCompileDeclarations?: string;
 }
 
 /**
diff --git a/packages/spector-runner/src/cli.ts b/packages/spector-runner/src/cli.ts
new file mode 100644
index 0000000000..bc93a53af6
--- /dev/null
+++ b/packages/spector-runner/src/cli.ts
@@ -0,0 +1,195 @@
+/* eslint-disable no-console */
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { compileScenarios } from "./compiler.js";
+import { loadConfigFile, runConfig } from "./config.js";
+import { runScenarioHook, runScenarioHooks } from "./hooks.js";
+import { loadSpectorConfig } from "./loader.js";
+import { buildScenarios } from "./run.js";
+import { TaskRunner } from "./task-runner.js";
+import type { SpecOptionValue } from "./types.js";
+
+const USAGE = `Usage:
+  spector-runner --config <spector.config.yaml> [--specs-root <dir>] [--emit <emitter>] [--phase <phase>] [options]
+  spector-runner --config-file <spector-runner.config.js> [--filter <regex>] [--jobs <n>] [--cwd <dir>] [--verbose]
+
+Compile every spec selected in one or more spector.config.yaml files in parallel
+by spawning \`tsp compile\` for each, then run the config's per-instance hooks.
+
+Config-file mode:
+  --config-file <path>     A spector-runner.config.{js,ts} module that default-exports
+                           a config (see defineConfig). Drives preRun/postScenario/postRun
+                           hooks and lets one run combine multiple spec roots. A .ts config
+                           needs a TS-capable runtime (run the CLI through \`tsx\`).
+
+Flag mode (spector.config.yaml):
+  --config <path>          Spector config file (repeatable).
+  --specs-root <dir>       Root the spec-path keys are relative to. Defaults to the
+                           config's \`specsRoot\`.
+  --emit, --emitter <e>    Emitter package name or path (repeatable). Use '.' for the local
+                           package. Optional when the config sets \`compileConfig\`.
+  --emitter-name <name>    Name used to namespace --option values. Default: read from the emit path's package.json.
+  --output-dir <template>  emitter-output-dir template. Placeholders: {path} {dir} {parentDir} {outputPath} {options.NAME}.
+                           Defaults to the config's \`outputDir\`.
+  --option <key=value>     Default emitter option (repeatable); per-spec config options override these.
+  --tspconfig <path>       Stub tspconfig.yaml passed as --config to every compile.
+  --phase <phase>          Which lifecycle phase(s) to run: 'all' (default), 'compile'
+                           (compile + postCompile hook) or 'declarations' (the
+                           postCompileDeclarations hook only, no recompile).
+
+Shared options:
+  --cwd <dir>              Directory to run compiles/hooks in and resolve the local tsp CLI + emitter. Default: process.cwd().
+  --jobs <n>               Max concurrent compiles. Default: CPU count.
+  --filter <regex>         Only run scenarios whose name matches this regex.
+  --verbose                Print output for every scenario, not just failures.
+  --help                   Show this help.`;
+
+function parseOptionPairs(pairs: string[]): Record<string, SpecOptionValue> {
+  const out: Record<string, SpecOptionValue> = {};
+  for (const pair of pairs) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) {
+      throw new Error(`Invalid --option '${pair}', expected key=value.`);
+    }
+    out[pair.slice(0, eq)] = pair.slice(eq + 1);
+  }
+  return out;
+}
+
+type Phase = "all" | "compile" | "declarations";
+
+function parsePhase(value: string | undefined): Phase {
+  const phase = value ?? "all";
+  if (phase !== "all" && phase !== "compile" && phase !== "declarations") {
+    throw new Error(`Invalid --phase '${phase}'. Expected 'all', 'compile' or 'declarations'.`);
+  }
+  return phase;
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      "config-file": { type: "string" },
+      config: { type: "string", multiple: true },
+      "specs-root": { type: "string" },
+      emit: { type: "string", multiple: true },
+      emitter: { type: "string", multiple: true },
+      "emitter-name": { type: "string" },
+      "output-dir": { type: "string" },
+      option: { type: "string", multiple: true },
+      tspconfig: { type: "string" },
+      phase: { type: "string" },
+      cwd: { type: "string" },
+      jobs: { type: "string" },
+      filter: { type: "string" },
+      verbose: { type: "boolean", default: false },
+      help: { type: "boolean", default: false },
+    },
+  });
+
+  if (values.help) {
+    console.log(USAGE);
+    return 0;
+  }
+
+  const jobs = values.jobs !== undefined ? Number(values.jobs) : undefined;
+
+  if (values["config-file"] !== undefined) {
+    const config = await loadConfigFile(resolve(values["config-file"]));
+    const summary = await runConfig(config, {
+      jobs,
+      cwd: values.cwd,
+      verbose: values.verbose,
+      filter: values.filter,
+    });
+    return summary.failed > 0 ? 1 : 0;
+  }
+
+  const configPaths = values.config ?? [];
+  if (configPaths.length === 0) {
+    throw new Error(`At least one --config <spector.config.yaml> is required.\n\n${USAGE}`);
+  }
+  const cwd = values.cwd ? resolve(values.cwd) : process.cwd();
+
+  // Top-level settings (specsRoot/outputDir/compileConfig/hooks) come from the
+  // first config; matching CLI flags override where provided.
+  const topConfig = loadSpectorConfig(configPaths[0]);
+
+  const specsRootValue = values["specs-root"] ?? topConfig.specsRoot;
+  if (specsRootValue === undefined) {
+    throw new Error(`--specs-root <dir> (or a config 'specsRoot') is required.\n\n${USAGE}`);
+  }
+  const specsRoot = resolve(cwd, specsRootValue);
+  const compileConfig = topConfig.compileConfig;
+  const outputDir = values["output-dir"] ?? topConfig.outputDir;
+  const hooks = topConfig.hooks ?? {};
+
+  const emit = [...(values.emit ?? []), ...(values.emitter ?? [])];
+  if (emit.length === 0 && compileConfig === undefined) {
+    throw new Error(
+      `At least one --emit <emitter> (or a config 'compileConfig') is required.\n\n${USAGE}`,
+    );
+  }
+
+  const phase = parsePhase(values.phase);
+
+  const scenarios = buildScenarios({
+    config: configPaths,
+    specsRoot,
+    emit,
+    emitterName: values["emitter-name"],
+    outputDir,
+    compileConfig,
+    options: parseOptionPairs(values.option ?? []),
+    tspconfig: values.tspconfig,
+    cwd,
+    jobs,
+    filter: values.filter,
+    verbose: values.verbose,
+  });
+
+  const runner = new TaskRunner({ verbose: values.verbose });
+  let failures = 0;
+
+  if (phase === "all" || phase === "compile") {
+    let hookFailures = 0;
+    const summary = await compileScenarios(scenarios, {
+      jobs,
+      cwd,
+      verbose: values.verbose,
+      config: values.tspconfig,
+      runner,
+      onScenarioComplete: hooks.postCompile
+        ? async (result) => {
+            if (result.success) {
+              const ok = await runScenarioHook(hooks.postCompile!, result.scenario, {
+                cwd,
+                phase: "compile",
+                verbose: values.verbose,
+                runner,
+              });
+              if (!ok) hookFailures++;
+            }
+          }
+        : undefined,
+    });
+    failures += summary.failed + hookFailures;
+  }
+
+  if (phase === "all" || phase === "declarations") {
+    if (hooks.postCompileDeclarations) {
+      const summary = await runScenarioHooks(hooks.postCompileDeclarations, scenarios, {
+        cwd,
+        phase: "declarations",
+        jobs,
+        verbose: values.verbose,
+      });
+      failures += summary.failed;
+    } else if (phase === "declarations") {
+      console.warn("No 'postCompileDeclarations' hook configured; nothing to run.");
+    }
+  }
+
+  return failures > 0 ? 1 : 0;
+}
diff --git a/packages/spector-runner/src/compiler.ts b/packages/spector-runner/src/compiler.ts
new file mode 100644
index 0000000000..d94a9d36ac
--- /dev/null
+++ b/packages/spector-runner/src/compiler.ts
@@ -0,0 +1,260 @@
+/* eslint-disable no-console */
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { availableParallelism } from "os";
+import { dirname, join } from "path";
+import pc from "picocolors";
+import { runWithConcurrency } from "./concurrency.js";
+import { TaskRunner } from "./task-runner.js";
+
+/**
+ * A single scenario to compile: one TypeSpec entrypoint emitted with a given
+ * set of emitters and options.
+ */
+export interface CompileScenario {
+  /** Unique, human-readable label used in logs (e.g. module name or spec path). */
+  readonly name: string;
+  /** Spec-path key this scenario came from (exposed to hooks as `SPECTOR_SPEC_PATH`). */
+  readonly specPath?: string;
+  /** Absolute path to the TypeSpec entrypoint (a `.tsp` file). */
+  readonly entrypoint: string;
+  /** Emitter package name(s) or absolute path(s) to run (`--emit`). */
+  readonly emit: readonly string[];
+  /**
+   * Working directory to spawn this scenario's `tsp compile` in, overriding the
+   * run-wide {@link CompileScenariosOptions.cwd}. Use it when each scenario must
+   * run in its own output folder (e.g. a committed per-output `tspconfig.yaml`
+   * resolved relative to it). The `tsp` CLI is still located from the run-wide
+   * cwd, so a local `node_modules/.bin/tsp` there is enough for every scenario.
+   */
+  readonly cwd?: string;
+  /**
+   * Emitter options, keyed by emitter *name* (not path). Each entry becomes a
+   * `--option=<emitter>.<key>=<value>` CLI argument.
+   */
+  readonly options?: Readonly<Record<string, Record<string, unknown>>>;
+  /** Extra raw CLI arguments appended to `tsp compile`. */
+  readonly args?: readonly string[];
+}
+
+/** Outcome of compiling a single {@link CompileScenario}. */
+export interface CompileScenarioResult {
+  readonly scenario: CompileScenario;
+  readonly status: "pass" | "fail";
+  /** `true` when `tsp compile` exited with code 0. */
+  readonly success: boolean;
+  /** Combined stdout + stderr of the `tsp compile` subprocess. */
+  readonly output: string;
+  /** Wall-clock duration of this compilation, in milliseconds. */
+  readonly durationMs: number;
+}
+
+export interface CompileScenariosOptions {
+  /**
+   * Maximum number of `tsp compile` subprocesses running at once.
+   * Defaults to the number of available CPUs.
+   */
+  readonly jobs?: number;
+  /** Show output for every scenario, not just failures. Defaults to CI detection. */
+  readonly verbose?: boolean;
+  /**
+   * Working directory the subprocesses run in. Also the starting point used to
+   * resolve the local `tsp` CLI (`node_modules/.bin/tsp`). Defaults to
+   * `process.cwd()`.
+   */
+  readonly cwd?: string;
+  /**
+   * Path to a `tspconfig.yaml` passed as `--config` to every compile. Use a
+   * stub config to stop an upstream `tspconfig.yaml` next to a spec from
+   * bleeding emitter options into the output.
+   */
+  readonly config?: string;
+  /** Reporter to use; defaults to a new {@link TaskRunner}. Pass one to share output styling. */
+  readonly runner?: TaskRunner;
+  /**
+   * Called once each scenario finishes (success or failure), in completion
+   * order. Use it for per-scenario post-processing (e.g. patching generated
+   * metadata) or cleanup after a failure. May be async; it is awaited.
+   */
+  readonly onScenarioComplete?: (result: CompileScenarioResult) => void | Promise<void>;
+}
+
+/** Aggregate result of a {@link compileScenarios} run. */
+export interface CompileScenariosSummary {
+  readonly results: readonly CompileScenarioResult[];
+  readonly succeeded: number;
+  readonly failed: number;
+  /** Total wall-clock duration of the whole run, in milliseconds. */
+  readonly durationMs: number;
+}
+
+/**
+ * Resolve the TypeSpec entrypoint for a spec-path key from a spector config.
+ *
+ * - A key ending in `.tsp` points directly at that entry file.
+ * - Otherwise `client.tsp` is preferred over `main.tsp` (matching emitter behavior).
+ *
+ * @param root Absolute path to the specs root the key is relative to.
+ * @param specPath Spec-path key from `spector.config.yaml`.
+ */
+export function resolveSpecEntrypoint(root: string, specPath: string): string {
+  if (specPath.endsWith(".tsp")) {
+    return join(root, specPath);
+  }
+  const client = join(root, specPath, "client.tsp");
+  if (existsSync(client)) {
+    return client;
+  }
+  return join(root, specPath, "main.tsp");
+}
+
+/** Locate the local `tsp` CLI by walking up from `cwd` (preferLocal behavior). */
+function resolveTspBin(cwd: string): string {
+  const binName = process.platform === "win32" ? "tsp.cmd" : "tsp";
+  let dir = cwd;
+  for (;;) {
+    const bin = join(dir, "node_modules", ".bin", binName);
+    if (existsSync(bin)) {
+      return bin;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(
+        `Could not find the 'tsp' CLI in any 'node_modules/.bin' starting from '${cwd}'. ` +
+          `Ensure '@typespec/compiler' is installed.`,
+      );
+    }
+    dir = parent;
+  }
+}
+
+function formatOptionValue(value: unknown): string {
+  return typeof value === "string" ? value : JSON.stringify(value);
+}
+
+/** Build the `tsp compile ...` argument list for a scenario. */
+function buildCompileArgs(scenario: CompileScenario, config?: string): string[] {
+  const args = ["compile", scenario.entrypoint];
+  for (const emitter of scenario.emit) {
+    args.push(`--emit=${emitter}`);
+  }
+  if (scenario.options) {
+    for (const [emitter, opts] of Object.entries(scenario.options)) {
+      for (const [key, value] of Object.entries(opts)) {
+        args.push(`--option=${emitter}.${key}=${formatOptionValue(value)}`);
+      }
+    }
+  }
+  if (config) {
+    args.push(`--config=${config}`);
+  }
+  if (scenario.args) {
+    args.push(...scenario.args);
+  }
+  return args;
+}
+
+/** Spawn `tsp compile` for one scenario and capture its combined output. */
+function compileScenario(
+  scenario: CompileScenario,
+  tspBin: string,
+  cwd: string,
+  config: string | undefined,
+): Promise<CompileScenarioResult> {
+  const start = performance.now();
+  const args = buildCompileArgs(scenario, config);
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (pc.isColorSupported) {
+    env.FORCE_COLOR = "1";
+  }
+
+  return new Promise((resolve) => {
+    const child = spawn(tspBin, args, {
+      cwd: scenario.cwd ?? cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: process.platform === "win32",
+      env,
+    });
+
+    let output = "";
+    child.stdout?.on("data", (data) => (output += data.toString()));
+    child.stderr?.on("data", (data) => (output += data.toString()));
+
+    const finish = (success: boolean, extra = ""): void => {
+      resolve({
+        scenario,
+        status: success ? "pass" : "fail",
+        success,
+        output: output + extra,
+        durationMs: performance.now() - start,
+      });
+    };
+
+    child.on("error", (error) => finish(false, `\nFailed to spawn 'tsp': ${String(error)}`));
+    child.on("close", (code) => finish(code === 0));
+  });
+}
+
+/**
+ * Compile a set of scenarios in parallel by spawning one `tsp compile`
+ * subprocess per scenario, running up to `jobs` at a time. This mirrors how the
+ * emitters previously drove regeneration (and `@typespec/tsp-integration`), so
+ * the reporting engine can be shared.
+ *
+ * Failures never reject: the returned summary reports which scenarios failed.
+ */
+export async function compileScenarios(
+  scenarios: readonly CompileScenario[],
+  options: CompileScenariosOptions = {},
+): Promise<CompileScenariosSummary> {
+  const jobs = Math.max(1, options.jobs ?? availableParallelism());
+  const cwd = options.cwd ?? process.cwd();
+  const runner = options.runner ?? new TaskRunner({ verbose: options.verbose });
+  const results: CompileScenarioResult[] = [];
+  const start = performance.now();
+
+  if (scenarios.length > 0) {
+    const tspBin = resolveTspBin(cwd);
+    await runWithConcurrency([...scenarios], jobs, async (scenario) => {
+      const result = await compileScenario(scenario, tspBin, cwd, options.config);
+      results.push(result);
+      const seconds = (result.durationMs / 1000).toFixed(1);
+      runner.reportTaskWithDetails(
+        result.status,
+        `${scenario.name} ${pc.dim(`(${seconds}s)`)}`,
+        result.output,
+      );
+      await options.onScenarioComplete?.(result);
+      return result;
+    });
+  }
+
+  const succeeded = results.filter((r) => r.success).length;
+  const failed = results.length - succeeded;
+  printSummary(results, succeeded, failed);
+
+  return { results, succeeded, failed, durationMs: performance.now() - start };
+}
+
+function printSummary(
+  results: readonly CompileScenarioResult[],
+  succeeded: number,
+  failed: number,
+): void {
+  console.log(`\n=== Summary ===`);
+  const passed = pc.bold(pc.green(`${succeeded} passed`));
+  const failedStr = failed > 0 ? pc.bold(pc.red(`${failed} failed`)) : undefined;
+  console.log(
+    [passed, failedStr].filter(Boolean).join(pc.gray(" | ")),
+    pc.gray(`(${results.length})`),
+  );
+
+  if (failed > 0) {
+    console.log("\nFailed scenarios:");
+    for (const result of results) {
+      if (!result.success) {
+        console.log(`  - ${result.scenario.name}`);
+      }
+    }
+  }
+}
diff --git a/packages/spector-runner/src/concurrency.ts b/packages/spector-runner/src/concurrency.ts
new file mode 100644
index 0000000000..e9583cac32
--- /dev/null
+++ b/packages/spector-runner/src/concurrency.ts
@@ -0,0 +1,52 @@
+/**
+ * Run async tasks over `items` with at most `concurrency` running at a time.
+ * Mirrors the scheduler in `@typespec/tsp-integration` so the engines stay
+ * aligned. Results are returned in completion order (not input order).
+ *
+ * If any `processor` call rejects, the returned promise rejects; provide a
+ * processor that never throws (capture failures in its result) when you want
+ * every item to run to completion.
+ */
+export async function runWithConcurrency<T, R>(
+  items: readonly T[],
+  concurrency: number,
+  processor: (item: T) => Promise<R>,
+): Promise<R[]> {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const toRun = [...items];
+  const results: R[] = [];
+  let completed = 0;
+  let running = 0;
+
+  return new Promise((resolve, reject) => {
+    function runNext(): void {
+      if (toRun.length === 0 || running >= concurrency) {
+        return;
+      }
+
+      const item = toRun.shift()!;
+      running++;
+      processor(item)
+        .then((result) => {
+          results.push(result);
+          completed++;
+          running--;
+
+          if (completed === items.length) {
+            resolve(results);
+            return;
+          }
+
+          runNext();
+        })
+        .catch(reject);
+    }
+
+    for (let i = 0; i < Math.min(concurrency, toRun.length); i++) {
+      runNext();
+    }
+  });
+}
diff --git a/packages/spector-runner/src/config.ts b/packages/spector-runner/src/config.ts
new file mode 100644
index 0000000000..34c4ef9b41
--- /dev/null
+++ b/packages/spector-runner/src/config.ts
@@ -0,0 +1,176 @@
+import { availableParallelism } from "os";
+import { pathToFileURL } from "url";
+import type {
+  CompileScenario,
+  CompileScenarioResult,
+  CompileScenariosSummary,
+} from "./compiler.js";
+import { compileScenarios } from "./compiler.js";
+
+/**
+ * Context passed to every hook and scenario builder. It reflects the run-wide
+ * settings after CLI overrides have been applied, so hooks (e.g. a baseline
+ * clone) and builders can adapt to the requested `filter`, `jobs`, etc.
+ */
+export interface RunHookContext {
+  /** Working directory compiles run in and the local `tsp` CLI is resolved from. */
+  readonly cwd: string;
+  /** Max concurrent `tsp compile` subprocesses for this run. */
+  readonly jobs: number;
+  /** Whether output is printed for every scenario (not just failures). */
+  readonly verbose: boolean;
+  /** Scenario-name regex the run was filtered by, or `undefined` for "all". */
+  readonly filter?: string;
+}
+
+/**
+ * Lifecycle hooks an emitter can declare so its regeneration runs entirely
+ * through the shared engine (the `spector-runner` CLI) instead of a bespoke
+ * driver. Each hook may be async and is awaited.
+ */
+export interface RunHooks {
+  /**
+   * Runs once before any scenario compiles. Use for one-time setup an emitter
+   * needs (syncing external spec repos, cloning a baseline of generated code,
+   * clearing previous output, etc.).
+   */
+  readonly preRun?: (ctx: RunHookContext) => void | Promise<void>;
+  /**
+   * Runs once each scenario finishes (success or failure), in completion order.
+   * Use for per-scenario post-processing (patching generated metadata, writing
+   * a `.gitignore`) or cleanup after a failure.
+   */
+  readonly postScenario?: (
+    result: CompileScenarioResult,
+    ctx: RunHookContext,
+  ) => void | Promise<void>;
+  /**
+   * Runs once after every scenario has finished. Use for a follow-up build step
+   * that isn't a `tsp compile` (e.g. rolling up `.d.ts` with api-extractor).
+   */
+  readonly postRun?: (
+    summary: CompileScenariosSummary,
+    ctx: RunHookContext,
+  ) => void | Promise<void>;
+}
+
+/**
+ * A full regeneration run described declaratively. An emitter authors one of
+ * these (a `spector-runner.config.{js,ts}` module that default-exports it) and
+ * the shared `spector-runner` CLI drives it end-to-end: {@link RunHooks.preRun},
+ * then all {@link scenarios} compiled in parallel, then {@link RunHooks.postRun}.
+ *
+ * Compose multiple spec roots / configs by calling {@link buildScenarios}
+ * (exported by this package) several times inside {@link scenarios} and
+ * concatenating the results.
+ */
+export interface SpectorRunnerConfig extends RunHooks {
+  /**
+   * The scenarios to compile, or a builder invoked with the run context. A
+   * builder lets an emitter compute scenarios from external data (e.g. upstream
+   * option tables) or skip expensive work when the run is filtered.
+   */
+  readonly scenarios:
+    | readonly CompileScenario[]
+    | ((ctx: RunHookContext) => readonly CompileScenario[] | Promise<readonly CompileScenario[]>);
+  /** Max concurrent compiles. CLI `--jobs` overrides this; default: CPU count. */
+  readonly jobs?: number;
+  /** Working directory for compiles + `tsp` resolution. CLI `--cwd` overrides; default: `process.cwd()`. */
+  readonly cwd?: string;
+  /** Print output for every scenario. CLI `--verbose` overrides. */
+  readonly verbose?: boolean;
+  /** Only run scenarios whose name matches this regex. CLI `--filter` overrides. */
+  readonly filter?: string;
+  /** Stub `tspconfig.yaml` passed as `--config` to every compile (unless a scenario sets its own `--config`). */
+  readonly tspconfig?: string;
+}
+
+/** Run-wide settings from the CLI that override the config's own values when set. */
+export interface RunConfigOverrides {
+  readonly jobs?: number;
+  readonly cwd?: string;
+  readonly verbose?: boolean;
+  readonly filter?: string;
+}
+
+/**
+ * Identity helper providing type-checking and editor completion when authoring
+ * a `spector-runner.config.{js,ts}`:
+ *
+ * ```js
+ * import { defineConfig, buildScenarios } from "@azure-tools/spector-runner";
+ * export default defineConfig({ scenarios: (ctx) => buildScenarios({ ... }) });
+ * ```
+ */
+export function defineConfig(config: SpectorRunnerConfig): SpectorRunnerConfig {
+  return config;
+}
+
+/**
+ * Dynamically import a config module and return its config. Accepts either a
+ * default export or a `config` named export; both must be a
+ * {@link SpectorRunnerConfig}. Note that a `.ts` config requires a TS-capable
+ * runtime (Node with type-stripping, or run the CLI through `tsx`).
+ */
+export async function loadConfigFile(path: string): Promise<SpectorRunnerConfig> {
+  const mod = (await import(pathToFileURL(path).href)) as {
+    default?: unknown;
+    config?: unknown;
+  };
+  const candidate = mod.default ?? mod.config;
+  if (
+    typeof candidate !== "object" ||
+    candidate === null ||
+    !("scenarios" in candidate) ||
+    (candidate as SpectorRunnerConfig).scenarios === undefined
+  ) {
+    throw new Error(
+      `Config module '${path}' must default-export a SpectorRunnerConfig with a 'scenarios' property. ` +
+        `Use 'export default defineConfig({ scenarios: ... })'.`,
+    );
+  }
+  return candidate as SpectorRunnerConfig;
+}
+
+/**
+ * Drive a whole regeneration run from a {@link SpectorRunnerConfig}: resolve the
+ * effective run settings (config values, then CLI `overrides`), invoke `preRun`,
+ * build + optionally filter the scenarios, compile them in parallel (wiring
+ * `postScenario` to the per-scenario completion hook), then invoke `postRun`.
+ *
+ * Failures never reject; inspect the returned summary's `failed` count.
+ */
+export async function runConfig(
+  config: SpectorRunnerConfig,
+  overrides: RunConfigOverrides = {},
+): Promise<CompileScenariosSummary> {
+  const cwd = overrides.cwd ?? config.cwd ?? process.cwd();
+  const jobs = Math.max(1, overrides.jobs ?? config.jobs ?? availableParallelism());
+  const verbose = overrides.verbose ?? config.verbose ?? false;
+  const filter = overrides.filter ?? config.filter;
+  const ctx: RunHookContext = { cwd, jobs, verbose, filter };
+
+  await config.preRun?.(ctx);
+
+  const built =
+    typeof config.scenarios === "function" ? await config.scenarios(ctx) : config.scenarios;
+  let scenarios = [...built];
+  if (filter !== undefined) {
+    const regex = new RegExp(filter);
+    scenarios = scenarios.filter((scenario) => regex.test(scenario.name));
+  }
+
+  const summary = await compileScenarios(scenarios, {
+    jobs,
+    cwd,
+    verbose,
+    config: config.tspconfig,
+    onScenarioComplete: config.postScenario
+      ? (result) => config.postScenario!(result, ctx)
+      : undefined,
+  });
+
+  await config.postRun?.(summary, ctx);
+
+  return summary;
+}
diff --git a/packages/spector-runner/src/hooks.ts b/packages/spector-runner/src/hooks.ts
new file mode 100644
index 0000000000..a070c6876d
--- /dev/null
+++ b/packages/spector-runner/src/hooks.ts
@@ -0,0 +1,116 @@
+/* eslint-disable no-console */
+import { spawn } from "child_process";
+import { availableParallelism } from "os";
+import pc from "picocolors";
+import type { CompileScenario } from "./compiler.js";
+import { runWithConcurrency } from "./concurrency.js";
+import { TaskRunner } from "./task-runner.js";
+
+/** Settings shared by every hook invocation in a run. */
+export interface HookRunOptions {
+  /** Working directory hook commands run in (also where the local CLI resolves). */
+  readonly cwd: string;
+  /** Name of the phase the hook runs in, exposed as `SPECTOR_PHASE`. */
+  readonly phase: string;
+  /** Max concurrent hook commands. Default: CPU count. */
+  readonly jobs?: number;
+  /** Show output for every scenario, not just failures. */
+  readonly verbose?: boolean;
+  /** Reporter to share output styling; defaults to a new {@link TaskRunner}. */
+  readonly runner?: TaskRunner;
+}
+
+/** Environment a hook command receives on top of `process.env`. */
+function hookEnv(scenario: CompileScenario, cwd: string, phase: string): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    SPECTOR_OUTPUT_DIR: scenario.cwd ?? cwd,
+    SPECTOR_SPEC_PATH: scenario.specPath ?? scenario.name,
+    SPECTOR_SPEC_NAME: scenario.name,
+    SPECTOR_PHASE: phase,
+  };
+  if (pc.isColorSupported) {
+    env.FORCE_COLOR = "1";
+  }
+  return env;
+}
+
+/**
+ * Run one hook command for one scenario, reporting the outcome through `runner`.
+ * Never throws: returns `true` on exit code 0, `false` otherwise.
+ */
+export function runScenarioHook(
+  command: string,
+  scenario: CompileScenario,
+  options: HookRunOptions,
+): Promise<boolean> {
+  const runner = options.runner ?? new TaskRunner({ verbose: options.verbose });
+  const start = performance.now();
+
+  return new Promise((resolve) => {
+    const child = spawn(command, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+      shell: true,
+      env: hookEnv(scenario, options.cwd, options.phase),
+    });
+
+    let output = "";
+    child.stdout?.on("data", (data) => (output += data.toString()));
+    child.stderr?.on("data", (data) => (output += data.toString()));
+
+    const finish = (success: boolean, extra = ""): void => {
+      const seconds = ((performance.now() - start) / 1000).toFixed(1);
+      runner.reportTaskWithDetails(
+        success ? "pass" : "fail",
+        `${scenario.name} ${pc.dim(`(${seconds}s)`)}`,
+        output + extra,
+      );
+      resolve(success);
+    };
+
+    child.on("error", (error) => finish(false, `\nFailed to run hook: ${String(error)}`));
+    child.on("close", (code) => finish(code === 0));
+  });
+}
+
+/** Aggregate result of running a hook over many scenarios. */
+export interface HookRunSummary {
+  readonly succeeded: number;
+  readonly failed: number;
+}
+
+/**
+ * Run `command` once per scenario, up to `jobs` at a time, printing a summary.
+ * Used for a phase that only runs a hook (e.g. `declarations`), without
+ * recompiling. Failures never reject; inspect the returned `failed` count.
+ */
+export async function runScenarioHooks(
+  command: string,
+  scenarios: readonly CompileScenario[],
+  options: HookRunOptions,
+): Promise<HookRunSummary> {
+  const jobs = Math.max(1, options.jobs ?? availableParallelism());
+  const runner = options.runner ?? new TaskRunner({ verbose: options.verbose });
+  let succeeded = 0;
+  let failed = 0;
+
+  await runWithConcurrency([...scenarios], jobs, async (scenario) => {
+    const ok = await runScenarioHook(command, scenario, { ...options, runner });
+    if (ok) {
+      succeeded++;
+    } else {
+      failed++;
+    }
+  });
+
+  console.log(`\n=== Summary (${options.phase}) ===`);
+  const passed = pc.bold(pc.green(`${succeeded} passed`));
+  const failedStr = failed > 0 ? pc.bold(pc.red(`${failed} failed`)) : undefined;
+  console.log(
+    [passed, failedStr].filter(Boolean).join(pc.gray(" | ")),
+    pc.gray(`(${scenarios.length})`),
+  );
+
+  return { succeeded, failed };
+}
diff --git a/packages/spector-runner/src/index.ts b/packages/spector-runner/src/index.ts
index e750831e47..d9754137c5 100644
--- a/packages/spector-runner/src/index.ts
+++ b/packages/spector-runner/src/index.ts
@@ -1,3 +1,20 @@
+export { compileScenarios, resolveSpecEntrypoint } from "./compiler.js";
+export type {
+  CompileScenario,
+  CompileScenarioResult,
+  CompileScenariosOptions,
+  CompileScenariosSummary,
+} from "./compiler.js";
+export { runWithConcurrency } from "./concurrency.js";
+export { defineConfig, loadConfigFile, runConfig } from "./config.js";
+export type {
+  RunConfigOverrides,
+  RunHookContext,
+  RunHooks,
+  SpectorRunnerConfig,
+} from "./config.js";
+export { runScenarioHook, runScenarioHooks } from "./hooks.js";
+export type { HookRunOptions, HookRunSummary } from "./hooks.js";
 export {
   getSpecOptions,
   isSpecEnabled,
@@ -5,6 +22,10 @@ export {
   parseSpectorConfig,
   resolveSpecs,
 } from "./loader.js";
+export { buildScenarios, formatOutputDir, runSpectorRunner } from "./run.js";
+export type { SpectorRunnerOptions } from "./run.js";
+export { TaskRunner } from "./task-runner.js";
+export type { TaskRunnerOptions, TaskStatus } from "./task-runner.js";
 export { SpectorConfigError } from "./types.js";
 export type {
   ResolvedSpec,
@@ -13,4 +34,5 @@ export type {
   SpecOptionValue,
   SpecOptions,
   SpectorConfig,
+  SpectorHooks,
 } from "./types.js";
diff --git a/packages/spector-runner/src/loader.ts b/packages/spector-runner/src/loader.ts
index f8262e4764..1ed6039d56 100644
--- a/packages/spector-runner/src/loader.ts
+++ b/packages/spector-runner/src/loader.ts
@@ -8,6 +8,7 @@ import {
   SpecOptionValue,
   SpectorConfig,
   SpectorConfigError,
+  SpectorHooks,
 } from "./types.js";
 
 function isOptionValue(value: unknown): value is SpecOptionValue {
@@ -67,6 +68,39 @@ function validateEntry(rawEntry: unknown, specPath: string): SpecEntry {
   return validateOptionsObject(rawEntry, specPath);
 }
 
+function validateOptionalString(value: unknown, key: string, source: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new SpectorConfigError(`"${source}": "${key}" must be a string.`);
+  }
+  return value;
+}
+
+function validateHooks(rawHooks: unknown, source: string): SpectorHooks | undefined {
+  if (rawHooks === undefined) {
+    return undefined;
+  }
+  if (typeof rawHooks !== "object" || rawHooks === null || Array.isArray(rawHooks)) {
+    throw new SpectorConfigError(`"${source}": "hooks" must be a map of hook name to command.`);
+  }
+  const allowed = new Set(["postCompile", "postCompileDeclarations"]);
+  const hooks: SpectorHooks = {};
+  for (const [key, value] of Object.entries(rawHooks)) {
+    if (!allowed.has(key)) {
+      throw new SpectorConfigError(
+        `"${source}": unknown hook "${key}". Allowed: postCompile, postCompileDeclarations.`,
+      );
+    }
+    if (typeof value !== "string") {
+      throw new SpectorConfigError(`"${source}": hook "${key}" must be a command string.`);
+    }
+    hooks[key as keyof SpectorHooks] = value;
+  }
+  return hooks;
+}
+
 /**
  * Parse and validate a spector config from a YAML string.
  *
@@ -95,7 +129,14 @@ export function parseSpectorConfig(content: string, source = "<string>"): Specto
     specs[specPath] = validateEntry(rawEntry, specPath);
   }
 
-  return { specs };
+  const root = parsed as Record<string, unknown>;
+  return {
+    specs,
+    specsRoot: validateOptionalString(root.specsRoot, "specsRoot", source),
+    outputDir: validateOptionalString(root.outputDir, "outputDir", source),
+    compileConfig: validateOptionalString(root.compileConfig, "compileConfig", source),
+    hooks: validateHooks(root.hooks, source),
+  };
 }
 
 /**
diff --git a/packages/spector-runner/src/run.ts b/packages/spector-runner/src/run.ts
new file mode 100644
index 0000000000..7063aa331a
--- /dev/null
+++ b/packages/spector-runner/src/run.ts
@@ -0,0 +1,186 @@
+import { existsSync, readFileSync } from "fs";
+import { isAbsolute, join, resolve } from "path";
+import type { CompileScenario, CompileScenariosSummary } from "./compiler.js";
+import { compileScenarios, resolveSpecEntrypoint } from "./compiler.js";
+import { loadSpectorConfig, resolveSpecs } from "./loader.js";
+import type { SpecOptions, SpecOptionValue } from "./types.js";
+
+export interface SpectorRunnerOptions {
+  /** One or more `spector.config.yaml` paths whose specs share {@link specsRoot}. */
+  readonly config: string | readonly string[];
+  /** Root the spec-path keys are relative to (e.g. the http-specs `specs` dir). */
+  readonly specsRoot: string;
+  /** Emitter package name(s) or path(s) passed to `tsp --emit`. Paths are resolved against {@link cwd}. */
+  readonly emit: readonly string[];
+  /**
+   * Compile each spec using the committed `tspconfig.yaml` (this filename) inside
+   * its output folder: the compile runs with that folder as its cwd and this file
+   * as `--config`, and no `--emit`/`--option` are synthesized. Requires
+   * {@link outputDir} to locate each folder.
+   */
+  readonly compileConfig?: string;
+  /**
+   * Emitter *name* used to namespace options (`--option <name>.<key>=<value>`).
+   * Defaults to the package name read from the first path-like {@link emit} entry.
+   */
+  readonly emitterName?: string;
+  /**
+   * Template for each scenario's `emitter-output-dir`, resolved against {@link cwd}.
+   * Placeholders: `{path}` (spec key), `{dir}` (its directory, `.tsp` file stripped),
+   * `{parentDir}` (`{dir}` minus its last segment) and `{options.NAME}` (a spec option).
+   * When omitted, the compiler's default output dir is used.
+   */
+  readonly outputDir?: string;
+  /** Default emitter options; per-spec config options override these by key. */
+  readonly options?: Readonly<Record<string, SpecOptionValue>>;
+  /** Stub `tspconfig.yaml` passed as `--config` to every compile. */
+  readonly tspconfig?: string;
+  /** Working directory for compiles, output-dir resolution, and `tsp` lookup. Default `process.cwd()`. */
+  readonly cwd?: string;
+  /** Max concurrent `tsp compile` subprocesses. Default: CPU count. */
+  readonly jobs?: number;
+  /** Only run scenarios whose name matches this regex (tested against the scenario name). */
+  readonly filter?: string;
+  readonly verbose?: boolean;
+  /** Extra scenarios (e.g. an emitter's local specs) appended to the config-derived ones. */
+  readonly extraScenarios?: readonly CompileScenario[];
+  /** Per-scenario completion hook (post-processing/cleanup), forwarded to the compiler. */
+  readonly onScenarioComplete?: (result: {
+    readonly scenario: CompileScenario;
+    readonly success: boolean;
+  }) => void | Promise<void>;
+}
+
+function isPathLike(value: string): boolean {
+  return value.startsWith(".") || isAbsolute(value);
+}
+
+/** Resolve an `--emit` value: path-like entries become absolute, package names pass through. */
+function resolveEmit(emit: string, cwd: string): string {
+  return isPathLike(emit) ? resolve(cwd, emit) : emit;
+}
+
+/** Read the emitter package name from a resolved emit value. */
+function deriveEmitterName(emit: string): string {
+  if (isAbsolute(emit)) {
+    const pkgJson = join(emit, "package.json");
+    if (existsSync(pkgJson)) {
+      const name = JSON.parse(readFileSync(pkgJson, "utf8")).name;
+      if (typeof name === "string" && name.length > 0) {
+        return name;
+      }
+    }
+    throw new Error(
+      `Could not determine the emitter name from '${emit}'. Pass 'emitterName' (or --emitter-name) explicitly.`,
+    );
+  }
+  return emit;
+}
+
+/** Fill an output-dir template for one spec. See {@link SpectorRunnerOptions.outputDir}. */
+export function formatOutputDir(template: string, path: string, options: SpecOptions): string {
+  const dir = path.endsWith(".tsp") ? path.slice(0, path.lastIndexOf("/")) : path;
+  const slash = dir.lastIndexOf("/");
+  const parentDir = slash < 0 ? "" : dir.slice(0, slash);
+  return template.replace(
+    /\{(path|dir|parentDir|outputPath|options\.[\w-]+)\}/g,
+    (_, key: string) => {
+      if (key === "path") return path;
+      if (key === "dir") return dir;
+      if (key === "parentDir") return parentDir;
+      // `{outputPath}` is the `outputPath` option, defaulting to the spec key.
+      if (key === "outputPath") {
+        return options.outputPath === undefined ? path : String(options.outputPath);
+      }
+      const name = key.slice("options.".length);
+      if (options[name] === undefined) {
+        throw new Error(
+          `Output-dir template '{${key}}' references missing option '${name}' for spec '${path}'.`,
+        );
+      }
+      return String(options[name]);
+    },
+  );
+}
+
+/** Translate spector config(s) into {@link CompileScenario}s for {@link compileScenarios}. */
+export function buildScenarios(options: SpectorRunnerOptions): CompileScenario[] {
+  const cwd = options.cwd ?? process.cwd();
+  const configs = Array.isArray(options.config) ? options.config : [options.config];
+  const compileConfig = options.compileConfig;
+  const emit = options.emit.map((e) => resolveEmit(e, cwd));
+  // In compileConfig mode the emitter + options come from each output folder's
+  // committed config, so an emitter name is only needed when we synthesize
+  // `--option` values ourselves.
+  const emitterName =
+    emit.length > 0 ? (options.emitterName ?? deriveEmitterName(emit[0])) : undefined;
+  const filter = options.filter ? new RegExp(options.filter) : undefined;
+
+  const scenarios: CompileScenario[] = [];
+  for (const configPath of configs) {
+    for (const { path, options: specOptions } of resolveSpecs(loadSpectorConfig(configPath))) {
+      const name =
+        specOptions.module !== undefined
+          ? String(specOptions.module)
+          : specOptions.outputPath !== undefined
+            ? String(specOptions.outputPath)
+            : path;
+      if (filter && !filter.test(name)) {
+        continue;
+      }
+      const entrypoint = resolveSpecEntrypoint(options.specsRoot, path);
+
+      if (compileConfig !== undefined) {
+        if (options.outputDir === undefined) {
+          throw new Error(`compileConfig requires an outputDir template to locate '${name}'.`);
+        }
+        const outputDir = resolve(cwd, formatOutputDir(options.outputDir, path, specOptions));
+        scenarios.push({
+          name,
+          specPath: path,
+          entrypoint,
+          emit,
+          cwd: outputDir,
+          args: ["--config", compileConfig],
+        });
+        continue;
+      }
+
+      const merged: Record<string, SpecOptionValue> = { ...options.options, ...specOptions };
+      if (options.outputDir !== undefined) {
+        merged["emitter-output-dir"] = resolve(
+          cwd,
+          formatOutputDir(options.outputDir, path, specOptions),
+        );
+      }
+      scenarios.push({
+        name,
+        specPath: path,
+        entrypoint,
+        emit,
+        options: { [emitterName!]: merged },
+      });
+    }
+  }
+  if (options.extraScenarios) {
+    scenarios.push(...options.extraScenarios);
+  }
+  return scenarios;
+}
+
+/**
+ * End-to-end driver: build scenarios from spector config(s) and compile them all
+ * in parallel. This is what the `spector-runner` CLI calls; emitters that need
+ * extra local specs or post-processing can call it directly with `extraScenarios`
+ * and `onScenarioComplete`.
+ */
+export function runSpectorRunner(options: SpectorRunnerOptions): Promise<CompileScenariosSummary> {
+  const scenarios = buildScenarios(options);
+  return compileScenarios(scenarios, {
+    jobs: options.jobs,
+    cwd: options.cwd,
+    config: options.tspconfig,
+    verbose: options.verbose,
+    onScenarioComplete: options.onScenarioComplete,
+  });
+}
diff --git a/packages/spector-runner/src/task-runner.ts b/packages/spector-runner/src/task-runner.ts
new file mode 100644
index 0000000000..19d344477c
--- /dev/null
+++ b/packages/spector-runner/src/task-runner.ts
@@ -0,0 +1,48 @@
+/* eslint-disable no-console */
+import pc from "picocolors";
+
+export type TaskStatus = "pass" | "fail" | "skip";
+
+export interface TaskRunnerOptions {
+  /**
+   * Show the details of every task, not just failures. Defaults to `true` when
+   * running in CI (the `CI` environment variable is set), `false` otherwise.
+   */
+  readonly verbose?: boolean;
+}
+
+/**
+ * Minimal task reporter shared with `@typespec/tsp-integration` so the two
+ * engines can be merged in the future. Prints a one-line status per task and
+ * groups details (collapsible in GitHub Actions).
+ */
+export class TaskRunner {
+  #verbose: boolean;
+
+  constructor(options: TaskRunnerOptions = {}) {
+    this.#verbose = options.verbose === undefined ? Boolean(process.env.CI) : options.verbose;
+  }
+
+  reportTaskWithDetails(status: TaskStatus, name: string, details: string): void {
+    const statusStr =
+      status === "pass" ? pc.green("pass") : status === "fail" ? pc.red("fail") : pc.gray("skip");
+    const message = `${statusStr} ${name}`;
+    if ((this.#verbose || status === "fail") && details !== "") {
+      this.group(message, details);
+    } else {
+      console.log(message);
+    }
+  }
+
+  group(name: string, content: string): void {
+    if (process.env.GITHUB_ACTIONS) {
+      console.log(`::group::${name}`);
+      console.log(content);
+      console.log("::endgroup::");
+    } else {
+      console.group(name);
+      console.log(content);
+      console.groupEnd();
+    }
+  }
+}
diff --git a/packages/spector-runner/src/types.ts b/packages/spector-runner/src/types.ts
index 65e4f9c234..2c25d5c856 100644
--- a/packages/spector-runner/src/types.ts
+++ b/packages/spector-runner/src/types.ts
@@ -20,12 +20,53 @@ export type SpecOptions = Record<string, SpecOptionValue>;
 export type SpecEntryOptions = { options?: SpecOptions };
 export type SpecEntry = boolean | SpecEntryOptions | SpecEntryOptions[];
 
+/**
+ * Per-instance lifecycle hooks, declared as shell command strings. Each runs
+ * once per selected spec, with the run's working directory as its `cwd` and the
+ * scenario details exposed via environment variables (so a hook can stay a
+ * short, reusable script):
+ *
+ * - `SPECTOR_OUTPUT_DIR` — absolute path to the spec's generated output folder.
+ * - `SPECTOR_SPEC_PATH`  — the spec-path key from the config.
+ * - `SPECTOR_SPEC_NAME`  — the scenario name (output sub-path or spec path).
+ * - `SPECTOR_PHASE`      — the phase the hook is running in.
+ */
+export interface SpectorHooks {
+  /** Runs after each successful `tsp compile` (the `compile`/`all` phases). */
+  postCompile?: string;
+  /**
+   * Runs per spec in the `declarations` phase (and at the end of `all`), without
+   * recompiling — for a follow-up build step over already-generated sources
+   * (e.g. rolling up `.d.ts` with api-extractor).
+   */
+  postCompileDeclarations?: string;
+}
+
 /**
  * Parsed `spector.config.yaml`. An opt-in allowlist: only specs listed with a
- * truthy value are generated.
+ * truthy value are generated. The optional top-level keys let an emitter drive
+ * its whole regeneration from the config file (via the bare `spector-runner`
+ * CLI) instead of a bespoke JS driver.
  */
 export interface SpectorConfig {
   specs: Record<string, SpecEntry>;
+  /** Root the spec-path keys are relative to (a `--specs-root` default). */
+  specsRoot?: string;
+  /**
+   * Template for each spec's output folder, resolved against the run cwd.
+   * Placeholders: `{path}` (spec key), `{dir}`, `{parentDir}`, `{outputPath}`
+   * (the `outputPath` option, defaulting to `{path}`) and `{options.NAME}`.
+   */
+  outputDir?: string;
+  /**
+   * Filename of a committed `tspconfig.yaml` inside each spec's output folder.
+   * When set, every compile runs with its output folder as the cwd and this file
+   * as `--config`, so the emitter + per-package options come from that committed
+   * config (no synthesized `--emit`/`--option`).
+   */
+  compileConfig?: string;
+  /** Per-instance lifecycle hooks (shell commands). */
+  hooks?: SpectorHooks;
 }
 
 /**
diff --git a/packages/spector-runner/test/cli.test.ts b/packages/spector-runner/test/cli.test.ts
new file mode 100644
index 0000000000..52c825eccc
--- /dev/null
+++ b/packages/spector-runner/test/cli.test.ts
@@ -0,0 +1,43 @@
+import { mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { main } from "../src/cli.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "spector-cli-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+describe("cli", () => {
+  it("prints help and exits 0 for --help", async () => {
+    expect(await main(["--help"])).toBe(0);
+  });
+
+  it("rejects when --config is missing", async () => {
+    await expect(main(["--specs-root", root, "--emit", "e"])).rejects.toThrow(/--config/);
+  });
+
+  it("rejects when --specs-root is missing", async () => {
+    const config = join(root, "c.yaml");
+    writeFileSync(config, "specs: {}\n");
+    await expect(main(["--config", config, "--emit", "e"])).rejects.toThrow(/--specs-root/);
+  });
+
+  it("rejects when --emit is missing", async () => {
+    const config = join(root, "c.yaml");
+    writeFileSync(config, "specs: {}\n");
+    await expect(main(["--config", config, "--specs-root", root])).rejects.toThrow(/--emit/);
+  });
+
+  it("returns 0 for an empty spec set", async () => {
+    const config = join(root, "c.yaml");
+    writeFileSync(config, "specs: {}\n");
+    expect(await main(["--config", config, "--specs-root", root, "--emit", "e"])).toBe(0);
+  });
+});
diff --git a/packages/spector-runner/test/compiler.test.ts b/packages/spector-runner/test/compiler.test.ts
new file mode 100644
index 0000000000..7914e744b4
--- /dev/null
+++ b/packages/spector-runner/test/compiler.test.ts
@@ -0,0 +1,161 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { CompileScenario, CompileScenarioResult } from "../src/index.js";
+import { compileScenarios, resolveSpecEntrypoint } from "../src/index.js";
+
+/** Package root — has `node_modules/.bin/tsp`, so subprocesses can find the CLI. */
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+let root: string;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "spector-compiler-"));
+});
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function writeSpec(dir: string, file: string, content: string): string {
+  const full = join(root, dir);
+  mkdirSync(full, { recursive: true });
+  const path = join(full, file);
+  writeFileSync(path, content);
+  return path;
+}
+
+describe("resolveSpecEntrypoint", () => {
+  it("returns the key directly when it ends in .tsp", () => {
+    expect(resolveSpecEntrypoint("/specs", "resiliency/old.tsp")).toBe("/specs/resiliency/old.tsp");
+  });
+
+  it("prefers client.tsp over main.tsp when present", () => {
+    writeSpec("withClient", "client.tsp", "");
+    writeSpec("withClient", "main.tsp", "");
+    expect(resolveSpecEntrypoint(root, "withClient")).toBe(join(root, "withClient", "client.tsp"));
+  });
+
+  it("falls back to main.tsp when no client.tsp exists", () => {
+    writeSpec("onlyMain", "main.tsp", "");
+    expect(resolveSpecEntrypoint(root, "onlyMain")).toBe(join(root, "onlyMain", "main.tsp"));
+  });
+});
+
+describe("compileScenarios", () => {
+  function scenario(name: string, entrypoint: string): CompileScenario {
+    return { name, entrypoint, emit: [] };
+  }
+
+  it("compiles a valid spec successfully with no emitters", async () => {
+    const entry = writeSpec("valid", "main.tsp", "namespace Valid;\n");
+    const summary = await compileScenarios([scenario("valid", entry)], {
+      verbose: false,
+      cwd: pkgRoot,
+    });
+    expect(summary.succeeded).toBe(1);
+    expect(summary.failed).toBe(0);
+    expect(summary.results[0].success).toBe(true);
+  });
+
+  it("reports a spec with an error diagnostic as failed", async () => {
+    const entry = writeSpec("invalid", "main.tsp", "model Foo { x: NotAType }\n");
+    const summary = await compileScenarios([scenario("invalid", entry)], {
+      verbose: false,
+      cwd: pkgRoot,
+    });
+    expect(summary.failed).toBe(1);
+    expect(summary.results[0].success).toBe(false);
+    expect(summary.results[0].output).toContain("NotAType");
+  });
+
+  it("reports a missing entrypoint as a failure", async () => {
+    const missing = join(root, "does-not-exist", "main.tsp");
+    const summary = await compileScenarios([scenario("missing", missing)], {
+      verbose: false,
+      cwd: pkgRoot,
+    });
+    expect(summary.failed).toBe(1);
+    expect(summary.results[0].success).toBe(false);
+  });
+
+  it("aggregates a mix of successes and failures across many scenarios", async () => {
+    const scenarios: CompileScenario[] = [];
+    for (let i = 0; i < 6; i++) {
+      const ok = i % 2 === 0;
+      const entry = writeSpec(
+        `mix${i}`,
+        "main.tsp",
+        ok ? `namespace Mix${i};\n` : "model Bad { x: Missing }\n",
+      );
+      scenarios.push(scenario(`mix${i}`, entry));
+    }
+    const summary = await compileScenarios(scenarios, { verbose: false, jobs: 3, cwd: pkgRoot });
+    expect(summary.results).toHaveLength(6);
+    expect(summary.succeeded).toBe(3);
+    expect(summary.failed).toBe(3);
+  });
+
+  it("invokes onScenarioComplete once per scenario", async () => {
+    const scenarios: CompileScenario[] = [0, 1, 2].map((i) => {
+      const entry = writeSpec(`hook${i}`, "main.tsp", `namespace Hook${i};\n`);
+      return scenario(`hook${i}`, entry);
+    });
+    const seen: string[] = [];
+    await compileScenarios(scenarios, {
+      verbose: false,
+      jobs: 2,
+      cwd: pkgRoot,
+      onScenarioComplete: (r: CompileScenarioResult) => {
+        seen.push(r.scenario.name);
+      },
+    });
+    expect(seen.sort()).toEqual(["hook0", "hook1", "hook2"]);
+  });
+
+  it("runs each scenario in its own cwd when scenario.cwd is set", async () => {
+    // A tspconfig.yaml that only exists in the scenario's cwd, referenced
+    // relatively. It compiles only if the subprocess runs in that cwd.
+    const specEntry = writeSpec("cwdcase", "main.tsp", "namespace CwdCase;\n");
+    writeSpec("cwdcase", "tspconfig.yaml", "options: {}\n");
+    const scenarioCwd = join(root, "cwdcase");
+    const summary = await compileScenarios(
+      [
+        {
+          name: "cwdcase",
+          entrypoint: specEntry,
+          emit: [],
+          cwd: scenarioCwd,
+          args: ["--config", "tspconfig.yaml"],
+        },
+      ],
+      { verbose: false, cwd: pkgRoot },
+    );
+    expect(summary.succeeded).toBe(1);
+    expect(summary.results[0].success).toBe(true);
+  });
+
+  it("respects the concurrency limit", async () => {
+    let active = 0;
+    let maxActive = 0;
+    const scenarios: CompileScenario[] = [];
+    for (let i = 0; i < 8; i++) {
+      const entry = writeSpec(`conc${i}`, "main.tsp", `namespace Conc${i};\n`);
+      scenarios.push(scenario(`conc${i}`, entry));
+    }
+    await compileScenarios(scenarios, {
+      verbose: false,
+      jobs: 3,
+      cwd: pkgRoot,
+      onScenarioComplete: async () => {
+        active++;
+        maxActive = Math.max(maxActive, active);
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        active--;
+      },
+    });
+    expect(maxActive).toBeLessThanOrEqual(3);
+  });
+});
diff --git a/packages/spector-runner/test/config.test.ts b/packages/spector-runner/test/config.test.ts
new file mode 100644
index 0000000000..849fe21dfe
--- /dev/null
+++ b/packages/spector-runner/test/config.test.ts
@@ -0,0 +1,122 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { CompileScenario } from "../src/index.js";
+import { defineConfig, loadConfigFile, runConfig } from "../src/index.js";
+
+/** Package root — has `node_modules/.bin/tsp`, so subprocesses can find the CLI. */
+const pkgRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+let root: string;
+
+beforeAll(() => {
+  root = mkdtempSync(join(tmpdir(), "spector-config-"));
+});
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function writeSpec(dir: string, file: string, content: string): string {
+  const full = join(root, dir);
+  mkdirSync(full, { recursive: true });
+  const path = join(full, file);
+  writeFileSync(path, content);
+  return path;
+}
+
+function scenario(name: string): CompileScenario {
+  const entry = writeSpec(name, "main.tsp", `namespace ${name.replace(/[^A-Za-z0-9]/g, "")};\n`);
+  return { name, entrypoint: entry, emit: [] };
+}
+
+describe("defineConfig", () => {
+  it("returns the config unchanged", () => {
+    const scenarios: CompileScenario[] = [];
+    const config = defineConfig({ scenarios });
+    expect(config.scenarios).toBe(scenarios);
+  });
+});
+
+describe("runConfig", () => {
+  it("invokes preRun, postScenario per scenario, then postRun in order", async () => {
+    const events: string[] = [];
+    await runConfig({
+      cwd: pkgRoot,
+      scenarios: [scenario("alpha"), scenario("beta")],
+      preRun: () => {
+        events.push("pre");
+      },
+      postScenario: (result) => {
+        events.push(`post:${result.scenario.name}`);
+      },
+      postRun: (summary) => {
+        events.push(`done:${summary.succeeded}`);
+      },
+    });
+
+    expect(events[0]).toBe("pre");
+    expect(events[events.length - 1]).toBe("done:2");
+    expect(events.filter((e) => e.startsWith("post:")).sort()).toEqual(["post:alpha", "post:beta"]);
+  });
+
+  it("supports an async scenario builder that receives the run context", async () => {
+    let seenJobs = 0;
+    const summary = await runConfig(
+      {
+        cwd: pkgRoot,
+        jobs: 5,
+        scenarios: async (ctx) => {
+          seenJobs = ctx.jobs;
+          return [scenario("built")];
+        },
+      },
+      { jobs: 2 },
+    );
+    // CLI override wins over the config's own jobs value.
+    expect(seenJobs).toBe(2);
+    expect(summary.succeeded).toBe(1);
+  });
+
+  it("filters scenarios by name and exposes the filter to hooks", async () => {
+    const seen: string[] = [];
+    let filterInPreRun: string | undefined;
+    const summary = await runConfig(
+      {
+        cwd: pkgRoot,
+        scenarios: [scenario("keep-me"), scenario("drop-me")],
+        preRun: (ctx) => {
+          filterInPreRun = ctx.filter;
+        },
+        postScenario: (result) => {
+          seen.push(result.scenario.name);
+        },
+      },
+      { filter: "keep" },
+    );
+
+    expect(filterInPreRun).toBe("keep");
+    expect(seen).toEqual(["keep-me"]);
+    expect(summary.results).toHaveLength(1);
+  });
+});
+
+describe("loadConfigFile", () => {
+  it("loads a default-exported config module", async () => {
+    const modPath = join(root, "runner.config.mjs");
+    writeFileSync(
+      modPath,
+      `export default { scenarios: [{ name: "x", entrypoint: "/x/main.tsp", emit: [] }] };\n`,
+    );
+    const config = await loadConfigFile(modPath);
+    expect(Array.isArray(config.scenarios)).toBe(true);
+  });
+
+  it("rejects a module without a scenarios property", async () => {
+    const modPath = join(root, "bad.config.mjs");
+    writeFileSync(modPath, `export default { nope: true };\n`);
+    await expect(loadConfigFile(modPath)).rejects.toThrow(/must default-export/);
+  });
+});
diff --git a/packages/spector-runner/test/hooks.test.ts b/packages/spector-runner/test/hooks.test.ts
new file mode 100644
index 0000000000..08185b3c91
--- /dev/null
+++ b/packages/spector-runner/test/hooks.test.ts
@@ -0,0 +1,67 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import type { CompileScenario } from "../src/index.js";
+import { runScenarioHook, runScenarioHooks } from "../src/index.js";
+
+let root: string;
+
+beforeEach(() => {
+  root = mkdtempSync(join(tmpdir(), "spector-hooks-"));
+});
+
+afterEach(() => {
+  rmSync(root, { recursive: true, force: true });
+});
+
+function scenario(name: string): CompileScenario {
+  const cwd = join(root, name);
+  mkdirSync(cwd, { recursive: true });
+  return { name, specPath: `spec/${name}`, entrypoint: "/x/main.tsp", emit: [], cwd };
+}
+
+// Writes "<specPath>|<phase>" into SPECTOR_OUTPUT_DIR/marker.txt.
+const writeMarker =
+  "node -e \"require('fs').writeFileSync(process.env.SPECTOR_OUTPUT_DIR + '/marker.txt', " +
+  "process.env.SPECTOR_SPEC_PATH + '|' + process.env.SPECTOR_PHASE)\"";
+
+describe("runScenarioHook", () => {
+  it("runs the command with the scenario env and returns true on success", async () => {
+    const s = scenario("a");
+    const ok = await runScenarioHook(writeMarker, s, { cwd: root, phase: "compile" });
+    expect(ok).toBe(true);
+    expect(readFileSync(join(s.cwd!, "marker.txt"), "utf8")).toBe("spec/a|compile");
+  });
+
+  it("returns false when the command exits non-zero", async () => {
+    const ok = await runScenarioHook('node -e "process.exit(1)"', scenario("b"), {
+      cwd: root,
+      phase: "compile",
+    });
+    expect(ok).toBe(false);
+  });
+});
+
+describe("runScenarioHooks", () => {
+  it("runs the command once per scenario and aggregates results", async () => {
+    const scenarios = [scenario("one"), scenario("two")];
+    const summary = await runScenarioHooks(writeMarker, scenarios, {
+      cwd: root,
+      phase: "declarations",
+      jobs: 2,
+    });
+    expect(summary).toEqual({ succeeded: 2, failed: 0 });
+    for (const s of scenarios) {
+      expect(readFileSync(join(s.cwd!, "marker.txt"), "utf8")).toBe(`spec/${s.name}|declarations`);
+    }
+  });
+
+  it("counts failures without rejecting", async () => {
+    const summary = await runScenarioHooks('node -e "process.exit(1)"', [scenario("x")], {
+      cwd: root,
+      phase: "declarations",
+    });
+    expect(summary).toEqual({ succeeded: 0, failed: 1 });
+  });
+});
diff --git a/packages/spector-runner/test/loader.test.ts b/packages/spector-runner/test/loader.test.ts
index 7ad637413d..f3f1ca3338 100644
--- a/packages/spector-runner/test/loader.test.ts
+++ b/packages/spector-runner/test/loader.test.ts
@@ -68,6 +68,44 @@ specs:
       SpectorConfigError,
     );
   });
+
+  it("parses the optional top-level specsRoot/outputDir/compileConfig/hooks", () => {
+    const config = parseSpectorConfig(`
+specsRoot: temp/specs
+outputDir: out/{outputPath}
+compileConfig: tspconfig.yaml
+hooks:
+  postCompile: node ./post.js
+  postCompileDeclarations: node ./decl.ts
+specs:
+  a: true
+`);
+    expect(config.specsRoot).toBe("temp/specs");
+    expect(config.outputDir).toBe("out/{outputPath}");
+    expect(config.compileConfig).toBe("tspconfig.yaml");
+    expect(config.hooks).toEqual({
+      postCompile: "node ./post.js",
+      postCompileDeclarations: "node ./decl.ts",
+    });
+  });
+
+  it("leaves the optional top-level keys undefined when omitted", () => {
+    const config = parseSpectorConfig(`specs:\n  a: true`);
+    expect(config.specsRoot).toBeUndefined();
+    expect(config.outputDir).toBeUndefined();
+    expect(config.compileConfig).toBeUndefined();
+    expect(config.hooks).toBeUndefined();
+  });
+
+  it("throws on a non-string top-level setting or an unknown/invalid hook", () => {
+    expect(() => parseSpectorConfig(`specsRoot: 3\nspecs:\n  a: true`)).toThrow(SpectorConfigError);
+    expect(() => parseSpectorConfig(`hooks:\n  nope: x\nspecs:\n  a: true`)).toThrow(
+      SpectorConfigError,
+    );
+    expect(() => parseSpectorConfig(`hooks:\n  postCompile: 1\nspecs:\n  a: true`)).toThrow(
+      SpectorConfigError,
+    );
+  });
 });
 
 describe("isSpecEnabled / getSpecOptions", () => {
diff --git a/packages/spector-runner/test/run.test.ts b/packages/spector-runner/test/run.test.ts
new file mode 100644
index 0000000000..5502184dae
--- /dev/null
+++ b/packages/spector-runner/test/run.test.ts
@@ -0,0 +1,206 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { buildScenarios, formatOutputDir } from "../src/index.js";
+
+describe("formatOutputDir", () => {
+  it("substitutes {path}, {dir} and {parentDir}", () => {
+    expect(
+      formatOutputDir("out/{parentDir}/{options.module}", "encode/datetime", { module: "dt" }),
+    ).toBe("out/encode/dt");
+    expect(formatOutputDir("{dir}", "encode/datetime", {})).toBe("encode/datetime");
+    expect(formatOutputDir("{path}", "encode/datetime", {})).toBe("encode/datetime");
+  });
+
+  it("strips a trailing .tsp file from {dir}/{parentDir}", () => {
+    expect(formatOutputDir("{dir}", "a/b/client.tsp", {})).toBe("a/b");
+    expect(formatOutputDir("{parentDir}", "a/b/client.tsp", {})).toBe("a");
+  });
+
+  it("yields an empty {parentDir} for a top-level spec", () => {
+    expect(
+      formatOutputDir("root/{parentDir}/{options.module}", "special-words", { module: "sw" }),
+    ).toBe("root//sw");
+  });
+
+  it("throws when an {options.NAME} placeholder has no matching option", () => {
+    expect(() => formatOutputDir("{options.module}", "a/b", {})).toThrow(/missing option 'module'/);
+  });
+
+  it("resolves {outputPath} to the outputPath option, defaulting to the spec key", () => {
+    expect(formatOutputDir("out/{outputPath}", "a/b", {})).toBe("out/a/b");
+    expect(formatOutputDir("out/{outputPath}", "a/b", { outputPath: "a/b/v2" })).toBe("out/a/b/v2");
+  });
+});
+
+describe("buildScenarios", () => {
+  let root: string;
+
+  beforeEach(() => {
+    root = mkdtempSync(join(tmpdir(), "spector-run-"));
+  });
+
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  function writeConfig(name: string, body: string): string {
+    const path = join(root, name);
+    writeFileSync(path, body);
+    return path;
+  }
+
+  function specsRoot(): string {
+    // The entrypoint files don't need to exist for buildScenarios; it only
+    // resolves paths (client.tsp is preferred only when present on disk).
+    return join(root, "specs");
+  }
+
+  it("maps config specs to scenarios with merged options and output dirs", () => {
+    const config = writeConfig(
+      "spector.config.yaml",
+      [
+        "specs:",
+        '  "encode/datetime": { options: { module: dt, slice-elements-byval: true } }',
+        '  "special-words": { options: { module: sw } }',
+      ].join("\n"),
+    );
+    const scenarios = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: ["@azure-tools/typespec-go"],
+      options: { "generate-fakes": true, "file-prefix": "zz_" },
+      outputDir: "out/{parentDir}/{options.module}",
+      cwd: root,
+    });
+
+    expect(scenarios.map((s) => s.name).sort()).toEqual(["dt", "sw"]);
+    const dt = scenarios.find((s) => s.name === "dt")!;
+    expect(dt.entrypoint).toBe(join(specsRoot(), "encode/datetime", "main.tsp"));
+    const opts = dt.options!["@azure-tools/typespec-go"];
+    // default + per-spec merge, per-spec wins on conflict
+    expect(opts["generate-fakes"]).toBe(true);
+    expect(opts["slice-elements-byval"]).toBe(true);
+    expect(opts.module).toBe("dt");
+    expect(opts["emitter-output-dir"]).toBe(join(root, "out/encode/dt"));
+  });
+
+  it("lets per-spec options override defaults", () => {
+    const config = writeConfig(
+      "c.yaml",
+      ["specs:", '  "a/b": { options: { module: m, "generate-fakes": false } }'].join("\n"),
+    );
+    const [scenario] = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: ["e"],
+      emitterName: "e",
+      options: { "generate-fakes": true },
+      cwd: root,
+    });
+    expect(scenario.options!.e["generate-fakes"]).toBe(false);
+  });
+
+  it("applies the filter against the scenario name (module)", () => {
+    const config = writeConfig(
+      "c.yaml",
+      [
+        "specs:",
+        '  "a/one": { options: { module: keep } }',
+        '  "a/two": { options: { module: drop } }',
+      ].join("\n"),
+    );
+    const scenarios = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: ["e"],
+      emitterName: "e",
+      filter: "keep",
+      cwd: root,
+    });
+    expect(scenarios.map((s) => s.name)).toEqual(["keep"]);
+  });
+
+  it("derives the emitter name from a path emit's package.json", () => {
+    const emitDir = join(root, "emitter");
+    mkdirSync(emitDir, { recursive: true });
+    writeFileSync(join(emitDir, "package.json"), JSON.stringify({ name: "@scope/my-emitter" }));
+    const config = writeConfig(
+      "c.yaml",
+      ["specs:", '  "a/b": { options: { module: m } }'].join("\n"),
+    );
+    const [scenario] = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: [emitDir],
+      cwd: root,
+    });
+    expect(Object.keys(scenario.options!)).toEqual(["@scope/my-emitter"]);
+  });
+
+  it("appends extraScenarios", () => {
+    const config = writeConfig(
+      "c.yaml",
+      ["specs:", '  "a/b": { options: { module: m } }'].join("\n"),
+    );
+    const scenarios = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: ["e"],
+      emitterName: "e",
+      cwd: root,
+      extraScenarios: [{ name: "extra", entrypoint: "/x/main.tsp", emit: ["e"] }],
+    });
+    expect(scenarios.map((s) => s.name)).toContain("extra");
+  });
+
+  it("in compileConfig mode compiles in each output dir with no synthesized emit/options", () => {
+    const config = writeConfig(
+      "c.yaml",
+      [
+        "specs:",
+        "  a/b: true",
+        '  "versioning/removed":',
+        "    - { options: { outputPath: versioning/removed/v1 } }",
+        "    - { options: { outputPath: versioning/removed/v2 } }",
+      ].join("\n"),
+    );
+    const scenarios = buildScenarios({
+      config,
+      specsRoot: specsRoot(),
+      emit: [],
+      compileConfig: "tspconfig.yaml",
+      outputDir: "gen/{outputPath}",
+      cwd: root,
+    });
+
+    // name defaults to the spec key, or the outputPath option when set.
+    expect(scenarios.map((s) => s.name).sort()).toEqual([
+      "a/b",
+      "versioning/removed/v1",
+      "versioning/removed/v2",
+    ]);
+    const v2 = scenarios.find((s) => s.name === "versioning/removed/v2")!;
+    expect(v2.cwd).toBe(join(root, "gen/versioning/removed/v2"));
+    expect(v2.args).toEqual(["--config", "tspconfig.yaml"]);
+    expect(v2.emit).toEqual([]);
+    expect(v2.options).toBeUndefined();
+    expect(v2.specPath).toBe("versioning/removed");
+    // entrypoint resolves from the spec key, not the outputPath.
+    expect(v2.entrypoint).toBe(join(specsRoot(), "versioning/removed", "main.tsp"));
+  });
+
+  it("throws in compileConfig mode when no outputDir template is given", () => {
+    const config = writeConfig("c.yaml", ["specs:", "  a/b: true"].join("\n"));
+    expect(() =>
+      buildScenarios({
+        config,
+        specsRoot: specsRoot(),
+        emit: [],
+        compileConfig: "tspconfig.yaml",
+        cwd: root,
+      }),
+    ).toThrow(/requires an outputDir/);
+  });
+});
diff --git a/packages/typespec-go/.scripts/azure-rest-api-specs.json b/packages/typespec-go/.scripts/azure-rest-api-specs.json
index 3bacb50510..e22ce678b1 100644
--- a/packages/typespec-go/.scripts/azure-rest-api-specs.json
+++ b/packages/typespec-go/.scripts/azure-rest-api-specs.json
@@ -1,6 +1,6 @@
 {
   "$schema": "./azure-rest-api-specs.schema.json",
-  "_description": "Pinned commit of Azure/azure-rest-api-specs used by .scripts/sync-azure-rest-api-specs.js and tspcompile.js. To update specs, change `commit` to a newer SHA from https://github.com/Azure/azure-rest-api-specs/commits/main, then run `pnpm tspcompile`.",
+  "_description": "Pinned commit of Azure/azure-rest-api-specs used by .scripts/sync-azure-rest-api-specs.js and spector-runner.config.js. To update specs, change `commit` to a newer SHA from https://github.com/Azure/azure-rest-api-specs/commits/main, then run `pnpm tspcompile`.",
   "repository": "https://github.com/Azure/azure-rest-api-specs.git",
   "commit": "f437f2fe14e41383b15850c619b599468333007b",
   "sparseCheckoutPaths": [
diff --git a/packages/typespec-go/.scripts/go-test.js b/packages/typespec-go/.scripts/go-test.js
index 6937ae2022..a7ef2f214e 100644
--- a/packages/typespec-go/.scripts/go-test.js
+++ b/packages/typespec-go/.scripts/go-test.js
@@ -4,7 +4,7 @@
 // Runs `go test ./...` for every Go module (a directory containing a go.mod)
 // under test/local/, test/http-specs/ and test/azure-http-specs/. Discovery is
 // module-based (not test-file-based) so that directories holding hand-written
-// tests for specs that are currently disabled in tspcompile.js -- and therefore
+// tests for specs that are currently disabled in spector-runner.config.js -- and therefore
 // have no generated code or go.mod -- are skipped instead of failing with
 // "directory ... does not contain main module".
 //
diff --git a/packages/typespec-go/.scripts/lint-go.js b/packages/typespec-go/.scripts/lint-go.js
index 6123517765..431f64918b 100644
--- a/packages/typespec-go/.scripts/lint-go.js
+++ b/packages/typespec-go/.scripts/lint-go.js
@@ -4,7 +4,7 @@
 // Runs golangci-lint and shadow against every Go module (a directory containing
 // a go.mod) under test/local/, test/http-specs/ and test/azure-http-specs/.
 // Discovery is module-based so directories holding hand-written tests for specs
-// currently disabled in tspcompile.js -- which have no generated code or go.mod
+// currently disabled in spector-runner.config.js -- which have no generated code or go.mod
 // after a fresh regenerate -- are skipped. Expects golangci-lint and `shadow`
 // to be available on PATH (installed by CI).
 
diff --git a/packages/typespec-go/.scripts/semaphore.js b/packages/typespec-go/.scripts/semaphore.js
deleted file mode 100644
index dd450b7065..0000000000
--- a/packages/typespec-go/.scripts/semaphore.js
+++ /dev/null
@@ -1,104 +0,0 @@
-// Licensed under the MIT License. See License.txt in the project root for license information.
-// original sources can be found at https://github.com/abrkn/semaphore.js
-"use strict";
-
-var nextTick = function (fn) {
-  setTimeout(fn, 0);
-};
-if (typeof process != "undefined" && process && typeof process.nextTick == "function") {
-  // node.js and the like
-  nextTick = process.nextTick;
-}
-
-export function semaphore(capacity) {
-  var semaphore = {
-    capacity: capacity || 1,
-    current: 0,
-    queue: [],
-    firstHere: false,
-
-    take: function () {
-      if (semaphore.firstHere === false) {
-        semaphore.current++;
-        semaphore.firstHere = true;
-        var isFirst = 1;
-      } else {
-        var isFirst = 0;
-      }
-      var item = { n: 1 };
-
-      if (typeof arguments[0] == "function") {
-        item.task = arguments[0];
-      } else {
-        item.n = arguments[0];
-      }
-
-      if (arguments.length >= 2) {
-        if (typeof arguments[1] == "function") item.task = arguments[1];
-        else item.n = arguments[1];
-      }
-
-      var task = item.task;
-      item.task = function () {
-        task(semaphore.leave);
-      };
-
-      if (semaphore.current + item.n - isFirst > semaphore.capacity) {
-        if (isFirst === 1) {
-          semaphore.current--;
-          semaphore.firstHere = false;
-        }
-        return semaphore.queue.push(item);
-      }
-
-      semaphore.current += item.n - isFirst;
-      item.task(semaphore.leave);
-      if (isFirst === 1) semaphore.firstHere = false;
-    },
-
-    leave: function (n) {
-      n = n || 1;
-
-      semaphore.current -= n;
-
-      if (!semaphore.queue.length) {
-        if (semaphore.current < 0) {
-          throw new Error("leave called too many times.");
-        }
-
-        return;
-      }
-
-      var item = semaphore.queue[0];
-
-      if (item.n + semaphore.current > semaphore.capacity) {
-        return;
-      }
-
-      semaphore.queue.shift();
-      semaphore.current += item.n;
-
-      nextTick(item.task);
-    },
-
-    available: function (n) {
-      n = n || 1;
-      return semaphore.current + n <= semaphore.capacity;
-    },
-  };
-
-  return semaphore;
-}
-
-if (typeof exports === "object") {
-  // node export
-  module.exports = semaphore;
-} else if (typeof define === "function" && define.amd) {
-  // amd export
-  define(function () {
-    return semaphore;
-  });
-} else {
-  // browser global
-  global.semaphore = semaphore;
-}
diff --git a/packages/typespec-go/.scripts/spector-runner.config.js b/packages/typespec-go/.scripts/spector-runner.config.js
new file mode 100644
index 0000000000..2304a7d0c5
--- /dev/null
+++ b/packages/typespec-go/.scripts/spector-runner.config.js
@@ -0,0 +1,183 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+//
+// Regeneration config for the Go emitter, driven by the shared
+// `@azure-tools/spector-runner` CLI:
+//
+//   spector-runner --config-file .scripts/spector-runner.config.js [--filter <regex>] [--verbose]
+//
+// The CLI owns parsing (`--filter`, `--jobs`, `--verbose`, `--cwd`), parallel
+// `tsp compile` scheduling, reporting, and the hook lifecycle. This file only
+// declares *what* to compile (scenarios) and the Go-specific pre/post steps.
+//
+// Two rarely-used toggles are read from the environment (the CLI has no matching
+// flags): set `TYPESPEC_GO_EMITTER_INSTALLED=1` to emit with the installed
+// package instead of the local build, and `TYPESPEC_GO_DEBUGGER=1` to pass the
+// emitter `debugger` option.
+import { buildScenarios, defineConfig } from "@azure-tools/spector-runner";
+import { existsSync, opendirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+import { syncAzureRestApiSpecs } from "./sync-azure-rest-api-specs.js";
+
+// limit to 8 concurrent builds
+const MAX_JOBS = 8;
+
+// Emitter *name*, used as the key for emitter options regardless of whether we
+// emit against the locally-built package (a path) or the installed package.
+const EMITTER_NAME = "@azure-tools/typespec-go";
+
+const pkgRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Stub tspconfig passed to every compile so that upstream tspconfig.yaml files
+// (e.g. those shipped with azure-rest-api-specs) don't bleed emitter options
+// into our regenerated test output. See .scripts/tspconfig.yaml.
+const stubConfig = resolve(pkgRoot, ".scripts/tspconfig.yaml");
+
+const httpSpecs = resolve(pkgRoot, "node_modules/@typespec/http-specs/specs") + "/";
+const azureHttpSpecs = resolve(pkgRoot, "node_modules/@azure-tools/azure-http-specs/specs") + "/";
+
+// default to using the locally built emitter unless told to use the installed one.
+const emitter = process.env.TYPESPEC_GO_EMITTER_INSTALLED ? EMITTER_NAME : pkgRoot;
+const useDebugger = process.env.TYPESPEC_GO_DEBUGGER !== undefined;
+
+// Emitter options applied to every module unless a spec overrides them by key.
+// TODO: disable examples by default https://github.com/Azure/autorest.go/issues/1441
+const defaultOptions = {
+  "generate-fakes": true,
+  "inject-spans": true,
+  "head-as-boolean": true,
+  "fix-const-stuttering": true,
+  "file-prefix": "zz_",
+};
+if (useDebugger) {
+  defaultOptions.debugger = true;
+}
+
+// Resolve a local input to its entry file: an explicit .tsp, else client.tsp
+// preferred over main.tsp.
+function entrypoint(input) {
+  if (input.endsWith(".tsp")) {
+    return input;
+  }
+  return existsSync(input + "/client.tsp") ? input + "/client.tsp" : input + "/main.tsp";
+}
+
+// Build a CompileScenario for a spec that isn't in the shared spector config.
+function local(moduleName, input, outputDir, options = {}) {
+  const merged = { ...defaultOptions, ...options };
+  // A containing-module replaces the per-module output; otherwise pass module.
+  if (merged["containing-module"] === undefined) {
+    merged.module = moduleName;
+  }
+  merged["emitter-output-dir"] = resolve(pkgRoot, outputDir);
+  return {
+    name: moduleName,
+    entrypoint: entrypoint(input),
+    emit: [emitter],
+    options: { [EMITTER_NAME]: merged },
+  };
+}
+
+// The spec-selection config (spector.config.*.yaml) plus these driver settings
+// are all buildScenarios needs to expand the http/azure-http scenarios; it
+// handles output-dir + option merging.
+const shared = {
+  emit: [emitter],
+  emitterName: EMITTER_NAME,
+  options: defaultOptions,
+  cwd: pkgRoot,
+};
+
+export default defineConfig({
+  cwd: pkgRoot,
+  jobs: MAX_JOBS,
+  tspconfig: stubConfig,
+  scenarios: (ctx) => {
+    const shouldGenerate = (name) => ctx.filter === undefined || new RegExp(ctx.filter).test(name);
+
+    // Service specs come from Azure/azure-rest-api-specs at a pinned commit
+    // (see .scripts/azure-rest-api-specs.json). Only sync (a network clone,
+    // no-op when cached) when a spec that needs them is actually selected.
+    const needsServiceSpecs = shouldGenerate("azkeys") || shouldGenerate("azblob");
+    const azureServiceSpecs = needsServiceSpecs ? syncAzureRestApiSpecs() + "/" : undefined;
+
+    return [
+      ...buildScenarios({
+        ...shared,
+        config: resolve(pkgRoot, "spector.config.http.yaml"),
+        specsRoot: httpSpecs,
+        outputDir: "test/http-specs/{parentDir}/{options.module}",
+      }),
+      ...buildScenarios({
+        ...shared,
+        config: resolve(pkgRoot, "spector.config.azure.yaml"),
+        specsRoot: azureHttpSpecs,
+        outputDir: "test/azure-http-specs/{parentDir}/{options.module}",
+      }),
+      // Local specs that aren't part of the shared spector spec packages: azkeys
+      // and azblob come from azure-rest-api-specs; the rest are checked-in test tsp.
+      azureServiceSpecs &&
+        local(
+          "azkeys",
+          azureServiceSpecs + "specification/keyvault/data-plane/Keys/client.tsp",
+          "test/local/azkeys",
+          { "single-client": true, "omit-constructors": true },
+        ),
+      azureServiceSpecs &&
+        local(
+          "azblob",
+          azureServiceSpecs + "specification/storage/data-plane/BlobStorage/client.tsp",
+          "test/local/azblob",
+          { "generate-fakes": false, "omit-constructors": true, "inject-spans": false },
+        ),
+      local("gogenerate", resolve(pkgRoot, "test/tsp/GoGenerate"), "test/local/gogenerate", {
+        "generate-fakes": false,
+        "go-generate": "after_generate.go",
+      }),
+      local("fakeserver", resolve(pkgRoot, "test/tsp/FakeServer"), "test/local/fakeserver"),
+      local(
+        "containingmod",
+        resolve(pkgRoot, "test/tsp/ContainingMod"),
+        "test/local/containingmod/subpkg",
+        { "containing-module": "containingmod" },
+      ),
+    ].filter((scenario) => scenario);
+  },
+  // Per-scenario post-processing that used to run after each subprocess compile.
+  postScenario: (result) => {
+    const fullOutputDir = result.scenario.options[EMITTER_NAME]["emitter-output-dir"];
+    if (result.success) {
+      // Force emitter version to a constant in _metadata.json to avoid unnecessary
+      // version drift in committed files.
+      const metadataPath = `${fullOutputDir}/testdata/_metadata.json`;
+      if (existsSync(metadataPath)) {
+        const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
+        metadata.emitterVersion = "0.0.0";
+        writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + "\n");
+      }
+    } else {
+      // delete files on error so it's easy to spot codegen failures
+      cleanGeneratedFiles(fullOutputDir);
+    }
+  },
+});
+
+function cleanGeneratedFiles(outputDir) {
+  if (!existsSync(outputDir)) {
+    return;
+  }
+  const dir = opendirSync(outputDir);
+  while (true) {
+    const dirEnt = dir.readSync();
+    if (dirEnt === null) {
+      break;
+    }
+    // preserve the version.go file so we can test the v2+ major version scenario
+    if (dirEnt.isFile() && dirEnt.name.startsWith("zz_") && dirEnt.name !== "zz_version.go") {
+      unlinkSync(dir.path + "/" + dirEnt.name);
+    }
+  }
+  dir.close();
+  cleanGeneratedFiles(outputDir + "/fake");
+}
diff --git a/packages/typespec-go/.scripts/sync-azure-rest-api-specs.js b/packages/typespec-go/.scripts/sync-azure-rest-api-specs.js
index cf153946c8..638e3cf0dd 100644
--- a/packages/typespec-go/.scripts/sync-azure-rest-api-specs.js
+++ b/packages/typespec-go/.scripts/sync-azure-rest-api-specs.js
@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License. See License.txt in the project root for license information.
 //
-// Syncs the subset of Azure/azure-rest-api-specs needed by tspcompile.js
+// Syncs the subset of Azure/azure-rest-api-specs needed by spector-runner.config.js
 // into ./temp/azure-rest-api-specs at a pinned commit. Uses a sparse,
 // blobless, shallow clone so that only the listed spec folders are
 // downloaded. Safe to re-run: skips work when the cache is already at
diff --git a/packages/typespec-go/.scripts/tspcompile.js b/packages/typespec-go/.scripts/tspcompile.js
deleted file mode 100644
index 38d1584b24..0000000000
--- a/packages/typespec-go/.scripts/tspcompile.js
+++ /dev/null
@@ -1,284 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// Licensed under the MIT License. See License.txt in the project root for license information.
-import { loadSpectorConfig, resolveSpecs } from "@azure-tools/spector-runner";
-import { exec, execSync } from "child_process";
-import { existsSync, opendirSync, readFileSync, unlinkSync, writeFileSync } from "fs";
-import { semaphore } from "./semaphore.js";
-import { syncAzureRestApiSpecs } from "./sync-azure-rest-api-specs.js";
-
-// limit to 8 concurrent builds
-const sem = semaphore(8);
-
-const pkgRoot =
-  execSync("git rev-parse --show-toplevel").toString().trim() + "/packages/typespec-go/";
-
-const httpSpecs = pkgRoot + "node_modules/@typespec/http-specs/specs/";
-const azureHttpSpecs = pkgRoot + "node_modules/@azure-tools/azure-http-specs/specs/";
-
-// Service specs come from Azure/azure-rest-api-specs at a pinned commit
-// (see .scripts/azure-rest-api-specs.json). The sync call is a no-op when
-// the cache already matches the pin.
-const azureServiceSpecs = syncAzureRestApiSpecs() + "/";
-
-const compiler = pkgRoot + "node_modules/@typespec/compiler/cmd/tsp.js";
-
-// Stub tspconfig used for every compile so that upstream tspconfig.yaml files
-// (e.g. those shipped with azure-rest-api-specs) don't bleed emitter options
-// from azure-sdk-for-go into our regenerated test fixtures.
-const stubConfig = pkgRoot + ".scripts/tspconfig.yaml";
-
-// Spec selection lives in the opt-in `spector.config.*.yaml` files (see
-// Azure/typespec-azure#4997), parsed by the shared @azure-tools/spector-runner
-// package. Each enabled spec resolves to a `module` option (the Go module name) plus any
-// per-test emitter options. We rebuild the legacy group shape below so the rest of this
-// script (loopSpec/generate) is unchanged.
-//
-// legacy group shape: { 'moduleName': [ 'input', 'emitter option 1', ... ] }
-// if no .tsp file is specified in input, it's assumed to be main.tsp
-function loadGroup(configPath) {
-  const group = {};
-  for (const { path, options } of resolveSpecs(loadSpectorConfig(configPath))) {
-    const { module, ...rest } = options;
-    if (module === undefined) {
-      throw new Error(`spec "${path}" in ${configPath} is missing the required "module" option`);
-    }
-    const optionArgs = Object.entries(rest).map(([key, value]) => `${key}=${value}`);
-    if (group[module] !== undefined) {
-      throw new Error(`duplicate module "${module}" in ${configPath}`);
-    }
-    group[module] = [path, ...optionArgs];
-  }
-  return group;
-}
-
-const httpSpecsGroup = loadGroup(pkgRoot + "spector.config.http.yaml");
-const azureHttpSpecsGroup = loadGroup(pkgRoot + "spector.config.azure.yaml");
-
-// default to using the locally built emitter
-let emitter = pkgRoot;
-const args = process.argv.slice(2);
-var filter = undefined;
-const switches = [];
-for (var i = 0; i < args.length; i += 1) {
-  const filterArg = args[i].match(/--filter=(?<filter>\w+)/);
-  if (filterArg) {
-    filter = filterArg.groups["filter"];
-    continue;
-  }
-
-  switch (args[i]) {
-    case "--verbose":
-      switches.push("--verbose");
-      break;
-    case "--emitter-installed":
-      // the emitter has been installed so use that one instead
-      emitter = "@azure-tools/typespec-go";
-      break;
-    default:
-      break;
-  }
-}
-
-if (filter !== undefined) {
-  console.log("Using filter: " + filter);
-}
-
-function should_generate(name) {
-  if (filter !== undefined) {
-    const re = new RegExp(filter);
-    return re.test(name);
-  }
-  return true;
-}
-
-const azkeys = azureServiceSpecs + "specification/keyvault/data-plane/Keys/client.tsp";
-generate("azkeys", azkeys, "test/local/azkeys", ["single-client=true", "omit-constructors=true"]);
-
-const azblob = azureServiceSpecs + "specification/storage/data-plane/BlobStorage/client.tsp";
-generate("azblob", azblob, "test/local/azblob", [
-  "generate-fakes=false",
-  "omit-constructors=true",
-  "inject-spans=false",
-]);
-
-const gogenerate = pkgRoot + "test/tsp/GoGenerate";
-generate("gogenerate", gogenerate, "test/local/gogenerate", [
-  "generate-fakes=false",
-  "go-generate=after_generate.go",
-]);
-
-const fakeserver = pkgRoot + "test/tsp/FakeServer";
-generate("fakeserver", fakeserver, "test/local/fakeserver");
-
-const containingmod = pkgRoot + "test/tsp/ContainingMod";
-generate("containingmod", containingmod, "test/local/containingmod/subpkg", [
-  "containing-module=containingmod",
-]);
-
-loopSpec(httpSpecsGroup, httpSpecs, "test/http-specs");
-loopSpec(azureHttpSpecsGroup, azureHttpSpecs, "test/azure-http-specs");
-
-function loopSpec(group, root, prefix) {
-  for (const module in group) {
-    const values = group[module];
-    let perTestOptions;
-    if (values.length > 1) {
-      perTestOptions = values.slice(1);
-    }
-    // keep the output directory structure similar to the cadl input directory.
-    // remove the last dir from the input path as we'll use the module name instead.
-    // if the input specifies a .tsp file, remove that first.
-    let outDir = values[0];
-    if (outDir.lastIndexOf(".tsp") > -1) {
-      outDir = outDir.substring(0, outDir.lastIndexOf("/"));
-    }
-    outDir = outDir.substring(0, outDir.lastIndexOf("/"));
-    generate(module, root + values[0], `${prefix}/${outDir}/` + module, perTestOptions);
-  }
-}
-
-function generate(moduleName, input, outputDir, perTestOptions) {
-  if (!should_generate(moduleName)) {
-    return;
-  }
-  if (perTestOptions === undefined) {
-    perTestOptions = [];
-  }
-
-  const fullOutputDir = pkgRoot + outputDir;
-
-  // check for containing-module and swap out module for it as needed
-  let outputKind = `module=${moduleName}`;
-  for (const perTestOption of perTestOptions) {
-    if (perTestOption.match(/containing\-module/)) {
-      outputKind = perTestOption;
-      break;
-    }
-  }
-
-  // these options can't be changed per test
-  const fixedOptions = [outputKind, `emitter-output-dir=${fullOutputDir}`, "file-prefix=zz_"];
-
-  // these options _can_ be changed per test
-  // TODO: disabled examples by default https://github.com/Azure/autorest.go/issues/1441
-  const defaultOptions = [
-    "generate-fakes=true",
-    "inject-spans=true",
-    "head-as-boolean=true",
-    "fix-const-stuttering=true",
-  ];
-
-  let allOptions = fixedOptions;
-
-  // merge in any per-test options.
-  // if a per-test option overlaps with a default option, use the per-test one.
-  for (const perTestOption of perTestOptions) {
-    // perTestOption === 'option=value', grab the option name
-    const optionName = perTestOption.match(/^([a-zA-Z0-9_-]+)/)[0];
-    const index = defaultOptions.findIndex((value, index, obj) => {
-      return value.startsWith(optionName);
-    });
-    if (index > -1) {
-      // found a match, replace the default option with the per-test one
-      defaultOptions[index] = perTestOption;
-    } else {
-      allOptions.push(perTestOption);
-    }
-  }
-
-  allOptions = allOptions.concat(defaultOptions);
-
-  sem.take(function () {
-    // if a tsp file isn't specified, first check
-    // for a client.tsp file. if that doesn't exist
-    // then fall back to main.tsp.
-    if (input.lastIndexOf(".tsp") === -1) {
-      if (existsSync(input + "/client.tsp")) {
-        input += "/client.tsp";
-      } else {
-        input += "/main.tsp";
-      }
-    }
-    console.log("generating " + input);
-    const options = [];
-    for (const option of allOptions) {
-      options.push(`--option="@azure-tools/typespec-go.${option}"`);
-    }
-    if (switches.includes("--debugger")) {
-      options.push(`--option="@azure-tools/typespec-go.debugger=true"`);
-    }
-    const command = `node ${compiler} compile ${input} --emit=${emitter} --config=${stubConfig} ${options.join(" ")}`;
-    if (switches.includes("--verbose")) {
-      console.log(command);
-    }
-    exec(command, function (error, stdout, stderr) {
-      try {
-        // print any output or error from the tsp compile command
-        logResult(error, stdout, stderr);
-        // format on success
-        if (error === null) {
-          // Force emitter version to a constant in _metadata.json to avoid unnecessary version drift in committed files
-          const metadataPath = `${fullOutputDir}/testdata/_metadata.json`;
-          if (existsSync(metadataPath)) {
-            const metadata = JSON.parse(readFileSync(metadataPath, "utf8"));
-            metadata.emitterVersion = "0.0.0";
-            writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + "\n");
-          }
-        } else {
-          // delete files on error so it's easy to spot codegen failures
-          cleanGeneratedFiles(fullOutputDir);
-          // record the failure so the script exits non-zero; otherwise an emit
-          // error here would only surface later as a downstream lint failure.
-          process.exitCode = 1;
-        }
-      } catch (err) {
-        console.error("An error occurred:");
-        if (err.message) {
-          console.error("Message:", err.message);
-        }
-        if (err.stack) {
-          console.error("Stack:", err.stack);
-        }
-        if (err.output) {
-          console.error("Output:", err.output.toString());
-        }
-      } finally {
-        sem.leave();
-      }
-    });
-  });
-}
-
-function cleanGeneratedFiles(outputDir) {
-  if (!existsSync(outputDir)) {
-    return;
-  }
-  const dir = opendirSync(outputDir);
-  while (true) {
-    const dirEnt = dir.readSync();
-    if (dirEnt === null) {
-      break;
-    }
-    // preserve the version.go file so we can test the v2+ major version scenario
-    if (dirEnt.isFile() && dirEnt.name.startsWith("zz_") && dirEnt.name !== "zz_version.go") {
-      unlinkSync(dir.path + "/" + dirEnt.name);
-    }
-  }
-  dir.close();
-  cleanGeneratedFiles(outputDir + "/fake");
-}
-
-function logResult(error, stdout, stderr) {
-  if (stdout !== "") {
-    console.log("stdout: " + stdout);
-  }
-  // typespec compiler prints compiler progress to stderr
-  // but it's not an error, so we use console.log
-  // to print it out.
-  if (stderr !== "") {
-    console.log("stderr: " + stderr);
-  }
-  if (error !== null) {
-    console.error("\x1b[91m%s\x1b[0m", "exec error: " + error);
-  }
-}
diff --git a/packages/typespec-go/.scripts/tspconfig.yaml b/packages/typespec-go/.scripts/tspconfig.yaml
index 6c957c8fa5..89a4524b8d 100644
--- a/packages/typespec-go/.scripts/tspconfig.yaml
+++ b/packages/typespec-go/.scripts/tspconfig.yaml
@@ -1,4 +1,4 @@
-# Stub tspconfig used by .scripts/tspcompile.js when emitting against specs
+# Stub tspconfig used by .scripts/spector-runner.config.js when emitting against specs
 # imported from Azure/azure-rest-api-specs. Upstream specs ship their own
 # tspconfig.yaml with @azure-tools/typespec-go options (module, containing-
 # module, go-generate, etc.) that target sdk/azure-sdk-for-go. Pointing tsp at
diff --git a/packages/typespec-go/package.json b/packages/typespec-go/package.json
index dd08da07a8..396c6bb90d 100644
--- a/packages/typespec-go/package.json
+++ b/packages/typespec-go/package.json
@@ -42,7 +42,7 @@
     "test:go:e2e": "pnpm spector --start && pnpm go-test && pnpm spector --stop",
     "go-test": "node .scripts/go-test.js",
     "lint:go": "node .scripts/lint-go.js",
-    "tspcompile": "node .scripts/tspcompile.js",
+    "tspcompile": "spector-runner --config-file .scripts/spector-runner.config.js",
     "spector": "node .scripts/spector.js",
     "sync-specs": "node .scripts/sync-azure-rest-api-specs.js",
     "diff-regen-code": "node ../../core/eng/emitter-diff/src/cli.ts --command \"npm run tspcompile\" --emitter-path packages/typespec-go --generated-code-path test/http-specs,test/azure-http-specs,test/local --setup \"git submodule update --init --recursive\" --setup \"pnpm install\" --setup \"npm run build:deps\"",
diff --git a/packages/typespec-python/eng/scripts/ci/regenerate.ts b/packages/typespec-python/eng/scripts/ci/regenerate.ts
index 5638b29209..f617acfe17 100644
--- a/packages/typespec-python/eng/scripts/ci/regenerate.ts
+++ b/packages/typespec-python/eng/scripts/ci/regenerate.ts
@@ -2,14 +2,13 @@
 /**
  * Regenerates Python SDK code from TypeSpec definitions.
  *
- * Uses in-process TypeSpec compilation to avoid subprocess spawning overhead.
- * Specs are compiled in parallel and the emitter writes the final `.py` files
- * directly inside the same process — no YAML-only intermediate, no batched
- * Python subprocess.  This single-phase pipeline is faster for the wrapper
- * use-case (azure flavor only, smaller spec set, Windows).
- *
- * Shared helpers/data live in `regenerate-common.ts` and are kept identical
- * with the upstream `@typespec/http-client-python` copy via `pnpm sync`.
+ * Spec selection comes from `spector.config.yaml` (see Azure/typespec-azure#4997);
+ * per-spec emitter options and output layout come from the upstream-synced tables
+ * in `regenerate-common.ts`. Each resulting task is compiled by spawning a
+ * `tsp compile` subprocess through the shared `@azure-tools/spector-runner`
+ * engine, so this wrapper and the Go/TS wrappers share one parallel-compile +
+ * reporting engine (the engine is intended to move into `core/` and be reused
+ * by upstream `@typespec/http-client-python`).
  */
 
 import { platform } from "os";
@@ -18,16 +17,24 @@ import pc from "picocolors";
 import { fileURLToPath } from "url";
 import { parseArgs } from "util";
 
-import { isSpecEnabled, loadSpectorConfig, SpectorConfig } from "@azure-tools/spector-runner";
+import type { CompileScenario, SpectorRunnerConfig } from "@azure-tools/spector-runner";
+import {
+  isSpecEnabled,
+  loadSpectorConfig,
+  runConfig,
+  SpectorConfig,
+} from "@azure-tools/spector-runner";
+import { rmSync } from "fs";
 
 import {
   buildTaskGroups,
+  defaultPackageName,
   getSubdirectories,
   prepareBaselineOfGeneratedCode,
   preprocess,
   RegenerateContext,
   RegenerateFlags,
-  runParallel,
+  TaskGroup,
 } from "./regenerate-common.js";
 
 const argv = parseArgs({
@@ -49,9 +56,9 @@ if (argv.values.help) {
 ${pc.bold("Usage:")} tsx regenerate.ts [options]
 
 ${pc.bold("Description:")}
-  Regenerates Python SDK code from TypeSpec definitions using in-process
-  compilation.  This avoids spawning a new Node.js process for each spec,
-  making it significantly faster.
+  Regenerates Python SDK code from TypeSpec definitions. Each spec is compiled
+  by spawning a \`tsp compile\` subprocess through the shared spector-runner
+  engine, run in parallel across specs.
 
 ${pc.bold("Options:")}
   ${pc.cyan("-f, --flavor <azure|unbranded>")}
@@ -139,6 +146,29 @@ function filterOptedIn(specs: string[]): { kept: string[]; skipped: string[] } {
   return { kept, skipped };
 }
 
+/**
+ * Flatten the upstream {@link buildTaskGroups} output into shared-engine
+ * {@link CompileScenario}s: one scenario per task. Each spec's option-sets and
+ * output dirs come from `buildTaskGroups` (upstream-synced data); this only maps
+ * that data onto the scenario shape the engine compiles.
+ */
+function groupsToScenarios(groups: TaskGroup[], ctx: RegenerateContext): CompileScenario[] {
+  const scenarios: CompileScenario[] = [];
+  for (const group of groups) {
+    for (const task of group.tasks) {
+      const packageName =
+        (task.options["package-name"] as string) || defaultPackageName(group.spec, ctx);
+      scenarios.push({
+        name: packageName,
+        entrypoint: task.spec,
+        emit: [ctx.pluginDir],
+        options: { [ctx.emitterName]: task.options },
+      });
+    }
+  }
+  return scenarios;
+}
+
 async function regenerateFlavor(
   flavor: string,
   name: string | undefined,
@@ -151,36 +181,54 @@ async function regenerateFlavor(
 
   const flags: RegenerateFlags = { flavor, debug, name };
 
-  await preprocess(flavor, GENERATED_FOLDER);
-
-  const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : [];
-  const standardSpecs = await getSubdirectories(HTTP_SPECS, flags);
-  const discovered = [...azureSpecs, ...standardSpecs];
-
-  const { kept: allSpecs, skipped } = filterOptedIn(discovered);
-  if (skipped.length > 0) {
-    console.log(pc.yellow(`Skipping ${skipped.length} spec(s) not opted into spector.config.yaml`));
-  }
-
-  const groups = buildTaskGroups(allSpecs, flags, ctx);
-  const totalTasks = groups.reduce((sum, g) => sum + g.tasks.length, 0);
-
-  console.log(pc.cyan(`Found ${allSpecs.length} specs (${totalTasks} total tasks) to compile`));
-  console.log(pc.cyan(`Using ${jobs} parallel jobs\n`));
+  // Drive this flavor through the shared @azure-tools/spector-runner engine:
+  // `preRun` prepares the generator, the scenario builder expands the
+  // upstream-synced task groups, and `postScenario` wipes partial output on a
+  // failure (matching the previous in-process behavior).
+  const config: SpectorRunnerConfig = {
+    cwd: ctx.pluginDir,
+    jobs,
+    preRun: () => preprocess(flavor, GENERATED_FOLDER),
+    scenarios: async () => {
+      const azureSpecs = flavor === "azure" ? await getSubdirectories(AZURE_HTTP_SPECS, flags) : [];
+      const standardSpecs = await getSubdirectories(HTTP_SPECS, flags);
+      const { kept, skipped } = filterOptedIn([...azureSpecs, ...standardSpecs]);
+      if (skipped.length > 0) {
+        console.log(
+          pc.yellow(`Skipping ${skipped.length} spec(s) not opted into spector.config.yaml`),
+        );
+      }
+
+      const groups = buildTaskGroups(kept, flags, ctx);
+      const scenarios = groupsToScenarios(groups, ctx);
+      console.log(
+        pc.cyan(`Found ${kept.length} specs (${scenarios.length} total tasks) to compile`),
+      );
+      console.log(pc.cyan(`Using ${jobs} parallel jobs\n`));
+      return scenarios;
+    },
+    postScenario: (result) => {
+      if (!result.success) {
+        // Match the previous in-process behavior: wipe partial output on failure.
+        const outputDir = result.scenario.options?.[ctx.emitterName]?.["emitter-output-dir"] as
+          string | undefined;
+        if (outputDir) {
+          rmSync(outputDir, { recursive: true, force: true });
+        }
+      }
+    },
+  };
 
   const startTime = performance.now();
-  const results = await runParallel(groups, jobs, ctx);
+  const summary = await runConfig(config, { jobs });
   const duration = (performance.now() - startTime) / 1000;
 
-  const succeeded = Array.from(results.values()).filter((v) => v).length;
-  const failed = results.size - succeeded;
-
   console.log(pc.cyan(`\n${"=".repeat(60)}`));
-  console.log(pc.cyan(`Results: ${succeeded} succeeded, ${failed} failed`));
+  console.log(pc.cyan(`Results: ${summary.succeeded} succeeded, ${summary.failed} failed`));
   console.log(pc.cyan(`Time: ${duration.toFixed(1)}s`));
   console.log(pc.cyan(`${"=".repeat(60)}\n`));
 
-  return failed === 0;
+  return summary.failed === 0;
 }
 
 async function main(): Promise<void> {
@@ -195,7 +243,7 @@ async function main(): Promise<void> {
 
   console.log(pc.cyan(`\nRegeneration config:`));
   console.log(pc.cyan(`  Platform: ${isWindows ? "Windows" : "Unix"}`));
-  console.log(pc.cyan(`  Mode:     in-process compilation (single-phase)`));
+  console.log(pc.cyan(`  Mode:     tsp compile subprocess (spector-runner engine)`));
   console.log(pc.cyan(`  Jobs:     ${jobs}`));
   if (name) {
     console.log(pc.cyan(`  Filter:   ${name}`));
diff --git a/packages/typespec-ts/package.json b/packages/typespec-ts/package.json
index 4fbf8bcda3..f18bf50ae7 100644
--- a/packages/typespec-ts/package.json
+++ b/packages/typespec-ts/package.json
@@ -28,9 +28,9 @@
     "start-test-server": "node ./test/commands/start-test-server.js",
     "copy:typespec": "node ./test/commands/copy-typespec.ts",
     "generate-and-run": "pnpm generate-tsp-only:client && concurrently --kill-others-on-fail \"pnpm integration-test:alone\" \"pnpm generate-tsp-only:declarations\" && pnpm stop-test-server",
-    "generate-tsp-only": "node ./test/commands/gen-spector.js",
-    "generate-tsp-only:client": "node ./test/commands/gen-spector.js --phase=client",
-    "generate-tsp-only:declarations": "node ./test/commands/gen-spector.js --phase=declarations",
+    "generate-tsp-only": "spector-runner --config spector.config.yaml --jobs 4",
+    "generate-tsp-only:client": "spector-runner --config spector.config.yaml --phase compile --jobs 4",
+    "generate-tsp-only:declarations": "spector-runner --config spector.config.yaml --phase declarations --jobs 4",
     "regen-test-baselines": "pnpm generate-tsp-only",
     "integration-test:alone": "vitest run --project integration-azure-modular",
     "stop-test-server": "pnpm exec tsp-spector server stop -p 3002",
diff --git a/packages/typespec-ts/spector.config.yaml b/packages/typespec-ts/spector.config.yaml
index adaa7e0d2c..dfb50a0959 100644
--- a/packages/typespec-ts/spector.config.yaml
+++ b/packages/typespec-ts/spector.config.yaml
@@ -3,6 +3,28 @@
 # Spec selection for @azure-tools/typespec-ts (opt-in).
 # See Azure/typespec-azure#4997. Keys are spec paths under temp/specs;
 # `outputPath` (when different from the key) is the generated folder.
+#
+# The shared `spector-runner` CLI drives the whole regeneration from this file:
+#   spector-runner --config spector.config.yaml --phase <all|compile|declarations>
+# Each spec compiles using the committed tspconfig.yaml in its output folder,
+# then the per-instance hooks run (see the hook scripts under test/commands).
+
+# Root the spec-path keys resolve against.
+specsRoot: temp/specs
+
+# Each spec's generated output folder.
+outputDir: test/azure-modular-integration/generated/{outputPath}
+
+# Compile using the committed tspconfig.yaml inside each output folder (it names
+# the emitter + per-package options), rather than synthesized --emit/--option.
+compileConfig: tspconfig.yaml
+
+# Per-instance lifecycle hooks (SPECTOR_OUTPUT_DIR points at the output folder).
+hooks:
+  # Cheap client post-processing: emit .gitignore + a self-contained test tsconfig.
+  postCompile: node ./test/commands/post-compile.js
+  # Public-surface baseline: tsc .d.ts + api-extractor rollup into src/index.d.ts.
+  postCompileDeclarations: node ./test/commands/emit-declarations.ts
 
 specs:
   versioning/removed:
diff --git a/packages/typespec-ts/test/commands/emit-declarations.ts b/packages/typespec-ts/test/commands/emit-declarations.ts
new file mode 100644
index 0000000000..256972e591
--- /dev/null
+++ b/packages/typespec-ts/test/commands/emit-declarations.ts
@@ -0,0 +1,174 @@
+/* eslint-disable no-console */
+// postCompileDeclarations hook: run once per spec by the shared spector-runner
+// engine in the `declarations` phase (SPECTOR_OUTPUT_DIR points at the generated
+// folder). Emits the public-surface baseline — tsc `.d.ts` files plus the
+// api-extractor rollup into `src/index.d.ts` (the only committed generated file).
+// This is a plain `tsc + api-extractor` pass over already-generated sources, so
+// it runs off the client/test critical path.
+import type { IExtractorConfigPrepareOptions } from "@microsoft/api-extractor";
+import { Extractor, ExtractorConfig, ExtractorLogLevel } from "@microsoft/api-extractor";
+import { join as joinPath } from "path";
+import type { CompilerOptions } from "typescript";
+import { createProgram } from "typescript";
+import { createTaskLogger } from "./logger.js";
+
+function deepMerge(target: any, source: any): any {
+  const result = { ...target };
+  for (const key of Object.keys(source)) {
+    if (
+      source[key] &&
+      typeof source[key] === "object" &&
+      !Array.isArray(source[key]) &&
+      target[key] &&
+      typeof target[key] === "object" &&
+      !Array.isArray(target[key])
+    ) {
+      result[key] = deepMerge(target[key], source[key]);
+    } else {
+      result[key] = source[key];
+    }
+  }
+  return result;
+}
+
+const declarationSubpath = "types";
+
+/**
+ * Emit the public-surface baseline for a generated package: tsc `.d.ts` files
+ * plus the api-extractor rollup into `src/index.d.ts`.
+ */
+export function emitDeclarations(outputPath: string): void {
+  const logger = createTaskLogger();
+  logger.log(`=== Start declarations ${outputPath} ===`);
+  try {
+    logger.log("=== Emitting declaration files ===");
+    emitDeclarationFiles(outputPath, logger);
+    logger.log("=== Emitting API summary ===");
+    emitDeclarationRollup(outputPath, logger);
+    logger.log(`=== End declarations ${outputPath} ===`);
+  } catch (e: any) {
+    logger.error(e.toString());
+    logger.flush();
+    throw e;
+  }
+  logger.flush();
+}
+
+function emitDeclarationFiles(
+  outputPath: string,
+  logger: ReturnType<typeof createTaskLogger>,
+): void {
+  const program = createProgram({
+    options: declarationTsconfig(outputPath).compilerOptions,
+    rootNames: [joinPath(outputPath, "src/index.ts")],
+  });
+
+  // side effect: loads source files into memory
+  // nothing will be emitted if this is omitted
+  program.getSourceFiles();
+
+  const { diagnostics } = program.emit();
+
+  if (diagnostics.length) {
+    logger.log(`Compiler diagnostics for ${outputPath}`);
+    diagnostics.forEach((diagnostic) => logger.log(diagnostic.messageText));
+  }
+}
+
+function emitDeclarationRollup(
+  outputPath: string,
+  logger: ReturnType<typeof createTaskLogger>,
+): void {
+  Extractor.invoke(extractorConfig(outputPath), {
+    localBuild: true,
+    messageCallback: (message) => {
+      switch (message.logLevel) {
+        case ExtractorLogLevel.None:
+          break;
+        default:
+          logger.log(message.formatMessageWithLocation(outputPath));
+      }
+      message.handled = true;
+    },
+  });
+}
+
+function extractorConfig(outputPath: string): ExtractorConfig {
+  const projectFolder = outputPath;
+  const mainEntryPointFilePath = joinPath("<projectFolder>", declarationSubpath, "src/index.d.ts");
+  const untrimmedFilePath = joinPath("<projectFolder>", "src/index.d.ts");
+  const packageJsonFullPath = joinPath(projectFolder, "package.json");
+
+  const baseConfigObject = {
+    apiReport: {
+      enabled: false,
+    },
+    docModel: {
+      enabled: true,
+    },
+    dtsRollup: {
+      enabled: true,
+      untrimmedFilePath,
+    },
+    compiler: {
+      overrideTsconfig: declarationTsconfig(outputPath),
+    },
+    mainEntryPointFilePath,
+    messages: {
+      compilerMessageReporting: {
+        default: {
+          logLevel: ExtractorLogLevel.None,
+        },
+      },
+      extractorMessageReporting: {
+        default: {
+          logLevel: ExtractorLogLevel.None,
+        },
+      },
+      tsdocMessageReporting: {
+        default: {
+          logLevel: ExtractorLogLevel.None,
+        },
+      },
+    },
+    newlineKind: "lf",
+    projectFolder,
+  };
+
+  // Defaults are merged in api-extractor when the config file is read from disk with
+  // `ExtractorConfig.loadFile`. This is derived from that method.
+  // https://github.com/microsoft/rushstack/blob/1a92f17fa537b55529adbec80203bd99afd8cd24/apps/api-extractor/src/api/ExtractorConfig.ts#L624-L627
+  const configObject = deepMerge(
+    structuredClone((ExtractorConfig as any)._defaultConfig),
+    baseConfigObject,
+  );
+  ExtractorConfig.jsonSchema.validateObject(configObject, "api extractor config object");
+
+  const config: IExtractorConfigPrepareOptions = {
+    configObject,
+    packageJsonFullPath,
+    configObjectFullPath: null as unknown as undefined,
+  };
+
+  return ExtractorConfig.prepare(config);
+}
+
+function declarationTsconfig(outputPath: string): Record<"compilerOptions", CompilerOptions> {
+  return {
+    compilerOptions: {
+      declaration: true,
+      emitDeclarationOnly: true,
+      declarationMap: true,
+      removeComments: true,
+      declarationDir: joinPath(outputPath, declarationSubpath),
+      rootDir: outputPath,
+    },
+  };
+}
+
+const outputPath = process.env.SPECTOR_OUTPUT_DIR;
+if (!outputPath) {
+  console.error("SPECTOR_OUTPUT_DIR is not set; run this through spector-runner.");
+  process.exit(1);
+}
+emitDeclarations(outputPath);
diff --git a/packages/typespec-ts/test/commands/gen-spector.js b/packages/typespec-ts/test/commands/gen-spector.js
deleted file mode 100644
index 08a12f2e77..0000000000
--- a/packages/typespec-ts/test/commands/gen-spector.js
+++ /dev/null
@@ -1,71 +0,0 @@
-/* eslint-disable no-console */
-import { loadSpectorConfig, resolveSpecs } from "@azure-tools/spector-runner";
-import { fileURLToPath } from "url";
-import { runTypespec } from "./run.ts";
-
-// Spec selection lives in the opt-in `spector.config.yaml` at the package root
-// (see Azure/typespec-azure#4997), parsed by the shared @azure-tools/spector-runner
-// package. Each enabled spec resolves to an input path plus optional emitter
-// metadata: `outputPath` (the generated folder, defaults to the spec path) and
-// `debug` (only run under --debug). This reconstructs the legacy list shape so
-// the rest of this script is unchanged.
-const configPath = fileURLToPath(new URL("../../spector.config.yaml", import.meta.url));
-const azureModularTsps = resolveSpecs(loadSpectorConfig(configPath)).map(({ path, options }) => ({
-  inputPath: path,
-  outputPath: typeof options.outputPath === "string" ? options.outputPath : path,
-  debug: options.debug === true,
-}));
-
-async function generateTypeSpecs(isDebugging, pathFilter, phase = "all") {
-  let list = azureModularTsps;
-
-  if (pathFilter) {
-    list = list.filter((tsp) => tsp.outputPath === pathFilter);
-  }
-
-  const maxConcurrentWorkers = 4;
-  let activePromises = [];
-  for (const tsp of list) {
-    if (isDebugging === true && tsp.debug !== true) {
-      continue;
-    }
-    const generatePromise = runTypespec(tsp, phase)
-      .then((result) => {
-        activePromises = activePromises.filter((p) => p !== generatePromise);
-        return result;
-      })
-      .catch((error) => {
-        activePromises = activePromises.filter((p) => p !== generatePromise);
-        throw error;
-      });
-
-    activePromises.push(generatePromise);
-
-    if (activePromises.length >= maxConcurrentWorkers) {
-      await Promise.race(activePromises);
-    }
-  }
-
-  await Promise.allSettled(activePromises);
-}
-
-async function main() {
-  const isDebugging = process.argv.indexOf("--debug") !== -1;
-  const nameFilter = process.argv.filter((s) => s.startsWith("--filter="));
-  const phaseOptions = process.argv.filter((s) => s.startsWith("--phase="));
-  const filter = nameFilter[0]?.split("=")[1];
-  const phase = phaseOptions[0]?.split("=")[1] ?? "all";
-  await generateTypeSpecs(isDebugging, filter, phase);
-}
-
-let exitCode = 0;
-try {
-  console.time("generate-spector");
-  await main();
-} catch (e) {
-  console.error(e);
-  exitCode = 1;
-} finally {
-  console.timeEnd("generate-spector");
-  process.exit(exitCode);
-}
diff --git a/packages/typespec-ts/test/commands/post-compile.js b/packages/typespec-ts/test/commands/post-compile.js
new file mode 100644
index 0000000000..ffbc835f86
--- /dev/null
+++ b/packages/typespec-ts/test/commands/post-compile.js
@@ -0,0 +1,55 @@
+/* eslint-disable no-console */
+// postCompile hook: run once per spec by the shared spector-runner engine right
+// after its `tsp compile` succeeds (SPECTOR_OUTPUT_DIR points at the generated
+// folder). Emits the committed `.gitignore` and the self-contained test
+// `tsconfig.json` the integration tests need.
+import * as fs from "fs/promises";
+import { join as joinPath } from "path";
+
+const outputPath = process.env.SPECTOR_OUTPUT_DIR;
+if (!outputPath) {
+  console.error("SPECTOR_OUTPUT_DIR is not set; run this through spector-runner.");
+  process.exit(1);
+}
+
+async function emitGitignore() {
+  await fs.writeFile(
+    joinPath(outputPath, ".gitignore"),
+    `/**
+!/src
+/src/**
+!/src/index.d.ts
+!/.gitignore
+!/tspconfig.yaml
+`,
+  );
+}
+
+async function emitTestTsconfig() {
+  // The emitter produces a monorepo-style tsconfig.json (project references into
+  // ./config/*.json that `extends` the azure-sdk-for-js repo's shared eng/tsconfigs).
+  // Those base configs don't exist in this repo, so vite/oxc can't load the config
+  // chain when it transforms the generated sources during integration tests. Overwrite
+  // the package tsconfig with a self-contained one so each generated package is
+  // transformable here. tsconfig.json is not part of the committed baseline, so this
+  // only affects local/CI test runs.
+  const tsconfig = {
+    compilerOptions: {
+      target: "es2022",
+      module: "esnext",
+      moduleResolution: "bundler",
+      verbatimModuleSyntax: false,
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+    },
+    include: ["src/**/*.ts"],
+  };
+  await fs.writeFile(
+    joinPath(outputPath, "tsconfig.json"),
+    JSON.stringify(tsconfig, null, 2) + "\n",
+  );
+}
+
+await emitGitignore();
+await emitTestTsconfig();
diff --git a/packages/typespec-ts/test/commands/run.ts b/packages/typespec-ts/test/commands/run.ts
deleted file mode 100644
index 696571d7e8..0000000000
--- a/packages/typespec-ts/test/commands/run.ts
+++ /dev/null
@@ -1,355 +0,0 @@
-import type { IExtractorConfigPrepareOptions } from "@microsoft/api-extractor";
-import { Extractor, ExtractorConfig, ExtractorLogLevel } from "@microsoft/api-extractor";
-import { existsSync } from "fs";
-import * as fs from "fs/promises";
-import { createRequire } from "module";
-import { dirname, join as joinPath } from "path";
-import type { CompilerOptions } from "typescript";
-import { createProgram } from "typescript";
-import { fileURLToPath } from "url";
-import { createTaskLogger } from "./logger.js";
-import { runCommand } from "./run-command.js";
-
-// Resolve the TypeSpec compiler CLI entry (cmd/tsp.js) once per process and invoke it
-// directly with `node`. Spawning `npx tsp` re-resolves the package on every call, which
-// adds ~5s of pure boot overhead per spec; `node <entry>` keeps the same subprocess
-// isolation (one fresh process per compile) without that tax.
-let cachedTspCliPath: string | undefined;
-function resolveTspCliPath(): string {
-  if (cachedTspCliPath) {
-    return cachedTspCliPath;
-  }
-  const require = createRequire(import.meta.url);
-  let dir = dirname(require.resolve("@typespec/compiler"));
-  for (let i = 0; i < 8; i++) {
-    const candidate = joinPath(dir, "cmd", "tsp.js");
-    if (existsSync(candidate)) {
-      cachedTspCliPath = candidate;
-      return candidate;
-    }
-    dir = dirname(dir);
-  }
-  throw new Error("Could not resolve @typespec/compiler CLI entry (cmd/tsp.js)");
-}
-
-function deepMerge(target: any, source: any): any {
-  const result = { ...target };
-  for (const key of Object.keys(source)) {
-    if (
-      source[key] &&
-      typeof source[key] === "object" &&
-      !Array.isArray(source[key]) &&
-      target[key] &&
-      typeof target[key] === "object" &&
-      !Array.isArray(target[key])
-    ) {
-      result[key] = deepMerge(target[key], source[key]);
-    } else {
-      result[key] = source[key];
-    }
-  }
-  return result;
-}
-
-// Which generation steps to run for a spec.
-// - "client": emit the client sources the integration tests import (steps the test
-//   suite needs: emitClient + gitignore + test tsconfig).
-// - "declarations": emit the public-surface baseline (tsc .d.ts + api-extractor rollup
-//   into src/index.d.ts). Only `check:tree` consumes these, so they can run off the
-//   test critical path.
-// - "all": run everything (used by regen-test-baselines and any single-pass caller).
-export type GenPhase = "client" | "declarations" | "all";
-
-interface GenEnv {
-  readonly logger: () => any;
-  readonly phase: () => GenPhase;
-  readonly sourceTypespec: () => any;
-  readonly targetFolder: () => any;
-  readonly scriptDir: () => string;
-  readonly declarationSubpath: () => string;
-}
-
-function genEnv(config: any, phase: GenPhase): GenEnv {
-  const { inputPath: sourceTypespec, outputPath: targetFolder } = config;
-
-  const __filename = fileURLToPath(import.meta.url);
-  const testRoot = dirname(__filename);
-
-  const logger = createTaskLogger();
-
-  const declarationDir = "types";
-
-  return {
-    logger: () => logger,
-    phase: () => phase,
-    sourceTypespec: () => sourceTypespec,
-    targetFolder: () => targetFolder,
-    scriptDir: () => testRoot,
-    declarationSubpath: () => declarationDir,
-  } as const;
-}
-
-export async function runTypespec(config: any, phase: GenPhase = "all") {
-  const env = genEnv(config, phase);
-  await runTypespecHelper(env);
-}
-
-async function runTypespecHelper(env: GenEnv): Promise<void> {
-  await (async () => {
-    let error;
-    const logger = env.logger();
-    const phase = env.phase();
-    const runClient = phase === "client" || phase === "all";
-    const runDeclarations = phase === "declarations" || phase === "all";
-    logger.log(`=== Start ${env.targetFolder()} (${phase}) ===`);
-    try {
-      if (runClient) {
-        await emitClient();
-        logger.log("=== Emitting gitignore ===");
-        await emitGitignore();
-        logger.log("=== Emitting test tsconfig ===");
-        await emitTestTsconfig();
-      }
-      if (runDeclarations) {
-        logger.log("=== Emitting declaration files ===");
-        await emitDeclarationFiles();
-        logger.log("=== Emitting API summary ===");
-        await emitDeclarationRollup();
-      }
-      logger.log(`=== End ${env.targetFolder()} ===`);
-    } catch (e: any) {
-      logger.error(e.toString());
-      error = e;
-    } finally {
-      logger.flush();
-    }
-    if (error) {
-      throw error;
-    }
-  })();
-
-  async function emitClient() {
-    const logger = env.logger();
-
-    const workingDir = outputPath();
-    const commandArguments = [
-      resolveTspCliPath(),
-      "compile",
-      `${await entryPath()}`,
-      "--config tspconfig.yaml ",
-    ];
-
-    await runCommand("node", commandArguments, workingDir, logger);
-  }
-
-  async function emitGitignore(): Promise<void> {
-    const gitignorePath = joinPath(outputPath(), "./.gitignore");
-    await fs.writeFile(
-      gitignorePath,
-      `/**
-!/src
-/src/**
-!/src/index.d.ts
-!/.gitignore
-!/tspconfig.yaml
-`,
-    );
-  }
-
-  async function emitTestTsconfig(): Promise<void> {
-    // The emitter produces a monorepo-style tsconfig.json (project references into
-    // ./config/*.json that `extends` the azure-sdk-for-js repo's shared eng/tsconfigs).
-    // Those base configs don't exist in this repo, so vite/oxc can't load the config
-    // chain when it transforms the generated sources during integration tests. Overwrite
-    // the package tsconfig with a self-contained one so each generated package is
-    // transformable here. tsconfig.json is not part of the committed baseline, so this
-    // only affects local/CI test runs.
-    const tsconfigPath = joinPath(outputPath(), "tsconfig.json");
-    const tsconfig = {
-      compilerOptions: {
-        target: "es2022",
-        module: "esnext",
-        moduleResolution: "bundler",
-        verbatimModuleSyntax: false,
-        strict: true,
-        esModuleInterop: true,
-        skipLibCheck: true,
-      },
-      include: ["src/**/*.ts"],
-    };
-    await fs.writeFile(tsconfigPath, JSON.stringify(tsconfig, null, 2) + "\n");
-  }
-
-  async function emitDeclarationFiles(): Promise<void> {
-    const logger = env.logger();
-    const program = createProgram({
-      options: tsconfig().compilerOptions,
-      rootNames: [joinPath(outputPath(), "src/index.ts")],
-    });
-
-    // side effect: loads source files into memory
-    // nothing will be emitted if this is omitted
-    program.getSourceFiles();
-
-    const { diagnostics } = program.emit();
-
-    if (diagnostics.length) {
-      logger.log(`Compiler diagnostics for ${outputPath()}`);
-      diagnostics.forEach((diagnostic) => logger.log(diagnostic.messageText));
-    }
-  }
-
-  async function emitDeclarationRollup(): Promise<void> {
-    const logger = env.logger();
-    Extractor.invoke(extractorConfig(), {
-      localBuild: true,
-      messageCallback: (message) => {
-        switch (message.logLevel) {
-          case ExtractorLogLevel.None:
-            break;
-          default:
-            logger.log(message.formatMessageWithLocation(outputPath()));
-        }
-        message.handled = true;
-      },
-    });
-  }
-
-  function extractorConfig(): ExtractorConfig {
-    const projectFolder = outputPath();
-    const mainEntryPointFilePath = joinPath(
-      "<projectFolder>",
-      env.declarationSubpath(),
-      "src/index.d.ts",
-    );
-    const untrimmedFilePath = joinPath("<projectFolder>", "src/index.d.ts");
-    const packageJsonFullPath = joinPath(projectFolder, "package.json");
-
-    const baseConfigObject = {
-      apiReport: {
-        enabled: false,
-      },
-      docModel: {
-        enabled: true,
-      },
-      dtsRollup: {
-        enabled: true,
-        untrimmedFilePath,
-      },
-      compiler: {
-        overrideTsconfig: tsconfig(),
-      },
-      mainEntryPointFilePath,
-      messages: {
-        compilerMessageReporting: {
-          default: {
-            logLevel: ExtractorLogLevel.None,
-          },
-        },
-        extractorMessageReporting: {
-          default: {
-            logLevel: ExtractorLogLevel.None,
-          },
-        },
-        tsdocMessageReporting: {
-          default: {
-            logLevel: ExtractorLogLevel.None,
-          },
-        },
-      },
-      newlineKind: "lf",
-      projectFolder,
-    };
-
-    // Defaults are merged in api-extractor when the config file is read from disk with
-    // `ExtractorConfig.loadFile`. This is derived from that method.
-    // https://github.com/microsoft/rushstack/blob/1a92f17fa537b55529adbec80203bd99afd8cd24/apps/api-extractor/src/api/ExtractorConfig.ts#L624-L627
-    const configObject = deepMerge(
-      structuredClone((ExtractorConfig as any)._defaultConfig),
-      baseConfigObject,
-    );
-    ExtractorConfig.jsonSchema.validateObject(configObject, "api extractor config object");
-
-    const config: IExtractorConfigPrepareOptions = {
-      configObject,
-      packageJsonFullPath,
-      configObjectFullPath: null as unknown as undefined,
-    };
-
-    return ExtractorConfig.prepare(config);
-  }
-
-  function tsconfig(): Record<"compilerOptions", CompilerOptions> {
-    return {
-      compilerOptions: {
-        declaration: true,
-        emitDeclarationOnly: true,
-        declarationMap: true,
-        removeComments: true,
-        declarationDir: joinPath(outputPath(), env.declarationSubpath()),
-        rootDir: outputPath(),
-      },
-    };
-  }
-
-  async function entryPath(): Promise<string> {
-    const specPath = joinPath(emitterRoot(), "./temp/specs", env.sourceTypespec());
-    const possibleEntryPaths = ["client.tsp", "main.tsp"].map((filename) =>
-      joinPath(specPath, filename),
-    );
-    const entryPath =
-      (await findAsync(possibleEntryPaths, entryFileExists)) ??
-      // if find fails, specPath should point to the entry file itself
-      specPath;
-
-    return entryPath;
-
-    async function entryFileExists(entryFilePath: string): Promise<boolean> {
-      const fileExists = await exists(entryFilePath);
-      if (fileExists) {
-        env.logger().log(`Existing the entry file: ${entryFilePath}`);
-      }
-      return fileExists;
-    }
-  }
-
-  function outputPath() {
-    const outputPath = joinPath(
-      testRoot(),
-      "azure-modular-integration",
-      "generated",
-      env.targetFolder(),
-    );
-
-    return outputPath;
-  }
-
-  function testRoot() {
-    return joinPath(env.scriptDir(), "..");
-  }
-
-  function emitterRoot() {
-    return joinPath(testRoot(), "..");
-  }
-}
-
-async function exists(filePath: any) {
-  try {
-    await fs.access(filePath);
-    return true;
-  } catch (err) {
-    return false;
-  }
-}
-
-async function findAsync<T>(
-  array: T[],
-  predicate: (x: T) => Promise<boolean>,
-): Promise<T | undefined> {
-  for (const x of array) {
-    if (await predicate(x)) {
-      return x;
-    }
-  }
-  return;
-}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a68662eb66..42a7e688ac 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -3222,6 +3222,9 @@ importers:
 
   packages/spector-runner:
     dependencies:
+      picocolors:
+        specifier: 'catalog:'
+        version: 1.1.1
       yaml:
         specifier: 'catalog:'
         version: 2.9.0