Merge branch 'master' into worktree/docs-service-reference

2026-07-22 20:48:29 +08:00
parent e844125d7d ad8f75a464
commit 069313b156
558 changed files with 41739 additions and 993 deletions
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -40,10 +40,12 @@ interface PackageManifest {
  bin?: string | Record<string, string>
  exports?: Record<
    string,
+    | string
    | {
      types?: string
      default?: string
    }
+    | null
    | undefined
  >
  files?: string[]
@@ -115,13 +117,41 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
    'lib/invariant.js',
    ...manifest.bin ? ['lib/bin.js'] : [],
    ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
+    // UI plugin packages ship their browser bundle beside the node lib
+    // (single-artifact ruling: dist/ retired, ./client resolves lib/client.js).
+    // Keyed on the artifact path, not the subpath name: apiproxy's ./client is
+    // a browser-safe source channel, not a bundle.
+    ...exportDefault(manifest, './client') === './lib/client.js' ? ['lib/client.js'] : [],
+    // runtime's shell-held loader subpath ships as its own bundle beside the client half.
+    ...exportDefault(manifest, './loader') === './lib/loader.js' ? ['lib/loader.js'] : [],
+    // web-react's store subpath ships its own bundle (single-entry builds; no shared chunk).
+    ...exportDefault(manifest, './store') === './lib/store/index.js' ? ['lib/store/index.js'] : [],
    ...extras,
+    // Subpaths whose runtime default is the tsc-emitted tree (lib/types/*.js —
+    // browser-safe source channels rehomed off src so plain Node can import
+    // them without type stripping) publish the emitted JS alongside the
+    // declarations.
+    ...usesEmittedTreeDefaults(manifest) ? ['lib/types/**/*.js'] : [],
    'lib/types/**/*.d.ts',
    'lib/types/**/*.d.ts.map',
    'src',
  ]
 }

+/** Runtime target of an export entry: conditional `default`, or the bare-string shorthand. */
+function exportDefault(manifest: PackageManifest, subpath: string): string | undefined {
+  const entry = manifest.exports?.[subpath]
+  if (typeof entry === 'string') return entry
+  if (typeof entry === 'object' && entry !== null) return entry.default
+  return undefined
+}
+
+/** Whether any export's runtime default points into the tsc-emitted lib/types tree. */
+function usesEmittedTreeDefaults(manifest: PackageManifest): boolean {
+  return Object.keys(manifest.exports ?? {}).some(subpath =>
+    exportDefault(manifest, subpath)?.startsWith('./lib/types/') === true)
+}
+
 function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
  const errors: string[] = []
  const label = manifest.name ?? dir
@@ -155,13 +185,16 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
    if (manifest.types !== 'lib/types/index.d.ts') {
      errors.push(`${label}: package.json must set "types": "lib/types/index.d.ts"`)
    }
-    if (manifest.exports?.['.']?.types !== './lib/types/index.d.ts') {
+    const rootExport = manifest.exports?.['.']
+    const rootEntry = typeof rootExport === 'object' && rootExport !== null ? rootExport : undefined
+    if (rootEntry?.types !== './lib/types/index.d.ts') {
      errors.push(`${label}: package.json exports["."].types must be "./lib/types/index.d.ts"`)
    }
-    if (manifest.exports?.['.']?.default !== './lib/index.js') {
+    if (rootEntry?.default !== './lib/index.js') {
      errors.push(`${label}: package.json exports["."].default must be "./lib/index.js"`)
    }
-    const invariantExport = manifest.exports?.['./invariant']
+    const invariantRaw = manifest.exports?.['./invariant']
+    const invariantExport = typeof invariantRaw === 'object' && invariantRaw !== null ? invariantRaw : undefined
    if (invariantExport?.types !== undefined && invariantExport.types !== './lib/types/invariant.d.ts') {
      errors.push(`${label}: package.json exports["./invariant"].types must be "./lib/types/invariant.d.ts"`)
    }
--- a/scripts/client-bundle-purity.spec.ts
+++ b/scripts/client-bundle-purity.spec.ts
@@ -0,0 +1,60 @@
+/**
+ * Pins the client-bundle purity gate (tsdown preset resolveId classifier):
+ * a bare-name import of a module-table package must rewrite to its /client
+ * external form (inlining it duplicates runtime identity — the P0
+/* leak that is not an
+ * inline-safe wire layer must fail the build loudly.
+ */
+import { describe, expect, it } from 'vitest'
+import { CLIENT_EXTERNALS, clientBundle } from '../packages/client/tsdown.client.ts'
+
+type ResolveId = (source: string) => null | { id: string; external: boolean }
+
+function purityResolveId(): ResolveId {
+  // libEntry is spelled at every call site (no default) so the
+  // package-invariants text check can see the invariant entry per package.
+  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
+  const plugins = (configs[1] as { plugins: { name: string; resolveId?: unknown }[] }).plugins
+  const gate = plugins.find(p => p.name === 'dsh-client-bundle-purity')
+  if (gate?.resolveId === undefined) throw new Error('purity plugin missing from client config')
+  return gate.resolveId as ResolveId
+}
+
+describe('client bundle purity gate', () => {
+  const resolveId = purityResolveId()
+
+  it('leaves table entries and non-scoped specifiers alone', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-ui-slots')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-runtime/client')).toBeNull()
+    expect(resolveId('react')).toBeNull()
+    expect(resolveId('zod')).toBeNull()
+  })
+
+  it('rewrites a bare table-package name to its external /client form (duplicate-instance prevention)', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-connection')).toEqual({
+      id: '@deepseek-ai/dsh-client-connection/client',
+      external: true,
+    })
+    expect(resolveId('@deepseek-ai/dsh-client-ui-layout')).toEqual({
+      id: '@deepseek-ai/dsh-client-ui-layout/client',
+      external: true,
+    })
+  })
+
+  it('lets inline-safe wire layers inline', () => {
+    expect(resolveId('@deepseek-ai/dsh-host-apiproxy/api')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-session/surface')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-brand')).toBeNull()
+  })
+
+  it('throws on any other @deepseek-ai leak', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-agent')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-web')).toThrow(/purity/)
+  })
+
+  it('every /client external has no bare-name twin in the table (the rewrite assumption)', () => {
+    for (const entry of CLIENT_EXTERNALS) {
+      if (entry.endsWith('/client')) expect(CLIENT_EXTERNALS).not.toContain(entry.slice(0, -'/client'.length))
+    }
+  })
+})
--- a/scripts/doc-typecheck-paths.ts
+++ b/scripts/doc-typecheck-paths.ts
@@ -1,11 +1,22 @@
 /** Map one workspace source alias target to its declaration-build target. */
 export function builtDeclarationPath(candidate: string): string {
+  // Two workspace shapes exist: whole-package entries end in /src, subpath
+  // wildcards (apiproxy's browser-safe /api and /client channels) in /src/*.
  if (candidate.endsWith('/src')) {
    return `${candidate.slice(0, -'/src'.length)}/lib/types`
  }
+  if (candidate.endsWith('/src/*')) {
+    return `${candidate.slice(0, -'/src/*'.length)}/lib/types/*`
+  }
  const sourceFile = /^(.*)\/src\/(.+)\.ts$/.exec(candidate)
  if (sourceFile?.[1] && sourceFile[2]) {
    return `${sourceFile[1]}/lib/types/${sourceFile[2]}.d.ts`
  }
+  // Directory subpath entries (web-react's /store, runtime's /client): the
+  // source dir maps to the same dir under lib/types (index resolution applies).
+  const sourceDir = /^(.*)\/src\/(.+)$/.exec(candidate)
+  if (sourceDir?.[1] && sourceDir[2]) {
+    return `${sourceDir[1]}/lib/types/${sourceDir[2]}`
+  }
  throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
 }
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -177,6 +177,9 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
+  LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
+  ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
+  Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
  InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -70,6 +70,7 @@ const GROUP_ORDER = [
  'web',
  'spill',
  'todo',
+  'plan',
  'cordis',
  'hooks',
  'session-persistence',
@@ -170,6 +171,14 @@ const SERVICE_ROLES: ServiceRole[] = [
    consumers: ['tool-ask-user', 'tui', 'acp'],
    note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
  },
+  {
+    key: 'planMode',
+    pkg: 'plan-mode',
+    title: 'Plan collaboration state',
+    mode: 'core',
+    consumers: ['acp'],
+    note: 'Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions.',
+  },
  {
    key: 'commands',
    pkg: 'commands',
--- a/scripts/gen-module-graph.ts
+++ b/scripts/gen-module-graph.ts
@@ -31,6 +31,7 @@ const GROUP_ORDER = [
  'spill',
  'timeout',
  'todo',
+  'plan',
  'cordis',
  'hooks',
  'session-persistence',
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -19,6 +19,7 @@ import type { BashExecRequest, BashExecSpec, BashProcess, BashRunResult } from '
 import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
+import PlanModeService from '@deepseek-ai/dsh-plan-mode'
 import WebService from '@deepseek-ai/dsh-web'
 import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
@@ -172,6 +173,18 @@ const TOOL_PACKAGES: ToolPackage[] = [
    note:
      'Owned by the tool registry as a reserved transport outside filterable capability layers under `mode: code` / `mode: both` (see the Code Mode Agent Note). Under `code` it is the registry\'s only wire contribution; the other visible capabilities are declared in a generated TypeScript SDK section, and a program calls them through serialized bindings that re-enter the complete guarded tool pipeline and link each nested execution to this outer result.',
  },
+  {
+    pkg: '@deepseek-ai/dsh-plan-mode',
+    dir: 'plan-mode',
+    source: 'packages/plan/plan-mode/src/index.ts',
+    requires: ['ctx.tools', 'ctx.systemPrompt', 'ctx.userInteraction (execution time, opportunistic)'],
+    writes: ['tool/call', 'plan/mode inactive on an approved review', 'tool/result'],
+    async mount(ctx) {
+      await ctx.plugin(PlanModeService, { section: 'Tool catalog schema harvest.' })
+    },
+    note:
+      'exit_plan_mode stays in the model-facing schema while planning is inactive so transitions add no tool-catalog churn on top of the plan-policy change. Its execute path rejects calls outside plan mode; in plan mode it presents the plan over the user-interaction seam (approve / keep planning with feedback), and approval logs plan mode inactive at the step boundary.',
+  },
  {
    pkg: '@deepseek-ai/dsh-tool-bash',
    dir: 'tool-bash',
--- a/scripts/prepare-ci-bubblewrap.sh
+++ b/scripts/prepare-ci-bubblewrap.sh
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ubuntu's package transaction scans the hosted image's full dpkg database and
+# runs post-install hooks. CI needs only the signed-archive payload, so pin and
+# verify that payload before extracting it into the ephemeral runner directory.
+readonly BUBBLEWRAP_VERSION='0.9.0-1ubuntu0.1'
+readonly BUBBLEWRAP_SHA256='1b506492bd9c7fd0cdb4f02ac822f1d3e336b0aead5113c1239baf8db5db562a'
+readonly BUBBLEWRAP_URL="https://archive.ubuntu.com/ubuntu/pool/main/b/bubblewrap/bubblewrap_${BUBBLEWRAP_VERSION}_amd64.deb"
+
+: "${RUNNER_TEMP:?prepare-ci-bubblewrap requires RUNNER_TEMP}"
+: "${GITHUB_PATH:?prepare-ci-bubblewrap requires GITHUB_PATH}"
+
+if [[ "$(uname -s)" != 'Linux' || "$(uname -m)" != 'x86_64' ]]; then
+  echo 'prepare-ci-bubblewrap supports only Linux x86_64 hosted runners' >&2
+  exit 1
+fi
+
+archive="${RUNNER_TEMP}/bubblewrap_${BUBBLEWRAP_VERSION}_amd64.deb"
+root="${RUNNER_TEMP}/dsh-bubblewrap"
+
+curl --fail --silent --show-error --location --retry 3 --output "$archive" "$BUBBLEWRAP_URL"
+printf '%s  %s\n' "$BUBBLEWRAP_SHA256" "$archive" | sha256sum --check --status
+mkdir -p "$root"
+dpkg-deb --extract "$archive" "$root"
+printf '%s\n' "$root/usr/bin" >> "$GITHUB_PATH"
+
+sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 \
+  || echo 'apparmor userns knob absent — the functional probe decides'
+"$root/usr/bin/bwrap" --version
+"$root/usr/bin/bwrap" --ro-bind / / --dev /dev --proc /proc --die-with-parent -- true
+echo 'bubblewrap functional probe passed'
--- a/scripts/publint-all.spec.ts
+++ b/scripts/publint-all.spec.ts
@@ -0,0 +1,61 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repositoryRoot = fileURLToPath(new URL('..', import.meta.url))
+const runner = fileURLToPath(new URL('./publint-all.ts', import.meta.url))
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function fixture(exportPath = './lib/index.js'): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-publint-all-'))
+  roots.push(root)
+  const packageDir = join(root, 'packages/core/probe')
+  mkdirSync(join(packageDir, 'lib'), { recursive: true })
+  writeFileSync(join(packageDir, 'package.json'), `${JSON.stringify({
+    name: '@deepseek-ai/dsh-probe',
+    version: '0.0.1',
+    type: 'module',
+    license: 'MIT',
+    engines: { node: '>=22.19' },
+    sideEffects: false,
+    files: ['lib'],
+    exports: { '.': { default: exportPath } },
+  }, null, 2)}\n`)
+  writeFileSync(join(packageDir, 'README.md'), '# Probe\n')
+  writeFileSync(join(packageDir, 'lib/index.js'), 'export const probe = true\n')
+  writeFileSync(join(packageDir, 'unpublished.js'), 'export const hidden = true\n')
+  return root
+}
+
+function run(root: string) {
+  return spawnSync(process.execPath, [
+    '--import', 'tsx', runner,
+    '--packages-root', root,
+  ], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+    timeout: 5_000,
+  })
+}
+
+describe('publint package runner', () => {
+  it('lints recursively declared files from an in-memory publication view', () => {
+    const result = run(fixture())
+    expect(result.status, result.stderr).toBe(0)
+    expect(result.stdout).toContain('linting 1 package(s)')
+    expect(result.stdout).toContain('All good!')
+  })
+
+  it('rejects an export that exists in the workspace but is not published', () => {
+    const result = run(fixture('./unpublished.js'))
+    expect(result.status).toBe(1)
+    expect(result.stdout).toContain('unpublished.js')
+  })
+})
--- a/scripts/publint-all.ts
+++ b/scripts/publint-all.ts
@@ -1,46 +1,53 @@
-import { execFile } from 'node:child_process'
-import { existsSync, readdirSync } from 'node:fs'
+/** Run publint over the exact manifest-declared publication view of every package. */
+
+import {
+  globSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+} from 'node:fs'
 import { availableParallelism } from 'node:os'
-import { resolve } from 'node:path'
-import { promisify } from 'node:util'
+import { dirname, relative, resolve, sep } from 'node:path'
+import { publint, type Message, type PackFile } from 'publint'
+import { formatMessage } from 'publint/utils'

-const execFileAsync = promisify(execFile)
 const CONCURRENCY_ENV = 'DSH_PUBLINT_CONCURRENCY'
+const repositoryRoot = resolve(import.meta.dirname, '..')
+const options = parseOptions(process.argv.slice(2))
+const packagesRoot = resolve(options.get('--packages-root') ?? repositoryRoot)

-// Discover harness packages at packages/<group>/<pkg>; group containers,
-// examples, and private vendored sources are not package targets.
-const root = resolve(import.meta.dirname, '..')
-const packagesRoot = resolve(root, 'packages')
+interface PackageTarget {
+  path: string
+  directory: string
+  manifest: PackageManifest
+}

-// Run publint's JS CLI through the current node, not the .bin shim: the
-// extensionless shim isn't spawnable on Windows (CVE-2024-27980) and the .cmd
-// variant needs shell:true, which space-joins args UNESCAPED (DEP0190) and
-// breaks when the repo path contains spaces. The JS entry is identical on every
-// platform (`bin` is `./src/cli.js` per publint's package.json).
-const publintCli = resolve(root, 'node_modules/publint/src/cli.js')
+interface PackageManifest {
+  name?: string
+  files?: unknown
+}

 type PublintResult =
-  | { path: string; status: 'passed'; stdout: string; stderr: string }
-  | { path: string; status: 'failed'; stdout: string; stderr: string; message: string }
+  | { path: string; status: 'passed'; messages: Message[]; manifest: Record<string, unknown> }
+  | { path: string; status: 'failed'; messages: Message[]; manifest: Record<string, unknown>; failure?: string }

-function workspacePackages(): string[] {
-  return readdirSync(packagesRoot, { withFileTypes: true })
-    .filter(group => group.isDirectory())
-    .flatMap(group =>
-      readdirSync(resolve(packagesRoot, group.name), { withFileTypes: true })
-        .filter(pkg => pkg.isDirectory())
-        .filter(pkg => existsSync(resolve(packagesRoot, group.name, pkg.name, 'package.json')))
-        .map(pkg => `packages/${group.name}/${pkg.name}`),
-    )
+function workspacePackages(): PackageTarget[] {
+  return globSync('packages/*/*/package.json', { cwd: packagesRoot })
+    .sort()
+    .map((manifestPath) => {
+      const absoluteManifestPath = resolve(packagesRoot, manifestPath)
+      const manifest = JSON.parse(readFileSync(absoluteManifestPath, 'utf8')) as PackageManifest
+      return { path: dirname(manifestPath), directory: dirname(absoluteManifestPath), manifest }
+    })
 }

 function publintConcurrency(total: number): number {
  if (total === 0) return 0

  const raw = process.env[CONCURRENCY_ENV]
-  if (raw !== undefined) {
+  if (raw !== undefined && raw !== '') {
    const parsed = Number.parseInt(raw, 10)
-    if (!Number.isSafeInteger(parsed) || parsed < 1) {
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || String(parsed) !== raw) {
      throw new Error(`publint-all: ${CONCURRENCY_ENV} must be a positive integer, got ${JSON.stringify(raw)}.`)
    }
    return Math.min(total, parsed)
@@ -49,57 +56,106 @@ function publintConcurrency(total: number): number {
  return Math.min(total, availableParallelism())
 }

-function outputText(value: unknown): string {
-  if (typeof value === 'string') return value
-  if (Buffer.isBuffer(value)) return value.toString()
-  return ''
+function publicationFiles(target: PackageTarget): PackFile[] {
+  const paths = new Set<string>()
+  addPath(resolve(target.directory, 'package.json'), paths)
+  const declared = Array.isArray(target.manifest.files)
+    ? target.manifest.files.filter((value): value is string => typeof value === 'string')
+    : []
+  for (const pattern of [
+    ...declared,
+    'README*',
+    'LICENSE*',
+    'LICENCE*',
+    'CHANGELOG*',
+    'CHANGES*',
+    'HISTORY*',
+    'NOTICE*',
+  ]) {
+    for (const match of globSync(pattern, { cwd: target.directory })) {
+      addPath(resolve(target.directory, match), paths)
+    }
+  }
+
+  return [...paths]
+    .sort()
+    .map(path => ({
+      name: `package/${relative(target.directory, path).split(sep).join('/')}`,
+      data: readFileSync(path),
+    }))
 }

-async function runPublint(path: string): Promise<PublintResult> {
+function addPath(path: string, paths: Set<string>): void {
+  const stat = statSync(path)
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(path)) addPath(resolve(path, entry), paths)
+  } else if (stat.isFile()) {
+    paths.add(path)
+  }
+}
+
+async function runPublint(target: PackageTarget): Promise<PublintResult> {
  try {
-    const { stdout, stderr } = await execFileAsync(process.execPath, [publintCli, path], {
-      cwd: root,
-      encoding: 'utf8',
-      maxBuffer: 10 * 1024 * 1024,
+    const result = await publint({
+      pkgDir: 'package',
+      pack: { files: publicationFiles(target) },
    })
-    return { path, status: 'passed', stdout, stderr }
+    const manifest = result.pkg as Record<string, unknown>
+    return result.messages.some(message => message.type === 'error')
+      ? { path: target.path, status: 'failed', messages: result.messages, manifest }
+      : { path: target.path, status: 'passed', messages: result.messages, manifest }
  } catch (error: unknown) {
-    const failed = error as { stdout?: unknown; stderr?: unknown; message?: string }
    return {
-      path,
+      path: target.path,
      status: 'failed',
-      stdout: outputText(failed.stdout),
-      stderr: outputText(failed.stderr),
-      message: failed.message ?? 'publint failed',
+      messages: [],
+      manifest: target.manifest as Record<string, unknown>,
+      failure: error instanceof Error ? error.message : String(error),
    }
  }
 }

-async function runAll(paths: string[], concurrency: number): Promise<PublintResult[]> {
+async function runAll(targets: PackageTarget[], concurrency: number): Promise<PublintResult[]> {
  let next = 0
  const results: Array<PublintResult | undefined> = []
  await Promise.all(Array.from({ length: concurrency }, async () => {
    for (;;) {
      const index = next
      next += 1
-      const path = paths[index]
-      if (path === undefined) return
-      results[index] = await runPublint(path)
+      const target = targets[index]
+      if (target === undefined) return
+      results[index] = await runPublint(target)
    }
  }))

-  return paths.map((path, index) => {
+  return targets.map((target, index) => {
    const result = results[index]
-    if (result === undefined) throw new Error(`publint-all: missing result for ${path}.`)
+    if (result === undefined) throw new Error(`publint-all: missing result for ${target.path}.`)
    return result
  })
 }

 function printResult(result: PublintResult): void {
  console.log(`Running publint for ${result.path}...`)
-  process.stdout.write(result.stdout)
-  process.stderr.write(result.stderr)
-  if (result.status === 'failed') console.error(result.message)
+  if ('failure' in result) console.error(result.failure)
+  for (const message of result.messages) {
+    console.log(formatMessage(message, result.manifest, { color: false }) ?? message.code)
+  }
+  if (result.status === 'passed' && result.messages.length === 0) console.log('All good!')
+}
+
+function parseOptions(args: string[]): Map<string, string> {
+  const parsed = new Map<string, string>()
+  for (let index = 0; index < args.length; index += 2) {
+    const name = args[index]
+    const value = args[index + 1]
+    if (name !== '--packages-root' || value === undefined || value.startsWith('--')) {
+      throw new Error(`publint-all: expected [--packages-root PATH], got ${JSON.stringify(args)}.`)
+    }
+    if (parsed.has(name)) throw new Error(`publint-all: duplicate option ${name}.`)
+    parsed.set(name, value)
+  }
+  return parsed
 }

 const packages = workspacePackages()
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -16,7 +16,12 @@ type Mode =
  | 'ci-coverage'
  | 'ci-snapshot'
  | 'ci-artifacts'
+  | 'ci-windows-blocking'
+  | 'ci-windows-complete'
+  | 'ci-windows-observational'
  | 'node-compat'
+  | 'pre-push'
+  | 'manual-push'
  | 'doc-sync'
 type GateStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped'

@@ -30,6 +35,7 @@ interface Gate {
  env?: Record<string, string | undefined>
  input?: string
  verify?: (result: GateResult) => Promise<void>
+  allowFailure?: boolean
 }

 interface GateResult {
@@ -75,7 +81,9 @@ console.log(`run-gates: ${mode} running ${gates.length} gate(s) with ${maxConcur
 const results = await runGates(gates, maxConcurrency)
 printSummary(results, performance.now() - startedAt)

-if (results.some(result => result.status === 'failed' || result.status === 'skipped')) process.exit(1)
+if (results.some(result => result.gate.allowFailure !== true && (result.status === 'failed' || result.status === 'skipped'))) {
+  process.exit(1)
+}

 function parseMode(raw: string | undefined): Mode {
  switch (raw) {
@@ -85,21 +93,26 @@ function parseMode(raw: string | undefined): Mode {
    case 'ci-coverage':
    case 'ci-snapshot':
    case 'ci-artifacts':
+    case 'ci-windows-blocking':
+    case 'ci-windows-complete':
+    case 'ci-windows-observational':
    case 'node-compat':
+    case 'pre-push':
+    case 'manual-push':
    case 'doc-sync':
      return raw
    default:
      throw new Error(
-        `run-gates: expected mode ci-primary | ci-static | ci-lint | ci-coverage | ci-snapshot | ci-artifacts | node-compat | doc-sync, got ${JSON.stringify(raw)}.`,
+        `run-gates: expected mode ci-primary | ci-static | ci-lint | ci-coverage | ci-snapshot | ci-artifacts | ci-windows-blocking | ci-windows-complete | ci-windows-observational | node-compat | pre-push | manual-push | doc-sync, got ${JSON.stringify(raw)}.`,
      )
  }
 }

 function defaultConcurrency(selectedMode: Mode, total: number): ConcurrencyDefault {
  const available = availableParallelism()
-  // The local doc mode caps workers: several gates each build a full ts.Program,
+  // Local modes cap workers: several doc gates each build a full ts.Program,
  // so an uncapped default on a large host trades wall clock for memory blowups.
-  const localCap = selectedMode === 'doc-sync'
+  const localCap = selectedMode === 'pre-push' || selectedMode === 'doc-sync'
  const modeLimit = localCap ? Math.min(4, available) : available
  return {
    workers: Math.min(total, modeLimit),
@@ -164,30 +177,36 @@ function gatesForMode(selected: Mode): Gate[] {
        pnpmScript('duplication', 'duplication'),
      ]
    case 'ci-coverage':
-      return [
-        pnpmScript('build', 'build'),
-        coverageGate(),
-      ]
+      return [coverageGate()]
    case 'ci-snapshot':
-      return [
-        pnpmScript('build', 'build'),
-        snapshotGate(),
-      ]
+      return [pnpmScript('build', 'build'), snapshotGate()]
    case 'ci-artifacts':
      return ciArtifactGates()
+    case 'ci-windows-blocking':
+      return ciWindowsBlockingGates()
+    case 'ci-windows-complete':
+      return ciWindowsCompleteGates()
+    case 'ci-windows-observational':
+      return ciWindowsObservationalGates()
    case 'node-compat':
+      return nodeCompatGates()
+    case 'pre-push': return []
+    case 'manual-push':
      return [
-        pnpmScript('typecheck', 'typecheck'),
-        pnpmExec('source-worker-smoke', [
-          'vitest',
-          'run',
-          'packages/workflow/workflow-workerthread/tests/source-worker.compat.spec.ts',
-        ], { label: 'source worker smoke' }),
-        pnpmExec('jsonl-zstd-smoke', [
-          'vitest',
-          'run',
-          'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts',
-        ], { label: 'JSONL Zstandard smoke' }),
+        pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
+        pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
+        pnpmScript('client-domain-graph', 'verify-client-domain-graph', { label: 'client domain graph' }),
+        pnpmScript('test', 'test'),
+        pnpmScript('duplication', 'duplication'),
+        snapshotGate(),
+        pnpmScript('build', 'build'),
+        pnpmScript('build:web', 'build:web'),
+        ...hygieneLeafGates({ artifactNeeds: ['build'] }),
+        ...docSyncLeafGates({
+          docTypecheckNeeds: ['build'],
+          docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
+        }),
+        pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
      ]
    case 'doc-sync':
      return docSyncLeafGates()
@@ -204,11 +223,12 @@ function ciPrimaryGates(): Gate[] {
    lintGate(),
    pnpmScript('duplication', 'duplication'),
    coverageGate(),
+    ...nodeCompatSmokeGates(),
    snapshotGate(),
    ...docSyncLeafGates(),
    pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
    pnpmScript('knip', 'knip'),
-    pnpmScript('build', 'build', { needs: ['typecheck'] }),
+    pnpmScript('build', 'build'),
    pnpmScript('publint', 'publint', { needs: ['build'] }),
    pnpmScript('node-next-types', 'verify-node-next-types', {
      label: 'node-next types',
@@ -219,13 +239,40 @@ function ciPrimaryGates(): Gate[] {
  ]
 }

+function nodeCompatGates(): Gate[] {
+  return [
+    ...flagEnabled('DSH_NODE_COMPAT_SKIP_TYPECHECK') ? [] : [pnpmScript('typecheck', 'typecheck')],
+    ...nodeCompatSmokeGates(),
+  ]
+}
+
+function nodeCompatSmokeGates(): Gate[] {
+  return [
+    pnpmExec('source-worker-smoke', [
+      'vitest',
+      'run',
+      'packages/workflow/workflow-workerthread/tests/source-worker.compat.spec.ts',
+    ], { label: 'source worker smoke' }),
+    pnpmExec('jsonl-zstd-smoke', [
+      'vitest',
+      'run',
+      'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts',
+    ], { label: 'JSONL Zstandard smoke' }),
+  ]
+}
+
 function ciStaticGates(): Gate[] {
  return [
    pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
    pnpmScript('constraints', 'constraints'),
    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
    pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
-    ...docSyncLeafGates(),
+    pnpmScript('build', 'build'),
+    ...docSyncLeafGates({
+      docTypecheckNeeds: ['build'],
+      docTypecheckEnv: { DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1' },
+      docsBuildScript: 'docs:build:mpa',
+    }),
    pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
    pnpmScript('knip', 'knip'),
  ]
@@ -244,11 +291,54 @@ function ciArtifactGates(): Gate[] {
  ]
 }

-function lintGate(): Gate {
+function ciWindowsBlockingGates(): Gate[] {
+  return [
+    pnpmScript('windows-build', 'build', { label: 'build' }),
+    pnpmScript('windows-site', 'docs:build', { label: 'production site' }),
+  ]
+}
+
+function ciWindowsCompleteGates(): Gate[] {
+  const observational = ciWindowsObservationalGates()
+    // The required production site replaces the observational MPA build; both
+    // VitePress modes write the same output directory and cannot overlap.
+    .filter(gate => gate.id !== 'build' && gate.id !== 'docs-site-build')
+    .map(gate => ({ ...gate, allowFailure: true }))
+  return [
+    pnpmScript('build', 'build'),
+    pnpmScript('windows-site', 'docs:build', { label: 'production site' }),
+    ...observational,
+  ]
+}
+
+function ciWindowsObservationalGates(): Gate[] {
+  return [
+    ...ciStaticGates(),
+    lintGate(),
+    pnpmScript('duplication', 'duplication'),
+    {
+      ...coverageGate(),
+      env: { DSH_EXAMPLE_MODE: 'lib' },
+      needs: ['build'],
+    },
+    snapshotGate(),
+    pnpmScript('publint', 'publint', { needs: ['build'] }),
+    pnpmScript('node-next-types', 'verify-node-next-types', {
+      label: 'node-next types',
+      needs: ['build'],
+    }),
+    builtPackageInvariantsGate(['build']),
+    builtBinSmokeGate(),
+  ]
+}
+
+function lintGate(eslintTargets: readonly string[] = ['.']): Gate {
+  const concurrencyArgs = eslintConcurrencyArgs()
  if (process.env.DSH_ESLINT_CACHE === '1') {
    return pnpmExec('lint', [
      'eslint',
-      '.',
+      ...eslintTargets,
+      ...concurrencyArgs,
      '--cache',
      '--cache-location',
      '.cache/eslint/',
@@ -259,11 +349,28 @@ function lintGate(): Gate {
      env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
    })
  }
+  if (concurrencyArgs.length > 0) {
+    return pnpmExec('lint', ['eslint', ...eslintTargets, ...concurrencyArgs], {
+      label: 'lint',
+      env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
+    })
+  }
  return pnpmScript('lint', 'lint', {
    env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
  })
 }

+function eslintConcurrencyArgs(): string[] {
+  const raw = process.env.DSH_ESLINT_CONCURRENCY
+  if (raw === undefined || raw === '') return []
+  if (raw === 'auto') return ['--concurrency=auto']
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || String(parsed) !== raw) {
+    throw new Error(`run-gates: DSH_ESLINT_CONCURRENCY must be a positive integer or auto, got ${JSON.stringify(raw)}.`)
+  }
+  return [`--concurrency=${raw}`]
+}
+
 function coverageGate(): Gate {
  return pnpmExec('coverage', [
    'vitest',
@@ -272,14 +379,12 @@ function coverageGate(): Gate {
    ...positiveIntArg('DSH_COVERAGE_MAX_WORKERS', '--maxWorkers'),
  ], {
    label: 'test:coverage',
-    env: { DSH_EXAMPLE_MODE: 'lib' },
-    needs: ['build'],
  })
 }

 // The snapshot suite boots the example bins in `lib` mode (built artifact under plain Node,
-// plugins via real exports). CI pairs it with `build`, so it exercises what ships rather than
-// the tsx/source path dev uses and therefore waits on `build`.
+// plugins via real exports) — CI and pre-push already build, so they exercise what ships rather
+// than the tsx/source path dev uses. It therefore waits on `build`.
 function snapshotGate(): Gate {
  return pnpmScript('snapshot', 'test:snapshot', {
    env: { DSH_EXAMPLE_MODE: 'lib' },
@@ -304,9 +409,38 @@ function positiveIntArg(envName: string, flag: string): string[] {
  return [`${flag}=${raw}`]
 }

-function docSyncLeafGates(): Gate[] {
+function flagEnabled(envName: string): boolean {
+  const raw = process.env[envName]
+  if (raw === undefined || raw === '') return false
+  if (raw !== '1') throw new Error(`run-gates: ${envName} must be 1 when set, got ${JSON.stringify(raw)}.`)
+  return true
+}
+
+function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
+  const artifactOptions = options.artifactNeeds === undefined ? {} : { needs: options.artifactNeeds }
  return [
-    pnpmScript('doc-typecheck', 'doc-typecheck'),
+    pnpmScript('knip', 'knip'),
+    pnpmScript('publint', 'publint', artifactOptions),
+    pnpmScript('constraints', 'constraints'),
+    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
+    builtPackageInvariantsGate(options.artifactNeeds),
+    pnpmScript('node-next-types', 'verify-node-next-types', {
+      label: 'node-next types',
+      ...artifactOptions,
+    }),
+  ]
+}
+
+function docSyncLeafGates(options: {
+  docTypecheckNeeds?: string[]
+  docTypecheckEnv?: Record<string, string | undefined>
+  docsBuildScript?: 'docs:build' | 'docs:build:mpa'
+} = {}): Gate[] {
+  const docTypecheckOptions: Partial<Gate> = {}
+  if (options.docTypecheckNeeds !== undefined) docTypecheckOptions.needs = options.docTypecheckNeeds
+  if (options.docTypecheckEnv !== undefined) docTypecheckOptions.env = options.docTypecheckEnv
+  return [
+    pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions),
    pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
    pnpmScript('cordis-api', 'verify-cordis-api', { label: 'cordis api' }),
    pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
@@ -327,8 +461,11 @@ function docSyncLeafGates(): Gate[] {
    pnpmScript('translation-prompt', 'verify-translation-prompt', { label: 'translation prompt' }),
    pnpmScript('translation-pairing', 'verify-translation-pairing', { label: 'translation pairing' }),
    pnpmScript('doc-budgets', 'verify-doc-budgets', { label: 'doc budgets' }),
-    // Keep the VitePress build in this single gate because projection rewrites website/.generated.
-    pnpmScript('docs-site', 'docs:check', { label: 'documentation site' }),
+    pnpmExec('docs-site-projection', ['vitest', 'run', 'scripts/project-doc-site.spec.ts'], {
+      label: 'documentation projection',
+    }),
+    // Keep the VitePress build itself in one gate because projection rewrites website/.generated.
+    pnpmScript('docs-site-build', options.docsBuildScript ?? 'docs:build', { label: 'documentation build' }),
    pnpmScript('package-readme-limitations', 'verify-package-readme-limitations', { label: 'package README limitations' }),
  ]
 }
@@ -498,7 +635,8 @@ function printSummary(results: GateResult[], durationMs: number): void {
  for (const result of unsuccessful) {
    const duration = (result.durationMs / 1000).toFixed(2)
    const reason = result.error ?? (result.exitCode === null ? 'no exit code' : `exit ${result.exitCode}`)
-    console.error(`  - ${result.status.toUpperCase()} ${result.gate.label} (${duration}s, ${reason})`)
+    const disposition = result.gate.allowFailure === true ? 'NON-BLOCKING ' : ''
+    console.error(`  - ${disposition}${result.status.toUpperCase()} ${result.gate.label} (${duration}s, ${reason})`)
    console.error(`    ${result.gate.displayCommand}`)
  }
 }
--- a/scripts/translation-pairing.manifest.json
+++ b/scripts/translation-pairing.manifest.json
@@ -1,6 +1,13 @@
 {
  "requiredSince": "2026-07-14",
  "required": [
+    ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
+    ".agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md",
+    ".agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md",
+    ".agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md",
+    ".agents/notes/implemented/architecture/2026-07-22-slot-type-chain-implementation.md",
+    ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
+    ".agents/notes/implemented/process/2026-07-19-web-styling-system.md",
    "README.md",
    "docs/cookbook/adding-a-package.md",
    "docs/cookbook/adding-a-tool.md",
@@ -23,9 +30,6 @@
    "docs/user/guide/index.md",
    "docs/user/guide/quickstart.md",
    "docs/user/index.md",
-    ".agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md",
-    ".agents/notes/implemented/architecture/2026-07-16-explicit-turn-cancellation.md",
-    ".agents/notes/implemented/process/2026-07-02-bilingual-docs-and-pairing-gate.md",
    "python/README.md",
    "python/sdk-runtime/README.md",
    "python/sdk/README.md"
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
--- a/scripts/verify-built-package-invariants.mjs
+++ b/scripts/verify-built-package-invariants.mjs
@@ -1,102 +1,106 @@
-/** Verify every packed companion through its package self-reference under plain Node. */
+/** Verify every compiled companion through its staged package self-reference under plain Node. */

-import { spawnSync } from 'node:child_process'
 import {
  copyFileSync,
+  cpSync,
+  existsSync,
  globSync,
  mkdirSync,
  mkdtempSync,
  readFileSync,
  rmSync,
+  writeFileSync,
 } from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'

-const root = resolve(import.meta.dirname, '..')
-const loaderUrl = pathToFileURL(resolve(root, 'vendor/loader/lib/index.js')).href
+const repositoryRoot = resolve(import.meta.dirname, '..')
+const options = parseOptions(process.argv.slice(2))
+const packagesRoot = resolve(options.get('--packages-root') ?? repositoryRoot)
+const loaderUrl = options.get('--loader-url')
+  ?? pathToFileURL(resolve(repositoryRoot, 'vendor/loader/lib/index.js')).href
 const failures = []
-const manifests = globSync('packages/*/*/package.json', { cwd: root }).sort()
-const packArgs = ['pack', '--dry-run', '--json', '--ignore-scripts']
-// Windows cannot spawn npm's .cmd shim directly; setup-node installs this JS
-// entrypoint beside node.exe, so the probe stays shell-free on every runner.
-const npmInvocation = process.platform === 'win32'
-  ? [process.execPath, [resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'), ...packArgs]]
-  : ['npm', packArgs]
+const manifests = globSync('packages/*/*/package.json', { cwd: packagesRoot }).sort()
+const { default: Loader } = await import(loaderUrl)
+const loader = Object.create(Loader.prototype)

 for (const manifestPath of manifests) {
-  const packageDir = dirname(resolve(root, manifestPath))
-  const manifest = JSON.parse(readFileSync(resolve(root, manifestPath), 'utf8'))
+  const packageDir = dirname(resolve(packagesRoot, manifestPath))
+  const manifest = JSON.parse(readFileSync(resolve(packagesRoot, manifestPath), 'utf8'))
  const packageName = manifest.name
  if (typeof packageName !== 'string' || packageName.length === 0) {
    failures.push(`${manifestPath}: missing package name`)
    continue
  }
-
-  const pack = spawnSync(npmInvocation[0], npmInvocation[1], {
-    cwd: packageDir,
-    encoding: 'utf8',
-  })
-  if (pack.status !== 0) {
-    const detail = pack.error?.message
-      ?? (pack.stderr.trim() || pack.stdout.trim() || `npm pack exited ${pack.status}`)
-    failures.push(`${packageName}: ${detail}`)
+  const invariantExport = manifest.exports?.['./invariant']
+  if (typeof invariantExport !== 'object'
+    || invariantExport.default !== './lib/invariant.js'
+    || !manifest.files?.includes('lib/invariant.js')) {
+    failures.push(`${packageName}: manifest does not publish ./lib/invariant.js as ./invariant`)
    continue
  }

-  let files
-  try {
-    const result = JSON.parse(pack.stdout)
-    files = result[0]?.files
-    if (!Array.isArray(files)) throw new Error('npm pack returned no file inventory')
-  } catch (error) {
-    failures.push(`${packageName}: cannot parse npm pack inventory: ${String(error)}`)
-    continue
-  }
-
-  // Keep the packed view below its owning package so Node reaches the real
+  // Keep the staged view below its owning package so Node reaches the real
  // pnpm dependency links. Junctioning node_modules elsewhere breaks pnpm's
-  // relative workspace links on Windows.
-  const stagedPackageDir = mkdtempSync(resolve(packageDir, '.dsh-packed-invariant-'))
+  // relative workspace links on Windows. Copy the manifest-declared lib view
+  // so a companion that imports an undeclared runtime chunk fails here.
+  const stagedPackageDir = mkdtempSync(resolve(packageDir, '.dsh-built-invariant-'))
  try {
-    for (const file of files) {
-      if (typeof file.path !== 'string'
-        || (file.path !== 'package.json' && !file.path.startsWith('lib/'))) continue
-      const target = resolve(stagedPackageDir, file.path)
-      mkdirSync(dirname(target), { recursive: true })
-      copyFileSync(resolve(packageDir, file.path), target)
-    }
-
-    const probe = `
-      const companion = await import(${JSON.stringify(`${packageName}/invariant`)});
-      const { default: Loader } = await import(${JSON.stringify(loaderUrl)});
-      if ('default' in companion) throw new Error('companion has a default export');
-      const loader = Object.create(Loader.prototype);
-      const unwrapped = loader.unwrapExports(companion);
-      if (unwrapped !== companion) throw new Error('Loader collapsed the companion namespace');
-      if (typeof unwrapped.name !== 'string') throw new Error('companion name is missing');
-      if (!Array.isArray(unwrapped.inject) || !unwrapped.inject.includes('invariants')) {
-        throw new Error('companion does not inject invariants');
-      }
-      if (typeof unwrapped.apply !== 'function') throw new Error('companion apply is missing');
-    `
-    const result = spawnSync(process.execPath, ['--input-type=module', '--eval', probe], {
-      cwd: stagedPackageDir,
-      encoding: 'utf8',
-    })
-    if (result.status !== 0) {
-      const detail = result.error?.message
-        ?? (result.stderr.trim() || result.stdout.trim() || `node exited ${result.status}`)
-      failures.push(`${packageName}: ${detail}`)
+    copyFileSync(resolve(packageDir, 'package.json'), resolve(stagedPackageDir, 'package.json'))
+    copyDeclaredLibFiles(packageDir, stagedPackageDir, manifest.files)
+    const probePath = resolve(stagedPackageDir, 'probe.mjs')
+    writeFileSync(
+      probePath,
+      `import * as companion from ${JSON.stringify(`${packageName}/invariant`)}\nexport default companion\n`,
+    )
+    const { default: companion } = await import(pathToFileURL(probePath).href)
+    if ('default' in companion) throw new Error('companion has a default export')
+    const unwrapped = loader.unwrapExports(companion)
+    if (unwrapped !== companion) throw new Error('Loader collapsed the companion namespace')
+    if (typeof unwrapped.name !== 'string') throw new Error('companion name is missing')
+    if (!Array.isArray(unwrapped.inject) || !unwrapped.inject.includes('invariants')) {
+      throw new Error('companion does not inject invariants')
    }
+    if (typeof unwrapped.apply !== 'function') throw new Error('companion apply is missing')
+  } catch (error) {
+    failures.push(`${packageName}: ${error instanceof Error ? error.message : String(error)}`)
  } finally {
    rmSync(stagedPackageDir, { recursive: true, force: true })
  }
 }

 if (failures.length > 0) {
-  console.error('verify-built-package-invariants: packed companion failures:')
+  console.error('verify-built-package-invariants: compiled companion failures:')
  for (const failure of failures) console.error(`  ${failure}`)
  process.exit(1)
 }

-console.log(`verify-built-package-invariants: ${manifests.length} packed companion(s) passed plain-Node Loader checks.`)
+console.log(`verify-built-package-invariants: ${manifests.length} compiled companion(s) passed plain-Node Loader checks.`)
+
+function parseOptions(args) {
+  const allowed = new Set(['--packages-root', '--loader-url'])
+  const parsed = new Map()
+  for (let index = 0; index < args.length; index += 2) {
+    const name = args[index]
+    const value = args[index + 1]
+    if (!allowed.has(name) || value === undefined || value.startsWith('--')) {
+      throw new Error(`verify-built-package-invariants: expected [--packages-root PATH] [--loader-url URL], got ${JSON.stringify(args)}.`)
+    }
+    if (parsed.has(name)) throw new Error(`verify-built-package-invariants: duplicate option ${name}.`)
+    parsed.set(name, value)
+  }
+  return parsed
+}
+
+function copyDeclaredLibFiles(packageDir, stagedPackageDir, files) {
+  for (const pattern of files) {
+    if (!pattern.startsWith('lib/')) continue
+    for (const relativePath of globSync(pattern, { cwd: packageDir })) {
+      const source = resolve(packageDir, relativePath)
+      if (!existsSync(source)) continue
+      const target = resolve(stagedPackageDir, relativePath)
+      mkdirSync(dirname(target), { recursive: true })
+      cpSync(source, target, { recursive: true })
+    }
+  }
+}
--- a/scripts/verify-built-package-invariants.spec.ts
+++ b/scripts/verify-built-package-invariants.spec.ts
@@ -0,0 +1,88 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const verifier = fileURLToPath(new URL('./verify-built-package-invariants.mjs', import.meta.url))
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function fixture(options: {
+  invariantSource?: string
+  invariantExport?: string
+  runtimeChunk?: string
+} = {}): { root: string; loaderUrl: string } {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-built-package-invariants-'))
+  roots.push(root)
+  const packageDir = join(root, 'packages/core/probe')
+  mkdirSync(join(packageDir, 'lib'), { recursive: true })
+  writeFileSync(join(packageDir, 'package.json'), `${JSON.stringify({
+    name: '@deepseek-ai/dsh-probe',
+    type: 'module',
+    files: ['lib/invariant.js'],
+    exports: {
+      './invariant': {
+        default: options.invariantExport ?? './lib/invariant.js',
+      },
+    },
+  }, null, 2)}\n`)
+  writeFileSync(
+    join(packageDir, 'lib/invariant.js'),
+    options.invariantSource ?? "export const name = 'probe-invariant'\nexport const inject = ['invariants']\nexport const apply = () => {}\n",
+  )
+  if (options.runtimeChunk !== undefined) {
+    writeFileSync(join(packageDir, 'lib/chunk.js'), options.runtimeChunk)
+  }
+  const loaderPath = join(root, 'loader.mjs')
+  writeFileSync(loaderPath, 'export default class Loader { unwrapExports(value) { return value } }\n')
+  return { root, loaderUrl: pathToFileURL(loaderPath).href }
+}
+
+function verify(root: string, loaderUrl: string) {
+  return spawnSync(process.execPath, [
+    verifier,
+    '--packages-root', root,
+    '--loader-url', loaderUrl,
+  ], {
+    encoding: 'utf8',
+    timeout: 5_000,
+  })
+}
+
+describe('built package invariant verifier', () => {
+  it('loads the staged compiled self-reference through plain Node and Loader normalization', () => {
+    const { root, loaderUrl } = fixture()
+    const result = verify(root, loaderUrl)
+    expect(result.status, result.stderr).toBe(0)
+    expect(result.stdout).toContain('1 compiled companion(s) passed plain-Node Loader checks')
+  })
+
+  it('rejects a default export and a broken invariant export map', () => {
+    const withDefault = fixture({
+      invariantSource: "export default {}\nexport const name = 'probe-invariant'\nexport const inject = ['invariants']\nexport const apply = () => {}\n",
+    })
+    const defaultResult = verify(withDefault.root, withDefault.loaderUrl)
+    expect(defaultResult.status).toBe(1)
+    expect(defaultResult.stderr).toContain('companion has a default export')
+
+    const brokenExport = fixture({ invariantExport: './lib/missing.js' })
+    const exportResult = verify(brokenExport.root, brokenExport.loaderUrl)
+    expect(exportResult.status).toBe(1)
+    expect(exportResult.stderr).toContain('@deepseek-ai/dsh-probe')
+  })
+
+  it('rejects an invariant bundle that needs an unstaged runtime chunk', () => {
+    const { root, loaderUrl } = fixture({
+      invariantSource: "export * from './chunk.js'\n",
+      runtimeChunk: "export const name = 'probe-invariant'\nexport const inject = ['invariants']\nexport const apply = () => {}\n",
+    })
+    const result = verify(root, loaderUrl)
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('chunk.js')
+  })
+})
--- a/scripts/verify-client-domain-graph.ts
+++ b/scripts/verify-client-domain-graph.ts
@@ -0,0 +1,102 @@
+/**
+ * Enforce intra-package domain layering inside `packages/client/*\/src/client/`.
+ * verify-module-graph covers package-level edges; this gate covers the
+ * directory level the future package split will land on: domain directories
+ * may import `contract/` and never each other, and only the assembly point
+ * (`apply.ts` / `index.ts`) may import across domains.
+ *
+ * Layer model (lower may not import higher):
+ *   0  contract/            shared contract surface (types + slot declarations)
+ *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
+ *   2  apply.ts, index.ts   assembly point and re-export shell
+ *
+ * Not yet wired into the gate sequence (loose-gate window); run directly:
+ *   pnpm exec tsx scripts/verify-client-domain-graph.ts
+ */
+
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+
+const root = resolve(import.meta.dirname, '..')
+const CLIENT_DIR = join(root, 'packages/client')
+
+/** Directory names treated as the shared contract layer (importable by all). */
+const CONTRACT_DIRS = new Set(['contract'])
+/** Top-level client files allowed to import across domains (assembly layer). */
+const ASSEMBLY_FILES = new Set(['apply.ts', 'index.ts', 'index.tsx'])
+
+interface Violation { file: string; imported: string; reason: string }
+
+/** Recursively list .ts/.tsx files under dir (relative paths). */
+function listSources(dir: string, prefix = ''): string[] {
+  const out: string[] = []
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name)
+    const rel = prefix ? `${prefix}/${name}` : name
+    if (statSync(full).isDirectory()) out.push(...listSources(full, rel))
+    else if (/\.tsx?$/.test(name) && !/\.legacy\./.test(name)) out.push(rel)
+  }
+  return out
+}
+
+/** First path segment of a client-relative file, or '' for top-level files. */
+function domainOf(rel: string): string {
+  const ix = rel.indexOf('/')
+  return ix === -1 ? '' : rel.slice(0, ix)
+}
+
+function checkPackage(pkgName: string, clientDir: string): Violation[] {
+  const violations: Violation[] = []
+  const files = listSources(clientDir)
+  for (const rel of files) {
+    const fromDomain = domainOf(rel)
+    const isAssembly = fromDomain === '' && ASSEMBLY_FILES.has(rel)
+    if (isAssembly) continue
+    const source = readFileSync(join(clientDir, rel), 'utf8')
+    for (const match of source.matchAll(/from\s+['"](\.[^'"]+)['"]/g)) {
+      const spec = match[1]
+      if (spec === undefined) continue
+      // Resolve the relative specifier against the importing file's directory
+      // to a client-dir-relative path.
+      const fromDir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : ''
+      const parts = (fromDir ? fromDir.split('/') : [])
+      for (const seg of spec.split('/')) {
+        if (seg === '.') continue
+        if (seg === '..') parts.pop()
+        else parts.push(seg)
+      }
+      const target = parts.join('/')
+      if (target.startsWith('..')) continue // out of client dir (package root) — package-level rules govern
+      const toDomain = domainOf(target)
+      if (toDomain === '' || CONTRACT_DIRS.has(toDomain)) continue // top-level shared file or contract layer
+      if (fromDomain === toDomain) continue // inside one domain
+      violations.push({
+        file: `${pkgName}/src/client/${rel}`,
+        imported: spec,
+        reason: fromDomain === ''
+          ? `top-level non-assembly file imports domain "${toDomain}" (only apply/index may assemble)`
+          : `domain "${fromDomain}" imports sibling domain "${toDomain}" (route shared surface through contract/)`,
+      })
+    }
+  }
+  return violations
+}
+
+const violations: Violation[] = []
+for (const pkg of readdirSync(CLIENT_DIR)) {
+  const clientDir = join(CLIENT_DIR, pkg, 'src/client')
+  try {
+    if (!statSync(clientDir).isDirectory()) continue
+  } catch {
+    // No client half in this package — nothing to layer-check.
+    continue
+  }
+  violations.push(...checkPackage(pkg, clientDir))
+}
+
+if (violations.length > 0) {
+  console.error(`verify-client-domain-graph: ${violations.length} violation(s):`)
+  for (const v of violations) console.error(`  ${v.file} -> ${v.imported}\n    ${v.reason}`)
+  process.exit(1)
+}
+console.log('verify-client-domain-graph: client domain layering clean.')
--- a/scripts/verify-cordis-config.ts
+++ b/scripts/verify-cordis-config.ts
@@ -152,15 +152,29 @@ function localPackageDirectories(): Map<string, string> {
 }

 function rootProjectReferences(): Set<string> {
-  const config = ts.readConfigFile(resolve(root, 'tsconfig.json'), path => ts.sys.readFile(path))
-  if (config.error !== undefined) {
-    throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+  // 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.
+  const collected = new Set<string>()
+  const queue = [resolve(root, 'tsconfig.json'), resolve(root, 'tsconfig.client.json')]
+  const seen = new Set<string>()
+  for (let file = queue.pop(); file !== undefined; file = queue.pop()) {
+    if (seen.has(file)) continue
+    seen.add(file)
+    const config = ts.readConfigFile(file, path => ts.sys.readFile(path))
+    if (config.error !== undefined) {
+      throw new Error(ts.flattenDiagnosticMessageText(config.error.messageText, '\n'))
+    }
+    const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? []
+    for (const reference of references) {
+      if (typeof reference.path !== 'string') continue
+      const target = resolve(dirname(file), reference.path)
+      if (target.endsWith('.json')) queue.push(target)
+      else collected.add(target)
+    }
  }
-  const references = (config.config as { references?: Array<{ path?: unknown }> }).references ?? []
-  return new Set(references.flatMap((reference) => {
-    if (typeof reference.path !== 'string') return []
-    return [resolve(root, reference.path)]
-  }))
+  return collected
 }

 function packageNameFromSpecifier(specifier: string): string | undefined {
--- a/scripts/verify-mermaid.ts
+++ b/scripts/verify-mermaid.ts
@@ -79,7 +79,10 @@ Object.defineProperty(globalThis, 'window', { value: window })
 Object.defineProperty(globalThis, 'document', { value: window.document })
 Object.defineProperty(globalThis, 'navigator', { value: window.navigator })
 const mermaid = (await import('mermaid')).default
-mermaid.initialize({ startOnLoad: false })
+// maxEdges: mermaid's default 500-edge render guard; the module graph grows
+// with every package edge and crossed it legitimately. Raise the guard here
+// (a secure config settable only via initialize) rather than trimming edges.
+mermaid.initialize({ startOnLoad: false, maxEdges: 1000 })
 for (const block of blocks) {
  try {
    await mermaid.parse(block.source, { suppressErrors: false })
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -45,11 +45,26 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
  'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
  'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/client/ui-slots': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-primitives': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/i18n': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
  'packages/examples/agent-spine-demo': { kind: 'indirect', reason: 'The bundle only mounts model-facing child plugins.' },
  'packages/fs/fs': { kind: 'indirect', reason: 'The service interface delegates model rendering to dsh-tool-fs.' },
  'packages/fs/fs-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
  'packages/fs/fs-sandbox': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-fs.' },
  'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
+  'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register no model surface.' },
+  'packages/host/runtime': { kind: 'indirect', reason: 'The assembly mounts model-facing plugins and injects provider/model defaults into agents.' },
+  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
  'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
  'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
  'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },