From 19e6f7d907e5bb12f0760606e7bff8bcc44d3d33 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Wed, 22 Jul 2026 23:58:37 +0800
Subject: [PATCH] refactor(tsconfig): single root solution graph over
 host/client aggregates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Root tsconfig.json becomes a pure solution (files:[] + two references);
the former root host aggregate moves verbatim to tsconfig.host.json.
New tsconfig.base.client.json carries the shared client compiler shape
(jsx/DOM lib/types:[]), and tsconfig.client.json plus the 12
packages/client tsconfigs extend it instead of restating the trio.
tsconfig.build.json is deleted: the solution covers the full emit graph,
absorbing the command-goal typecheck/build drift.

Consumers migrate to the single graph: typecheck/build scripts and the
lefthook pre-push hook run bare `tsc -b` (pre-push now covers the client
side); the run-gates build gate needs typecheck so two concurrent tsc -b
runs cannot race the same tsbuildinfo; ts-project.ts and the standalone
doc-typecheck mode seed tsconfig.host.json explicitly (never the root
solution — flattening host+client into one program collides the cordis
Context merges); verify-cordis-config BFS seeds the root solution alone.

Per missions/tsconfig-single-graph-migration.md §2–§3.
---
 lefthook.yml                                  |   2 +-
 package.json                                  |   4 +-
 packages/client/connection/tsconfig.json      |  10 +-
 packages/client/i18n/tsconfig.json            |  10 +-
 packages/client/runtime/tsconfig.json         |  10 +-
 packages/client/ui-conversation/tsconfig.json |  11 +-
 packages/client/ui-layout/tsconfig.json       |  11 +-
 packages/client/ui-primitives/tsconfig.json   |  11 +-
 packages/client/ui-sidebar/tsconfig.json      |  11 +-
 packages/client/ui-slots/tsconfig.json        |  10 +-
 packages/client/ui-theme/tsconfig.json        |  10 +-
 packages/client/ui-trajectory/tsconfig.json   |  11 +-
 packages/client/web-react/tsconfig.json       |  11 +-
 packages/client/web/tsconfig.json             |  11 +-
 scripts/doc-typecheck.ts                      |  22 ++-
 scripts/gen-scoped-events.ts                  |   2 +-
 scripts/run-gates.ts                          |   5 +-
 scripts/ts-project.ts                         |   8 +-
 scripts/verify-cordis-config.ts               |  11 +-
 tsconfig.base.client.json                     |  11 ++
 tsconfig.client.json                          |   7 +-
 tsconfig.build.json => tsconfig.host.json     |  42 +++--
 tsconfig.json                                 | 154 ++----------------
 tsdown.config.ts                              |   2 +-
 24 files changed, 111 insertions(+), 286 deletions(-)
 create mode 100644 tsconfig.base.client.json
 rename tsconfig.build.json => tsconfig.host.json (88%)

diff --git a/lefthook.yml b/lefthook.yml
index 49a1499976..cf2e6bb11d 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -20,4 +20,4 @@ pre-commit:
 pre-push:
   jobs:
     - name: typecheck
-      run: node_modules/.bin/tsc -b tsconfig.json --pretty false
+      run: node_modules/.bin/tsc -b --pretty false
diff --git a/package.json b/package.json
index 611e1d49e2..38db3a2ac7 100644
--- a/package.json
+++ b/package.json
@@ -14,10 +14,10 @@
     "website"
   ],
   "scripts": {
-    "build": "tsc -b tsconfig.build.json && tsdown",
+    "build": "tsc -b && tsdown",
     "build:web": "pnpm --filter @deepseek-ai/dsh-frontend run build",
     "clean:build": "rm -rf .typecheck packages/*/*/lib vendor/*/lib *.tsbuildinfo",
-    "typecheck": "tsc -b tsconfig.json tsconfig.client.json",
+    "typecheck": "tsc -b",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
     "duplication": "jscpd --config .jscpd.json packages scripts",
diff --git a/packages/client/connection/tsconfig.json b/packages/client/connection/tsconfig.json
index 3f45ca0231..8b0357cf97 100644
--- a/packages/client/connection/tsconfig.json
+++ b/packages/client/connection/tsconfig.json
@@ -1,14 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/i18n/tsconfig.json b/packages/client/i18n/tsconfig.json
index 76dd83e8d6..63eb9779ca 100644
--- a/packages/client/i18n/tsconfig.json
+++ b/packages/client/i18n/tsconfig.json
@@ -1,14 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/runtime/tsconfig.json b/packages/client/runtime/tsconfig.json
index 82ebf4f989..9584ecc857 100644
--- a/packages/client/runtime/tsconfig.json
+++ b/packages/client/runtime/tsconfig.json
@@ -1,14 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-conversation/tsconfig.json b/packages/client/ui-conversation/tsconfig.json
index ed0065fa04..7755337093 100644
--- a/packages/client/ui-conversation/tsconfig.json
+++ b/packages/client/ui-conversation/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-layout/tsconfig.json b/packages/client/ui-layout/tsconfig.json
index f2c03d8d12..c82482294b 100644
--- a/packages/client/ui-layout/tsconfig.json
+++ b/packages/client/ui-layout/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-primitives/tsconfig.json b/packages/client/ui-primitives/tsconfig.json
index fa9b40f9e6..e2650b47b6 100644
--- a/packages/client/ui-primitives/tsconfig.json
+++ b/packages/client/ui-primitives/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-sidebar/tsconfig.json b/packages/client/ui-sidebar/tsconfig.json
index a560748366..c48fe2567f 100644
--- a/packages/client/ui-sidebar/tsconfig.json
+++ b/packages/client/ui-sidebar/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-slots/tsconfig.json b/packages/client/ui-slots/tsconfig.json
index fc829c7a83..b8ccb71310 100644
--- a/packages/client/ui-slots/tsconfig.json
+++ b/packages/client/ui-slots/tsconfig.json
@@ -1,14 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-theme/tsconfig.json b/packages/client/ui-theme/tsconfig.json
index 076aa22e9f..51f9171643 100644
--- a/packages/client/ui-theme/tsconfig.json
+++ b/packages/client/ui-theme/tsconfig.json
@@ -1,14 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/ui-trajectory/tsconfig.json b/packages/client/ui-trajectory/tsconfig.json
index e3b1abe266..f525474d9d 100644
--- a/packages/client/ui-trajectory/tsconfig.json
+++ b/packages/client/ui-trajectory/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/web-react/tsconfig.json b/packages/client/web-react/tsconfig.json
index 57b533b2a6..90b7619fed 100644
--- a/packages/client/web-react/tsconfig.json
+++ b/packages/client/web-react/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/packages/client/web/tsconfig.json b/packages/client/web/tsconfig.json
index 87a6b0dcab..f974787045 100644
--- a/packages/client/web/tsconfig.json
+++ b/packages/client/web/tsconfig.json
@@ -1,15 +1,8 @@
 {
-  "extends": "../../../tsconfig.base.json",
+  "extends": "../../../tsconfig.base.client.json",
   "compilerOptions": {
     "rootDir": "src",
-    "outDir": "lib/types",
-    "jsx": "react-jsx",
-    "lib": [
-      "ES2024",
-      "DOM",
-      "DOM.Iterable"
-    ],
-    "types": []
+    "outDir": "lib/types"
   },
   "include": [
     "src"
diff --git a/scripts/doc-typecheck.ts b/scripts/doc-typecheck.ts
index 5034d65cae..9a9e007758 100644
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -55,15 +55,20 @@ const configHost: ts.ParseConfigFileHost = {
   },
 }
 
-/** Load root settings and redirect workspace aliases to declarations from the coordinated build. */
+/**
+ * Load host-aggregate settings and redirect workspace aliases to declarations
+ * from the coordinated build. Doc fragments speak the host vocabulary; the host
+ * aggregate (never the root solution — it has no compilerOptions) carries the
+ * workspace paths via tsconfig.base.json.
+ */
 function builtTypeCompilerOptions(): ts.CompilerOptions {
-  const configPath = join(root, 'tsconfig.json')
+  const configPath = join(root, 'tsconfig.host.json')
   const parsed = ts.getParsedCommandLineOfConfigFile(configPath, {}, configHost)
   if (!parsed) throw new Error(`doc-typecheck: cannot parse ${configPath}`)
   if (parsed.errors.length > 0) {
     throw new Error(parsed.errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'))
   }
-  if (parsed.options.paths === undefined) throw new Error('doc-typecheck: root tsconfig has no workspace paths')
+  if (parsed.options.paths === undefined) throw new Error('doc-typecheck: host tsconfig has no workspace paths')
   const paths = Object.fromEntries(Object.entries(parsed.options.paths).map(([specifier, candidates]) => [
     specifier,
     candidates.map(builtDeclarationPath),
@@ -125,9 +130,14 @@ function formatDiagnostics(diagnostics: readonly ts.Diagnostic[], blocks: Block[
   return remapBlockPaths(formatted, blocks)
 }
 
-/** Reuse the repo typecheck graph references from a temp project one directory below root. */
+/**
+ * Reuse the host-aggregate references from a temp project one directory below
+ * root. Doc fragments speak the host vocabulary, so the standalone project
+ * seeds tsconfig.host.json (never the root solution: flattening host+client
+ * into one program collides the cordis Context merges).
+ */
 function workspaceReferences(): { path: string }[] {
-  const file = join(root, 'tsconfig.json')
+  const file = join(root, 'tsconfig.host.json')
   // Parse with TypeScript's own JSONC reader: a regex comment stripper corrupts the `/*/` path
   // candidate in the workspace wildcard.
   const result = ts.readConfigFile(file, path => readFileSync(path, 'utf8'))
@@ -144,7 +154,7 @@ function workspaceReferences(): { path: string }[] {
 /** The standalone temp project used when no coordinated build owns declaration freshness. */
 function tempTsconfig(): string {
   return JSON.stringify({
-    extends: '../tsconfig.json',
+    extends: '../tsconfig.host.json',
     compilerOptions: {
       noUnusedLocals: false,
       noUnusedParameters: false,
diff --git a/scripts/gen-scoped-events.ts b/scripts/gen-scoped-events.ts
index 4aa6637934..ead001a79b 100644
--- a/scripts/gen-scoped-events.ts
+++ b/scripts/gen-scoped-events.ts
@@ -370,7 +370,7 @@ function quote(value: string): string {
 
 /**
  * Render the generated scoped-event resolver module for one repository root.
- * @param projectRoot - repository root carrying tsconfig.json.
+ * @param projectRoot - repository root carrying tsconfig.host.json.
  * @returns complete generated TypeScript source.
  */
 export function renderScopedEvents(projectRoot: string = root): string {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 1c3958434c..896ffacfd1 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -228,7 +228,10 @@ function ciPrimaryGates(): Gate[] {
     ...docSyncLeafGates(),
     pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
     pnpmScript('knip', 'knip'),
-    pnpmScript('build', 'build'),
+    // typecheck and build now drive the same root solution graph; without the
+    // dependency two concurrent `tsc -b` runs race the same tsbuildinfo files.
+    // The tsc step is an incremental no-op after typecheck.
+    pnpmScript('build', 'build', { needs: ['typecheck'] }),
     pnpmScript('publint', 'publint', { needs: ['build'] }),
     pnpmScript('node-next-types', 'verify-node-next-types', {
       label: 'node-next types',
diff --git a/scripts/ts-project.ts b/scripts/ts-project.ts
index 0b59aee873..930c055d4f 100644
--- a/scripts/ts-project.ts
+++ b/scripts/ts-project.ts
@@ -22,9 +22,13 @@ const configHost: ts.ParseConfigFileHost = {
   },
 }
 
-/** Parse a root tsconfig and flatten all referenced projects into one semantic graph. */
+/**
+ * Parse the host aggregate tsconfig and flatten all referenced projects into one
+ * semantic graph. Never seed the root solution: flattening host+client into one
+ * program collides the cordis Context merges.
+ */
 function loadProjectGraph(projectRoot: string): ProjectGraph {
-  const rootConfigPath = resolve(projectRoot, 'tsconfig.json')
+  const rootConfigPath = resolve(projectRoot, 'tsconfig.host.json')
   const rootConfig = parseConfig(rootConfigPath)
   const rootNames = new Set<string>()
   const visited = new Set<string>()
diff --git a/scripts/verify-cordis-config.ts b/scripts/verify-cordis-config.ts
index c9820a67a8..916db4a168 100644
--- a/scripts/verify-cordis-config.ts
+++ b/scripts/verify-cordis-config.ts
@@ -152,12 +152,13 @@ function localPackageDirectories(): Map<string, string> {
 }
 
 function rootProjectReferences(): Set<string> {
-  // Typecheck runs two sibling aggregates (root = host program,
-  // tsconfig.client.json = client program; the two sides merge cordis Context
-  // under the same keys, so one program cannot see both). Seed both and follow
-  // any nested aggregate references to collect the covered leaf project set.
+  // The root solution references the host and client aggregates (the two
+  // sides merge cordis Context under the same keys, so one program cannot see
+  // both — but this BFS only collects reference paths, it never forms a
+  // program). Seed the solution and follow nested aggregate references to
+  // collect the covered leaf project set.
   const collected = new Set<string>()
-  const queue = [resolve(root, 'tsconfig.json'), resolve(root, 'tsconfig.client.json')]
+  const queue = [resolve(root, 'tsconfig.json')]
   const seen = new Set<string>()
   for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
     if (seen.has(file)) continue
diff --git a/tsconfig.base.client.json b/tsconfig.base.client.json
new file mode 100644
index 0000000000..411c006da9
--- /dev/null
+++ b/tsconfig.base.client.json
@@ -0,0 +1,11 @@
+{
+  // Client-side compiler shape shared by tsconfig.client.json and every
+  // packages/client/* package: browser lib surface, React JSX, no ambient
+  // node types (packages that need them override locally).
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "react-jsx",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
+    "types": []
+  }
+}
diff --git a/tsconfig.client.json b/tsconfig.client.json
index ceb498a1a9..d7ee9090e7 100644
--- a/tsconfig.client.json
+++ b/tsconfig.client.json
@@ -4,14 +4,13 @@
   // under the same keys (sessions, loader) with different services; shared
   // leaves (session/llm/tools/apiproxy/...) build once and are referenced by
   // both programs through each client package's own references.
-  "extends": "./tsconfig.base.json",
+  "extends": "./tsconfig.base.client.json",
   "compilerOptions": {
     "noEmit": true,
     "rewriteRelativeImportExtensions": false,
-    "jsx": "react-jsx",
-    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     // Tests execute under vitest on node (e2e files spawn processes); browser
-    // purity of package src is each package's own tsconfig + verify-client-closure.
+    // purity of package src is each package's own tsconfig plus
+    // scripts/client-bundle-purity.spec.ts.
     "types": ["node"]
   },
   "include": [
diff --git a/tsconfig.build.json b/tsconfig.host.json
similarity index 88%
rename from tsconfig.build.json
rename to tsconfig.host.json
index fc0050f34b..f340f235da 100644
--- a/tsconfig.build.json
+++ b/tsconfig.host.json
@@ -1,5 +1,25 @@
 {
-  "files": [],
+  // Host aggregate (one of the two check units; see tsconfig.json). packages/client
+  // type-checks in tsconfig.client.json: the two sides merge cordis Context under
+  // the same keys, one program cannot see both.
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "rewriteRelativeImportExtensions": false
+  },
+  "include": [
+    "examples/*/src/**/*.ts",
+    "examples/*/start.ts",
+    "examples/*/tests/**/*.ts",
+    "packages/*/*/tests/**/*.ts",
+    "scripts/**/*.ts",
+    "website/**/*.ts",
+    "website/.vitepress/**/*.ts"
+  ],
+  "exclude": [
+    "packages/client/**",
+    "scripts/client-bundle-purity.spec.ts"
+  ],
   "references": [
     { "path": "./vendor/cosmokit" },
     { "path": "./vendor/schemastery" },
@@ -33,7 +53,9 @@
     { "path": "./packages/goal/goal" },
     { "path": "./packages/goal/tool-goal" },
     { "path": "./packages/goal/goal-session" },
+    { "path": "./packages/goal/command-goal" },
     { "path": "./packages/context/time-context" },
+    { "path": "./packages/context/session-reference" },
     { "path": "./packages/ui/user-interaction" },
     { "path": "./packages/ui/user-approval" },
     { "path": "./packages/ui/permission" },
@@ -53,9 +75,6 @@
     { "path": "./packages/pty/tool-pty" },
     { "path": "./packages/code-runtime/code-runtime" },
     { "path": "./packages/code-runtime/code-runtime-worker" },
-    { "path": "./packages/compact/compact" },
-    { "path": "./packages/compact/compact-basic" },
-    { "path": "./packages/compact/compact-tool-result-prune" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
     { "path": "./packages/bash/bash-local" },
@@ -70,6 +89,9 @@
     { "path": "./packages/fs/fs-sandbox" },
     { "path": "./packages/fs/tool-fs" },
     { "path": "./packages/fs/tool-fs-search" },
+    { "path": "./packages/compact/compact" },
+    { "path": "./packages/compact/compact-basic" },
+    { "path": "./packages/compact/compact-tool-result-prune" },
     { "path": "./packages/web/web" },
     { "path": "./packages/web/web-search-exa" },
     { "path": "./packages/web/web-search-perplexity" },
@@ -116,18 +138,6 @@
     { "path": "./packages/host/apiproxy" },
     { "path": "./packages/host/runtime" },
     { "path": "./packages/host/webserver" },
-    { "path": "./packages/client/ui-slots" },
-    { "path": "./packages/client/ui-primitives" },
-    { "path": "./packages/client/web-react" },
-    { "path": "./packages/client/connection" },
-    { "path": "./packages/client/runtime" },
-    { "path": "./packages/client/ui-layout" },
-    { "path": "./packages/client/ui-sidebar" },
-    { "path": "./packages/client/ui-conversation" },
-    { "path": "./packages/client/ui-trajectory" },
-    { "path": "./packages/client/ui-theme" },
-    { "path": "./packages/client/i18n" },
-    { "path": "./packages/client/web" },
     { "path": "./packages/sdk/helper" },
     { "path": "./packages/sdk/scripts" },
     { "path": "./packages/sdk/create-sdk" },
diff --git a/tsconfig.json b/tsconfig.json
index c42fda4147..a98f88aae0 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,149 +1,15 @@
 {
-  // Host aggregate. packages/client type-checks in tsconfig.client.json: the two
-  // sides merge cordis Context under the same keys, one program cannot see both.
+  // Solution file: the whole-repo graph for `tsc -b tsconfig.json` and the
+  // tsserver entry. `extends` carries the base paths for get-tsconfig
+  // consumers — tsx running examples/ and scripts/ (no nearer tsconfig)
+  // resolves workspace imports through this file. `files: []` keeps it
+  // program-less, so the host/client cordis Context merges never meet.
+  // NEVER add include/files entries, and NEVER flatten this solution into a
+  // single ts.Program (scripts seed tsconfig.host.json or tsconfig.client.json).
   "extends": "./tsconfig.base.json",
-  "compilerOptions": {
-    "noEmit": true,
-    "rewriteRelativeImportExtensions": false
-  },
-  "include": [
-    "examples/*/src/**/*.ts",
-    "examples/*/start.ts",
-    "examples/*/tests/**/*.ts",
-    "packages/*/*/tests/**/*.ts",
-    "scripts/**/*.ts",
-    "website/**/*.ts",
-    "website/.vitepress/**/*.ts"
-  ],
-  "exclude": [
-    "packages/client/**",
-    "scripts/client-bundle-purity.spec.ts"
-  ],
+  "files": [],
   "references": [
-    { "path": "./vendor/cosmokit" },
-    { "path": "./vendor/schemastery" },
-    { "path": "./vendor/cordis" },
-    { "path": "./vendor/loader" },
-    { "path": "./vendor/include" },
-    { "path": "./vendor/group" },
-    { "path": "./vendor/timer" },
-    { "path": "./vendor/hmr" },
-    { "path": "./vendor/logger-console" },
-    { "path": "./packages/util/brand" },
-    { "path": "./packages/util/paths" },
-    { "path": "./packages/util/timeout" },
-    { "path": "./packages/util/retention" },
-    { "path": "./packages/llm/llm" },
-    { "path": "./packages/llm/token-meter" },
-    { "path": "./packages/core/session" },
-    { "path": "./packages/core/scope" },
-    { "path": "./packages/session-persistence/session-persistence" },
-    { "path": "./packages/session-persistence/session-checkpoint-policy" },
-    { "path": "./packages/session-persistence/session-persistence-jsonl" },
-    { "path": "./packages/session-persistence/session-persistence-sqlite" },
-    { "path": "./packages/session-query/session-query" },
-    { "path": "./packages/session-title/session-title" },
-    { "path": "./packages/session-title/session-title-llm" },
-    { "path": "./packages/session-title/session-title-first-message-llm" },
-    { "path": "./packages/session-title/session-title-all-messages-llm" },
-    { "path": "./packages/core/system-prompt" },
-    { "path": "./packages/core/agent" },
-    { "path": "./packages/ui/commands" },
-    { "path": "./packages/goal/goal" },
-    { "path": "./packages/goal/tool-goal" },
-    { "path": "./packages/goal/goal-session" },
-    { "path": "./packages/goal/command-goal" },
-    { "path": "./packages/context/time-context" },
-    { "path": "./packages/context/session-reference" },
-    { "path": "./packages/ui/user-interaction" },
-    { "path": "./packages/ui/user-approval" },
-    { "path": "./packages/ui/permission" },
-    { "path": "./packages/core/tools" },
-    { "path": "./packages/skill/skill" },
-    { "path": "./packages/skill/skill-local" },
-    { "path": "./packages/skill/tool-skill" },
-    { "path": "./packages/ui/tool-ask-user" },
-    { "path": "./packages/context/workspace-context" },
-    { "path": "./packages/core/agent-loop" },
-    { "path": "./packages/llm/llm-retry" },
-    { "path": "./packages/examples/agent-spine-demo" },
-    { "path": "./packages/examples/cli-demo" },
-    { "path": "./packages/bash/bash" },
-    { "path": "./packages/pty/pty" },
-    { "path": "./packages/pty/pty-local" },
-    { "path": "./packages/pty/tool-pty" },
-    { "path": "./packages/code-runtime/code-runtime" },
-    { "path": "./packages/code-runtime/code-runtime-worker" },
-    { "path": "./packages/llm/llm-deepseek" },
-    { "path": "./packages/llm/llm-pi-ai" },
-    { "path": "./packages/bash/bash-local" },
-    { "path": "./packages/sandbox/sandbox" },
-    { "path": "./packages/sandbox/sandbox-local" },
-    { "path": "./packages/sandbox/sandbox-policy" },
-    { "path": "./packages/bash/bash-sandbox" },
-    { "path": "./packages/bash/tool-bash" },
-    { "path": "./packages/fs/fs" },
-    { "path": "./packages/fs/fs-local" },
-    { "path": "./packages/fs/fs-policy" },
-    { "path": "./packages/fs/fs-sandbox" },
-    { "path": "./packages/fs/tool-fs" },
-    { "path": "./packages/fs/tool-fs-search" },
-    { "path": "./packages/compact/compact" },
-    { "path": "./packages/compact/compact-basic" },
-    { "path": "./packages/compact/compact-tool-result-prune" },
-    { "path": "./packages/web/web" },
-    { "path": "./packages/web/web-search-exa" },
-    { "path": "./packages/web/web-search-perplexity" },
-    { "path": "./packages/web/web-search-deepseek" },
-    { "path": "./packages/web/web-fetch-local" },
-    { "path": "./packages/web/tool-web" },
-    { "path": "./packages/spill/spill" },
-    { "path": "./packages/spill/spill-local" },
-    { "path": "./packages/spill/spill-policy" },
-    { "path": "./packages/timeout/timeout-policy" },
-    { "path": "./packages/support/invariants" },
-    { "path": "./packages/support/agent-loop-testkit" },
-    { "path": "./packages/ui/acp" },
-    { "path": "./packages/examples/acp-demo" },
-    { "path": "./packages/ui/app-boot" },
-    { "path": "./packages/ui/jsonrpc" },
-    { "path": "./packages/examples/jsonrpc-demo" },
-    { "path": "./packages/ui/tui" },
-    { "path": "./packages/examples/tui-demo" },
-    { "path": "./packages/support/llm-replay" },
-    { "path": "./packages/support/acp-snapshot" },
-    { "path": "./packages/support/loader-smoke" },
-    { "path": "./packages/subagent/subagent" },
-    { "path": "./packages/subagent/tool-subagent" },
-    { "path": "./packages/subagent/subagent-inprocess" },
-    { "path": "./packages/subagent/subagent-subprocess" },
-    { "path": "./packages/subagent/subagent-spawn" },
-    { "path": "./packages/subagent/subagent-fork" },
-    { "path": "./packages/subagent/subagent-acp" },
-    { "path": "./packages/tasks/tasks" },
-    { "path": "./packages/tasks/tool-tasks" },
-    { "path": "./packages/workflow/workflow" },
-    { "path": "./packages/workflow/workflow-workerthread" },
-    { "path": "./packages/workflow/tool-workflow" },
-    { "path": "./packages/workflow/tool-ralph" },
-    { "path": "./packages/todo/tool-todo" },
-    { "path": "./packages/plan/plan-mode" },
-    { "path": "./packages/guard/repeat-tool-guard" },
-    { "path": "./packages/cordis/tool-cordis" },
-    { "path": "./packages/hooks/hook-protocol" },
-    { "path": "./packages/hooks/hooks-claude" },
-    { "path": "./packages/hooks/hooks-codex" },
-    { "path": "./packages/mcp/mcp-client" },
-    { "path": "./packages/host/apiproxy" },
-    { "path": "./packages/host/runtime" },
-    { "path": "./packages/host/webserver" },
-    { "path": "./packages/sdk/helper" },
-    { "path": "./packages/sdk/scripts" },
-    { "path": "./packages/sdk/create-sdk" },
-    { "path": "./packages/sdk/telemetry" },
-    { "path": "./packages/lsp/lsp" },
-    { "path": "./packages/lsp/lsp-local" },
-    { "path": "./packages/lsp/tool-lsp" },
-    { "path": "./apps/cli" }
+    { "path": "./tsconfig.host.json" },
+    { "path": "./tsconfig.client.json" }
   ]
 }
diff --git a/tsdown.config.ts b/tsdown.config.ts
index 8ad1a5c41c..41a490436f 100644
--- a/tsdown.config.ts
+++ b/tsdown.config.ts
@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown'
 
 /**
  * JS bundling for vendored Cordis and Harness TypeScript packages.
- * TypeScript source is compiled first by `tsc -b tsconfig.build.json`; tsdown
+ * TypeScript source is compiled first by `tsc -b` (the root solution); tsdown
  * reads only the emitted JS under lib/types and writes the package root and
  * invariant companion runtime bundles. Declarations are NOT produced here,
  * hence `dts: false`.