Merge latest master into tool JSON schema DSL

# Conflicts:
#	examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.expected.md
#	examples/acp-agent/tests/snapshots/both-mode-turn/system-prompt.expected.md
#	examples/acp-agent/tests/snapshots/code-mode-turn/system-prompt.expected.md
#	examples/acp-agent/tests/snapshots/code-mode-workspace-context/system-prompt.expected.md

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',

scripts/gen-module-graph.ts

@@ -31,6 +31,7 @@ const GROUP_ORDER = [
   'spill',
   'timeout',
   'todo',
+  'plan',
   'cordis',
   'hooks',
   'session-persistence',

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',

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'

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')
+  })
+})

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()

scripts/run-gates.ts

@@ -16,6 +16,9 @@ type Mode =
   | 'ci-coverage'
   | 'ci-snapshot'
   | 'ci-artifacts'
+  | 'ci-windows-blocking'
+  | 'ci-windows-complete'
+  | 'ci-windows-observational'
   | 'node-compat'
   | 'pre-push'
   | 'manual-push'
@@ -32,6 +35,7 @@ interface Gate {
   env?: Record<string, string | undefined>
   input?: string
   verify?: (result: GateResult) => Promise<void>
+  allowFailure?: boolean
 }
 
 interface GateResult {
@@ -77,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) {
@@ -87,13 +93,17 @@ 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 | pre-push | 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)}.`,
       )
   }
 }
@@ -167,31 +177,19 @@ 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 [
-        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' }),
-      ]
+      return nodeCompatGates()
     case 'pre-push': return []
     case 'manual-push':
       return [
@@ -225,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',
@@ -240,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'),
   ]
@@ -265,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/',
@@ -280,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',
@@ -293,8 +379,6 @@ function coverageGate(): Gate {
     ...positiveIntArg('DSH_COVERAGE_MAX_WORKERS', '--maxWorkers'),
   ], {
     label: 'test:coverage',
-    env: { DSH_EXAMPLE_MODE: 'lib' },
-    needs: ['build'],
   })
 }
 
@@ -325,6 +409,13 @@ function positiveIntArg(envName: string, flag: string): string[] {
   return [`${flag}=${raw}`]
 }
 
+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 [
@@ -343,6 +434,7 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
 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
@@ -369,8 +461,11 @@ function docSyncLeafGates(options: {
     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' }),
   ]
 }
@@ -540,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}`)
   }
 }

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 })
+    }
+  }
+}

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')
+  })
+})

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 })