Merge worktree/schedule-explicit-at into worktree/schedule-fixed-rate

scripts/AGENTS.md

@@ -1,3 +1,3 @@
 # AGENTS.md — Repository scripts
 
-Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation at the owning gate boundary instead of a shared platform layer.
+Gate scripts invoke pnpm shell-free, normalize repository-relative glob paths to `/` at ingestion, and keep platform adaptation in the gate that needs it instead of a shared platform layer.

scripts/archived-agent-notes.ts

@@ -4,7 +4,7 @@ import { createHash } from 'node:crypto'
 import { basename } from 'node:path'
 import { AGENT_NOTE_CLASSES } from './agent-note-tree.ts'
 
-/** Versioned shape of the frozen-content manifest. */
+/** Versioned fields in the frozen-content manifest. */
 export interface ArchiveManifest {
   version: 1
   files: Readonly<Record<string, string>>

scripts/build-exe-for-python-sdk.ts

@@ -8,7 +8,7 @@
 
 import { spawn } from 'node:child_process'
 import { existsSync, statSync } from 'node:fs'
-import { chmod, copyFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { chmod, copyFile, cp, lstat, mkdir, readFile, readdir, realpath, rm, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, resolve, sep } from 'node:path'
 import { parseArgs } from 'node:util'
 
@@ -16,8 +16,8 @@ const root = resolve(import.meta.dirname, '..')
 
 /** The closure manifest whose dependencies define the executable. */
 const DEPLOY_ROOT_PACKAGE = 'dsh-jsonrpc-agent-pkg'
-/** The app entry inside the deployed closure. */
-const ENTRY_BIN = 'node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js'
+/** The closed-runtime app entry inside the deployed closure. */
+const ENTRY_BIN = 'node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/packaged-bin.js'
 const OUTPUT_BASENAME = 'dsh-jsonrpc-agent-pkg'
 /** Default Node major; SEA mode requires at least Node 22. */
 const DEFAULT_NODE_RANGE = 'node24'
@@ -28,6 +28,8 @@ const OUT_DIR = 'dist-exe'
 const PYTHON_RUNTIME_DIR = 'python/sdk-runtime/src/deepseek_harness_runtime/runtime'
 /** The deployed closure doubles as the node-mode carrier. */
 const PYTHON_NODE_SUBDIR = 'node'
+/** Legacy deploy may hoist peer-specialized workspace packages back here. */
+const DEPLOY_SOURCE_NODE_MODULES = 'python/sdk-runtime/node_modules'
 /** Documentation excluded from the generated runtime directory. */
 const DEPLOY_ONLY_DOCS = ['README.md', 'README.zh.md', 'README.i18n.yaml']
 
@@ -256,6 +258,8 @@ class SingleExeBuild {
       '--config.link-workspace-packages=true',
       this.staging,
     ])
+    await this.restoreLegacyHoists()
+    await this.materializeStagedLinks()
     if (this.cli.dryRun) {
       for (const name of DEPLOY_ONLY_DOCS) console.log(`build-exe-for-python-sdk: [dry-run] rm -f ${join(this.staging, name)}`)
     } else {
@@ -263,6 +267,94 @@ class SingleExeBuild {
     }
   }
 
+  /**
+   * Restore direct packages that pnpm's legacy hoister places beside the deploy
+   * source instead of in the target. The runtime manifest supplies every peer,
+   * so package-local node_modules trees are omitted to preserve one flat Cordis
+   * instance and a symlink-free packaged payload.
+   */
+  private async restoreLegacyHoists(): Promise<void> {
+    if (this.cli.dryRun) {
+      console.log('build-exe-for-python-sdk: [dry-run] restore direct dependencies omitted by legacy deploy')
+      return
+    }
+    const manifestPath = join(this.staging, 'package.json')
+    const manifest = JSON.parse(await readFile(manifestPath, 'utf8')) as {
+      dependencies?: Record<string, string>
+    }
+    const sourceNodeModules = resolve(root, DEPLOY_SOURCE_NODE_MODULES)
+    const restored: string[] = []
+    for (const dependency of Object.keys(manifest.dependencies ?? {}).sort()) {
+      const destination = join(this.staging, 'node_modules', dependency)
+      if (existsSync(destination)) continue
+      const source = join(sourceNodeModules, dependency)
+      if (!existsSync(source)) {
+        throw new Error(
+          `build-exe-for-python-sdk: deployed dependency ${dependency} is absent from both ${destination} and ${source}.`,
+        )
+      }
+      await mkdir(dirname(destination), { recursive: true })
+      const nestedNodeModules = join(source, 'node_modules')
+      await cp(source, destination, {
+        recursive: true,
+        dereference: true,
+        filter: path => path !== nestedNodeModules && !path.startsWith(nestedNodeModules + sep),
+      })
+      restored.push(dependency)
+    }
+    const stillMissing = Object.keys(manifest.dependencies ?? {})
+      .filter(dependency => !existsSync(join(this.staging, 'node_modules', dependency)))
+    if (stillMissing.length > 0) {
+      throw new Error(`build-exe-for-python-sdk: staged dependencies remain missing: ${stillMissing.join(', ')}.`)
+    }
+    if (restored.length > 0) {
+      console.log(`build-exe-for-python-sdk: restored legacy deploy hoists: ${restored.join(', ')}`)
+    }
+  }
+
+  /** Replace deploy-time package links with files and reject any remaining link. */
+  private async materializeStagedLinks(): Promise<void> {
+    if (this.cli.dryRun) {
+      console.log('build-exe-for-python-sdk: [dry-run] materialize staged package links')
+      return
+    }
+    const nodeModules = join(this.staging, 'node_modules')
+    let remaining = await this.findSymlink(nodeModules)
+    while (remaining !== undefined) {
+      const segments = remaining.slice(nodeModules.length + 1).split(sep)
+      const binIndex = segments.lastIndexOf('.bin')
+      if (binIndex >= 0) {
+        await rm(join(nodeModules, ...segments.slice(0, binIndex + 1)), { recursive: true, force: true })
+        remaining = await this.findSymlink(nodeModules)
+        continue
+      }
+      const destination = remaining
+      const source = await realpath(destination)
+      const nestedNodeModules = join(source, 'node_modules')
+      await rm(destination, { recursive: true, force: true })
+      await cp(source, destination, {
+        recursive: true,
+        dereference: true,
+        filter: path => path !== nestedNodeModules && !path.startsWith(nestedNodeModules + sep),
+      })
+      remaining = await this.findSymlink(nodeModules)
+    }
+  }
+
+  /** Return the first symbolic link below a directory, if one exists. */
+  private async findSymlink(directory: string): Promise<string | undefined> {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      const metadata = await lstat(path)
+      if (metadata.isSymbolicLink()) return path
+      if (metadata.isDirectory()) {
+        const nested = await this.findSymlink(path)
+        if (nested !== undefined) return nested
+      }
+    }
+    return undefined
+  }
+
   /** Add the executable entry and pkg assets to the staged manifest. */
   async injectPkgConfig(): Promise<void> {
     const patch = { bin: ENTRY_BIN, pkg: { assets: ASSET_GLOBS } }

scripts/build-python-release.py

@@ -17,6 +17,8 @@ from pathlib import Path
 
 
 ROOT = Path(__file__).resolve().parents[1]
+SDK_DISTRIBUTION = "deepseek-harness-sdk"
+RUNTIME_DISTRIBUTION = "deepseek-harness-runtime-bin"
 PLATFORMS = {
     "linux-x64": ("manylinux_2_28_x86_64", "dsh-jsonrpc-agent-pkg-linux-x64"),
     "linux-arm64": ("manylinux_2_28_aarch64", "dsh-jsonrpc-agent-pkg-linux-arm64"),
@@ -41,6 +43,8 @@ def main() -> None:
     args = parser.parse_args()
     version = repository_version()
     validate_release_tag(args.tag, version)
+    # Wheels carry the PEP 440 spelling; the tag keeps the repository spelling.
+    wheel_version = pep440_version(version)
     if args.package == "runtime" and (args.platform is None or args.runtime_exe is None):
         parser.error("runtime builds require --platform and --runtime-exe")
     if args.package == "sdk" and (args.platform is not None or args.runtime_exe is not None):
@@ -51,19 +55,19 @@ def main() -> None:
     with tempfile.TemporaryDirectory(prefix="dsh-python-release-") as temporary:
         staging = Path(temporary) / args.package
         if args.package == "sdk":
-            stage_sdk(staging, version)
+            stage_sdk(staging, wheel_version)
             environment = None
-            expected = output_dir / f"deepseek_harness-{version}-py3-none-any.whl"
+            expected = output_dir / f"deepseek_harness_sdk-{wheel_version}-py3-none-any.whl"
         else:
             platform_tag, executable_name = PLATFORMS[args.platform]
-            stage_runtime(staging, version, args.runtime_exe.resolve(), executable_name)
+            stage_runtime(staging, wheel_version, args.runtime_exe.resolve(), executable_name)
             environment = {"DSH_RUNTIME_PLATFORM_TAG": platform_tag}
-            expected = output_dir / f"deepseek_harness_runtime_bin-{version}-py3-none-{platform_tag}.whl"
+            expected = output_dir / f"deepseek_harness_runtime_bin-{wheel_version}-py3-none-{platform_tag}.whl"
         command = ["uv", "build", "--wheel", "--out-dir", str(output_dir), str(staging)]
         subprocess.run(command, cwd=ROOT, env=None if environment is None else {**os.environ, **environment}, check=True)
     if not expected.is_file():
         raise RuntimeError(f"build did not produce expected wheel: {expected}")
-    verify_wheel(expected, args.package, version, None if args.platform is None else PLATFORMS[args.platform])
+    verify_wheel(expected, args.package, wheel_version, None if args.platform is None else PLATFORMS[args.platform])
     print(expected)
 
 
@@ -74,13 +78,35 @@ def repository_version(root: Path = ROOT) -> str:
     except (OSError, json.JSONDecodeError) as error:
         raise ValueError(f"could not read repository version from {package_json}") from error
     version = payload.get("version") if isinstance(payload, dict) else None
-    if not isinstance(version, str) or re.fullmatch(r"\d+\.\d+\.\d+", version) is None:
+    if not isinstance(version, str) or re.fullmatch(r"\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?", version) is None:
         raise ValueError(
-            f"{package_json} version must be stable X.Y.Z, got {version!r}"
+            f"{package_json} version must be X.Y.Z with an optional prerelease segment, got {version!r}"
         )
     return version
 
 
+def pep440_version(version: str) -> str:
+    """The Python spelling of a repository version.
+
+    A release candidate is `0.0.1-rc.1` in the repository and `0.0.1rc1` under
+    PEP 440. Build backends normalize to the latter, so the wheel filename and
+    metadata carry it: comparing them against the repository spelling would
+    reject every prerelease build.
+    """
+    stable, separator, prerelease = version.partition("-")
+    if not separator:
+        return stable
+    match = re.fullmatch(r"(a|b|c|rc|alpha|beta|pre|preview)\.?(\d+)", prerelease)
+    if match is None:
+        raise ValueError(
+            f"prerelease segment {prerelease!r} has no PEP 440 spelling; use rc.N, alpha.N, or beta.N"
+        )
+    identifier = {"alpha": "a", "beta": "b", "c": "rc", "pre": "rc", "preview": "rc"}.get(
+        match.group(1), match.group(1)
+    )
+    return f"{stable}{identifier}{match.group(2)}"
+
+
 def validate_release_tag(tag: str | None, version: str) -> None:
     if tag is None:
         return
@@ -160,6 +186,11 @@ def verify_wheel(
             raise RuntimeError(f"{wheel} has wrong WHEEL tags: {wheel_metadata.get_all('Tag')}")
         if metadata.get("Version") != version:
             raise RuntimeError(f"{wheel} has version {metadata.get('Version')}, expected {version}")
+        expected_distribution = SDK_DISTRIBUTION if package == "sdk" else RUNTIME_DISTRIBUTION
+        if metadata.get("Name") != expected_distribution:
+            raise RuntimeError(
+                f"{wheel} has distribution name {metadata.get('Name')}, expected {expected_distribution}"
+            )
         runtime_files = [
             name for name in archive.namelist() if "/runtime/dsh-jsonrpc-agent-pkg-" in name
         ]
@@ -177,7 +208,7 @@ def verify_wheel(
             raise RuntimeError(f"SDK wheel unexpectedly contains runtime executables: {runtime_files}")
         if package == "sdk":
             requirements = metadata.get_all("Requires-Dist") or []
-            expected_requirement = f"deepseek-harness-runtime-bin=={version}"
+            expected_requirement = f"{RUNTIME_DISTRIBUTION}=={version}"
             if expected_requirement not in requirements:
                 raise RuntimeError(f"{wheel} does not pin {expected_requirement}; found {requirements}")
 

scripts/change-scope.spec.ts

@@ -97,14 +97,14 @@ function repositoryState(root: string): Record<string, string> {
 }
 
 describe('change-scope', () => {
-  it('uses an explicit base on a fresh branch without a same-name remote and after its first push', () => {
+  it('uses an explicit base on a fresh branch without a same-name remote and after its first push', { timeout: 20_000 }, () => {
     const { root } = fixture()
     git(root, ['switch', '-c', 'feature'])
     git(root, ['branch', '--set-upstream-to=origin/master'])
     const headSha = commit(root, 'feature.txt', 'feature\n')
 
     const fresh = jsonReport(root, 'origin/master')
-    expect(fresh.repositoryRoot).toBe(realpathSync(root))
+    expect(realpathSync.native(fresh.repositoryRoot)).toBe(realpathSync.native(root))
     expect(fresh.resolved).toEqual({
       baseSha: git(root, ['rev-parse', 'origin/master']),
       headSha,
@@ -122,7 +122,7 @@ describe('change-scope', () => {
     const { root } = fixture('worktree ')
     const report = jsonReport(root, 'HEAD')
 
-    expect(report.repositoryRoot).toBe(realpathSync(root))
+    expect(realpathSync.native(report.repositoryRoot)).toBe(realpathSync.native(root))
     expect(report.paths).toEqual({ committed: [], staged: [], unstaged: [], untracked: [] })
   })
 

scripts/check-workspace-constraints.ts

@@ -21,15 +21,15 @@ const workspaceGlobs = [
   { dir: 'apps', depth: 1 },
 ] as const
 const vendoredPackages = new Set([
-  'cordis',
-  'cosmokit',
-  'schemastery',
-  '@cordisjs/plugin-loader',
-  '@cordisjs/plugin-include',
-  '@cordisjs/plugin-group',
-  '@cordisjs/plugin-timer',
-  '@cordisjs/plugin-hmr',
-  '@cordisjs/plugin-logger-console',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/cosmokit',
+  '@deepseek-ai/schemastery',
+  '@deepseek-ai/cordis-plugin-loader',
+  '@deepseek-ai/cordis-plugin-include',
+  '@deepseek-ai/cordis-plugin-group',
+  '@deepseek-ai/cordis-plugin-timer',
+  '@deepseek-ai/cordis-plugin-hmr',
+  '@deepseek-ai/cordis-plugin-logger-console',
 ])
 const publicLandlockPackages = new Set([
   '@deepseek-ai/node-addon-landlock-run',
@@ -41,6 +41,14 @@ const publicationSourceAllowlist: Readonly<Record<string, readonly string[]>> =
   '@deepseek-ai/node-addon-landlock-run': ['src/main.c'],
 }
 const repositoryUrl = 'git+https://github.com/deepseek-harness/deepseek-harness.git'
+/**
+ * Source home the published packages point consumers at. It differs from
+ * {@link repositoryUrl}, which the Landlock packages keep because npm resolves
+ * their trusted publishing against the repository that runs the workflow.
+ */
+const publishedRepositoryUrl = 'git+https://github.com/deepseek-ai/deepseek-harness.git'
+/** Directories whose packages this repository publishes: one release member each. */
+const releaseMemberDirectory = /^(?:packages\/[^/]+\/[^/]+|apps\/[^/]+|vendor\/[^/]+)$/
 
 const localArtifactDirs = new Set(['node_modules'])
 const appPackageFiles: Readonly<Record<string, readonly string[]>> = {
@@ -72,6 +80,8 @@ interface PackageManifest {
   repository?: { type?: string; url?: string; directory?: string }
   peerDependencies?: Record<string, string>
   devDependencies?: Record<string, string>
+  dependencies?: Record<string, string>
+  optionalDependencies?: Record<string, string>
 }
 
 /** One workspace manifest and its repo-relative path. */
@@ -119,19 +129,21 @@ function workspaceManifests(): WorkspaceManifest[] {
 }
 
 const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
-  // Profile bundles publish their dsh.bundle.patch layer beside the lib.
-  '@deepseek-ai/dsh-base': ['cordis.patch.yml'],
+  // Profile bundles publish their dsh.bundle.patch layer beside the lib;
+  // dsh-base also ships the win32 shell platform layer the launcher reads.
+  '@deepseek-ai/dsh-base': ['cordis.patch.yml', 'windows.cordis.patch.yml'],
   '@deepseek-ai/dsh-web-app': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-headless': ['cordis.patch.yml'],
   '@deepseek-ai/dsh-client-ui-theme': ['lib/styles'],
-  '@deepseek-ai/dsh-helper': ['lib/assets'],
+  // The Python runtime uses a distinct closed-resolution bin; the public CLI
+  // keeps config-owned bare-package resolution through lib/bin.js.
+  '@deepseek-ai/dsh-jsonrpc-demo': ['lib/packaged-bin.js'],
+  // The argv-prefix runner entry ships beside the lib as its own bundle;
+  // sandbox-local resolves it through the package's ./runner export. tsdown
+  // also shares its generated FFI code through a hashed runtime chunk.
+  '@deepseek-ai/dsh-sandbox-windows-acl': ['lib/runner.js', 'lib/types-*.js'],
   '@deepseek-ai/dsh-skill-badge': ['assets'],
   '@deepseek-ai/dsh-subprocess-local': ['scripts/ensure-spawn-helper.mjs'],
-  '@deepseek-ai/dsh-scripts': [
-    'lib/dev/tsdown-config.js',
-    'lib/local-plugin-loader-hooks.js',
-    'lib/assets',
-  ],
 }
 
 function sameStringList(actual: readonly string[] | undefined, expected: readonly string[]): boolean {
@@ -157,6 +169,9 @@ function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
     ...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'] : [],
+    // A surface bundle's startup row is its own bundle: the Loader imports it
+    // as a row module, so it cannot ride inside the package entry.
+    ...exportDefault(manifest, './startup') === './lib/startup.js' ? ['lib/startup.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
@@ -221,8 +236,8 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
     if (manifest.private === true) {
       errors.push(`${label}: published Landlock package must not set "private": true`)
     }
-    if (manifest.publishConfig?.access !== 'public') {
-      errors.push(`${label}: published Landlock package must set publishConfig.access to "public"`)
+    if (manifest.publishConfig?.access !== 'restricted') {
+      errors.push(`${label}: published Landlock package must set publishConfig.access to "restricted"`)
     }
     const expectedDirectory = dir
     if (manifest.repository?.type !== 'git'
@@ -230,6 +245,21 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
       || manifest.repository.directory !== expectedDirectory) {
       errors.push(`${label}: published Landlock package repository must use ${repositoryUrl} with directory ${expectedDirectory} for trusted publishing`)
     }
+  } else if (releaseMemberDirectory.test(dir)) {
+    // Release members state that they are publishable: npm refuses a private
+    // package, the scope is published privately, and the repository field is
+    // how a consumer of a private package finds its source.
+    if (manifest.private === true) {
+      errors.push(`${label}: release member must not set "private": true`)
+    }
+    if (manifest.publishConfig?.access !== 'restricted') {
+      errors.push(`${label}: release member must set publishConfig.access to "restricted"`)
+    }
+    if (manifest.repository?.type !== 'git'
+      || manifest.repository.url !== publishedRepositoryUrl
+      || manifest.repository.directory !== dir) {
+      errors.push(`${label}: release member repository must use ${publishedRepositoryUrl} with directory ${dir}`)
+    }
   } else if (manifest.private !== true) {
     errors.push(`${label}: package.json must set "private": true`)
   }
@@ -267,13 +297,13 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
   }
 
   if (dir.startsWith('packages/') && manifest.name?.startsWith('@deepseek-ai/dsh-')) {
-    const peer = manifest.peerDependencies?.cordis
-    const dev = manifest.devDependencies?.cordis
+    const peer = manifest.peerDependencies?.['@deepseek-ai/cordis']
+    const dev = manifest.devDependencies?.['@deepseek-ai/cordis']
 
-    if (!peer) errors.push(`${label}: cordis must be a peerDependency`)
-    if (!dev) errors.push(`${label}: cordis must also be a devDependency`)
+    if (!peer) errors.push(`${label}: @deepseek-ai/cordis must be a peerDependency`)
+    if (!dev) errors.push(`${label}: @deepseek-ai/cordis must also be a devDependency`)
     if (peer && dev && peer !== dev) {
-      errors.push(`${label}: cordis peer (${peer}) and dev (${dev}) ranges must match`)
+      errors.push(`${label}: @deepseek-ai/cordis peer (${peer}) and dev (${dev}) ranges must match`)
     }
     if (manifest.version !== repositoryVersion) {
       errors.push(`${label}: package.json version must match root version ${repositoryVersion ?? '(missing)'}`)
@@ -342,13 +372,44 @@ function checkHierarchyShape(): string[] {
 }
 
 function checkRepositoryVersion(): string[] {
-  if (repositoryVersion && /^\d+\.\d+\.\d+$/.test(repositoryVersion)) return []
-  return ['package.json: version must be stable X.Y.Z']
+  // The root carries the dsh release family's version, so a prerelease such as
+  // 0.0.1-rc.1 is a valid state between `release:dsh` and its publication.
+  if (repositoryVersion && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(repositoryVersion)) return []
+  return ['package.json: version must be X.Y.Z with an optional prerelease segment']
 }
 
+/** Dependency sections whose ranges reach a published tarball or a local install. */
+const dependencySections = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'] as const
+
+/**
+ * Require the `workspace:` protocol for every reference to a workspace member.
+ *
+ * A hand-written range says nothing about the version the workspace actually
+ * carries, and `pnpm pack` leaves it alone: `^0.0.1` published from version
+ * `0.0.2` names a version that does not exist. The protocol makes pack
+ * substitute the member's real version, so no release step rewrites ranges.
+ * @param manifests - every workspace manifest.
+ * @returns One error per reference that names a workspace member without the protocol.
+ */
+function checkWorkspaceProtocol(manifests: readonly WorkspaceManifest[]): string[] {
+  const members = new Set(manifests.map(entry => entry.manifest.name).filter(name => name !== undefined))
+  const errors: string[] = []
+  for (const { dir, manifest } of manifests) {
+    for (const section of dependencySections) {
+      for (const [name, range] of Object.entries(manifest[section] ?? {})) {
+        if (!members.has(name) || range.startsWith('workspace:')) continue
+        errors.push(`${manifest.name ?? dir}: ${section}.${name} must use the workspace: protocol, got ${range}`)
+      }
+    }
+  }
+  return errors
+}
+
+const manifests = workspaceManifests()
 const errors = [
   ...checkRepositoryVersion(),
-  ...workspaceManifests().flatMap(checkWorkspace),
+  ...manifests.flatMap(checkWorkspace),
+  ...checkWorkspaceProtocol(manifests),
   ...checkHierarchyShape(),
   ...collectProjectReferenceFaceViolations(root),
 ]

scripts/ci-workflow.spec.ts

@@ -27,41 +27,76 @@ describe('CI workflow', () => {
     }
   })
 
-  it('keeps Wine blocking while native Windows reports independently', () => {
+  it('keeps a required Wine Windows job, a non-blocking native Windows job with failover, and a master-only standby', () => {
     const workflow = loadWorkflow('.github/workflows/ci.yml')
     if (!isRecord(workflow.jobs)
       || !isRecord(workflow.jobs.windows)
       || !isRecord(workflow.jobs['windows-native'])
+      || !isRecord(workflow.jobs['wine-apt-cache'])
+      || !isRecord(workflow.jobs['serial-windows'])
       || !isRecord(workflow.jobs['all-checks-passed'])) {
-      throw new TypeError('CI workflow must define Wine, native Windows, and aggregate jobs')
+      throw new TypeError('CI workflow must define windows, windows-native, wine-apt-cache, serial-windows, and all-checks-passed jobs')
     }
 
     const windows = workflow.jobs.windows
     const windowsNative = workflow.jobs['windows-native']
+    const wineAptCache = workflow.jobs['wine-apt-cache']
+    const serialWindows = workflow.jobs['serial-windows']
     const aggregate = workflow.jobs['all-checks-passed']
-    if (!Array.isArray(windows.steps) || !Array.isArray(windowsNative.steps) || !Array.isArray(aggregate.needs)) {
-      throw new TypeError('Windows jobs must define steps and the aggregate must define needs')
+    if (!Array.isArray(windows.steps) || !Array.isArray(aggregate.needs)) {
+      throw new TypeError('Windows job must define steps and the aggregate must define needs')
     }
-    const nativeCommandSteps = windowsNative.steps.filter((step): step is Record<string, unknown> & { run: string } => (
+    const commandSteps = windows.steps.filter((step): step is Record<string, unknown> & { run: string } => (
       isRecord(step) && typeof step.run === 'string'
     ))
 
+    // Required PR job: Wine on ubuntu-latest, runs wine-windows-gates.sh.
     expect(windows['runs-on']).toBe('ubuntu-latest')
     expect(windows.name).toBe('windows node 24 / wine blocking')
     expect(windows.if).toBe("github.event_name == 'pull_request'")
-    expect(JSON.stringify(windows)).toContain('bash scripts/wine-windows-gates.sh')
-    expect(workflow.jobs).toHaveProperty('wine-apt-cache')
-    expect(windowsNative['runs-on']).toBe('windows-2025')
+    expect(commandSteps.some(step => step.run.includes('wine-windows-gates.sh'))).toBe(true)
+
+    // windows-native: non-blocking native job with failover, runs windows-complete.
+    expect(typeof windowsNative['runs-on']).toBe('string')
+    expect(windowsNative['runs-on']).toContain('DSH_CI_FAILOVER')
+    expect(windowsNative['runs-on']).toContain('self-hosted')
+    expect(windowsNative['runs-on']).toContain('dsh-win-ci')
+    expect(windowsNative['runs-on']).toContain('dsh-windows-2025-16core')
     expect(windowsNative.name).toBe('windows node 24 / native complete')
-    expect(windowsNative['timeout-minutes']).toBe(60)
     expect(windowsNative.if).toBe("github.event_name == 'pull_request'")
-    expect(windowsNative).not.toHaveProperty('continue-on-error')
-    expect(nativeCommandSteps).toHaveLength(3)
-    expect(nativeCommandSteps.every(step => step.shell === 'pwsh')).toBe(true)
+    const nativeCommandSteps = (windowsNative.steps as unknown[]).filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
     expect(nativeCommandSteps.map(step => step.run)).toContain('pnpm run check:ci:windows-complete')
-    expect(JSON.stringify(windowsNative)).not.toMatch(/wine/i)
+
+    // wine-apt-cache: master-only, seeds the Wine apt cache.
+    expect(wineAptCache.if).toBe("github.event_name == 'push' && github.ref == 'refs/heads/master'")
+    expect(wineAptCache['runs-on']).toBe('ubuntu-latest')
+
+    // serial-windows: master-only standby, self-hosted, non-blocking.
+    expect(serialWindows.if).toBe("github.event_name == 'push' && github.ref == 'refs/heads/master'")
+    expect(serialWindows['runs-on']).toEqual(['self-hosted', 'dsh-win-ci', 'windows'])
+    expect(serialWindows.name).toBe('serial / windows (self-hosted standby)')
+
+    // Aggregate: Wine `windows` required, native `windows-native` excluded.
     expect(aggregate.needs).toContain('windows')
     expect(aggregate.needs).not.toContain('windows-native')
+    expect(aggregate.needs).not.toContain('serial-windows')
+  })
+
+  it('keeps supported LSP source under native Windows coverage', () => {
+    const config = readFileSync(resolve(root, 'vitest.config.ts'), 'utf8')
+
+    expect(config).not.toContain('packages/lsp/lsp-local/src/connection.ts')
+    expect(config).not.toContain('packages/lsp/lsp-local/src/index.ts')
+    expect(config).not.toContain('packages/lsp/lsp-local/src/instance.ts')
+  })
+
+  it('keeps every Vitest project process-isolated on native Windows', () => {
+    const config = readFileSync(resolve(root, 'vitest.config.ts'), 'utf8')
+
+    expect(config).not.toContain("pool: process.platform === 'win32' ? 'threads' : 'forks'")
+    expect(config.match(/pool: 'forks'/g)).toHaveLength(2)
   })
 })
 
@@ -93,20 +128,42 @@ describe('E2B e2e workflow', () => {
 })
 
 describe('Issue lifecycle workflow', () => {
-  it('uses review signals instead of rerunning when a draft becomes ready', () => {
+  it('uses explicit review handoff events without rerunning when a draft becomes ready', () => {
     const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
     const lifecyclePullRequest = workflowEvent(lifecycle, 'pull_request')
     const lifecycleReview = workflowEvent(lifecycle, 'pull_request_review')
+    const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
     const policy = loadWorkflow('.github/workflows/issue-policy.yml')
     const policyPullRequest = workflowEvent(policy, 'pull_request')
 
     expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
     expect(lifecyclePullRequest.types).toContain('review_requested')
-    expect(lifecycleReview.types).toContain('submitted')
+    expect(lifecycleReview.types).toEqual(['submitted'])
+    expect(lifecycleJob.if).toBe(
+      "${{ github.event_name != 'pull_request_review' || (github.event.action == 'submitted' && github.event.review.state == 'changes_requested') }}",
+    )
     expect(policyPullRequest.types).toContain('ready_for_review')
   })
 })
 
+describe('Git hooks', () => {
+  it('leaves frozen Agent Note sidecars to the archive verifier', () => {
+    const lefthook = loadWorkflow('lefthook.yml')
+
+    for (const hookName of ['pre-commit', 'pre-merge-commit']) {
+      const hook = lefthook[hookName]
+      if (!isRecord(hook) || !Array.isArray(hook.jobs)) {
+        throw new TypeError(`lefthook must define ${hookName} jobs`)
+      }
+      const pairing: unknown = hook.jobs.find(
+        (job: unknown) => isRecord(job) && job.name === 'translation pairing (staged records)',
+      )
+
+      expect(pairing).toMatchObject({ exclude: ['.agents/notes/archived/**'] })
+    }
+  })
+})
+
 function loadWorkflow(path: string): Record<string, unknown> {
   const workflow: unknown = yaml.load(readFileSync(resolve(root, path), 'utf8'))
   if (!isRecord(workflow)) throw new TypeError(`${path} must define a workflow`)
@@ -120,6 +177,13 @@ function workflowEvent(workflow: Record<string, unknown>, event: string): Record
   return workflow.on[event]
 }
 
+function workflowJob(workflow: Record<string, unknown>, job: string): Record<string, unknown> {
+  if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs[job])) {
+    throw new TypeError(`workflow must define the ${job} job`)
+  }
+  return workflow.jobs[job]
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }

scripts/client-bundle-purity.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Pins shared client-bundle preset contracts: the module-edge purity gate and
+ * Pins shared client-bundle preset rules: the module-edge purity gate and
  * the physical watch dependencies hidden behind virtual CSS Modules.
  */
 import { fileURLToPath } from 'node:url'
@@ -97,9 +97,9 @@ describe('client bundle purity gate', () => {
 
   it('carries exactly one documented temporary exemption: runtime/client (store engine pending rehoming)', () => {
     expect(resolveId('@deepseek-ai/dsh-client-runtime/client')).toBeNull()
-    const dshClientChannels = CLIENT_EXTERNALS.filter(
+    const clientChannels = CLIENT_EXTERNALS.filter(
       entry => entry.startsWith('@deepseek-ai/') && entry.endsWith('/client'))
-    expect(dshClientChannels).toEqual(['@deepseek-ai/dsh-client-runtime/client'])
+    expect(clientChannels).toEqual(['@deepseek-ai/dsh-client-runtime/client'])
   })
 })
 

scripts/client-tsconfig.spec.ts

@@ -1,7 +1,7 @@
 /** Regression coverage for source declarations owned by the client test aggregate. */
 
 import { existsSync, readdirSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { resolve, sep } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import ts from 'typescript'
 import { describe, expect, it } from 'vitest'
@@ -14,6 +14,7 @@ function clientCssDeclarations(): string[] {
     .filter(entry => entry.isDirectory())
     .map(entry => resolve(clientRoot, entry.name, 'src/css-modules.d.ts'))
     .filter(existsSync)
+    .map(file => file.replaceAll(sep, '/'))
     .sort()
 }
 
@@ -26,6 +27,7 @@ describe('client TypeScript aggregate', () => {
     }
     const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, root)
     const loaded = parsed.fileNames
+      .map(file => file.replaceAll(sep, '/'))
       .filter(file => file.endsWith('/src/css-modules.d.ts'))
       .sort()
     expect(loaded).toEqual(clientCssDeclarations())

scripts/cordis-core-api.ts

@@ -23,7 +23,7 @@ export interface CordisCoreApiPage {
   sections: CordisCoreApiSection[]
 }
 
-/** Explicit editorial grouping for the pinned Cordis core surface. */
+/** Explicit editorial grouping for the pinned Cordis core API. */
 export const CORDIS_CORE_API_PAGES: CordisCoreApiPage[] = [
   {
     out: 'docs/cordis-api/context.md',

scripts/cordis-walk.ts

@@ -11,12 +11,12 @@ import ts from 'typescript'
 
 /** Cheap textual prefilter for a cordis module merge, quote-style agnostic
  * (the AST match below reads `stmt.name.text` and never sees the quotes). */
-const MERGE_HEAD = /declare module ['"](?:cordis|\.\/context\.ts)['"]/
+const MERGE_HEAD = /declare module ['"](?:@deepseek-ai\/cordis|\.\/context\.ts)['"]/
 
 /**
  * Parse every file matching `patterns` (repo-relative, sorted, `/`-normalized)
  * that textually contains a cordis module merge, yielding one entry per merge
- * BLOCK — a file may legally hold several `declare module 'cordis'` blocks
+ * BLOCK — a file may legally hold several `declare module '@deepseek-ai/cordis'` blocks
  * (the Typert analyzer reads them all), so the exhaustiveness scan must too.
  * Files without a merge are skipped.
  * @param scanRoot - Repository root the patterns are resolved against.
@@ -39,14 +39,14 @@ export function contextMergeFiles(
   return out
 }
 
-/** Every cordis module-merge body in `sf`: `declare module 'cordis'` (harness
+/** Every cordis module-merge body in `sf`: `declare module '@deepseek-ai/cordis'` (harness
  * packages) or `declare module './context.ts'` (vendor core), in source order.
  * Module-local: consumers walk blocks through {@link contextMergeFiles}. */
 function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
   const bodies: ts.ModuleBlock[] = []
   for (const stmt of sf.statements) {
     if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue
-    if (stmt.name.text !== 'cordis' && stmt.name.text !== './context.ts') continue
+    if (stmt.name.text !== '@deepseek-ai/cordis' && stmt.name.text !== './context.ts') continue
     if (stmt.body && ts.isModuleBlock(stmt.body)) bodies.push(stmt.body)
   }
   return bodies
@@ -60,7 +60,7 @@ export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
 }
 
 /**
- * Every `key: Type` property a `declare module 'cordis'` Context merge
+ * Every `key: Type` property a `declare module '@deepseek-ai/cordis'` Context merge
  * declares in one module body.
  * @param body - The cordis module augmentation block.
  * @param sf - Owning source file (for text extraction).
@@ -79,9 +79,9 @@ export function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<stri
 }
 
 /**
- * Every event name a `declare module 'cordis'` Events merge declares in one
+ * Every event name a `declare module '@deepseek-ai/cordis'` Events merge declares in one
  * module body. Names are the literal member keys (`'agent/created'`), read
- * from method and property members alike so a declaration shape the projector
+ * from method and property members alike so a declaration form the projector
  * would reject still enters the exhaustiveness scan.
  * @param body - The cordis module augmentation block.
  * @param sf - Owning source file (for computed-name text extraction).

scripts/coverage-exempt.ts

@@ -1,6 +1,6 @@
 /**
  * Heavy suites the coverage aggregate runs uninstrumented in a parallel gate.
- * Membership contract: a suite qualifies only when every coverage-measured
+ * Membership rule: a suite qualifies only when every coverage-measured
  * file it executes in-process (`coverage.include` spans package src trees;
  * typert generator src is threshold-excluded in vitest.config.ts) is already
  * fully covered by other suites, so removing it from the instrumented run

scripts/dev-web.spec.ts

@@ -1,9 +1,28 @@
-import { mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { expect, it } from 'vitest'
 import type { TsdownBundle } from 'tsdown'
-import { watchClientPlugins } from './dev-web.ts'
+import { discoverPluginDirs, watchClientPlugins } from './dev-web.ts'
+
+it('discovers dsh.client packages with sibling roles', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-discovery-'))
+  try {
+    const current = join(root, 'packages', 'client', 'current')
+    await mkdir(current, { recursive: true })
+    await writeFile(join(current, 'package.json'), JSON.stringify({
+      dsh: {
+        bundle: { patch: './cordis.patch.yml' },
+        client: { platform: 'web' },
+        profile: { bundles: [] },
+      },
+    }))
+
+    expect(discoverPluginDirs(root)).toEqual(['packages/client/current'])
+  } finally {
+    await rm(root, { recursive: true, force: true })
+  }
+})
 
 it('rebuilds a client-plugin bundle after its source changes', async () => {
   const root = await mkdtemp(join(tmpdir(), 'dsh-dev-web-watch-'))

scripts/dev-web.ts

@@ -1,8 +1,8 @@
 /**
- * Watch-build for client-plugin HMR: runs every dshClient plugin package
+ * Watch-build for client-plugin HMR: runs every `dsh.client` plugin package
  * through the tsdown JS API in watch mode. Reload signaling is not this
  * script's business — the host webserver stat-polls the bundles it serves and
- * broadcasts `rebuilt` frames itself (`dsh web --dev`), so any process that
+ * broadcasts `rebuilt` frames itself (`dsh web`), so any process that
  * rewrites `lib/client.js` files triggers reloads; this script is merely the
  * convenient way to keep them all rebuilt on source change.
  *
@@ -27,7 +27,7 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 
 /**
  * Discover the watch workspace by declaration: every packages/<group>/<name>
- * whose package.json carries `dshClient` with platform "web" is a client
+ * whose package.json carries `dsh.client` with platform "web" is a client
  * plugin bundle emitter. Scanned once at startup — a package added while
  * watching means restarting this script.
  * @param root - repository root containing the grouped package directories.
@@ -36,8 +36,10 @@ const repoRoot = fileURLToPath(new URL('..', import.meta.url))
 export function discoverPluginDirs(root = repoRoot): string[] {
   const dirs: string[] = []
   for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
-    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as { dshClient?: { platform?: unknown } }
-    if (manifest.dshClient?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
+    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as {
+      dsh?: { client?: { platform?: unknown } }
+    }
+    if (manifest.dsh?.client?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
   }
   return dirs
 }
@@ -88,7 +90,7 @@ const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(re
 if (isMain) {
   const pluginDirs = discoverPluginDirs()
   if (pluginDirs.length === 0) {
-    console.error('dev-web: no dshClient (platform "web") packages found under packages/')
+    console.error('dev-web: no dsh.client (platform "web") packages found under packages/')
     process.exit(1)
   }
 
@@ -106,7 +108,7 @@ if (isMain) {
 
   await watchClientPlugins(repoRoot, pluginDirs, pollInterval)
   console.log(
-    `dev-web: watching ${String(pluginDirs.length)} dshClient plugin packages`
+    `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
     + `${pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : ''}:\n  ${pluginDirs.join('\n  ')}`,
   )
 }

scripts/doc-budgets.manifest.json

@@ -1,11 +1,11 @@
 {
-  "AGENTS.md": 1782,
+  "AGENTS.md": 1900,
   "docs/AGENTS.md": 1320,
-  "docs/architecture.md": 2174,
+  "docs/architecture.md": 2400,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 1150,
   "examples/AGENTS.md": 310,
   "packages/AGENTS.md": 675,
-  "packages/README.md": 942
+  "packages/README.md": 994
 }

scripts/doc-typecheck-paths.ts

@@ -1,6 +1,6 @@
 /** 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
+  // Two workspace path forms 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`

scripts/doc-typecheck.ts

@@ -221,7 +221,7 @@ const { primary: all, derivatives } = partitionPairedMarkdownDerivatives(
 const checked = all.filter(b => b.kind === 'check')
 const ignored = all.filter(b => b.kind === 'ignore')
 // Only compile-eligible fences belong in the opt-out ratio; every other skipped
-// kind has an independent verifier named in BlockKind's contract above.
+// kind has an independent verifier named in the BlockKind rules above.
 const ratioDenominator = checked.length + ignored.length
 
 if (checked.length === 0) {

scripts/gen-config-catalog.ts

@@ -2,7 +2,7 @@
  * Generate `docs/config-catalog.md` from package entry points, config types,
  * JSDoc, and static Schemastery schemas. Every package must classify, referenced
  * types must resolve without collisions, and every enumerable schema path must
- * exist on the declared config type. External and dynamic shapes stay unknown;
+ * exist on the declared config type. External and dynamic types stay unknown;
  * declared runtime-only fields need not appear in the schema. `--check` verifies
  * the committed artifact.
  */
@@ -220,7 +220,7 @@ interface World {
 }
 
 /** How a schema key path fared against the declared config type: definitely
- * present, definitely absent, or crossing a shape the walk cannot enumerate
+ * present, definitely absent, or crossing a type the walk cannot enumerate
  * (only `missing` is a violation — `unknown` must never mis-report). */
 type PathLookup = 'found' | 'missing' | 'unknown'
 
@@ -307,7 +307,7 @@ const PASSTHROUGH_WRAPPERS = new Set(['Partial', 'Required', 'Readonly', 'NonNul
 
 /**
  * Walk a schema key path against a declared type. This is a PRESENCE check,
- * not a shape check: it answers "does the declared config type have a member
+ * not a runtime value check: it answers "does the declared config type have a member
  * here", resolving interfaces (heritage included), type aliases, literals,
  * intersections, unions, arrays, indexed access, pass-through utility
  * wrappers, and type references across package-local and workspace imports.
@@ -412,7 +412,7 @@ function unwrapExpr(expr: ts.Expression): ts.Expression {
  * Statically walk a schemastery schema expression to its key paths plus the
  * packages whose schemas an intersect composes. A key path is the top-level
  * key or a nested path through object/array compositions (`agents[].id`).
- * Handles the shapes the repo declares — `z.object({…})` (possibly behind
+ * Handles the declaration forms the repo uses — `z.object({…})` (possibly behind
  * chained calls) and `z.intersect([X.Config, …])` — and hard-errors on
  * anything else, so a schema the walk cannot see fails the gate instead of
  * silently thinning it. Nested values that are neither `object` nor `array`
@@ -521,7 +521,7 @@ function findSchemaExpr(ctx: FileCtx, pluginClass: ts.ClassDeclaration | null):
 function findInject(ctx: FileCtx, pluginClass: ts.ClassDeclaration | null, violations: string[]): string[] {
   const fromArray = (expr: ts.Expression, where: string): string[] => {
     if (!ts.isArrayLiteralExpression(expr)) {
-      violations.push(`${where}: inject is not a plain string-array literal; teach the generator the new shape.`)
+      violations.push(`${where}: inject is not a plain string-array literal; teach the generator the new declaration form.`)
       return []
     }
     return expr.elements.map(el => ts.isStringLiteral(el) ? el.text : el.getText(ctx.sf))
@@ -727,7 +727,7 @@ export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
   }
 
   // Fold composed schemas' key paths in, then check each path against the type.
-  // Only a definite miss fails; shapes the walk cannot enumerate stay unknown.
+  // Only a definite miss fails; types the walk cannot enumerate stay unknown.
   const byName = new Map(entries.map(e => [e.pkg, e]))
   for (const entry of entries) {
     if (entry.kind !== 'config' || entry.schemaKeys === null || entry.schemaKeys === undefined) continue
@@ -819,7 +819,7 @@ export function render(entries: CatalogEntry[]): string {
     '',
     '# Plugin Config Catalog',
     '',
-    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated `cordis-surface` region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated Cordis API region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
     '',
     'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
     '',
@@ -832,7 +832,7 @@ export function render(entries: CatalogEntry[]): string {
   lines.push(
     '## Loadable plugins with no config',
     '',
-    'These load from a `cordis.yml` entry with no `config:` block; they declare no config surface.',
+    'These load from a `cordis.yml` entry with no `config:` block; they declare no configuration API.',
     '',
     ...entries.filter(e => e.kind === 'no-config').map(e => renderTerse(e, '')),
     '',

scripts/gen-cordis-catalog-partition.spec.ts

@@ -128,7 +128,7 @@ describe('cordis-walk scan reach', () => {
     const dir = join(root, 'packages/client/ui-x/src/client')
     mkdirSync(dir, { recursive: true })
     writeFileSync(join(dir, 'index.ts'), [
-      "declare module 'cordis' {",
+      "declare module '@deepseek-ai/cordis' {",
       '  interface Events {',
       "    'x/changed'(): void",
       '  }',
@@ -153,12 +153,12 @@ describe('cordis-walk scan reach', () => {
     // backstop must not stop at the first one, skip the double-quoted legal
     // form, or ignore .tsx sources.
     writeFileSync(join(dir, 'split.ts'), [
-      "declare module 'cordis' {",
+      "declare module '@deepseek-ai/cordis' {",
       '  interface Context {',
       '    first: FirstService',
       '  }',
       '}',
-      'declare module "cordis" {',
+      'declare module "@deepseek-ai/cordis" {',
       '  interface Events {',
       "    'second/changed'(): void",
       '  }',
@@ -167,7 +167,7 @@ describe('cordis-walk scan reach', () => {
       '',
     ].join('\n'))
     writeFileSync(join(dir, 'view.tsx'), [
-      "declare module 'cordis' {",
+      "declare module '@deepseek-ai/cordis' {",
       '  interface Context {',
       '    fromTsx: TsxService',
       '  }',
@@ -189,7 +189,7 @@ describe('cordis-walk scan reach', () => {
 
   it('reads string-literal and identifier member names from an Events merge', () => {
     const sf = ts.createSourceFile('x.ts', [
-      "declare module 'cordis' {",
+      "declare module '@deepseek-ai/cordis' {",
       '  interface Events {',
       "    'scope/list'(items: string[]): void",
       '    plain(): void',

scripts/gen-cordis-catalog.ts

@@ -2,7 +2,7 @@
  * Generate the per-subsystem Cordis service/event reference regions from the
  * Typert catalog projection. Every harness `ctx.<key>` service and event scope
  * maps to exactly one `docs/subsystems/` page through the curated tables below;
- * the generator injects each page's surface between its GENERATED markers —
+ * the generator injects each page's Cordis API reference between its GENERATED markers —
  * byte-identically into both language sides of the pair — and re-records a
  * pair's `.i18n.yaml` only when nothing outside the region changed. The
  * projection enforces event modes, JSDoc parameter/return completeness, and
@@ -40,13 +40,15 @@ export { REGION_BEGIN, REGION_END }
  * The owning subsystems page for every harness `ctx.<key>` service the
  * projection discovers. Fail-closed both ways: a discovered key absent here
  * and an entry whose key the projection no longer discovers are both hard
- * errors, so the partition can never silently drift from the service surface.
+ * errors, so the partition can never silently drift from the service API.
  */
 export const SERVICE_PAGE: Record<string, string> = {
   agentLoop: 'core.md',
   agentDefaultModel: 'core.md',
+  agentPresets: 'core.md',
   agents: 'core.md',
   approval: 'approval.md',
+  attachments: 'attachment.md',
   bash: 'bash.md',
   bashEnv: 'bash.md',
   clientModuleHost: 'client-modules.md',
@@ -61,6 +63,7 @@ export const SERVICE_PAGE: Record<string, string> = {
   httpServer: 'http-server.md',
   invariants: 'invariants.md',
   llm: 'llm-streaming.md',
+  messageFeedback: 'feedback.md',
   permission: 'permission.md',
   planMode: 'plan.md',
   pty: 'pty.md',
@@ -97,42 +100,42 @@ export const SERVICE_PAGE: Record<string, string> = {
 /**
  * Context keys declared in `interface Context` merges that the rendering
  * projection cannot see, each with the reason and its documentation owner.
- * The scan that enforces this list reads EVERY `declare module 'cordis'`
+ * The scan that enforces this list reads EVERY `declare module '@deepseek-ai/cordis'`
  * Context merge under `packages/x/x/src/**` — any depth, not only root
  * `index.ts` files with a same-named service class — so a new service can
  * never silently join this blind spot: it either enters {@link SERVICE_PAGE}
  * or names itself here. Client-face keys (the projection analyzes the host
- * face only) name the package README that owns their surface.
+ * face only) name the package README that owns their API.
  * TODO(cordis-catalog-interface-services): the interface-typed and
  * non-index-declared entries would all render once the projection resolves a
  * Context key through its declaring file's imports to the class declaration.
  */
 export const SERVICE_WALK_EXEMPTIONS: Record<string, string> = {
   agent: 'not a service: the DX accessor field on Agent.ctx (root accessor defaulting to undefined) — docs/subsystems/core.md owns the Agent handle',
-  configuredAgentIdentities: 'not a service: launcher-provided boot-context value (ConfiguredAgentIdentities | undefined) — packages/core/agent-loop/README.md owns the launcher contract',
-  launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns the launcher contract',
+  appExit: 'not a service: launcher-provided bounded process-exit callback — packages/boot/cmdline/README.md owns the launcher contract',
+  cmdlineArgs: 'not a service: launcher-provided immutable app argument accessor — packages/boot/cmdline/README.md owns the launcher contract',
+  configuredAgentIdentities: 'not a service: launcher-provided boot-context value (ConfiguredAgentIdentities | undefined) — packages/core/agent-loop/README.md owns this launcher contract',
+  launcherSessionQueryPath: 'not a service: launcher-provided boot-context value (string | undefined) — packages/session-query/session-query-sqlite/README.md owns this launcher contract',
   dshHomePath: 'not a service: boot-provided root accessor function (typeof dshHomePath | undefined) for Loader !!js config expressions — packages/boot/app-boot/README.md owns the boot contract',
-  headlessIo: 'not a service: launcher-provided root accessor value (HeadlessIo | undefined) for the headless bundle runner — packages/bundle/headless/README.md owns the launcher contract',
-  launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns the launcher contract',
-  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the surface',
-  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the surface',
-  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the surface',
-  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the surface',
-  chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the surface',
-  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the surface',
-  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the surface',
-  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
-  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the surface',
-  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the surface',
-  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the surface',
-  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the surface',
-  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the surface',
-  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the surface',
-  sessionHistory: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
-  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the surface',
-  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
-  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the surface',
-  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the surface',
+  launcherEnvironment: 'not a service: launcher-provided root accessor value (EnvironmentSnapshot | undefined) — packages/util/environment/README.md owns this launcher contract',
+  lsp: 'interface-typed (LspService); implementing class Lsp is not the declared type name — packages/lsp/lsp/README.md owns the API',
+  apiProxy: 'interface-typed (ApiProxy) with the class in api-proxy.ts, not index.ts — packages/host/apiproxy/README.md owns the API',
+  appShell: 'client-side interface-typed browser service — packages/client/web/README.md owns the API',
+  connection: 'client-side interface-typed browser service — packages/client/connection/README.md owns the API',
+  chatFileMentions: 'client-side slot-contract accessor (ChatFileMentions) — packages/client/ui-conversation/README.md owns the API',
+  command: 'client-side interface-typed browser service — packages/client/ui-command/README.md owns the API',
+  conversation: 'client-side interface-typed browser service — packages/client/ui-conversation/README.md owns the API',
+  conversationEvents: 'client-side interface-typed registry — packages/client/runtime/README.md owns the API',
+  conversationViews: 'client-side interface-typed registry — packages/client/runtime/README.md owns the API',
+  layout: 'client-side interface-typed browser service — packages/client/ui-layout/README.md owns the API',
+  locale: 'client-side interface-typed browser service — packages/client/locale/README.md owns the API',
+  models: 'client-side interface-typed browser service — packages/client/ui-model/README.md owns the API',
+  modules: 'client-side interface-typed browser service — packages/client/modules/README.md owns the API',
+  remote: 'client-side interface-typed gateway accessor (ClientRemote) — packages/api/gateway/README.md owns the API',
+  slash: 'client-side interface-typed browser service — packages/client/ui-slash/README.md owns the API',
+  slots: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the API',
+  theme: 'client-side interface-typed browser service — packages/client/ui-theme/README.md owns the API',
+  workspaces: 'client-side interface-typed browser service — packages/client/runtime/README.md owns the API',
 }
 
 /**
@@ -166,7 +169,7 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
  * Event names declared in `interface Events` merges that the rendering
  * projection cannot see, each with the reason and its documentation owner.
  * The mirror of {@link SERVICE_WALK_EXEMPTIONS} for events: an independent
- * scan reads EVERY `declare module 'cordis'` Events merge under
+ * scan reads EVERY `declare module '@deepseek-ai/cordis'` Events merge under
  * `packages/x/x/src/**`, so a declared event either renders onto a subsystems
  * page (via {@link EVENT_SCOPE_PAGE}) or names itself here — never vanishes
  * silently. Keys are full event names, not scopes: client-face events share
@@ -174,18 +177,19 @@ export const EVENT_SCOPE_PAGE: Record<string, string> = {
  * so a scope-level exemption would mask a host-face regression.
  */
 export const EVENT_WALK_EXEMPTIONS: Record<string, string> = {
-  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the surface',
-  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the surface',
-  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the surface',
-  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the surface',
-  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the surface',
-  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the surface',
+  'commands/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'connection/reset': 'client-face transport signal — packages/client/runtime/README.md owns the API',
+  'credentials/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'locale/change': 'client-face locale switch signal — packages/client/locale/README.md owns the API',
+  'models/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'session/preset-changed': 'client-face per-session catalog invalidation signal — packages/client/runtime/README.md owns the API',
+  'settings/changed': 'client-face registry invalidation signal — packages/client/runtime/README.md owns the API',
+  'slash/input-begin-command': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-consume-token': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-insert-reference': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slash/input-insert-text': 'client-face slash-input protocol — packages/client/ui-slash/README.md owns the API',
+  'slots/changed': 'client-face slot invalidation signal — packages/client/runtime/README.md owns the API',
+  'theme/change': 'client-face theme switch signal — packages/client/ui-theme/README.md owns the API',
 }
 
 /**
@@ -225,6 +229,25 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ResolvedRetryPolicy: 'llm-streaming.md',
   Message: 'llm-streaming.md',
   MessageSource: 'llm-streaming.md',
+  MessageFeedbackDeleteRequest: 'feedback.md',
+  MessageFeedbackDeleteResult: 'feedback.md',
+  MessageFeedbackDeleteValue: 'feedback.md',
+  MessageFeedbackFailure: 'feedback.md',
+  MessageFeedbackItem: 'feedback.md',
+  MessageFeedbackListRequest: 'feedback.md',
+  MessageFeedbackListResult: 'feedback.md',
+  MessageFeedbackListValue: 'feedback.md',
+  MessageFeedbackNoteBlank: 'feedback.md',
+  MessageFeedbackNoteTooLarge: 'feedback.md',
+  MessageFeedbackPutRequest: 'feedback.md',
+  MessageFeedbackPutResult: 'feedback.md',
+  MessageFeedbackRating: 'feedback.md',
+  MessageFeedbackRejected: 'feedback.md',
+  MessageFeedbackSessionNotFound: 'feedback.md',
+  MessageFeedbackSuccess: 'feedback.md',
+  MessageFeedbackTargetNotFound: 'feedback.md',
+  MessageFeedbackVersion: 'feedback.md',
+  MessageFeedbackVersionConflict: 'feedback.md',
   UserMessage: 'session.md',
   PreStepDecision: 'core.md',
   PreStepContext: 'core.md',
@@ -242,6 +265,9 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',
   ApprovalService: 'approval.md',
+  ImageAttachmentRef: 'attachment.md',
+  SaveImageAttachment: 'attachment.md',
+  StoredImageAttachment: 'attachment.md',
   BashExecRequest: 'bash.md',
   BashExecSpec: 'bash.md',
   BashProcess: 'bash.md',
@@ -282,7 +308,6 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   CommandDescriptor: 'commands.md',
   CommandId: 'commands.md',
   CommandResult: 'commands.md',
-  CommandSurface: 'commands.md',
   LlmAdapter: 'llm-streaming.md',
   PreparedLlmCall: 'llm-streaming.md',
   LlmService: 'llm-streaming.md',
@@ -295,6 +320,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SessionLocation: 'persistence.md',
   SessionPreparation: 'persistence.md',
   SessionPersistenceSnapshot: 'persistence.md',
+  SessionRawArtifact: 'persistence.md',
   ConfinedArgv: 'sandbox.md',
   SandboxExecutionPolicy: 'sandbox.md',
   SandboxMode: 'sandbox.md',
@@ -346,6 +372,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   SkillProvider: 'skills.md',
   SkillProviderObservation: 'skills.md',
   SkillRegistration: 'skills.md',
+  SkillViewOptions: 'skills.md',
   SkillSummary: 'skills.md',
   SaveTextSpill: 'spill.md',
   SpillRef: 'spill.md',
@@ -376,6 +403,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   TaskRead: 'tasks.md',
   TaskSnapshot: 'tasks.md',
   TaskStart: 'tasks.md',
+  TasksChangedListener: 'tasks.md',
   TokenMeasurement: 'token-meter.md',
   CodeDispatchLog: 'tools.md',
   PostToolDecision: 'tools.md',
@@ -388,6 +416,7 @@ export const LINK_MAP: Readonly<Record<string, string>> = {
   ToolExecutionResult: 'tools.md',
   ToolExecutionToken: 'tools.md',
   ToolGuard: 'tools.md',
+  ToolPresentationMode: 'tools.md',
   ToolRegistry: 'tools.md',
   ToolRestriction: 'tools.md',
   ToolSchema: 'tools.md',
@@ -453,6 +482,7 @@ export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'Promise',
   'Record',
   'Readonly',
+  'Uint8Array',
 ])
 
 /** Project types deliberately documented outside the subsystems catalog. */
@@ -462,6 +492,9 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   ConsumeTokenRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertTextRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
+  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
+  AgentPreset: 'discovered preset record is owned by packages/preset/agent-presets/README.md',
+  PresetMetadata: 'preset display text is owned by packages/preset/agent-presets/README.md',
   BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
   BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
   CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
@@ -472,13 +505,13 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
   TypeRTDisposer: 'TypeRT lifecycle contract is owned by packages/typert/type-meta/README.md',
   InvokeRemoteRequest: 'gateway invocation contract is owned by packages/api/gateway/README.md',
-  LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
+  LocaleDict: 'service-local dictionary fields are 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',
   WebUpgradeRoute:
     'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
-  KnobState: 'projection unit state shape is owned by packages/interaction/permission/README.md',
+  KnobState: 'projection unit state fields are owned by packages/interaction/permission/README.md',
   PermissionSelect: 'permissions projection payload is owned by packages/interaction/permission/src/types.ts',
   PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
   Sandbox: 'external E2B SDK handle is owned by packages/e2b/e2b/README.md',
@@ -528,8 +561,8 @@ export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
 
 
 /**
- * Splice a page's generated cordis-surface region into its Markdown content.
- * The page must contain exactly one cordis-surface region (the markers are
+ * Splice a page's generated Cordis API region into its Markdown content.
+ * The page must contain exactly one `cordis-surface` marker region (the markers are
  * part of the hand-owned page skeleton once, then owned by the generator);
  * zero or several is a partition error the caller reports with the page path.
  * The match is on THIS generator's exact markers, not the generic region
@@ -575,7 +608,7 @@ export interface WalkPartitionMaps {
 }
 
 /**
- * Judge the rendered surface and the independent AST scan against the curated
+ * Judge the rendered API and the independent AST scan against the curated
  * partition maps, fail-closed in both directions for services AND events: a
  * rendered key/scope must be mapped to a page, a mapped key/scope must still
  * render, and — the backstop — a DECLARED key/event the projection cannot see
@@ -583,7 +616,7 @@ export interface WalkPartitionMaps {
  * direction guards the scan itself: everything rendered must also be declared
  * to the scan, so a scan blind spot cannot decay silently. Pure so the
  * acceptance paths are provable without running the projection.
- * @param input - rendered surface plus the declared-key/event scans.
+ * @param input - rendered API plus the declared-key/event scans.
  * @param maps - the curated page maps and walk exemptions.
  * @returns one message per violation, empty when the partition holds.
  */
@@ -634,7 +667,7 @@ export function walkPartitionProblems(input: WalkPartitionInput, maps: WalkParti
   // in a Context/Events merge the scan must also reach, so a rendered key or
   // event the scan cannot see means the SCAN regressed (glob, prefilter, or
   // block walk) — a partial blind spot that exemption staleness alone would
-  // never surface.
+  // never appear.
   for (const key of input.renderedKeys.keys()) {
     if (!input.declaredKeys.has(key)) problems.push(`ctx.${key} is rendered by the projection but the independent scan finds no Context merge declaring it; the scan has a blind spot (glob, prefilter, or module-block walk) — fix the scan, not the maps.`)
   }
@@ -741,7 +774,7 @@ export function maybeRecordPair(pageRel: string, before: Map<string, Buffer>, sc
     // after review, never silently by regeneration.
     return false
   }
-  // The record must be exactly the well-formed two-entry shape for THIS pair;
+  // The record must contain exactly the two valid entries for THIS pair;
   // a malformed or renamed-key sidecar is the pairing gate's problem to
   // report, never something regeneration silently repairs into validity.
   const recorded = parsePairMeta(meta)

scripts/gen-doc-graphs.ts

@@ -62,6 +62,7 @@ type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
 
 const GROUP_ORDER = [
   'util',
+  'attachment',
   'llm',
   'core',
   'typert',
@@ -95,6 +96,15 @@ const GROUP_ORDER = [
 ]
 
 const SERVICE_ROLES: ServiceRole[] = [
+  {
+    key: 'attachments',
+    pkg: 'attachment',
+    title: 'Durable binary attachment storage',
+    mode: 'seam',
+    implementations: ['attachment-local'],
+    consumers: ['host-runtime', 'llm-pi-ai'],
+    note: 'The host commits accepted images before session events; provider adapters resolve authorized durable references into provider-native content.',
+  },
   {
     key: 'llm',
     pkg: 'llm',
@@ -125,7 +135,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'session',
     title: 'In-memory session store',
     mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants', 'message-feedback'],
     note: 'Owns append-only Session instances and emits the durable session event feed.',
   },
   {
@@ -157,7 +167,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Durable session persistence seam',
     mode: 'seam',
     implementations: ['session-persistence-jsonl', 'session-persistence-sqlite'],
-    consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
+    consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite', 'message-feedback'],
     note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
   },
   {
@@ -201,9 +211,16 @@ const SERVICE_ROLES: ServiceRole[] = [
     pkg: 'storage-domain',
     title: 'Domain data facility',
     mode: 'core',
-    consumers: ['workspace'],
+    consumers: ['workspace', 'message-feedback'],
     note: 'Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state.',
   },
+  {
+    key: 'messageFeedback',
+    pkg: 'message-feedback',
+    title: 'Lifecycle-bound message feedback',
+    mode: 'core',
+    note: 'Owns local per-assistant-message feedback, lifecycle and target validation, per-item compare-and-set, and the Host unary Remote contract without entering Session history or telemetry.',
+  },
   {
     key: 'workspace',
     pkg: 'workspace',
@@ -258,7 +275,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Human question/answer seam',
     mode: 'seam',
     consumers: ['tool-ask-user'],
-    note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
+    note: 'UI front ends provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
   },
   {
     key: 'planMode',
@@ -267,6 +284,13 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'core',
     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: 'agentPresets',
+    pkg: 'agent-presets',
+    title: 'Per-session agent composition',
+    mode: 'core',
+    note: 'Discovers preset directories over trusted and user-authored roots and mounts one preset cordis.yml under an agent scope during creation, rejecting a row that never activates or that publishes into the root service realm.',
+  },
   {
     key: 'commands',
     pkg: 'commands',
@@ -313,7 +337,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Default Agent model selection',
     mode: 'core',
     consumers: ['headless', 'host-apiproxy'],
-    note: 'Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner.',
+    note: 'Layers the default ModelSelection through settings so direct and Host-backed Agent entry points share one state owner.',
   },
   {
     key: 'agentLoop',
@@ -371,7 +395,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['pty-local'],
     consumers: ['tool-pty'],
-    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface.',
+    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model tools.',
   },
   {
     key: 'sandbox',
@@ -452,7 +476,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['tasks-local'],
     consumers: ['tool-bash', 'tool-pty', 'tool-subagent', 'tool-tasks'],
-    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry.',
+    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing controller that reads, lists, and kills it; tasks-local is the process-local registry.',
   },
   {
     key: 'web',
@@ -495,7 +519,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     title: 'Client plugin graph host',
     mode: 'core',
     consumers: ['hmr'],
-    note: 'Composes the __DSH_BOOT__ entry graph from an incremental dshClient scan, serves plugin bundles, and notifies rebuilt/graph-changed subscribers.',
+    note: 'Composes the __DSH_BOOT__ entry graph from an incremental dsh.client scan, serves plugin bundles, and notifies rebuilt/graph-changed subscribers.',
   },
   {
     key: 'workflows',
@@ -504,7 +528,7 @@ const SERVICE_ROLES: ServiceRole[] = [
     mode: 'seam',
     implementations: ['workflow-workerthread'],
     consumers: ['tool-workflow', 'tool-ralph'],
-    note: 'One engine per context (bash shape, no named-provider registry); the general workflow and fixed Ralph consumers start runs whose agent() calls fan out through ctx.subagents.',
+    note: 'One engine per context, as in bash, with no named-provider registry; the general workflow and fixed Ralph consumers start runs whose agent() calls fan out through ctx.subagents.',
   },
 ]
 
@@ -675,7 +699,7 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
   lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
   lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
   if (pluginName === '@deepseek-ai/dsh-acp-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
+    lines.push(`  ${appNode} --> ${nodeId('entrypoint', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
   }
   lines.push(
     `  ${agentCore} --> ${nodeId('spine', 'llm')}["ctx.llm"]`,
@@ -727,7 +751,18 @@ type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExp
  */
 const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
 
-/** Collect event dispatch/listener relations from real cross-file receiver types. */
+/**
+ * Collect event dispatch/listener relations from real cross-file receiver types.
+ *
+ * TODO: the program is seeded from the host aggregate alone (ts-project.ts
+ * documents why: one program cannot hold both faces' Context merges), so a
+ * Client package enters only when a host file imports it. Client-face
+ * listeners on client-face events are therefore under-reported —
+ * `connection/reset` omits `ui-skill`/`ui-agent-preset`, `models/changed`
+ * omits `ui-model`, `session/preset-changed` omits `ui-skill`. Closing it
+ * needs a second Client program whose relations merge into these, not a
+ * wider seed.
+ */
 export class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
   private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
@@ -787,7 +822,7 @@ export class EventRelationCollector {
    * Return every indexed call resolving to one local helper declaration.
    * Fast path: when every same-file reference to the non-exported helper is
    * provably a direct callee, module scoping confines all of its calls to that
-   * file, so only that file is indexed. Any other reference shape may alias
+   * file, so only that file is indexed. Any other reference form may alias
    * the function value outward, so the original full package-source index
    * decides instead.
    */
@@ -1127,7 +1162,7 @@ function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): strin
     lines.push(`| \`${event.name}\` | \`${event.mode}\` | ${sourceLink(event.source)} | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
   }
   // Every declared event needs a dispatcher: zero means dead vocabulary or an
-  // unrecognized semantic dispatch shape. Listener-free extension points remain
+  // unrecognized semantic dispatch form. Listener-free extension points remain
   // valid. Client-declared events are exempt: the relation scan seeds the HOST
   // aggregate program only (host+client cannot share one program — the cordis
   // Context merges collide), so client dispatch sites are structurally
@@ -1140,8 +1175,8 @@ function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): strin
   if (undispatched.length > 0) {
     throw new Error(
       `event-producer-consumer matrix: no dispatcher found for declared event${undispatched.length > 1 ? 's' : ''} `
-      + `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch shape the semantic scan misses `
-      + '(teach scripts/gen-doc-graphs.ts the shape)',
+      + `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch form the semantic scan misses `
+      + '(teach scripts/gen-doc-graphs.ts that form)',
     )
   }
   const declared = new Set(events.map(event => event.name))
@@ -1234,9 +1269,9 @@ function renderLifecycle(): string {
     '',
     '`dsh-compact-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
     '',
-    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later boundary claims their next-step batch.',
+    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.',
     '',
-    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
+    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
@@ -1246,7 +1281,7 @@ function renderToolPipeline(): string {
   const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs'
   return [
     ...generatedHeader('Tool Execution Pipeline'),
-    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards, definition-owned `finalizeContent`, and `tools/result` are the owner-enforced boundaries around them.',
+    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.',
     '',
     '```mermaid',
     'flowchart TD',
@@ -1300,7 +1335,7 @@ function renderToolPipeline(): string {
     '  allResults --> context',
     '```',
     '',
-    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition\'s snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
+    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition\'s snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
     '',
     ...maintenanceFooter(maintenance),
   ].join('\n')
@@ -1352,7 +1387,7 @@ function renderIndex(docs: GraphDoc[]): string {
   const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
   return [
     ...generatedHeader('Documentation Graph Index'),
-    'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the [subsystem pages](subsystems/core.md) (types + the generated `cordis-surface` regions) and [tool-catalog.md](tool-catalog.md).',
+    'These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated Cordis API regions) and [tool-catalog.md](tool-catalog.md).',
     '',
     'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
     '',

scripts/gen-persistence-catalog.ts

@@ -13,6 +13,7 @@ import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/persistence-catalog.md'
+const OUT_RUNTIME_TYPES = 'packages/core/session/src/known-event-types.ts'
 
 /** The fenced-block info string for generated declaration blocks (skipped by
  * doc-typecheck, since their imported types are not standalone-compilable). */
@@ -360,7 +361,7 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
     '',
     'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog Agent Note](../.agents/notes/archived/process/2026-07-04-persistence-log-catalog.md).',
     '',
-    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, the optional `ignorable` unknown-type skip marker, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](subsystems/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
     '',
     '## Event envelope',
     '',
@@ -383,31 +384,79 @@ export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnv
   return lines.join('\n')
 }
 
-/** CLI entry: default writes the catalog, `--check` fails if the committed copy
+/**
+ * Render the runtime known-vocabulary module: every event type the packages in
+ * this repo can write, as a generated `ReadonlySet` the read path checks
+ * unknown-type refusal against (`SessionEvent.ignorable` contract).
+ */
+export function renderKnownEventTypes(events: AnnotatedLogEventEntry[]): string {
+  const names = [...new Set(events.map(e => e.name))].sort()
+  return [
+    '/**',
+    ' * GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run',
+    ' * `pnpm run gen-persistence-catalog` to regenerate (verified fresh by',
+    ' * `pnpm run verify-persistence-catalog`, part of `doc-sync`).',
+    ' * @module @deepseek-ai/dsh-session/known-event-types',
+    ' */',
+    '',
+    '/**',
+    ' * Every `SessionEventMap` member declared in this repository — the event',
+    ' * vocabulary this build understands. The persistence read path refuses to',
+    ' * interpret a log containing a type outside this set unless the event',
+    ' * carries the envelope\'s `ignorable` marker (see `SessionEvent.ignorable`',
+    ' * in `./types.ts`): such a log was likely written by a newer harness, and',
+    ' * silently skipping a required event would reconstruct a wrong session.',
+    ' * Downstream (out-of-repo) plugin events are outside this list by',
+    ' * construction; a registration surface for them is deferred until such a',
+    ' * consumer exists.',
+    ' */',
+    'export const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string> = new Set([',
+    ...names.map(name => `  '${name}',`),
+    '])',
+    '',
+  ].join('\n')
+}
+
+/** One generated artifact: repo-relative target and its freshly-rendered content. */
+interface GeneratedArtifact {
+  readonly out: string
+  readonly content: string
+}
+
+/** CLI entry: default writes the artifacts, `--check` fails if a committed copy
  * is stale. Guarded behind an entry-point check so importing this module for
- * tests neither regenerates the committed file nor calls process.exit. */
+ * tests neither regenerates the committed files nor calls process.exit. */
 function main(): void {
-  const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()), collectEventEnvelopeTypes())
+  const events = annotateSurface(collectLogEvents(), collectSurfaceEventTypes())
+  const artifacts: GeneratedArtifact[] = [
+    { out: OUT, content: render(events, collectEventEnvelopeTypes()) },
+    { out: OUT_RUNTIME_TYPES, content: renderKnownEventTypes(events) },
+  ]
   if (process.argv.includes('--check')) {
-    let committed: string | null = null
-    try {
-      committed = readFileSync(resolve(root, OUT), 'utf8')
-    } catch {
-      // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-      // file is not a state this repo produces. Either way the remedy is the
-      // same — regenerate — so treat a read failure as "stale".
-      committed = null
-    }
-    if (committed === content) {
-      console.log(`gen-persistence-catalog: ${OUT} is up to date.`)
+    const stale = artifacts.filter((artifact) => {
+      let committed: string | null = null
+      try {
+        committed = readFileSync(resolve(root, artifact.out), 'utf8')
+      } catch {
+        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
+        // file is not a state this repo produces. Either way the remedy is the
+        // same — regenerate — so treat a read failure as "stale".
+        committed = null
+      }
+      return committed !== artifact.content
+    })
+    if (stale.length === 0) {
+      console.log(`gen-persistence-catalog: ${artifacts.map(a => a.out).join(', ')} are up to date.`)
       process.exit(0)
     }
-    console.error(`gen-persistence-catalog: ${OUT} is stale. Run \`pnpm run gen-persistence-catalog\` and commit ${OUT}.`)
+    console.error(`gen-persistence-catalog: ${stale.map(a => a.out).join(', ')} stale. Run \`pnpm run gen-persistence-catalog\` and commit the result.`)
     process.exit(1)
   }
 
-  writeFileSync(resolve(root, OUT), content)
-  console.log(`gen-persistence-catalog: wrote ${OUT}.`)
+  for (const artifact of artifacts) {
+    writeFileSync(resolve(root, artifact.out), artifact.content)
+    console.log(`gen-persistence-catalog: wrote ${artifact.out}.`)
+  }
 }
 
 // Run only when invoked as a script, not when imported by a test.

scripts/gen-scoped-events.ts

@@ -309,14 +309,14 @@ class ScopedEventGenerator {
   }
 }
 
-/** Return whether an Events interface is inside declare module 'cordis'. */
+/** Return whether an Events interface is inside declare module '@deepseek-ai/cordis'. */
 function isCordisModuleInterface(node: ts.InterfaceDeclaration): boolean {
   const block = node.parent
   const declaration = block.parent
   return ts.isModuleBlock(block)
     && ts.isModuleDeclaration(declaration)
     && ts.isStringLiteral(declaration.name)
-    && declaration.name.text === 'cordis'
+    && declaration.name.text === '@deepseek-ai/cordis'
 }
 
 /** Return whether a parameter is the explicit TypeScript this receiver. */

scripts/gen-third-party-notices.spec.ts

@@ -134,13 +134,17 @@ describe('parseVendoredRows', () => {
     const rows = parseVendoredRows(readFileSync(resolve(root, 'vendor/README.md'), 'utf8'))
 
     expect(rows.length).toBeGreaterThan(0)
-    expect(rows).toContainEqual({ npmName: 'cordis', upstream: 'https://github.com/cordiverse/cordis' })
+    expect(rows).toContainEqual({
+      npmName: '@deepseek-ai/cordis',
+      upstreamName: 'cordis',
+      upstream: 'https://github.com/cordiverse/cordis',
+    })
     // The upstream column carries a trailing package path for some rows; it is not part of the URL.
     expect(rows.every(row => /^https:\/\/\S+$/.test(row.upstream))).toBe(true)
   })
 
-  it('yields nothing when the table shape changes, so the generator fails loud', () => {
-    expect(parseVendoredRows('| `cordis/` | cordis | 4.0.0 | https://example.com | `abc123` |\n')).toEqual([])
+  it('yields nothing when the table columns change, so the generator fails loud', () => {
+    expect(parseVendoredRows('| `cordis/` | `@deepseek-ai/cordis` | cordis | 4.0.0 | https://example.com | `abc123` |\n')).toEqual([])
   })
 
   it('covers every vendored directory, so no package can drop out of the notices', () => {
@@ -215,7 +219,7 @@ describe('parsePyprojectRequirements', () => {
     ].join('\n'))).toEqual(['pydantic', 'tomli', 'pytest'])
   })
 
-  it('accepts dependency-group includes and rejects unsupported requirement shapes', () => {
+  it('accepts dependency-group includes and rejects unsupported requirement forms', () => {
     expect(parsePyprojectRequirements('[dependency-groups]\nbase = ["pytest"]\nall = [{ include-group = "base" }]\n'))
       .toEqual(['pytest'])
     expect(() => parsePyprojectRequirements('[project]\ndependencies = "pytest"\n')).toThrow(/must be an array/)
@@ -227,7 +231,7 @@ describe('collectPythonDependencies', () => {
   it('excludes normalized local project names without exempting a third-party prefix', () => {
     const pyprojects = [
       '[project]\nname = "deepseek-harness-runtime-bin"\ndependencies = ["pydantic"]\n',
-      '[project]\nname = "deepseek-harness"\ndependencies = ["DeepSeek.Harness_Runtime-Bin", "deepseek-unrelated"]\n',
+      '[project]\nname = "deepseek-harness-sdk"\ndependencies = ["DeepSeek.Harness_Runtime-Bin", "deepseek-unrelated"]\n',
     ]
     expect(() => collectPythonDependencies(pyprojects)).toThrow(
       'python dependency deepseek-unrelated is missing from PYTHON_METADATA',

scripts/gen-third-party-notices.ts

@@ -27,8 +27,8 @@ const ALL_KINDS = ['dependencies', 'devDependencies', 'optionalDependencies', 'p
  * root manifest), test infrastructure, the documentation site, the runnable
  * demo leaves, and the native launcher's build workspace. A runtime
  * declaration by anything outside these areas is a disclosure-relevant
- * runtime dependency, because `scripts/install.sh` installs the repository
- * itself and any plugin package can be mounted from a user's `cordis.yml`.
+ * runtime dependency because any plugin package can be mounted from a user's
+ * `cordis.yml`.
  */
 const DEV_ONLY_AREAS = [
   'package.json',
@@ -83,7 +83,7 @@ const OVERRIDES: Record<string, { license?: string; repo?: string }> = {
  * the generator fails when a manifest names a package this map misses.
  */
 const PYTHON_METADATA: Record<string, { license: string; repo: string; role: string }> = {
-  pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness`' },
+  pydantic: { license: 'MIT', repo: 'https://github.com/pydantic/pydantic', role: 'runtime dependency of `deepseek-harness-sdk`' },
   hatchling: { license: 'MIT', repo: 'https://github.com/pypa/hatch', role: 'build backend' },
   pytest: { license: 'MIT', repo: 'https://github.com/pytest-dev/pytest', role: 'test-only' },
 }
@@ -369,7 +369,7 @@ function collectNpmDeps(): ExternalDep[] {
  */
 export function tierExternalDeps(manifests: Map<string, Manifest>, names: Set<string>): Map<string, boolean> {
   const tiers = new Map<string, boolean>()
-  // `tsx` is runtime by fiat: `bin/dsh` execs the CLI through its ESM hook.
+  // `tsx` is runtime by fiat: the root source-run scripts execute through its ESM hook.
   tiers.set('tsx', true)
   for (const [path, manifest] of manifests) {
     const devOnly = DEV_ONLY_AREAS.some(area => (area.endsWith('/') ? path.startsWith(area) : path === area))
@@ -387,6 +387,8 @@ export function tierExternalDeps(manifests: Map<string, Manifest>, names: Set<st
 /** A vendored package row parsed out of the `vendor/README.md` manifest table. */
 export interface VendoredRow {
   npmName: string
+  /** The name this package carries upstream; MIT attribution names the fork's origin, not our scope. */
+  upstreamName: string
   upstream: string
 }
 
@@ -398,11 +400,12 @@ export interface VendoredRow {
 export function parseVendoredRows(text: string): VendoredRow[] {
   const rows: VendoredRow[] = []
   for (const line of text.split('\n')) {
-    const match = /^\| \x60\S+\/\x60 \| \x60([^\x60]+)\x60 \| \S+ \| (https:\/\/\S+?)(?: \([^)]*\))? \| \x60[0-9a-f]+\x60 \|$/.exec(line)
+    const match = new RegExp(String.raw`^\| \x60\S+\/\x60 \| \x60([^\x60]+)\x60 \| \x60([^\x60]+)\x60 \| \S+ \| `
+      + String.raw`(https:\/\/\S+?)(?: \([^)]*\))? \| \x60[0-9a-f]+\x60 \|$`).exec(line)
     if (match === null) continue
-    const [, npmName, upstream] = match
-    if (npmName === undefined || upstream === undefined) continue
-    rows.push({ npmName, upstream })
+    const [, npmName, upstreamName, upstream] = match
+    if (npmName === undefined || upstreamName === undefined || upstream === undefined) continue
+    rows.push({ npmName, upstreamName, upstream })
   }
   return rows
 }
@@ -475,7 +478,7 @@ function collectPythonRequirementArray(
   }
 }
 
-/** Read an optional TOML table and reject a present value of another shape. */
+/** Read an optional TOML table and reject a present non-table value. */
 function optionalTomlTable(value: TomlValueWithoutBigInt | undefined, location: string): TomlTableWithoutBigInt | undefined {
   if (value === undefined || isTomlTable(value)) return value
   throw new Error(`gen-third-party-notices: ${location} must be a table.`)
@@ -487,7 +490,7 @@ function optionalTomlTable(value: TomlValueWithoutBigInt | undefined, location:
  * `[build-system]`, `dependencies` under `[project]`, and every key under
  * `[project.optional-dependencies]` and `[dependency-groups]`. A TOML parser
  * owns comments, quoted keys, escapes, and array boundaries; unsupported
- * requirement shapes fail instead of disappearing from the notices.
+ * requirement forms fail instead of disappearing from the notices.
  * @param text - the complete `pyproject.toml` contents.
  * @returns the local project name and declared requirement names.
  */
@@ -696,15 +699,15 @@ The complete npm transitive closure, including the Landlock launcher workspace,
 
 ## Vendored source (\`vendor/\`)
 
-The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm. All are MIT-licensed; each directory preserves its upstream \`LICENSE\` file. Exact upstream commits and local modifications are recorded in [\`vendor/README.md\`](vendor/README.md).
+The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm, and republished under the \`@deepseek-ai\` scope. All are MIT-licensed; each directory preserves its upstream \`LICENSE\` file. Exact upstream commits and local modifications are recorded in [\`vendor/README.md\`](vendor/README.md).
 
-| Package | Upstream | License |
-| --- | --- | --- |
-${vendored.map(row => `| \`${row.npmName}\` | [${row.upstream.replace('https://', '')}](${row.upstream}) | MIT |`).join('\n')}
+| Package | Upstream name | Upstream | License |
+| --- | --- | --- | --- |
+${vendored.map(row => `| \`${row.npmName}\` | \`${row.upstreamName}\` | [${row.upstream.replace('https://', '')}](${row.upstream}) | MIT |`).join('\n')}
 
 ## Runtime npm dependencies
 
-External packages that a workspace package resolves at runtime. \`scripts/install.sh\` installs this repository itself, so the tier covers every plugin a user can mount from \`cordis.yml\` — not only what the \`dsh\` CLI, Web UI, and Python SDK runtime load by default.
+External packages that a workspace package resolves at runtime. The tier covers every plugin a user can mount from \`cordis.yml\` — not only what the \`dsh\` CLI, Web UI, and Python SDK runtime load by default.
 
 ${renderNpmTable(runtimeDeps)}
 

scripts/gen-tool-catalog.ts

@@ -8,7 +8,7 @@
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, resolve } from 'node:path'
-import { Context } from 'cordis'
+import { Context } from '@deepseek-ai/cordis'
 import type { ToolSchema } from '@deepseek-ai/dsh-llm'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
 import type { Agent } from '@deepseek-ai/dsh-agent'
@@ -24,13 +24,15 @@ import * as BashEnvPlugin from '@deepseek-ai/dsh-bash-env'
 import { PwshLocalExecutor } from '@deepseek-ai/dsh-pwsh-local'
 import LocalSubprocessService from '@deepseek-ai/dsh-subprocess-local'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
+import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type { ImageAttachmentLimits, ImageAttachmentRef, SaveImageAttachment, StoredImageAttachment } from '@deepseek-ai/dsh-attachment'
 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'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
+import type { SubagentProvider, SubagentReportDelivery } from '@deepseek-ai/dsh-subagent'
 import * as ToolSubagentControl from '@deepseek-ai/dsh-tool-subagent-control'
 import * as ToolSubagentListAgents from '@deepseek-ai/dsh-tool-subagent-control/list-agents'
 import * as ToolSubagentReport from '@deepseek-ai/dsh-tool-subagent-report'
@@ -61,6 +63,29 @@ import VmWorkflowEngine from '@deepseek-ai/dsh-workflow-workerthread'
 import * as ToolRalph from '@deepseek-ai/dsh-tool-ralph'
 import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 
+/** Attachment seam marker that makes the attachments-conditional `read_image` schema harvestable. */
+class CatalogAttachmentStore extends AttachmentStore {
+  readonly imageLimits: ImageAttachmentLimits = Object.freeze({
+    maxImageBytes: 1,
+    maxImagesPerMessage: 1,
+    maxMessageImageBytes: 1,
+    maxImagePixels: 1,
+    mediaTypes: Object.freeze(['image/png'] as const),
+  })
+
+  override validateImage(_input: SaveImageAttachment): Promise<void> {
+    return Promise.reject(new Error('gen-tool-catalog: attachment validation is unreachable during schema harvest'))
+  }
+
+  override saveImage(_input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    return Promise.reject(new Error('gen-tool-catalog: attachment writes are unreachable during schema harvest'))
+  }
+
+  override readImage(_ref: ImageAttachmentRef): Promise<StoredImageAttachment> {
+    return Promise.reject(new Error('gen-tool-catalog: attachment reads are unreachable during schema harvest'))
+  }
+}
+
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/tool-catalog.md'
 
@@ -121,7 +146,7 @@ interface ToolPackage {
    * name to its own source.
    */
   source: string | Readonly<Record<string, string>>
-  /** Services or owning runtime surfaces the package requires at execution time. */
+  /** Services or owning runtimes the package requires at execution time. */
   requires: string[]
   /** Session events or other visible state the tools write or affect. */
   writes: string[]
@@ -135,14 +160,14 @@ interface ToolPackage {
   /**
    * Config for the caller's `ToolRegistry` mount. The registry itself ships a
    * model-facing tool (`run_code`, registered under a non-native `mode`), so
-   * ITS catalog entry boots the registry in the mode that surfaces it;
+   * ITS catalog entry boots the registry in the mode that exposes it;
    * every other entry uses the default (native) registry.
    */
   toolsConfig?: ToolsConfig
   /**
    * A deployment note rendered after the package's tools, for a fact that
    * booting the package alone cannot show. The registered tool NAME can be a
-   * load-time config (`tool-subagent`'s `toolName`), so one package may surface
+   * load-time config (`tool-subagent`'s `toolName`), so one package may appear
    * under several names across deployments — the boot yields the package
    * DEFAULT, and this note records the shipped alternatives the model sees.
    */
@@ -225,7 +250,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolPwsh)
     },
     note:
-      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus the sandbox surface — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
+      'The pwsh tool is the PowerShell-dialect consumer of the bash executor seam for Windows compositions (a PowerShell executor such as `@deepseek-ai/dsh-pwsh-local` backs `ctx.bash`); it mirrors the bash tool call-for-call minus sandbox controls — `run_in_background` runs register with the generic `ctx.tasks` runtime and are collected/stopped through the `task_*` tools, and the managed `DSH_*` environment comes from `@deepseek-ai/dsh-bash-env`. Each call runs in a fresh process (no persistent PTY session), with native `C:\\...` paths and `$env:NAME` variables.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-cordis',
@@ -263,22 +288,24 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolStrReplaceEditor)
     },
     note:
-      'Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal surface.',
+      'Standalone view/create/unique literal replace/line insert tool over the filesystem seam; it composes with any shell or terminal API.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs',
     dir: 'tool-fs',
     source: 'packages/fs/tool-fs/src/index.ts',
-    requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt'],
-    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after read presence/absence or successful mutation', 'tool/result'],
+    requires: ['ctx.tools', 'ctx.fs', 'ctx.systemPrompt', 'ctx.attachments (read_image registration)', 'ctx.llm + an image-capable route (read_image execution)'],
+    writes: ['tool/call', 'fs/write-intent or fs/edit-intent for mutations', 'fs/observed after read presence/absence or successful file operation', 'durable attachment (read_image)', 'tool/result'],
     async mount(ctx) {
       // The tool needs `fs`; the bare provider is sufficient because policy
-      // changes behavior, not schema shape.
+      // changes behavior, not schema shape. The catalog seam marker opts into
+      // the attachments-conditional read_image schema without attachment I/O.
       await ctx.plugin(LocalFileSystem)
+      await ctx.plugin(CatalogAttachmentStore)
       await ctx.plugin(ToolFs)
     },
     note:
-      'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin.',
+      'The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. `read_image` is not registered without `ctx.attachments`; its schema is route-independent, and execution refuses unless the exact routed model declares image input.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-fs-search',
@@ -418,7 +445,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolSubagent, { provider: 'mock' })
     },
     note:
-      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`.',
+      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped compositions load this package once per subagent backend, so the model additionally sees `subagent_fork` bound to the fork backend. Each instance\'s description and `run_in_background` parameter follow its own `backgroundMode` and `enableRunInBackground`, so the two shipped schemas are not identical: `subagent` is `continuable`, while `subagent_fork` stays `one-shot` — see `packages/bundle/base/cordis.patch.yml` and `examples/acp-agent/cordis.yml`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-subagent-control',
@@ -446,20 +473,22 @@ const TOOL_PACKAGES: ToolPackage[] = [
     pkg: '@deepseek-ai/dsh-tool-subagent-report',
     dir: 'tool-subagent-report',
     source: 'packages/subagent/tool-subagent-report/src/index.ts',
-    requires: ['ctx.subagents', 'a live continuable in-process child Agent'],
+    requires: ['ctx.subagents', 'ctx.systemPrompt', 'a live continuable in-process child Agent'],
     writes: ['tool/call', 'tool/result', 'a user-role message in the direct parent session'],
     async mount(ctx) {
       await ctx.plugin(AgentRegistry)
       await ctx.plugin(SubagentService)
+      const { reportDelivery } = ToolSubagentReport.Config({}) as { reportDelivery: SubagentReportDelivery }
       await mountCatalogChildScope(ctx, (childCtx) => {
-        ToolSubagentReport.installReportTool(childCtx, ctx, 'quiet')
+        ToolSubagentReport.installReportTool(childCtx, ctx, reportDelivery)
       })
     },
     scope: ctx => catalogChildScopes.get(ctx) as Agent,
     note:
       'Registered per continuable in-process child rather than globally, so this schema is visible only '
-      + 'inside such a child and survives its global `toolFilter`. The parent-facing `send_message` tool '
-      + 'is installed independently.',
+      + 'inside such a child and survives its global `toolFilter`. The same contribution installs the '
+      + 'child-scoped `tool:report` prompt section, which this catalog does not render. The parent-facing '
+      + '`send_message` tool is installed independently.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-tasks',
@@ -472,7 +501,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
       await ctx.plugin(ToolTasks)
     },
     note:
-      'The kind-agnostic background-task control surface: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the control surface that arms producers\' `ctx.tasks.start()`.',
+      'The kind-agnostic background-task controller: background bash commands, PTY sends, and subagents are read, listed, and killed through the same three tools. Loading the plugin attaches the controller that arms producers\' `ctx.tasks.start()`.',
   },
   {
     pkg: '@deepseek-ai/dsh-tool-todo',
@@ -633,11 +662,11 @@ export function render(catalog: ToolCatalog): string {
     '',
     '# Tool Schema Catalog',
     '',
-    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated `cordis-surface` wiring region) — this page is the *tools* the agent is offered.',
+    'Every model-facing tool a shipped plugin contributes to `ctx.tools`: the `name`, `description`, and JSON-Schema `parameters` the model receives via the system-prompt assembly. It complements the [subsystem pages](subsystems/core.md) (the types plus each page\'s generated Cordis API region) — this page is the *tools* the agent is offered.',
     '',
     'This file is GENERATED and verified fresh by `pnpm run verify-tool-catalog` (part of `doc-sync`) — do not edit it by hand. Unlike the cordis catalog (a pure source-AST pass), this generator BOOTS each tool plugin on a real context and reads `ctx.tools.schemas()`, because a tool schema is not statically knowable (runtime-spread enums, concatenated descriptions, config-driven names, raw-JSON-Schema MCP tools). A completeness guard globs `packages/*/tool-*` and fails if any package is missing from the generator\'s boot manifest, so a new tool cannot be silently undocumented. See [the tool-schema-catalog Agent Note](../.agents/notes/implemented/process/2026-07-02-tool-schema-catalog.md).',
     '',
-    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may surface a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
+    'Scope: shipped product tools under `packages/*/tool-*`, each booted with its DEFAULT config, except where a Config field is REQUIRED with no default — there the generator must choose, and the per-package note records which branch this page shows. The registered tool NAME can be a load-time config (e.g. `tool-subagent`\'s `toolName`), so a deployment may expose a package under a different or additional name — a per-package note records those shipped aliases where they exist. The `examples/` demo tools (e.g. `echo`) are excluded, matching the cordis catalog\'s packages-only scope.',
     '',
     '## Tool Package Map',
     '',

scripts/gen-translation-brief.ts

@@ -7,7 +7,7 @@
  * the narrowest safe granularity — code-fence-only splice, changed
  * Markdown units, heading sections, whole document — and `--apply` writes
  * the computed counterpart for pairs whose change is code-fence-only.
- * The briefing contract lives in `scripts/translation-brief.ts`; the
+ * The briefing rules live in `scripts/translation-brief.ts`; the
  * consuming workflow is `.agents/skills/dsh-translate-docs/SKILL.md`.
  */
 

scripts/hero-composer-dom-continuity.mjs

@@ -1,78 +0,0 @@
-// Regression drive for the unified hero composer:
-// cold start with zero workspaces -> create a workspace -> type. Asserts the
-// composer textarea is the SAME DOM node across the disabled->live flip (a
-// remount drops the __heroMark marker property) — the session-maybe
-// composer.bar contract.
-//
-// Prereqs: `pnpm run build`, then a fresh server against empty state:
-//   rm -rf .storages && DSH_HOME=$(mktemp -d) node --experimental-transform-types \
-//     --import ./scripts/tspath-loader.ts apps/cli/src/bin.ts web --port 44285 \
-//     --workspace-root $(mktemp -d)
-// Run: node scripts/hero-composer-dom-continuity.mjs
-// (BASE_URL overrides the target; screenshots land in .artifacts/.)
-import { createRequire } from 'node:module'
-
-// playwright is a devDependency of apps/web only — resolve through its tree.
-const require = createRequire(new URL('../apps/web/package.json', import.meta.url))
-const { chromium } = require('playwright')
-
-const BASE = process.env.BASE_URL ?? 'http://127.0.0.1:44285'
-const SHOTS = new URL('../.artifacts/screenshots/0729-0357-hero-unify/', import.meta.url).pathname
-
-const browser = await chromium.launch()
-const page = await browser.newPage({ viewport: { width: 1280, height: 800 } })
-page.on('console', msg => { if (msg.type() === 'error') console.log('[console.error]', msg.text()) })
-page.on('pageerror', err => { console.log('[pageerror]', err.message) })
-
-await page.goto(BASE)
-await page.waitForSelector('textarea', { timeout: 20000 })
-await page.screenshot({ path: SHOTS + '01-cold-start.png' })
-
-const initial = await page.evaluate(() => {
-  const boxes = [...document.querySelectorAll('textarea')]
-  boxes.forEach((b, i) => { b.__heroMark = 'alive-' + i })
-  return boxes.map(b => ({ disabled: b.disabled, placeholder: b.placeholder }))
-})
-console.log('cold-start textareas:', JSON.stringify(initial))
-
-// Open the picker and create a workspace by name (typed-input flow). The name
-// must be unique per registry; keystrokes go through pressSequentially so the
-// dialog's React onChange enables the submit button.
-await page.getByRole('button', { name: 'Choose workspace' }).click()
-await page.getByText('Create a new workspace').click()
-await page.screenshot({ path: SHOTS + '03-create-form.png' })
-const nameBox = page.getByPlaceholder('Workspace name')
-await nameBox.click()
-const wsName = 'proj-' + Date.now().toString(36)
-await nameBox.pressSequentially(wsName, { delay: 30 })
-await page.locator('button:text-is("Create workspace")').click()
-
-// Wait for the composer to go live (placeholder flips, textarea enabled).
-await page.waitForFunction(() => {
-  const box = document.querySelector('textarea')
-  return box !== null && !box.disabled
-}, { timeout: 20000 })
-await page.screenshot({ path: SHOTS + '04-live.png' })
-
-const after = await page.evaluate(() => {
-  const boxes = [...document.querySelectorAll('textarea')]
-  return boxes.map(b => ({
-    mark: b.__heroMark ?? 'REMOUNTED',
-    disabled: b.disabled,
-    placeholder: b.placeholder,
-  }))
-})
-console.log('post-pick textareas:', JSON.stringify(after))
-
-// Type into the live composer.
-await page.locator('textarea').first().fill('hello from acceptance run')
-const typed = await page.evaluate(() => document.querySelector('textarea')?.value)
-console.log('typed value:', JSON.stringify(typed))
-await page.screenshot({ path: SHOTS + '05-typed.png' })
-
-const survived = after.length === 1 && after[0].mark === 'alive-0'
-console.log(survived
-  ? 'DOM-CONTINUITY: PASS (same textarea node across cold-start -> live)'
-  : 'DOM-CONTINUITY: FAIL ' + JSON.stringify(after))
-await browser.close()
-process.exit(survived && typed === 'hello from acceptance run' ? 0 : 1)

scripts/install-lefthook.spec.ts

@@ -610,7 +610,7 @@ describe('worktree-local Lefthook installer', { timeout: 15_000 }, () => {
 
     expect(result.status).toBe(1)
     expect(result.stderr).toContain('sibling dormant worktree config')
-    expect(result.stderr).toContain(linkedConfig)
+    expect(result.stderr).toContain(JSON.stringify(linkedConfig))
     expect(gitResult(fixture, fixture.main, ['config', '--get', 'extensions.worktreeConfig']).status).toBe(1)
     expect(gitResult(fixture, fixture.linked, ['config', '--get', 'core.hooksPath']).status).toBe(1)
     expect(git(fixture, fixture.main, ['config', '--file', linkedConfig, '--get', 'core.hooksPath'])).toBe(linkedHooks)

scripts/install.sh

@@ -1,425 +0,0 @@
-#!/bin/sh
-# dsh one-line installer.
-#
-#   curl -fsSL https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/master/scripts/install.sh | sh
-#
-# It clones the harness under ~/.dsh/source (the master clone at
-# ~/.dsh/source/master), adds a per-install staging worktree at
-# ~/.dsh/source/staging-<timestamp> on branch dsh-staging/<timestamp>, checks
-# host dependencies (git, Node, pnpm) and offers to install a missing pnpm, runs
-# `pnpm install`, points the stable `~/.dsh/source/current` symlink
-# at that staging worktree and symlinks `dsh` onto PATH at `current/bin/dsh`,
-# records your API credentials in the Harness home (`~/.dsh`) dsh reads at boot,
-# builds the repository artifacts, and launches the Web UI. Keeping every
-# checkout under ~/.dsh/source keeps successive
-# upgrades in one place instead of scattered sibling clones, and lets staging
-# worktrees share the master clone's object store. The PATH symlink resolves through
-# `current`, so an upgrade repoints one stable symlink instead of relinking PATH:
-# the `dsh` on PATH never moves and can never dangle.
-#
-# When run from inside an existing checkout (e.g. `sh scripts/install.sh` rather
-# than `curl ... | sh`) it never clones and never touches that working tree;
-# DSH_REF is ignored. Instead it *adopts* the checkout: `git rev-parse
-# --git-common-dir` resolves the repository behind it (for a linked worktree that
-# is the real clone, not the worktree), and a fresh staging worktree branched
-# from the checkout's HEAD lands in the source container beside `current`. The
-# container owns staging worktrees and `current`; the clone is discovered, not
-# owned, so an arbitrary clone (~/src/dsh) and a managed one converge on one
-# layout and stay upgradable. Adoption carries committed work only: the staging
-# worktree branches from HEAD, so uncommitted changes stay in the checkout.
-# Setting DSH_SOURCE to a different directory opts back into the normal
-# clone/worktree path.
-#
-# Adopting an arbitrary clone leaves the container not self-contained: its
-# staging worktrees hold an absolute gitdir pointer into that clone, so deleting
-# it breaks them. `git worktree list` in that clone is the record of which
-# worktrees depend on it.
-#
-# When run through `curl | sh` the script text arrives on stdin, so every
-# prompt and the final launch read the controlling terminal (/dev/tty) directly;
-# with no terminal the script prints the manual next steps instead.
-#
-# Overridable via environment:
-#   DSH_REF          branch or tag to clone/checkout    (default: master)
-#   DSH_REPO         clone URL                           (default: the GitHub repo)
-#   DSH_SOURCE       source container directory          (default: ~/.dsh/source)
-#   DSH_MASTER       master clone directory              (default: $DSH_SOURCE/master)
-#   DSH_CURRENT      stable symlink to the active worktree (default: $DSH_SOURCE/current)
-#   DSH_BIN_DIR      directory the `dsh` symlink lands in (default: ~/.local/bin)
-#   DSH_HOME         Harness home holding profiles and user patches (default: ~/.dsh)
-set -eu
-
-DSH_REF=${DSH_REF:-master}
-DSH_REPO=${DSH_REPO:-https://github.com/deepseek-ai/deepseek-harness-sdk.git}
-# DSH_SOURCE is the staging-worktree container and the default home of `current`.
-# DSH_MASTER names the main clone: clone mode defaults it inside DSH_SOURCE,
-# while adoption discovers an existing clone anywhere on disk. Remember whether
-# DSH_SOURCE was explicit so a different path selects clone mode.
-if [ -n "${DSH_SOURCE:-}" ]; then DSH_SOURCE_EXPLICIT=1; else DSH_SOURCE_EXPLICIT=0; fi
-DSH_SOURCE=${DSH_SOURCE:-$HOME/.dsh/source}
-DSH_MASTER=${DSH_MASTER:-$DSH_SOURCE/master}
-# The stable symlink the PATH launcher resolves through: PATH/dsh ->
-# current/bin/dsh -> <staging>/bin/dsh. Installs and upgrades repoint `current`;
-# the PATH target remains current/bin/dsh.
-DSH_CURRENT=${DSH_CURRENT:-$DSH_SOURCE/current}
-DSH_BIN_DIR=${DSH_BIN_DIR:-$HOME/.local/bin}
-# One UTC basic timestamp names this install's staging branch and worktree.
-DSH_STAMP=$(date -u +%Y%m%dT%H%M%SZ)
-DSH_STAGING_BRANCH=dsh-staging/$DSH_STAMP
-DSH_STAGING=$DSH_SOURCE/staging-$DSH_STAMP
-
-# --- path helpers ---------------------------------------------------------------
-# Every path comparison below runs on physical paths. Git always reports resolved
-# paths, so comparing one against an unresolved path disagrees whenever a symlink
-# sits anywhere above the checkout — a symlinked home directory is enough, and
-# macOS reaches every mktemp path that way through /var -> private/var. The
-# mismatch silently misclassifies an existing managed install as a foreign clone
-# and builds a second container beside the real one.
-# `git rev-parse --path-format=absolute` would do this, but it needs git 2.31+.
-#
-# A not-yet-created directory (the container on a fresh install) has no physical
-# path. Falling back here rather than at each call site keeps every caller a
-# plain assignment, so no site can compare against an empty path by forgetting
-# its own fallback.
-resolve_dir() { CDPATH= cd -- "$1" 2>/dev/null && pwd -P || printf '%s\n' "$1"; }
-
-# --- in-repo detection ---------------------------------------------------------
-# Under `curl ... | sh` the script text arrives on stdin, so $0 is the shell
-# name and no file path resolves; running a checked-out copy (`sh
-# scripts/install.sh`) makes $0 the script file. When $0 is a readable file whose
-# parent is a scripts/ dir inside a real dsh checkout (bin/dsh launcher present),
-# this is in-repo mode: never clone, never touch that working tree. An explicit
-# DSH_SOURCE pointing elsewhere opts back into the clone/worktree path.
-IN_REPO=0
-DSH_CHECKOUT=''
-if [ -f "$0" ]; then
-  _self_dir=$(resolve_dir "$(dirname -- "$0")")
-  if [ -n "$_self_dir" ]; then
-    # Physical without its own resolve_dir: dirname is textual, so trimming a
-    # resolved path leaves one. The comparison below depends on that.
-    _repo_root=$(dirname -- "$_self_dir")
-    if [ "$(basename -- "$_self_dir")" = scripts ] \
-      && [ -x "$_repo_root/bin/dsh" ] && [ -f "$_repo_root/scripts/install.sh" ]; then
-      # Compare the explicit DSH_SOURCE physically: an unresolved but equivalent
-      # path must still count as "the caller meant this checkout".
-      _src_resolved=$(resolve_dir "$DSH_SOURCE")
-      if [ "$DSH_SOURCE_EXPLICIT" = 0 ] || [ "$_src_resolved" = "$_repo_root" ]; then
-        IN_REPO=1
-        DSH_CHECKOUT=$_repo_root
-      fi
-    fi
-  fi
-fi
-
-# --- terminal-aware prompting --------------------------------------------------
-# stdin is the piped script, so read the controlling terminal for input.
-if { true </dev/tty; } 2>/dev/null; then
-  HAS_TTY=1
-  # Restore terminal echo on exit or interrupt: ask_secret disables echo between
-  # its stty toggles, and dash (a common `sh`) does not run an EXIT trap when the
-  # shell is killed by a signal, so the fatal signals need their own handler. A
-  # successful run ends in exec, which replaces this process and drops the traps.
-  trap 'stty echo </dev/tty 2>/dev/null || true' EXIT
-  trap 'stty echo </dev/tty 2>/dev/null || true; exit 130' INT TERM HUP
-else
-  HAS_TTY=0
-fi
-
-# Colour only when writing to a terminal.
-if [ -t 1 ]; then
-  B=$(printf '\033[1m'); DIM=$(printf '\033[2m'); RED=$(printf '\033[31m')
-  GRN=$(printf '\033[32m'); YEL=$(printf '\033[33m'); RST=$(printf '\033[0m')
-else
-  B=''; DIM=''; RED=''; GRN=''; YEL=''; RST=''
-fi
-
-info()  { printf '%s==>%s %s\n' "$GRN" "$RST" "$1"; }
-step()  { printf '\n%s==>%s %s%s%s\n' "$GRN" "$RST" "$B" "$1" "$RST"; }
-warn()  { printf '%s warn%s %s\n' "$YEL" "$RST" "$1" >&2; }
-die()   { printf '%serror%s %s\n' "$RED" "$RST" "$1" >&2; exit 1; }
-
-# ask PROMPT [DEFAULT] -> answer on stdout (plain-text line).
-ask() {
-  [ "$HAS_TTY" = 1 ] || die "no terminal available for input; re-run in an interactive shell"
-  printf '%s%s%s ' "$B" "$1" "$RST" >/dev/tty
-  IFS= read -r _ans </dev/tty || _ans=''
-  [ -n "$_ans" ] || _ans=${2:-}
-  printf '%s' "$_ans"
-}
-
-# ask_secret PROMPT -> answer on stdout, with terminal echo suppressed.
-ask_secret() {
-  [ "$HAS_TTY" = 1 ] || die "no terminal available for input; re-run in an interactive shell"
-  printf '%s%s%s ' "$B" "$1" "$RST" >/dev/tty
-  stty -echo </dev/tty 2>/dev/null || true
-  IFS= read -r _sec </dev/tty || _sec=''
-  stty echo </dev/tty 2>/dev/null || true
-  printf '\n' >/dev/tty
-  printf '%s' "$_sec"
-}
-
-# confirm PROMPT [Y] -> exit 0 on yes. Default is no unless second arg is "Y".
-confirm() {
-  _def=${2:-N}
-  if [ "$HAS_TTY" != 1 ]; then
-    [ "$_def" = Y ]  # non-interactive: take the default
-    return
-  fi
-  if [ "$_def" = Y ]; then _hint='[Y/n]'; else _hint='[y/N]'; fi
-  printf '%s%s%s %s ' "$B" "$1" "$RST" "$_hint" >/dev/tty
-  IFS= read -r _r </dev/tty || _r=''
-  [ -n "$_r" ] || _r=$_def
-  case "$_r" in [yY]|[yY][eE][sS]) return 0 ;; *) return 1 ;; esac
-}
-
-printf '%s\n' "${B}DeepSeek Harness — dsh installer${RST}"
-if [ "$IN_REPO" = 1 ]; then
-  printf '%scheckout %s%s\n' "$DIM" "$DSH_CHECKOUT" "$RST"
-else
-  printf '%smaster %s @ %s%s\n' "$DIM" "$DSH_MASTER" "$DSH_REF" "$RST"
-  printf '%sstaging %s%s\n' "$DIM" "$DSH_STAGING" "$RST"
-  printf '%scurrent %s%s\n' "$DIM" "$DSH_CURRENT" "$RST"
-fi
-
-# --- 1. dependency check -------------------------------------------------------
-step "Checking dependencies"
-
-command -v git >/dev/null 2>&1 || die "git is required but not found. Install git, then re-run."
-info "git ... ok"
-
-# Node ^22.19.0 || >=24.0.0 (see the root package.json "engines" field).
-node_ok() {
-  command -v node >/dev/null 2>&1 || return 1
-  _v=$(node -v 2>/dev/null) || return 1
-  _v=${_v#v}
-  _major=${_v%%.*}
-  _rest=${_v#*.}
-  _minor=${_rest%%.*}
-  case "$_major" in ''|*[!0-9]*) return 1 ;; esac
-  case "$_minor" in ''|*[!0-9]*) _minor=0 ;; esac
-  [ "$_major" -ge 24 ] && return 0
-  [ "$_major" -eq 22 ] && [ "$_minor" -ge 19 ] && return 0
-  return 1
-}
-if node_ok; then
-  info "node $(node -v) ... ok"
-else
-  if command -v node >/dev/null 2>&1; then
-    die "Node $(node -v) is unsupported. dsh needs ^22.19.0 || >=24.0.0 — upgrade Node, then re-run."
-  fi
-  die "Node is required but not found. Install Node ^22.19.0 || >=24, then re-run."
-fi
-
-# pnpm is the only dependency we offer to install for you.
-if command -v pnpm >/dev/null 2>&1; then
-  info "pnpm $(pnpm --version) ... ok"
-else
-  warn "pnpm is not installed."
-  if confirm "Install pnpm now?" Y; then
-    if command -v corepack >/dev/null 2>&1 && corepack enable pnpm >/dev/null 2>&1; then
-      info "enabled pnpm via corepack"
-    elif command -v npm >/dev/null 2>&1 && npm install -g pnpm >/dev/null 2>&1; then
-      info "installed pnpm via npm"
-    else
-      die "could not install pnpm automatically. Install it (https://pnpm.io/installation), then re-run."
-    fi
-    command -v pnpm >/dev/null 2>&1 || die "pnpm still not on PATH after install. Open a new shell, then re-run."
-  else
-    die "pnpm is required. Install it (https://pnpm.io/installation), then re-run."
-  fi
-fi
-
-# --- 2. resolve the repository and lay out the staging worktree ---------------
-# The source container owns staging worktrees and `current`; the repository is
-# *discovered*, not owned. A curl install discovers it by cloning to $DSH_MASTER;
-# in-repo adoption discovers it from the checkout. Both then run one shared
-# worktree/exclude/lock path, so an arbitrary clone and a managed install
-# converge on the same layout.
-#
-# REPO_COMMON is the shared git directory every worktree of the repository
-# points at; REPO_ROOT is the working tree that owns it (the master clone).
-REPO_COMMON=''
-REPO_ROOT=''
-
-if [ "$IN_REPO" = 1 ]; then
-  step "Using existing checkout at $DSH_CHECKOUT"
-  info "running from inside the repo — never cloning, and DSH_REF is ignored"
-
-  # Resolve the repository behind the checkout. --git-common-dir returns the
-  # SHARED git dir, so a linked worktree resolves to the real clone rather than
-  # itself; it is relative for a plain clone, so anchor it before resolving.
-  # Require the resolved git dir to exist: resolve_dir echoes its argument back
-  # for a missing path, so test the directory rather than the returned string.
-  if _common=$(git -C "$DSH_CHECKOUT" rev-parse --git-common-dir 2>/dev/null) && [ -n "$_common" ]; then
-    case "$_common" in /*) ;; *) _common=$DSH_CHECKOUT/$_common ;; esac
-    [ -d "$_common" ] && REPO_COMMON=$(resolve_dir "$_common")
-  fi
-  [ -n "$REPO_COMMON" ] || die "$DSH_CHECKOUT is not a git repository — cannot adopt it."
-  REPO_ROOT=$(dirname -- "$REPO_COMMON")
-
-  # Reuse the container when the repository already lives inside it (the normal
-  # managed install re-running its own script); otherwise treat that clone as
-  # its own master and keep worktrees in the default container.
-  _src_resolved=$(resolve_dir "$DSH_SOURCE")
-  case "$REPO_ROOT/" in
-    "$_src_resolved"/*) info "repository $REPO_ROOT is already inside $DSH_SOURCE" ;;
-    *) info "adopting clone $REPO_ROOT as its own master" ;;
-  esac
-  DSH_MASTER=$REPO_ROOT
-else
-  step "Fetching source into $DSH_MASTER"
-  if [ -d "$DSH_MASTER/.git" ]; then
-    info "existing master clone found — updating"
-    git -C "$DSH_MASTER" fetch origin "$DSH_REF"
-    # Reset the master checkout to the freshly fetched tip. FETCH_HEAD (not
-    # origin/<ref>) so this resolves for a tag as well as a branch, and -B makes
-    # the re-run idempotent whether or not DSH_REF changed since the last install.
-    git -C "$DSH_MASTER" checkout -q -B "$DSH_REF" FETCH_HEAD
-  else
-    mkdir -p "$DSH_SOURCE"
-    git clone --branch "$DSH_REF" "$DSH_REPO" "$DSH_MASTER"
-  fi
-  # Physical on both branches: REPO_ROOT is compared against resolved paths
-  # below, and REPO_COMMON stays symmetric with it so neither can be read as
-  # carrying a different kind of path.
-  REPO_COMMON=$(resolve_dir "$DSH_MASTER/.git")
-  REPO_ROOT=$(resolve_dir "$DSH_MASTER")
-fi
-
-step "Adding staging worktree at $DSH_STAGING"
-[ -e "$DSH_STAGING" ] && die "staging path $DSH_STAGING already exists — remove it or set DSH_SOURCE elsewhere, then re-run."
-mkdir -p "$DSH_SOURCE"
-# The staging worktree owns the branch dsh runs from; the repository stays as
-# the fetch/upgrade base and is never a launcher target. A clone install
-# branches from the ref it just fetched; adoption branches from the checkout's
-# HEAD so the contributor's committed work is what runs.
-if [ "$IN_REPO" = 1 ]; then
-  git -C "$DSH_CHECKOUT" worktree add -b "$DSH_STAGING_BRANCH" "$DSH_STAGING" HEAD
-else
-  git -C "$DSH_MASTER" worktree add -b "$DSH_STAGING_BRANCH" "$DSH_STAGING" FETCH_HEAD 2>/dev/null \
-    || git -C "$DSH_MASTER" worktree add -b "$DSH_STAGING_BRANCH" "$DSH_STAGING" HEAD
-fi
-# Exclude the per-worktree merge lock in the shared git dir's info/exclude,
-# which every linked worktree inherits.
-_exclude="$REPO_COMMON/info/exclude"
-if [ -f "$_exclude" ] && ! grep -qxF '.agents/merge.lock' "$_exclude" 2>/dev/null; then
-  printf '.agents/merge.lock\n' >>"$_exclude"
-fi
-mkdir -p "$DSH_STAGING/.agents"
-: >"$DSH_STAGING/.agents/merge.lock"
-
-# --- 3. install dependencies (no build; the launcher runs from source) --------
-step "Installing dependencies with pnpm (this can take a while)"
-( cd "$DSH_STAGING" && pnpm install )
-
-[ -x "$DSH_STAGING/bin/dsh" ] || die "launcher $DSH_STAGING/bin/dsh missing after install — is DSH_REF a branch that ships apps/cli?"
-
-# --- 4. put `dsh` on PATH ------------------------------------------------------
-# Every install goes through a stable `current` symlink so an upgrade repoints
-# one symlink (current -> new worktree) and the PATH launcher never moves:
-# PATH/dsh -> current/bin/dsh -> <staging>/bin/dsh.
-step "Linking dsh into $DSH_BIN_DIR"
-mkdir -p "$DSH_BIN_DIR"
-# The launcher must resolve to a staging worktree, never to the repository
-# itself: an upgrade repoints `current`, so aliasing it onto the master clone
-# would make every upgrade rewrite the fetch/upgrade base. Compare physical
-# paths — a symlinked or unresolved path would slip past a string compare.
-_staging_resolved=$(resolve_dir "$DSH_STAGING")
-[ "$_staging_resolved" = "$REPO_ROOT" ] \
-  && die "refusing to point $DSH_CURRENT at the repository $REPO_ROOT — the launcher must resolve to a staging worktree."
-# Point `current` at this staging worktree with `ln -sfn`: -f replaces an
-# existing `current` (re-run or upgrade) and -n stops `ln` from dereferencing
-# an existing symlink-to-directory and dropping the new link *inside* the old
-# worktree. `mv` is unusable here — BSD/macOS `mv` follows the existing dir
-# symlink the same way. The swap is one unlink+symlink pair on a local fs; the
-# installer holds no other process racing this path.
-ln -sfn "$DSH_STAGING" "$DSH_CURRENT"
-info "pointed $DSH_CURRENT -> $DSH_STAGING"
-DSH_LAUNCH_TARGET=$DSH_CURRENT/bin/dsh
-ln -sf "$DSH_LAUNCH_TARGET" "$DSH_BIN_DIR/dsh"
-info "linked $DSH_BIN_DIR/dsh -> $DSH_LAUNCH_TARGET"
-
-case ":$PATH:" in
-  *":$DSH_BIN_DIR:"*) ON_PATH=1 ;;
-  *) ON_PATH=0 ;;
-esac
-if [ "$ON_PATH" = 0 ]; then
-  warn "$DSH_BIN_DIR is not on your PATH."
-  _line="export PATH=\"$DSH_BIN_DIR:\$PATH\""
-  _rc=''
-  _sh=${SHELL:-}  # SHELL may be unset; word-removal on an unset var trips set -u under dash.
-  case "${_sh##*/}" in
-    zsh)  _rc="$HOME/.zshrc" ;;
-    bash) _rc="$HOME/.bashrc" ;;
-  esac
-  if [ -n "$_rc" ] && [ -f "$_rc" ] && grep -qF "$_line" "$_rc" 2>/dev/null; then
-    info "$_rc already exports $DSH_BIN_DIR — open a new shell to pick it up"
-  elif [ -n "$_rc" ] && confirm "Add it to $_rc?" Y; then
-    printf '\n# Added by the dsh installer\n%s\n' "$_line" >>"$_rc"
-    info "updated $_rc — run 'source $_rc' or open a new shell to pick it up"
-  else
-    warn "add this line to your shell profile yourself:"
-    printf '    %s\n' "$_line"
-  fi
-fi
-
-# --- 5. credentials ------------------------------------------------------------
-# Mirror app-boot's resolveDshHome precedence ($DSH_HOME, else ~/.dsh) so creds land where dsh reads them.
-if [ -n "${DSH_HOME:-}" ]; then
-  CONF="$DSH_HOME"
-else
-  CONF="$HOME/.dsh"
-fi
-ENV_FILE="$CONF/.env"
-
-step "Configuring credentials"
-if [ -f "$ENV_FILE" ] && grep -q '^DEEPSEEK_API_KEY=' "$ENV_FILE" 2>/dev/null; then
-  info "DEEPSEEK_API_KEY already set in $ENV_FILE"
-  if ! confirm "Replace it?" N; then
-    SKIP_CREDS=1
-  fi
-fi
-if [ "${SKIP_CREDS:-0}" != 1 ]; then
-  if [ "$HAS_TTY" = 1 ]; then
-    API_KEY=$(ask_secret "DeepSeek API key (input hidden):")
-    if [ -z "$API_KEY" ]; then
-      warn "no key entered — skipping. Set DEEPSEEK_API_KEY in $ENV_FILE before using dsh."
-    else
-      BASE_URL=$(ask "DeepSeek base URL (optional, Enter to skip):")
-      mkdir -p "$CONF"
-      # The installer owns exactly the two DEEPSEEK_* lines; any other lines the
-      # user keeps in this .env are preserved. The rewrite happens in a subshell
-      # so umask 077 (which closes the create-time permission race) does not leak
-      # into the exec'd dsh, and lands atomically via a same-dir temp + mv.
-      _tmp="$ENV_FILE.dsh.$$"
-      (
-        umask 077
-        if [ -f "$ENV_FILE" ]; then
-          grep -v -e '^DEEPSEEK_API_KEY=' -e '^DEEPSEEK_BASE_URL=' "$ENV_FILE" >"$_tmp" || true
-        else
-          : >"$_tmp"
-        fi
-        printf 'DEEPSEEK_API_KEY=%s\n' "$API_KEY" >>"$_tmp"
-        if [ -n "$BASE_URL" ]; then printf 'DEEPSEEK_BASE_URL=%s\n' "$BASE_URL" >>"$_tmp"; fi
-      )
-      mv "$_tmp" "$ENV_FILE"
-      chmod 600 "$ENV_FILE" 2>/dev/null || true
-      info "wrote $ENV_FILE"
-    fi
-  else
-    warn "no terminal for credential input — set DEEPSEEK_API_KEY in $ENV_FILE before using dsh."
-  fi
-fi
-
-# --- 6. build and launch the Web interface -------------------------------------
-step "Done"
-if [ "$HAS_TTY" = 1 ]; then
-  step "Building DeepSeek Harness for Web UI"
-  ( cd "$DSH_STAGING" && pnpm run build )
-  info "launching Web UI — run 'dsh web' anytime to start again"
-  exec "$DSH_BIN_DIR/dsh" web </dev/tty
-else
-  info "install complete. Build and start the Web UI with:"
-  printf '    (cd %s && pnpm run build)\n' "$DSH_STAGING"
-  printf '    %s web\n' "$DSH_BIN_DIR/dsh"
-fi

scripts/jsdoc.ts

@@ -1,6 +1,6 @@
 /**
  * Shared JSDoc parsing and completeness checks for the Cordis, persistence,
- * and config catalogs and the export-surface gate.
+ * and config catalogs and the exported-API gate.
  */
 
 import ts from 'typescript'
@@ -124,7 +124,7 @@ export function parseTags(raw: string): { params: Map<string, string>; returns:
  * binding-pattern parameters, and reject stale tags. Exempt parameters may
  * still be documented.
  * @param where - the offender label violations open with, e.g. `event 'x' (file:1)`.
- * @param surface - surface noun used in binding-pattern diagnostics.
+ * @param apiKind - API kind used in binding-pattern diagnostics.
  * @param parameters - the declaration's parameter list.
  * @param tags - the parsed `@param` name→description map from parseTags.
  * @param sf - source file used to render binding patterns.
@@ -133,7 +133,7 @@ export function parseTags(raw: string): { params: Map<string, string>; returns:
  */
 export function checkParams(
   where: string,
-  surface: string,
+  apiKind: string,
   parameters: readonly ts.ParameterDeclaration[],
   tags: Map<string, string>,
   sf: ts.SourceFile,
@@ -142,7 +142,7 @@ export function checkParams(
 ): void {
   for (const p of parameters) {
     if (!ts.isIdentifier(p.name)) {
-      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${surface} surface needs simple identifier parameters so @param can name them.`)
+      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`)
       continue
     }
     if (isExempt(p)) continue

scripts/lint-rule-fingerprint.spec.ts

@@ -15,7 +15,7 @@ interface Profile {
 // A one-time audit against eslint.config.mjs blob 696b08282885296830189fdafe7051a356806fc2
 // mapped @typescript-eslint/* to typescript/* and four extension rules to their
 // Oxlint core equivalents. These fingerprints pin the resulting repository
-// contract; they do not re-evaluate that deleted baseline or track its preset.
+// snapshot; they do not re-evaluate that deleted baseline or track its preset.
 const profiles = {
   source: {
     count: 88,
@@ -84,7 +84,7 @@ describe('Oxlint repository rule fingerprint', () => {
   }
   const overrides: readonly unknown[] = parsed.overrides
 
-  it('pins the complete override shape', () => {
+  it('pins every override field', () => {
     expect(overrides).toHaveLength(8)
   })
 

scripts/oxlint-contract.spec.ts

@@ -249,7 +249,7 @@ export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 +
         rm(configPath, { force: true }),
       ])
     }
-  })
+  }, 20_000)
 
   it('accepts an ignored-only staged selection', () => {
     const result = runOxlint([

scripts/package-invariants.spec.ts

@@ -49,7 +49,7 @@ function fixture(options: {
     },
     files: ['lib/index.js', 'lib/invariant.js'],
     peerDependencies: options.invariantDependency === false ? {} : {
-      '@deepseek-ai/dsh-invariants': '^0.0.1',
+      '@deepseek-ai/dsh-invariants': 'workspace:^',
     },
     devDependencies: options.invariantDependency === false ? {} : {
       '@deepseek-ai/dsh-invariants': 'workspace:^',

scripts/package-invariants.ts

@@ -19,7 +19,7 @@ interface PackageManifest {
   devDependencies?: Record<string, string>
 }
 
-/** One package and the files participating in its invariant publication contract. */
+/** One package and the files participating in its invariant publication rules. */
 export interface PackageInvariantOwner {
   readonly dir: string
   readonly manifestPath: string
@@ -53,7 +53,7 @@ export function packageInvariantOwners(root: string): PackageInvariantOwner[] {
     })
 }
 
-/** Return all violations of the package-invariant companion contract. */
+/** Return all violations of the package-invariant companion rules. */
 export function collectPackageInvariantViolations(root: string): PackageInvariantViolation[] {
   const violations: PackageInvariantViolation[] = []
   for (const owner of packageInvariantOwners(root)) {
@@ -96,11 +96,11 @@ function checkManifest(
     addViolation(violations, owner.manifestPath, 'files must publish lib/invariant.js')
   }
   if (owner.packageName === '@deepseek-ai/dsh-invariants') return
-  if (manifest.peerDependencies?.['@deepseek-ai/dsh-invariants'] !== '^0.0.1') {
+  if (manifest.peerDependencies?.['@deepseek-ai/dsh-invariants'] !== 'workspace:^') {
     addViolation(
       violations,
       owner.manifestPath,
-      '@deepseek-ai/dsh-invariants must be a ^0.0.1 peerDependency',
+      '@deepseek-ai/dsh-invariants must be a workspace:^ peerDependency',
     )
   }
   if (manifest.devDependencies?.['@deepseek-ai/dsh-invariants'] !== 'workspace:^') {

scripts/prepare-ci-bubblewrap.sh

@@ -19,7 +19,7 @@ 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"
+curl --fail --silent --show-error --location --retry 3 --retry-all-errors --output "$archive" "$BUBBLEWRAP_URL"
 printf '%s  %s\n' "$BUBBLEWRAP_SHA256" "$archive" | sha256sum --check --status
 mkdir -p "$root"
 dpkg-deb --extract "$archive" "$root"

scripts/project-doc-site.spec.ts

@@ -104,7 +104,7 @@ describe('rewriteMarkdown', () => {
       repositoryRef: 'abc123',
     })).toBe(
       '[B](./reference/b.md#part) '
-      + '[source](https://github.com/deepseek-ai/deepseek-harness-sdk/blob/abc123/packages/tool.ts#L2) '
+      + '[source](https://github.com/deepseek-ai/deepseek-harness/blob/abc123/packages/tool.ts#L2) '
       + '[web](https://example.com)\n',
     )
   })
@@ -130,7 +130,7 @@ describe('rewriteMarkdown', () => {
       pages,
       repoRoot: root,
       repositoryRef: 'abc123',
-    })).toBe('![logo](https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/abc123/packages/logo.svg)\n')
+    })).toBe('![logo](https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/abc123/packages/logo.svg)\n')
   })
 
   it('hands an image to the placer and uses the URL it returns', () => {
@@ -209,7 +209,7 @@ describe('rewriteMarkdown', () => {
       repositoryRef: 'abc123',
     })).toBe(
       '[title](./reference/b.md "b.md") '
-      + '[escaped](https://github.com/deepseek-ai/deepseek-harness-sdk/blob/abc123/docs/x(y).md)\n',
+      + '[escaped](https://github.com/deepseek-ai/deepseek-harness/blob/abc123/docs/x(y).md)\n',
     )
   })
 

scripts/project-doc-site.ts

@@ -15,7 +15,7 @@ import { gfm } from 'micromark-extension-gfm'
 import type { Nodes } from 'mdast'
 import { docsPages, type DocsLocale, type DocsPage } from '../website/docs.ts'
 
-const REPOSITORY_URL = 'https://github.com/deepseek-ai/deepseek-harness-sdk'
+const REPOSITORY_URL = 'https://github.com/deepseek-ai/deepseek-harness'
 const root = resolve(import.meta.dirname, '..')
 const generatedRoot = resolve(root, 'website/.generated')
 
@@ -209,7 +209,7 @@ function githubTarget(
   image: boolean,
 ): string {
   const path = repoPath(absPath, repoRoot)
-  if (image) return `https://raw.githubusercontent.com/deepseek-ai/deepseek-harness-sdk/${repositoryRef}/${path}${suffix}`
+  if (image) return `https://raw.githubusercontent.com/deepseek-ai/deepseek-harness/${repositoryRef}/${path}${suffix}`
   const kind = lstatSync(absPath).isDirectory() ? 'tree' : 'blob'
   const lineSuffix = line === undefined ? suffix : `#L${line}`
   return `${REPOSITORY_URL}/${kind}/${repositoryRef}/${path}${lineSuffix}`

scripts/publish-npm-baseline.ts

@@ -258,7 +258,9 @@ class WorkspacePackageSet {
       const name = expectString(manifest, 'name', manifestPath)
       const version = expectString(manifest, 'version', manifestPath)
       const isVendored = manifestPath.startsWith('vendor/')
-      if (!isVendored && !name.startsWith('@deepseek-ai/')) {
+      // Vendored packages are rescoped too (vendor/README.md), so publication
+      // never carries an upstream name that would squat it on the registry.
+      if (!name.startsWith('@deepseek-ai/')) {
         throw new Error(`${manifestPath} must name an @deepseek-ai package`)
       }
       if (name === '@deepseek-ai/dsh-root') {

scripts/release/bump.ts

@@ -0,0 +1,398 @@
+/**
+ * Bump one release family's version and commit it, so the published version is
+ * readable from the repository rather than derived inside CI
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ *
+ * The dsh family shares one version across its members and the workspace root:
+ * `major`, `minor`, `patch`, or an explicit `x.y.z` (including a prerelease such
+ * as `0.0.1-rc.1`). The vendored family has one version line per package and
+ * publishes only what changed since that package's own `vendor-<package>-v*`
+ * tag, which is the record of the commit it last published from.
+ *
+ * The version lands in the manifests, the lockfile follows, and a human creates
+ * the tag after the commit merges. CI never writes to the repository.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join, matchesGlob } from 'node:path'
+import { parseArgs } from 'node:util'
+import { releaseFamily, type ReleaseFamily, type ReleaseMember } from './families.ts'
+import { attempt, capture, isEntry } from './process.ts'
+
+/** Files npm publishes whether or not `files` lists them. */
+const ALWAYS_PUBLISHED = ['package.json', 'README*', 'LICENSE*', 'LICENCE*'] as const
+
+/**
+ * Inputs that decide what a built payload contains. A package whose `files`
+ * selects `lib/` publishes build output that git does not track, so a change to
+ * the sources or the build configuration changes the tarball while no published
+ * path appears in the diff.
+ */
+const BUILD_INPUTS = ['src/**', 'tsconfig*.json', 'tsdown.config.*', 'build.config.*'] as const
+
+/** Release types the dsh family accepts besides an explicit version. */
+const RELEASE_TYPES = ['major', 'minor', 'patch'] as const
+
+/** The workspace root manifest, which carries the dsh family's version. */
+const ROOT_MANIFEST = 'package.json'
+
+/** One manifest the bump rewrites, and the tag its new version will carry. */
+interface PlannedVersion {
+  /** Repository-relative manifest path. */
+  readonly manifestPath: string
+  /** Label for the log line. */
+  readonly label: string
+  /** The version the manifest currently carries. */
+  readonly from: string
+  /** The version to write. */
+  readonly to: string
+  /** The tag this version publishes from, or undefined for the workspace root. */
+  readonly tag: string | undefined
+}
+
+/**
+ * Split a version into its release numbers, discarding any prerelease segment.
+ * @param version - the current version.
+ * @returns Major, minor, and patch.
+ */
+function releaseNumbers(version: string): [number, number, number] {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/.exec(version)
+  if (match === null) throw new Error(`cannot read release numbers from version ${version}`)
+  return [Number(match[1]), Number(match[2]), Number(match[3])]
+}
+
+/**
+ * Order two versions by their release numbers alone.
+ * @param left - one version.
+ * @param right - the other version.
+ * @returns Negative when `left` is lower, positive when higher, zero when equal.
+ */
+function compareReleaseNumbers(left: string, right: string): number {
+  const [leftMajor, leftMinor, leftPatch] = releaseNumbers(left)
+  const [rightMajor, rightMinor, rightPatch] = releaseNumbers(right)
+  return leftMajor - rightMajor || leftMinor - rightMinor || leftPatch - rightPatch
+}
+
+/**
+ * The prerelease segment of a version, or undefined when it has none.
+ * @param version - the version to read.
+ * @returns The segment after the first `-`.
+ */
+function prereleaseOf(version: string): string | undefined {
+  const index = version.indexOf('-')
+  return index === -1 ? undefined : version.slice(index + 1)
+}
+
+/**
+ * Order two versions by semver precedence.
+ *
+ * Git's version sort cannot stand in for this: `--sort=v:refname` places
+ * `4.0.1-rc.1` above `4.0.1`, while semver gives a prerelease lower precedence
+ * than the release it precedes. Prerelease identifiers compare field by field,
+ * numeric fields numerically, so `rc.10` outranks `rc.1`.
+ * @param left - one version.
+ * @param right - the other version.
+ * @returns Negative when `left` is lower, positive when higher, zero when equal.
+ */
+export function compareVersions(left: string, right: string): number {
+  const numbers = compareReleaseNumbers(left, right)
+  if (numbers !== 0) return numbers
+  const leftPre = prereleaseOf(left)
+  const rightPre = prereleaseOf(right)
+  if (leftPre === undefined || rightPre === undefined) {
+    if (leftPre === rightPre) return 0
+    return leftPre === undefined ? 1 : -1
+  }
+  const leftFields = leftPre.split('.')
+  const rightFields = rightPre.split('.')
+  for (let index = 0; index < Math.max(leftFields.length, rightFields.length); index += 1) {
+    const leftField = leftFields[index]
+    const rightField = rightFields[index]
+    // A shorter identifier list has lower precedence when all its fields match.
+    if (leftField === undefined) return -1
+    if (rightField === undefined) return 1
+    if (leftField === rightField) continue
+    const leftNumeric = /^\d+$/.test(leftField)
+    const rightNumeric = /^\d+$/.test(rightField)
+    if (leftNumeric && rightNumeric) return Number(leftField) - Number(rightField)
+    // Numeric fields have lower precedence than alphanumeric ones.
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1
+    return leftField < rightField ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * The next dsh version.
+ * @param current - the family's current shared version.
+ * @param request - `major`, `minor`, `patch`, or an explicit version.
+ * @returns The target version.
+ */
+function nextSharedVersion(current: string, request: string): string {
+  if (!RELEASE_TYPES.includes(request as typeof RELEASE_TYPES[number])) {
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(request)) {
+      throw new Error(`usage: release:dsh <major|minor|patch|x.y.z>, got ${request}`)
+    }
+    return request
+  }
+  const [major, minor, patch] = releaseNumbers(current)
+  if (request === 'major') return `${String(major + 1)}.0.0`
+  if (request === 'minor') return `${String(major)}.${String(minor + 1)}.0`
+  return `${String(major)}.${String(minor)}.${String(patch + 1)}`
+}
+
+/**
+ * The version a vendored package publishes next.
+ *
+ * The baseline is the higher of the manifest version and the last published
+ * version: a vendor re-sync restores upstream's version, which is lower than
+ * what this repository already published, and incrementing that would name a
+ * version the registry already carries.
+ *
+ * A prerelease does not consume its own release numbers. Publishing
+ * `4.0.1-rc.1` leaves `4.0.1` free, so the next stable version is `4.0.1`
+ * rather than `4.0.2`, and a second prerelease keeps those numbers too.
+ * @param current - the package's manifest version.
+ * @param published - the version its newest tag names, when it has one.
+ * @param prerelease - prerelease identifier to append, for a rehearsal publication.
+ * @returns The target version.
+ */
+export function nextVendorVersion(
+  current: string,
+  published: string | undefined,
+  prerelease?: string,
+): string {
+  const ahead = published !== undefined && compareReleaseNumbers(published, current) > 0
+  const baseline = ahead ? published : current
+  const [major, minor, patch] = releaseNumbers(baseline)
+  // Reuse the numbers when the published version that set them is a prerelease
+  // of them; increment when a stable release already holds them.
+  const reuse = ahead && published.includes('-')
+  const numbers = reuse
+    ? `${String(major)}.${String(minor)}.${String(patch)}`
+    : `${String(major)}.${String(minor)}.${String(patch + 1)}`
+  return prerelease === undefined ? numbers : `${numbers}-${prerelease}`
+}
+
+/**
+ * Whether a repository-relative path reaches the member's published payload.
+ * @param member - the member the path belongs to.
+ * @param path - repository-relative path.
+ * @returns True when `files`, npm's always-published set, or a build input selects it.
+ */
+export function reachesPayload(member: ReleaseMember, path: string): boolean {
+  const relative = path.slice(member.directory.length + 1)
+  const files = member.manifest.files
+  const selected = Array.isArray(files) ? files.filter((entry): entry is string => typeof entry === 'string') : []
+  const built = selected.some(pattern => pattern.startsWith('lib'))
+  const patterns = [...ALWAYS_PUBLISHED, ...selected, ...built ? BUILD_INPUTS : []]
+  return patterns.some(pattern =>
+    matchesGlob(relative, pattern) || matchesGlob(relative, `${pattern}/**`) || relative === pattern)
+}
+
+/**
+ * The newest version a member published, read from its tags.
+ * @param family - the member's family.
+ * @param member - the member.
+ * @returns The version, or undefined when the member never published.
+ */
+function lastPublishedVersion(family: ReleaseFamily, member: ReleaseMember): string | undefined {
+  const prefix = family.tagPrefixFor(member)
+  const versions = capture('git', ['tag', '--list', `${prefix}*`])
+    .split('\n').filter(line => line !== '').map(tag => tag.slice(prefix.length))
+  if (versions.length === 0) return undefined
+  return versions.reduce((newest, candidate) => compareVersions(candidate, newest) > 0 ? candidate : newest)
+}
+
+/**
+ * Confirm the registry carries the version a tag names.
+ *
+ * A tag is a commit pointer, not proof of publication: a tag pushed for a
+ * publication that then failed would otherwise read as "already published" and
+ * skip the package indefinitely. Querying a private package needs credentials,
+ * so an unauthenticated machine reports the gap instead of failing.
+ * @param name - package name.
+ * @param version - the version the tag names.
+ */
+function confirmPublished(name: string, version: string): void {
+  const result = attempt('npm', ['view', `${name}@${version}`, 'version'])
+  if (result.status === 0) return
+  const output = `${result.stdout}${result.stderr}`
+  if (output.includes('ENEEDAUTH') || output.includes('E401') || output.includes('E403')) {
+    console.log(`release bump: cannot reach the registry for ${name}@${version}; skipping the tag check`)
+    return
+  }
+  if (output.includes('E404') || output.includes('404 Not Found')) {
+    throw new Error(
+      `${name}@${version} is tagged but absent from the registry.`
+      + '\nThe tag was pushed for a publication that did not complete: re-run that publish, or delete the tag.',
+    )
+  }
+  throw new Error(`npm view ${name}@${version} failed:\n${output}`)
+}
+
+/**
+ * Write a version into a manifest, preserving formatting and key order.
+ * @param root - repository root.
+ * @param manifestPath - repository-relative manifest path.
+ * @param from - the version the manifest currently carries.
+ * @param to - the target version.
+ */
+function writeVersion(root: string, manifestPath: string, from: string, to: string): void {
+  const path = join(root, manifestPath)
+  const text = readFileSync(path, 'utf8')
+  const line = `"version": "${from}"`
+  if (!text.includes(line)) throw new Error(`${manifestPath}: cannot locate ${line}`)
+  writeFileSync(path, text.replace(line, `"version": "${to}"`))
+}
+
+/**
+ * Read the workspace root version.
+ * @param root - repository root.
+ * @returns The root manifest version.
+ */
+function rootVersion(root: string): string {
+  const manifest: unknown = JSON.parse(readFileSync(join(root, ROOT_MANIFEST), 'utf8'))
+  const version = (manifest as Record<string, unknown>).version
+  if (typeof version !== 'string') throw new Error('package.json must declare a string version')
+  return version
+}
+
+/**
+ * Plan the dsh family's rewrite: one version for every member and the root.
+ * @param family - the dsh family.
+ * @param root - repository root.
+ * @param members - the family's members.
+ * @param request - `major`, `minor`, `patch`, or an explicit version.
+ * @returns The manifests to rewrite and the shared target version.
+ */
+function planShared(
+  family: ReleaseFamily,
+  root: string,
+  members: readonly ReleaseMember[],
+  request: string,
+): { planned: PlannedVersion[]; version: string } {
+  const [first] = members
+  if (first === undefined) throw new Error(`release family ${family.id} has no members`)
+  const version = nextSharedVersion(first.version, request)
+  // The workspace root carries the family version too: the workspace constraint
+  // requires every member's version to equal the root's.
+  const planned: PlannedVersion[] = [
+    { manifestPath: ROOT_MANIFEST, label: ROOT_MANIFEST, from: rootVersion(root), to: version, tag: undefined },
+  ]
+  for (const member of members) {
+    planned.push({
+      manifestPath: join(member.directory, 'package.json'),
+      label: member.directory,
+      from: member.version,
+      to: version,
+      tag: family.tagFor({ ...member, version }),
+    })
+  }
+  return { planned, version }
+}
+
+/**
+ * Plan the vendored family's rewrite: every package whose payload changed since
+ * it last published.
+ * @param family - the vendored family.
+ * @param members - the family's members.
+ * @param prerelease - prerelease identifier to append, for a rehearsal publication.
+ * @returns The manifests to rewrite.
+ */
+function planPerPackage(
+  family: ReleaseFamily,
+  members: readonly ReleaseMember[],
+  prerelease: string | undefined,
+): PlannedVersion[] {
+  const planned: PlannedVersion[] = []
+  for (const member of members) {
+    const published = lastPublishedVersion(family, member)
+    if (published !== undefined) {
+      confirmPublished(member.name, published)
+      const since = `${family.tagPrefixFor(member)}${published}`
+      const changed = capture('git', ['diff', '--name-only', `${since}..HEAD`, '--', member.directory])
+        .split('\n').filter(line => line !== '')
+      if (!changed.some(path => reachesPayload(member, path))) continue
+    }
+    const to = nextVendorVersion(member.version, published, prerelease)
+    planned.push({
+      manifestPath: join(member.directory, 'package.json'),
+      label: member.directory,
+      from: member.version,
+      to,
+      tag: family.tagFor({ ...member, version: to }),
+    })
+  }
+  return planned
+}
+
+/**
+ * Bump the family named by `--family` and commit; `--dry-run` only reports the
+ * plan. `--prerelease rc.1` makes the vendored family publish a rehearsal
+ * version, which never takes the stable dist-tag.
+ */
+function main(): void {
+  const { values, positionals } = parseArgs({
+    options: {
+      family: { type: 'string' },
+      prerelease: { type: 'string' },
+      'dry-run': { type: 'boolean', default: false },
+    },
+    allowPositionals: true,
+  })
+  if (values.family === undefined) throw new Error('usage: bump.ts --family <dsh|vendor> [version]')
+
+  const family = releaseFamily(values.family)
+  const root = process.cwd()
+  const members = family.members(root)
+  family.verifyVersions(members)
+
+  let planned: PlannedVersion[]
+  let sharedVersion: string | undefined
+  if (family.id === 'dsh') {
+    const request = positionals[0]
+    if (request === undefined) throw new Error('usage: release:dsh <major|minor|patch|x.y.z>')
+    if (values.prerelease !== undefined) {
+      throw new Error('release:dsh takes the prerelease in its version argument, as in 0.0.1-rc.1')
+    }
+    const shared = planShared(family, root, members, request)
+    planned = shared.planned
+    sharedVersion = shared.version
+  } else {
+    if (positionals.length > 0) throw new Error('release:vendor takes no version: each package increments its own patch')
+    if (values.prerelease !== undefined && !/^[0-9A-Za-z.-]+$/.test(values.prerelease)) {
+      throw new Error(`--prerelease must be a semver prerelease identifier, got ${values.prerelease}`)
+    }
+    planned = planPerPackage(family, members, values.prerelease)
+  }
+
+  if (planned.length === 0) {
+    console.log(`release bump: family ${family.id}, nothing changed since publication`)
+    return
+  }
+
+  const dryRun = values['dry-run']
+  if (!dryRun) {
+    for (const entry of planned) writeVersion(root, entry.manifestPath, entry.from, entry.to)
+    capture('pnpm', ['install', '--lockfile-only'])
+  }
+
+  const summary = sharedVersion
+    ?? planned.map(entry => `${entry.label.replace('vendor/', '')} ${entry.to}`).join(', ')
+  console.log(`release bump: family ${family.id} -> ${summary}`)
+  for (const entry of planned) console.log(`  ${entry.label}: ${entry.from} -> ${entry.to}`)
+
+  if (dryRun) {
+    console.log('release bump: dry run, nothing written')
+    return
+  }
+  capture('git', ['add', 'pnpm-lock.yaml', ...planned.map(entry => entry.manifestPath)])
+  capture('git', ['commit', '-m', `release(${family.id}): ${summary}`])
+  console.log('release bump: committed. After this merges to master, tag it:')
+  for (const tag of [...new Set(planned.map(entry => entry.tag).filter(tag => tag !== undefined))]) {
+    console.log(`  git tag ${tag} <merge commit> && git push origin ${tag}`)
+  }
+}
+
+if (isEntry(import.meta.url)) main()

scripts/release/families.spec.ts

@@ -0,0 +1,176 @@
+/** Release family discovery, publish order, tag naming, and the bump judgements. */
+
+import { describe, expect, it } from 'vitest'
+import { releaseFamily, type ReleaseMember } from './families.ts'
+import { compareVersions, nextVendorVersion, reachesPayload } from './bump.ts'
+
+/**
+ * A release member standing in for a manifest on disk.
+ * @param directory - repository-relative package directory.
+ * @param name - package name.
+ * @param manifest - manifest fields the subject reads.
+ * @returns The member.
+ */
+function member(directory: string, name: string, manifest: Record<string, unknown> = {}): ReleaseMember {
+  return { directory, name, version: '0.0.1', manifest }
+}
+
+describe('release families', () => {
+  it('names one tag for the whole dsh family and one per vendored package', () => {
+    const dsh = releaseFamily('dsh')
+    const vendor = releaseFamily('vendor')
+    const cli = member('apps/cli', '@deepseek-ai/dsh')
+    const cordis = { ...member('vendor/cordis', '@deepseek-ai/cordis'), version: '4.0.1' }
+
+    expect(dsh.tagFor(cli)).toBe('dsh-v0.0.1')
+    expect(vendor.tagFor(cordis)).toBe('vendor-cordis-v4.0.1')
+    // The prefix is constructed, not recovered from a tag: a version with a
+    // hyphen would defeat any suffix-stripping.
+    expect(vendor.tagPrefixFor({ ...cordis, version: '4.0.0-rc.7' })).toBe('vendor-cordis-v')
+    expect(vendor.tagFor({ ...cordis, version: '4.0.0-rc.7' })).toBe('vendor-cordis-v4.0.0-rc.7')
+  })
+
+  it('rejects a family whose members disagree on the shared version', () => {
+    const dsh = releaseFamily('dsh')
+    const members = [member('apps/cli', '@deepseek-ai/dsh'), { ...member('apps/web', '@deepseek-ai/dsh-frontend'), version: '0.0.2' }]
+
+    expect(() => { dsh.verifyVersions(members) }).toThrow(/must share one version/)
+    expect(() => { dsh.verifyVersions([members[0]!]) }).not.toThrow()
+  })
+
+  it('accepts independent vendored versions and rejects an unpublishable one', () => {
+    const vendor = releaseFamily('vendor')
+    const members = [
+      { ...member('vendor/cordis', '@deepseek-ai/cordis'), version: '4.0.1' },
+      { ...member('vendor/cosmokit', '@deepseek-ai/cosmokit'), version: '1.8.2' },
+    ]
+
+    expect(() => { vendor.verifyVersions(members) }).not.toThrow()
+    expect(() => { vendor.verifyVersions([{ ...members[0]!, version: 'latest' }]) }).toThrow(/unpublishable version/)
+  })
+
+  it('publishes a dependency before its consumer, and orders ties by name', () => {
+    const dsh = releaseFamily('dsh')
+    const members = [
+      member('packages/a/consumer', '@deepseek-ai/dsh-consumer', { dependencies: { '@deepseek-ai/dsh-library': 'workspace:^' } }),
+      member('packages/a/library', '@deepseek-ai/dsh-library'),
+      member('packages/a/zebra', '@deepseek-ai/dsh-zebra'),
+    ]
+
+    expect(dsh.publishOrder(members).map(entry => entry.name)).toEqual([
+      '@deepseek-ai/dsh-library',
+      '@deepseek-ai/dsh-consumer',
+      '@deepseek-ai/dsh-zebra',
+    ])
+  })
+
+  it('reports a runtime dependency cycle instead of emitting an arbitrary order', () => {
+    const dsh = releaseFamily('dsh')
+    const members = [
+      member('packages/a/left', '@deepseek-ai/dsh-left', { dependencies: { '@deepseek-ai/dsh-right': 'workspace:^' } }),
+      member('packages/a/right', '@deepseek-ai/dsh-right', { dependencies: { '@deepseek-ai/dsh-left': 'workspace:^' } }),
+    ]
+
+    expect(() => { dsh.publishOrder(members) }).toThrow(/dependency cycle/)
+  })
+
+  it('applies the harness payload policy to dsh and keeps upstream payloads for vendored packages', () => {
+    const dsh = releaseFamily('dsh')
+    const vendor = releaseFamily('vendor')
+    const harness = member('packages/a/library', '@deepseek-ai/dsh-library')
+    const vendored = member('vendor/cordis', '@deepseek-ai/cordis')
+
+    expect(() => { dsh.validatePayload(harness, ['package/lib/index.js', 'package/src/index.ts']) })
+      .toThrow(/publishes source file/)
+    expect(() => { vendor.validatePayload(vendored, ['package/lib/index.js', 'package/src/index.ts']) }).not.toThrow()
+    expect(() => { vendor.validatePayload(vendored, []) }).toThrow(/empty tarball/)
+  })
+
+  it('drives the installed entry only for the family that publishes one', () => {
+    expect(releaseFamily('dsh').installedEntry).toEqual({ packageName: '@deepseek-ai/dsh', binPath: 'lib/bin.js' })
+    expect(releaseFamily('vendor').installedEntry).toBeUndefined()
+  })
+
+  it('rejects an unknown family identifier', () => {
+    expect(() => { releaseFamily('native') }).toThrow(/unknown release family/)
+  })
+})
+
+describe('vendored version baseline', () => {
+  it('drops an upstream prerelease segment and increments the patch', () => {
+    expect(nextVendorVersion('4.0.0-rc.7', undefined)).toBe('4.0.1')
+    expect(nextVendorVersion('1.0.0-rc.5', undefined)).toBe('1.0.1')
+    expect(nextVendorVersion('1.8.1', undefined)).toBe('1.8.2')
+  })
+
+  it('increments from the last published version when a re-sync restored a lower one', () => {
+    // Upstream moved rc.7 -> rc.8 after this repository published 4.0.1;
+    // incrementing the manifest alone would name 4.0.1 a second time.
+    expect(nextVendorVersion('4.0.0-rc.8', '4.0.1')).toBe('4.0.2')
+    expect(nextVendorVersion('4.1.0', '4.0.1')).toBe('4.1.1')
+  })
+
+  it('appends a rehearsal prerelease without consuming its release numbers', () => {
+    // A rehearsal burns 4.0.1-rc.1 and leaves 4.0.1 free, so the stable release
+    // that follows takes those same numbers instead of skipping to 4.0.2.
+    expect(nextVendorVersion('4.0.0-rc.7', undefined, 'rc.1')).toBe('4.0.1-rc.1')
+    expect(nextVendorVersion('4.0.0-rc.7', '4.0.1-rc.1', 'rc.2')).toBe('4.0.1-rc.2')
+    expect(nextVendorVersion('4.0.0-rc.7', '4.0.1-rc.1')).toBe('4.0.1')
+    expect(nextVendorVersion('4.0.0-rc.7', '4.0.1')).toBe('4.0.2')
+  })
+})
+
+describe('version precedence', () => {
+  it('ranks a release above the prerelease it follows', () => {
+    // git --sort=v:refname disagrees, placing 4.0.1-rc.1 above 4.0.1, which is
+    // why the newest published version is chosen here rather than by git.
+    expect(compareVersions('4.0.1', '4.0.1-rc.1')).toBeGreaterThan(0)
+    expect(compareVersions('4.0.1-rc.1', '4.0.1')).toBeLessThan(0)
+  })
+
+  it('compares numeric prerelease fields numerically', () => {
+    expect(compareVersions('4.0.1-rc.10', '4.0.1-rc.1')).toBeGreaterThan(0)
+    expect(compareVersions('4.0.1-rc.2', '4.0.1-rc.10')).toBeLessThan(0)
+  })
+
+  it('ranks a numeric field below an alphanumeric one, and a shorter list below a longer', () => {
+    expect(compareVersions('4.0.1-1', '4.0.1-alpha')).toBeLessThan(0)
+    expect(compareVersions('4.0.1-rc', '4.0.1-rc.1')).toBeLessThan(0)
+    expect(compareVersions('4.0.2', '4.0.1')).toBeGreaterThan(0)
+    expect(compareVersions('4.0.1-rc.1', '4.0.1-rc.1')).toBe(0)
+  })
+})
+
+describe('payload change judgement', () => {
+  const sourceShipping = member('vendor/cosmokit', '@deepseek-ai/cosmokit', {
+    files: ['lib/index.js', 'lib/types/**/*.d.ts', 'src'],
+  })
+  const buildOutputOnly = member('vendor/cordis', '@deepseek-ai/cordis', {
+    files: ['lib/index.js', 'lib/types/**/*.d.ts', 'bin.js'],
+  })
+
+  it('counts the manifest and the files npm always publishes', () => {
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/package.json')).toBe(true)
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/README.md')).toBe(true)
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/src/index.ts')).toBe(true)
+  })
+
+  it('counts build inputs for a package whose payload is build output', () => {
+    // cordis publishes lib/ only, and lib/ is not tracked: without this, a real
+    // source change reads as "nothing changed" and the next publish fails on a
+    // version whose bytes moved.
+    expect(reachesPayload(buildOutputOnly, 'vendor/cordis/src/context.ts')).toBe(true)
+    expect(reachesPayload(buildOutputOnly, 'vendor/cordis/tsconfig.json')).toBe(true)
+  })
+
+  it('ignores paths no tarball carries', () => {
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/tests/unit.spec.ts')).toBe(false)
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/CHANGELOG.md')).toBe(false)
+    // The README pattern is deliberately loose: over-reporting a change costs one
+    // unnecessary patch bump, while under-reporting fails the next publish on a
+    // version whose bytes moved.
+    expect(reachesPayload(sourceShipping, 'vendor/cosmokit/README.i18n.yaml')).toBe(true)
+    expect(reachesPayload(member('packages/a/library', '@deepseek-ai/dsh-library', { files: ['lib/index.js'] }),
+      'packages/a/library/tests/library.spec.ts')).toBe(false)
+  })
+})

scripts/release/families.ts

@@ -0,0 +1,310 @@
+/**
+ * The three independent publish sequences this repository releases from
+ * (`packages/` + `apps/`, `vendor/`, and `native/`) and the two this module
+ * owns: `dsh` and `vendor`. Each family carries its own version baseline, tag
+ * naming, and publish set, so releasing one never republishes another
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ *
+ * The family dimension lives here only. A new sequence adds a subclass and a
+ * `releaseFamilies()` entry; nothing else in the release scripts branches on it.
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { hasTypeRTRemoteNavigation, validateTarballPayload } from '../publication-payload.ts'
+
+/** Dependency sections that constrain publish order: a consumer must publish after its dependency. */
+const ORDER_SECTIONS = ['dependencies', 'optionalDependencies'] as const
+
+/** The workspace root manifest, which is never a release member. */
+const WORKSPACE_ROOT_PACKAGE = '@deepseek-ai/dsh-root'
+
+/** One publishable package of a release family. */
+export interface ReleaseMember {
+  /** Repository-relative package directory, for example `packages/core/session`. */
+  readonly directory: string
+  /** Package name from its manifest. */
+  readonly name: string
+  /** Package version from its manifest. */
+  readonly version: string
+  /** The parsed manifest, for payload policy and publication checks. */
+  readonly manifest: Readonly<Record<string, unknown>>
+}
+
+/**
+ * Read and parse a JSON file.
+ * @param path - absolute file path.
+ * @returns The parsed object.
+ */
+function readManifest(path: string): Record<string, unknown> {
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`${path} is not a JSON object`)
+  }
+  return parsed as Record<string, unknown>
+}
+
+/**
+ * Read a required string field.
+ * @param manifest - parsed manifest.
+ * @param field - field name.
+ * @param context - manifest path for the error message.
+ * @returns The field value.
+ */
+function requireString(manifest: Record<string, unknown>, field: string, context: string): string {
+  const value = manifest[field]
+  if (typeof value !== 'string' || value === '') throw new Error(`${context} must declare a string ${field}`)
+  return value
+}
+
+/** The executable a family's installed artifacts are driven through. */
+export interface InstalledEntry {
+  /** Package that carries the executable. */
+  readonly packageName: string
+  /** Path to the executable inside that package. */
+  readonly binPath: string
+}
+
+/** A release sequence: its members, its version baseline, and its tag naming. */
+export abstract class ReleaseFamily {
+  /** Workflow-facing identifier, also the `--family` argument. */
+  abstract readonly id: string
+
+  /** Glob patterns, relative to the repository root, that select this family's manifests. */
+  abstract readonly patterns: readonly string[]
+
+  /** Git tag prefix this family publishes from. */
+  abstract readonly tagPrefix: string
+
+  /**
+   * Discover this family's members.
+   * @param root - repository root.
+   * @returns Members sorted by directory, with names validated and deduplicated.
+   */
+  members(root: string): ReleaseMember[] {
+    const manifestPaths = globSync([...this.patterns], { cwd: root }).sort()
+    if (manifestPaths.length === 0) throw new Error(`release family ${this.id} matched no manifests`)
+
+    const members: ReleaseMember[] = []
+    const seen = new Set<string>()
+    for (const manifestPath of manifestPaths) {
+      const normalized = manifestPath.replaceAll('\\', '/')
+      const manifest = readManifest(resolve(root, manifestPath))
+      const name = requireString(manifest, 'name', normalized)
+      const version = requireString(manifest, 'version', normalized)
+      if (name === WORKSPACE_ROOT_PACKAGE) throw new Error(`${normalized} selected the workspace root`)
+      if (!name.startsWith('@deepseek-ai/')) throw new Error(`${normalized} must name an @deepseek-ai package`)
+      if (seen.has(name)) throw new Error(`${name} appears twice in release family ${this.id}`)
+      seen.add(name)
+      members.push({
+        directory: normalized.slice(0, normalized.length - '/package.json'.length),
+        name,
+        version,
+        manifest,
+      })
+    }
+    return members
+  }
+
+  /**
+   * Order members so every package publishes after the family members it depends on.
+   * @param members - this family's members.
+   * @returns The same members in publish order; ties break by name for determinism.
+   */
+  publishOrder(members: readonly ReleaseMember[]): ReleaseMember[] {
+    const byName = new Map(members.map(member => [member.name, member]))
+    const ordered: ReleaseMember[] = []
+    const placed = new Set<string>()
+    const visiting = new Set<string>()
+
+    const visit = (member: ReleaseMember, path: readonly string[]): void => {
+      if (placed.has(member.name)) return
+      if (visiting.has(member.name)) {
+        throw new Error(`dependency cycle in release family ${this.id}: ${[...path, member.name].join(' -> ')}`)
+      }
+      visiting.add(member.name)
+      for (const dependency of this.orderEdges(member, byName)) {
+        visit(dependency, [...path, member.name])
+      }
+      visiting.delete(member.name)
+      placed.add(member.name)
+      ordered.push(member)
+    }
+
+    for (const member of [...members].sort((left, right) => left.name.localeCompare(right.name))) {
+      visit(member, [])
+    }
+    return ordered
+  }
+
+  /**
+   * The family members one member depends on at runtime.
+   * @param member - the dependent member.
+   * @param byName - every family member by package name.
+   * @returns Dependencies inside this family, sorted by name.
+   */
+  private orderEdges(member: ReleaseMember, byName: ReadonlyMap<string, ReleaseMember>): ReleaseMember[] {
+    const edges: ReleaseMember[] = []
+    for (const section of ORDER_SECTIONS) {
+      const dependencies = member.manifest[section]
+      if (dependencies === null || typeof dependencies !== 'object' || Array.isArray(dependencies)) continue
+      for (const name of Object.keys(dependencies)) {
+        const dependency = byName.get(name)
+        if (dependency !== undefined && dependency.name !== member.name) edges.push(dependency)
+      }
+    }
+    return edges.sort((left, right) => left.name.localeCompare(right.name))
+  }
+
+  /**
+   * Assert this family's version baseline holds across its members.
+   * @param members - this family's members.
+   */
+  abstract verifyVersions(members: readonly ReleaseMember[]): void
+
+  /**
+   * The tag prefix a member's versions are tagged under. Every tag for that
+   * member starts with it, which is how the last published version is found.
+   * @param member - the member being published.
+   * @returns The prefix, ending in `-v`.
+   */
+  abstract tagPrefixFor(member: ReleaseMember): string
+
+  /**
+   * The tag a member publishes from.
+   * @param member - the member being published.
+   * @returns The full tag name, without `refs/tags/`.
+   */
+  tagFor(member: ReleaseMember): string {
+    return `${this.tagPrefixFor(member)}${member.version}`
+  }
+
+  /**
+   * Check what a member's packed tarball carries.
+   * @param member - the packed member.
+   * @param files - every path inside its tarball.
+   */
+  abstract validatePayload(member: ReleaseMember, files: readonly string[]): void
+
+  /**
+   * The executable that proves this family's artifacts install and run, or
+   * `undefined` for a family that publishes no executable.
+   */
+  abstract readonly installedEntry: InstalledEntry | undefined
+}
+
+/** `packages/*` and `apps/*`: one shared version across the whole family. */
+class DshFamily extends ReleaseFamily {
+  readonly id = 'dsh'
+  readonly patterns = ['packages/*/*/package.json', 'apps/*/package.json'] as const
+  readonly tagPrefix = 'dsh-v'
+
+  /**
+   * Require one version across the family, the way a single tag can name it.
+   * @param members - this family's members.
+   */
+  verifyVersions(members: readonly ReleaseMember[]): void {
+    const versions = new Set(members.map(member => member.version))
+    if (versions.size !== 1) {
+      const detail = members.map(member => `${member.directory}: ${member.version}`).join('\n')
+      throw new Error(`dsh release members must share one version:\n${detail}`)
+    }
+  }
+
+  /**
+   * The single family prefix: every member shares one version, so one tag names it.
+   * @returns `dsh-v`.
+   */
+  tagPrefixFor(): string {
+    return this.tagPrefix
+  }
+
+  /**
+   * Reject source and declaration-map members, the repository's publication policy.
+   * @param member - the packed member.
+   * @param files - every path inside its tarball.
+   */
+  validatePayload(member: ReleaseMember, files: readonly string[]): void {
+    validateTarballPayload(files, member.name, {
+      typeRTRemoteNavigation: hasTypeRTRemoteNavigation(member.manifest),
+    })
+  }
+
+  readonly installedEntry = { packageName: '@deepseek-ai/dsh', binPath: 'lib/bin.js' }
+}
+
+/** `vendor/*`: every package keeps its own version line, so every package has its own tag. */
+class VendorFamily extends ReleaseFamily {
+  readonly id = 'vendor'
+  readonly patterns = ['vendor/*/package.json'] as const
+  readonly tagPrefix = 'vendor-'
+
+  /**
+   * Accept independent versions; only reject a version this repository cannot publish.
+   * @param members - this family's members.
+   */
+  verifyVersions(members: readonly ReleaseMember[]): void {
+    for (const member of members) {
+      if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(member.version)) {
+        throw new Error(`${member.directory} has an unpublishable version: ${member.version}`)
+      }
+    }
+  }
+
+  /**
+   * A prefix per member, because one vendor release can carry several versions.
+   * @param member - the member being published.
+   * @returns `vendor-<unscoped name>-v`.
+   */
+  tagPrefixFor(member: ReleaseMember): string {
+    return `${this.tagPrefix}${member.name.replace('@deepseek-ai/', '')}-v`
+  }
+
+  /**
+   * Require the payload the vendored manifest declares, including upstream's
+   * `src` tree and declaration maps.
+   *
+   * The harness policy that rejects both does not apply here: these manifests
+   * export `./src/*` for source navigation, so dropping `src` would publish a
+   * package whose export map points at absent files. What must hold instead is
+   * that every path the manifest selects is present, which `files` already
+   * decides and `pnpm pack` already enforces.
+   * @param member - the packed member.
+   * @param files - every path inside its tarball.
+   */
+  validatePayload(member: ReleaseMember, files: readonly string[]): void {
+    if (files.length === 0) throw new Error(`${member.name} packed an empty tarball`)
+  }
+
+  /** No installed-entry probe: these are libraries a consumer imports, with no executable. */
+  readonly installedEntry = undefined
+}
+
+/** Every release family this module owns, in workflow order. */
+function releaseFamilies(): readonly ReleaseFamily[] {
+  return [new DshFamily(), new VendorFamily()]
+}
+
+/**
+ * Resolve a family by its `--family` identifier.
+ * @param id - family identifier.
+ * @returns The family.
+ */
+export function releaseFamily(id: string): ReleaseFamily {
+  const family = releaseFamilies().find(candidate => candidate.id === id)
+  if (family === undefined) {
+    const known = releaseFamilies().map(candidate => candidate.id).join(', ')
+    throw new Error(`unknown release family ${id}; expected one of ${known}`)
+  }
+  return family
+}
+
+/**
+ * The npm tarball filename `pnpm pack` writes for a member.
+ * @param member - the packed member.
+ * @returns The tarball filename.
+ */
+export function tarballName(member: ReleaseMember): string {
+  const unscoped = member.name.startsWith('@') ? member.name.slice(1).replace('/', '-') : member.name
+  return `${unscoped}-${member.version}.tgz`
+}

scripts/release/pack.ts

@@ -0,0 +1,61 @@
+/**
+ * Pack one release family's whole publish set into a single directory, in
+ * publish order, and record that order for the publish step.
+ *
+ * The pack step is the release boundary: it runs without credentials, produces
+ * every tarball from one commit, and hands the publish step exactly those bytes
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ */
+
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { releaseFamily, tarballName, type ReleaseFamily, type ReleaseMember } from './families.ts'
+import { isEntry, run } from './process.ts'
+import { PUBLISH_ORDER_FILE, tarballFiles } from './tarball.ts'
+
+/** Where pack output lands when `--out` is omitted. */
+const DEFAULT_OUTPUT = 'dist/npm'
+
+/**
+ * Pack one member and check what its tarball carries.
+ * @param family - the release family being packed.
+ * @param member - the member to pack.
+ * @param destination - absolute output directory.
+ * @returns The tarball filename.
+ */
+function packMember(family: ReleaseFamily, member: ReleaseMember, destination: string): string {
+  run('pnpm', ['--dir', member.directory, 'pack', '--pack-destination', destination])
+
+  const filename = tarballName(member)
+  const tarball = join(destination, filename)
+  if (!existsSync(tarball)) throw new Error(`${member.name} produced no tarball at ${tarball}`)
+  family.validatePayload(member, tarballFiles(tarball))
+  return filename
+}
+
+/** Pack the family named by `--family` into `--out`. */
+function main(): void {
+  const { values } = parseArgs({
+    options: { family: { type: 'string' }, out: { type: 'string' } },
+    allowPositionals: false,
+  })
+  if (values.family === undefined) throw new Error('usage: pack.ts --family <dsh|vendor> [--out dist/npm]')
+
+  const family = releaseFamily(values.family)
+  const root = process.cwd()
+  const destination = resolve(root, values.out ?? DEFAULT_OUTPUT)
+  const members = family.publishOrder(family.members(root))
+  family.verifyVersions(members)
+
+  rmSync(destination, { recursive: true, force: true })
+  mkdirSync(destination, { recursive: true })
+
+  const order: string[] = []
+  for (const member of members) order.push(packMember(family, member, destination))
+  writeFileSync(join(destination, PUBLISH_ORDER_FILE), `${order.join('\n')}\n`)
+
+  console.log(`release pack: family ${family.id}, ${String(order.length)} tarball(s) in ${values.out ?? DEFAULT_OUTPUT}`)
+}
+
+if (isEntry(import.meta.url)) main()

scripts/release/process.ts

@@ -0,0 +1,82 @@
+/**
+ * Process helpers shared by the release scripts: the release steps drive `git`,
+ * `pnpm`, `npm`, and `tar`, and each needs one of three failure behaviours.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { realpathSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+/** Where and with what environment a release step runs a command. */
+export interface RunOptions {
+  /** Working directory; defaults to the current one. */
+  readonly cwd?: string
+  /** Child environment; defaults to this process's. */
+  readonly env?: NodeJS.ProcessEnv
+}
+
+/** What a command produced, for a caller that decides what a failure means. */
+export interface CommandResult {
+  /** Exit status, or null when a signal ended the process. */
+  readonly status: number | null
+  /** Captured standard output. */
+  readonly stdout: string
+  /** Captured standard error. */
+  readonly stderr: string
+}
+
+/**
+ * Run a command and capture its output without judging the exit status.
+ * @param command - executable name.
+ * @param args - command arguments.
+ * @param options - working directory and environment.
+ * @returns The exit status and captured streams.
+ */
+export function attempt(command: string, args: readonly string[], options: RunOptions = {}): CommandResult {
+  const result = spawnSync(command, [...args], { cwd: options.cwd, env: options.env, encoding: 'utf8' })
+  if (result.error !== undefined) throw result.error
+  return { status: result.status, stdout: result.stdout, stderr: result.stderr }
+}
+
+/**
+ * Run a command, capture its standard output, and fail on a non-zero exit.
+ * @param command - executable name.
+ * @param args - command arguments.
+ * @param options - working directory and environment.
+ * @returns The trimmed standard output.
+ */
+export function capture(command: string, args: readonly string[], options: RunOptions = {}): string {
+  const result = attempt(command, args, options)
+  if (result.status !== 0) {
+    throw new Error(`${command} ${args.join(' ')} exited with ${String(result.status)}:\n${result.stdout}\n${result.stderr}`)
+  }
+  return result.stdout.trim()
+}
+
+/**
+ * Run a command with inherited streams, so its progress reaches the log, and
+ * fail on a non-zero exit.
+ * @param command - executable name.
+ * @param args - command arguments.
+ * @param options - working directory and environment.
+ */
+export function run(command: string, args: readonly string[], options: RunOptions = {}): void {
+  const result = spawnSync(command, [...args], { cwd: options.cwd, env: options.env, stdio: 'inherit' })
+  if (result.error !== undefined) throw result.error
+  if (result.status !== 0) throw new Error(`${command} ${args.join(' ')} exited with ${String(result.status)}`)
+}
+
+/**
+ * Whether this module is the process entry point.
+ *
+ * The release scripts are both commands and modules: a test imports their pure
+ * logic, and importing a module runs its body, so an unguarded `main()` would
+ * run the wrong command with the wrong arguments.
+ * @param moduleUrl - the caller's `import.meta.url`.
+ * @returns True when Node started this module.
+ */
+export function isEntry(moduleUrl: string): boolean {
+  const invoked = process.argv[1]
+  if (invoked === undefined) return false
+  return realpathSync(invoked) === realpathSync(fileURLToPath(moduleUrl))
+}

scripts/release/publish.ts

@@ -0,0 +1,101 @@
+/**
+ * Publish one packed release family from the tarballs the pack step produced.
+ *
+ * Publication is decided per package against the registry, never from a list of
+ * "what this release includes": a version the registry lacks is published, a
+ * version whose published tarball has the same integrity is skipped, and a
+ * version whose published tarball differs fails the run — that last case means
+ * the content changed without a version bump
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ *
+ * Skipping on identical integrity is what makes re-running the publish step over
+ * the same artifact safe.
+ */
+
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { releaseFamily } from './families.ts'
+import { attempt, isEntry, run } from './process.ts'
+import { packedIdentity, readPublishOrder } from './tarball.ts'
+
+/** npm access level for every package this repository publishes. */
+const ACCESS = 'restricted'
+
+/** What the registry knows about one version. */
+type RegistryState =
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'present'; readonly integrity: string }
+
+/**
+ * The subresource integrity string npm records for a tarball.
+ * @param tarball - absolute tarball path.
+ * @returns A `sha512-<base64>` string.
+ */
+function integrityOf(tarball: string): string {
+  return `sha512-${createHash('sha512').update(readFileSync(tarball)).digest('base64')}`
+}
+
+/**
+ * Ask the registry whether a version exists, and with what integrity.
+ * @param name - package name.
+ * @param version - package version.
+ * @returns The registry state for that version.
+ */
+function registryState(name: string, version: string): RegistryState {
+  const result = attempt('npm', ['view', `${name}@${version}`, 'dist.integrity', '--json'])
+  if (result.status !== 0) {
+    const output = `${result.stdout}${result.stderr}`
+    if (output.includes('E404') || output.includes('404 Not Found')) return { kind: 'absent' }
+    throw new Error(`npm view ${name}@${version} failed:\n${output}`)
+  }
+  const parsed: unknown = JSON.parse(result.stdout)
+  if (typeof parsed !== 'string' || parsed === '') {
+    throw new Error(`registry reported no dist.integrity for ${name}@${version}`)
+  }
+  return { kind: 'present', integrity: parsed }
+}
+
+/** Publish the family named by `--family` from the directory named by `--from`. */
+function main(): void {
+  const { values } = parseArgs({
+    options: { family: { type: 'string' }, from: { type: 'string' } },
+    allowPositionals: false,
+  })
+  if (values.family === undefined || values.from === undefined) {
+    throw new Error('usage: publish.ts --family <dsh|vendor> --from <packed directory>')
+  }
+
+  const family = releaseFamily(values.family)
+  const directory = resolve(process.cwd(), values.from)
+
+  let published = 0
+  let skipped = 0
+  for (const filename of readPublishOrder(directory)) {
+    const tarball = join(directory, filename)
+    const { name, version } = packedIdentity(tarball)
+    const state = registryState(name, version)
+    if (state.kind === 'present') {
+      const local = integrityOf(tarball)
+      if (state.integrity !== local) {
+        throw new Error(
+          `${name}@${version} is already published with different content`
+          + `\n  registry: ${state.integrity}\n  packed:   ${local}`
+          + '\nBump the version, or investigate why the build is not reproducible.',
+        )
+      }
+      console.log(`release publish: ${name}@${version} already published, skipping`)
+      skipped += 1
+      continue
+    }
+    // A prerelease version never takes the latest dist-tag.
+    const tagArgs = version.includes('-') ? ['--tag', 'next'] : []
+    run('npm', ['publish', tarball, '--access', ACCESS, ...tagArgs])
+    published += 1
+  }
+
+  console.log(`release publish: family ${family.id}, ${String(published)} published, ${String(skipped)} already present`)
+}
+
+if (isEntry(import.meta.url)) main()

scripts/release/tarball.ts

@@ -0,0 +1,53 @@
+/**
+ * Reading packed npm tarballs and the order file that accompanies them.
+ *
+ * The release steps after pack treat a directory of tarballs as the unit of
+ * work, so they read what a tarball declares rather than what the checkout
+ * currently says.
+ */
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { capture } from './process.ts'
+
+/** Name of the file recording the order in which a packed family uploads. */
+export const PUBLISH_ORDER_FILE = 'publish-order.txt'
+
+/** What a packed tarball calls itself. */
+export interface PackedIdentity {
+  /** Package name from the packed manifest. */
+  readonly name: string
+  /** Package version from the packed manifest. */
+  readonly version: string
+}
+
+/**
+ * List a tarball's members.
+ * @param tarball - absolute tarball path.
+ * @returns Every path inside the archive.
+ */
+export function tarballFiles(tarball: string): string[] {
+  return capture('tar', ['-tzf', tarball]).split('\n').filter(line => line !== '')
+}
+
+/**
+ * Read a packed tarball's own manifest.
+ * @param tarball - absolute tarball path.
+ * @returns The name and version the tarball declares.
+ */
+export function packedIdentity(tarball: string): PackedIdentity {
+  const manifest: unknown = JSON.parse(capture('tar', ['-xOzf', tarball, 'package/package.json']))
+  if (manifest === null || typeof manifest !== 'object') throw new Error(`${tarball} has no manifest`)
+  const { name, version } = manifest as Record<string, unknown>
+  if (typeof name !== 'string' || typeof version !== 'string') throw new Error(`${tarball} manifest lacks name/version`)
+  return { name, version }
+}
+
+/**
+ * Read a packed directory's upload order.
+ * @param directory - absolute path of a pack output directory.
+ * @returns Tarball filenames in upload order.
+ */
+export function readPublishOrder(directory: string): string[] {
+  return readFileSync(join(directory, PUBLISH_ORDER_FILE), 'utf8').split('\n').filter(line => line !== '')
+}

scripts/release/verify-packed-install.ts

@@ -0,0 +1,120 @@
+/**
+ * Install packed tarballs into a throwaway consumer outside the repository and
+ * drive the installed executable with plain Node.
+ *
+ * Every tarball the installed tree needs comes from `--from`, so the only
+ * registry traffic is for external dependencies. That matters beyond hermetic
+ * verification: the harness packages declare the vendored framework as a peer,
+ * and those packages live in another release sequence that this credential-free
+ * job cannot fetch from a private registry — so a dsh verification passes the
+ * vendored family's pack output too, while publishing only its own
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ *
+ * What this proves is that `files` selected a complete payload and that the
+ * published dependency ranges resolve. A workspace link or a stale `lib/` in the
+ * checkout cannot stand in for a missing file here.
+ */
+
+import { mkdtempSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { parseArgs } from 'node:util'
+import { releaseFamily } from './families.ts'
+import { capture, isEntry } from './process.ts'
+import { packedIdentity } from './tarball.ts'
+
+/**
+ * Environment for the installed artifact: no host Node hooks, no host DeepSeek
+ * Harness home, and no ambient npm user agent that would confuse npm.
+ * @param consumerRoot - the throwaway consumer directory.
+ * @returns The child environment.
+ */
+function consumerEnvironment(consumerRoot: string): NodeJS.ProcessEnv {
+  const environment = { ...process.env }
+  delete environment.npm_config_user_agent
+  delete environment.NPM_CONFIG_USER_AGENT
+  delete environment.NODE_OPTIONS
+  delete environment.NODE_PATH
+  environment.DSH_HOME = resolve(consumerRoot, '.dsh')
+  environment.DSH_AGENTS_HOME = resolve(consumerRoot, '.agents')
+  environment.DSH_TELEMETRY_DISABLED = '1'
+  return environment
+}
+
+/**
+ * Every packed tarball in the given directories, as `file:` dependency entries.
+ *
+ * The directories are read by their contents rather than a pack order file: a
+ * directory here can hold tarballs packed only to satisfy a cross-sequence
+ * dependency, which no release order describes.
+ * @param directories - absolute directories holding packed tarballs.
+ * @returns Package name to tarball file URL, and the version each carries.
+ */
+function packedDependencies(directories: readonly string[]): Map<string, { url: string; version: string }> {
+  const dependencies = new Map<string, { url: string; version: string }>()
+  for (const directory of directories) {
+    const tarballs = readdirSync(directory).filter(name => name.endsWith('.tgz')).sort()
+    if (tarballs.length === 0) throw new Error(`${directory} holds no packed tarball`)
+    for (const filename of tarballs) {
+      const tarball = join(directory, filename)
+      const { name, version } = packedIdentity(tarball)
+      dependencies.set(name, { url: pathToFileURL(tarball).href, version })
+    }
+  }
+  return dependencies
+}
+
+/** Install every tarball under `--from` and drive the `--family` entry. */
+function main(): void {
+  const { values } = parseArgs({
+    options: { family: { type: 'string' }, from: { type: 'string', multiple: true } },
+    allowPositionals: false,
+  })
+  if (values.family === undefined || values.from === undefined || values.from.length === 0) {
+    throw new Error('usage: verify-packed-install.ts --family <dsh|vendor> --from <packed directory> [--from ...]')
+  }
+
+  const family = releaseFamily(values.family)
+  const entry = family.installedEntry
+  if (entry === undefined) {
+    console.log(`release verify-packed-install: family ${family.id} publishes no executable, nothing to drive`)
+    return
+  }
+
+  const root = process.cwd()
+  const packed = packedDependencies(values.from.map(directory => resolve(root, directory)))
+  const expected = packed.get(entry.packageName)
+  if (expected === undefined) throw new Error(`${entry.packageName} is not among the packed tarballs`)
+
+  const consumerRoot = mkdtempSync(join(tmpdir(), `dsh-packed-${family.id}-`))
+  try {
+    writeFileSync(join(consumerRoot, 'package.json'), `${JSON.stringify({
+      name: `dsh-packed-install-${family.id}`,
+      version: '0.0.0',
+      private: true,
+      dependencies: Object.fromEntries([...packed].map(([name, entryPacked]) => [name, entryPacked.url])),
+    }, null, 2)}\n`)
+
+    const environment = consumerEnvironment(consumerRoot)
+    console.log(`release verify-packed-install: installing ${String(packed.size)} tarball(s) into ${consumerRoot}`)
+    // Optional dependencies are omitted: the Landlock platform packages behind
+    // them need a musl toolchain and one build per architecture, and a consumer
+    // that cannot install them must still start — which is what optional means
+    // here. Their entry package is a plain dependency of dsh-sandbox-local, so
+    // its tarball is supplied through --from.
+    capture('npm', ['install', '--no-audit', '--no-fund', '--package-lock=false', '--omit=optional'],
+      { cwd: consumerRoot, env: environment })
+
+    const bin = join(consumerRoot, 'node_modules', ...entry.packageName.split('/'), entry.binPath)
+    const version = capture(process.execPath, [bin, '--version'], { cwd: consumerRoot, env: environment })
+    if (version !== expected.version) {
+      throw new Error(`installed ${entry.packageName} --version reported ${JSON.stringify(version)}, expected ${expected.version}`)
+    }
+    console.log(`release verify-packed-install: installed ${entry.packageName} reports ${version}`)
+  } finally {
+    rmSync(consumerRoot, { recursive: true, force: true })
+  }
+}
+
+if (isEntry(import.meta.url)) main()

scripts/release/verify.ts

@@ -0,0 +1,70 @@
+/**
+ * Verify a release family's version baseline, and — when publishing — that the
+ * run comes from the family's tag and its members are publishable.
+ *
+ * Publication happens only from GitHub Actions, so the tag and publishability
+ * checks are gates on the workflow, not advisory local warnings
+ * ([rationale](../../.agents/notes/implemented/process/2026-08-10-npm-release-sequences.md)).
+ */
+
+import { parseArgs } from 'node:util'
+import { isEntry } from './process.ts'
+import { releaseFamily, type ReleaseFamily, type ReleaseMember } from './families.ts'
+
+/**
+ * Assert every member may be published: npm refuses a `private` package.
+ * @param members - the family's members.
+ */
+function verifyPublishable(members: readonly ReleaseMember[]): void {
+  const priv = members.filter(member => member.manifest.private === true)
+  if (priv.length > 0) {
+    throw new Error(`publishing requires removing "private": true from:\n${priv.map(member => member.directory).join('\n')}`)
+  }
+}
+
+/**
+ * Assert the workflow runs from a tag this family publishes from, and that the
+ * tag names a version the family actually carries.
+ * @param family - the release family.
+ * @param members - the family's members.
+ * @param ref - the `GITHUB_REF` value.
+ */
+function verifyTag(family: ReleaseFamily, members: readonly ReleaseMember[], ref: string): void {
+  const prefix = 'refs/tags/'
+  if (!ref.startsWith(prefix)) {
+    throw new Error(`publishing release family ${family.id} requires running from a ${family.tagPrefix}* tag, got ${ref || '(no ref)'}`)
+  }
+  const tag = ref.slice(prefix.length)
+  if (!tag.startsWith(family.tagPrefix)) {
+    throw new Error(`tag ${tag} does not belong to release family ${family.id} (expected ${family.tagPrefix}*)`)
+  }
+  const expected = members.map(member => family.tagFor(member))
+  if (!expected.includes(tag)) {
+    throw new Error(`tag ${tag} names no version this family carries; its members would tag as:\n${[...new Set(expected)].join('\n')}`)
+  }
+}
+
+/** Run the verification for the family named by `--family`. */
+function main(): void {
+  const { values } = parseArgs({
+    options: { family: { type: 'string' } },
+    allowPositionals: false,
+  })
+  if (values.family === undefined) throw new Error('usage: verify.ts --family <dsh|vendor>')
+
+  const family = releaseFamily(values.family)
+  const members = family.members(process.cwd())
+  family.verifyVersions(members)
+
+  const publishing = process.env.RELEASE_PUBLISH === 'true'
+  if (publishing) {
+    verifyPublishable(members)
+    verifyTag(family, members, process.env.GITHUB_REF ?? '')
+  }
+
+  const versions = [...new Set(members.map(member => member.version))]
+  const summary = versions.length === 1 ? versions[0] : `${String(versions.length)} versions`
+  console.log(`release verify: family ${family.id}, ${String(members.length)} member(s), ${summary}${publishing ? ', publish gates passed' : ''}`)
+}
+
+if (isEntry(import.meta.url)) main()

scripts/rescope-vendor.spec.ts

@@ -0,0 +1,41 @@
+/**
+ * Acceptance-path coverage for the rescope codemod's exact-edit classifier: a
+ * duplicated insertion — what a non-idempotent apply produces — must be
+ * rejected rather than applied again.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { exactEditState } from './rescope-vendor.ts'
+
+const ANCHOR = '\n## Sync procedure'
+const INSERTED = `\n15. **rescope**: one log entry.\n${ANCHOR}`
+
+describe('exactEditState', () => {
+  it('classifies an insertion by its target form, so a duplicate is invalid', () => {
+    expect(exactEditState(`log\n${ANCHOR}\n`, ANCHOR, INSERTED, 1)).toBe('pending')
+    expect(exactEditState(`log${INSERTED}\n`, ANCHOR, INSERTED, 1)).toBe('applied')
+    // The anchor survives an insertion, so counting the source form would have
+    // called this pending and inserted the entry a second time.
+    expect(exactEditState(`log${INSERTED}${INSERTED}\n`, ANCHOR, INSERTED, 1)).toBe('invalid')
+    expect(exactEditState('log\n', ANCHOR, INSERTED, 1)).toBe('invalid')
+  })
+
+  it('classifies a deletion by its source form, and requires its remainder to survive', () => {
+    const remainder = 'exclude:\n'
+    const withEntries = 'exclude:\n  - cordis@4\n'
+    expect(exactEditState(withEntries, withEntries, remainder, 1)).toBe('pending')
+    expect(exactEditState(remainder, withEntries, remainder, 1)).toBe('applied')
+    // Upstream dropped the whole field: the source form is gone, but so is the
+    // remainder, so this is a moved site rather than a completed deletion.
+    expect(exactEditState('unrelated:\n', withEntries, remainder, 1)).toBe('invalid')
+  })
+
+  it('requires a replacement to leave no source form and the exact target count', () => {
+    expect(exactEditState('a = 1\n', 'a = 1', 'b = 2', 1)).toBe('pending')
+    expect(exactEditState('b = 2\n', 'a = 1', 'b = 2', 1)).toBe('applied')
+    expect(exactEditState('b = 2\nb = 2\n', 'a = 1', 'b = 2', 1)).toBe('invalid')
+    // A moved or partially applied site: neither state is complete.
+    expect(exactEditState('a = 1\nb = 2\n', 'a = 1', 'b = 2', 1)).toBe('invalid')
+    expect(exactEditState('x\n', 'a = 1', 'b = 2', 1)).toBe('invalid')
+  })
+})

scripts/rescope-vendor.ts

@@ -0,0 +1,695 @@
+/**
+ * Rescope the vendored Cordis packages into the `@deepseek-ai` scope, and undo
+ * that rescope with `--reverse`. Every harness package declares `cordis` as a
+ * peer dependency, so publication carries this framework layer too; publishing
+ * it under the upstream names would squat them on the registry
+ * ([rationale](../.agents/notes/implemented/process/2026-08-10-vendor-package-rescope.md),
+ * [name mapping](../docs/rescope.md)).
+ *
+ * The generic pass rewrites ONLY delimited, complete package-name tokens:
+ * `'old'` / `"old"` / `` `old` `` / `'old/subpath'`, plus a YAML `name: old`
+ * scalar. A match needs a quote (or `name: `) immediately left and the matching
+ * quote — optionally after a `/subpath` — immediately right, which excludes
+ * `cordis.yml`, the Loader's `cordis:` builtin prefix, `cordis-config-entry`,
+ * `@deepseek-ai/dsh-tool-cordis`, and `cordiverse/cordis`, and makes the
+ * rewrite idempotent because the scoped name's `cordis` is preceded by `/`.
+ * Markdown follows the rename inside every fence, and in `docs/` prose too:
+ * a tutorial that teaches an unresolvable name is wrong, while prose elsewhere
+ * records what was true when it was written.
+ *
+ * Sites the token rule cannot express (dot-notation access, unquoted object
+ * keys, regex literals, the vendored-manifest table) are listed in
+ * {@link EXACT_EDITS} with an exact hit count, so an upstream change to one of
+ * them fails loudly instead of being silently skipped.
+ *
+ * Usage: `pnpm run rescope-vendor [--apply|--check] [--reverse]`. Without a
+ * mode it reports what would change. `--check` asserts the post-state: no
+ * residue, every exact edit landed, every postcondition holds, and a second
+ * `--apply` would be a no-op.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** One vendored package's directory, upstream npm name, and rescoped name. */
+interface Rename {
+  readonly directory: string
+  readonly upstream: string
+  readonly scoped: string
+}
+
+/** The mapping this codemod applies; `vendor/README.md` carries the same table. */
+const RENAMES: readonly Rename[] = [
+  { directory: 'cordis', upstream: 'cordis', scoped: '@deepseek-ai/cordis' },
+  { directory: 'cosmokit', upstream: 'cosmokit', scoped: '@deepseek-ai/cosmokit' },
+  { directory: 'schemastery', upstream: 'schemastery', scoped: '@deepseek-ai/schemastery' },
+  { directory: 'loader', upstream: '@cordisjs/plugin-loader', scoped: '@deepseek-ai/cordis-plugin-loader' },
+  { directory: 'include', upstream: '@cordisjs/plugin-include', scoped: '@deepseek-ai/cordis-plugin-include' },
+  { directory: 'group', upstream: '@cordisjs/plugin-group', scoped: '@deepseek-ai/cordis-plugin-group' },
+  { directory: 'timer', upstream: '@cordisjs/plugin-timer', scoped: '@deepseek-ai/cordis-plugin-timer' },
+  { directory: 'hmr', upstream: '@cordisjs/plugin-hmr', scoped: '@deepseek-ai/cordis-plugin-hmr' },
+  { directory: 'logger-console', upstream: '@cordisjs/plugin-logger-console', scoped: '@deepseek-ai/cordis-plugin-logger-console' },
+]
+
+const EXTENSIONS = ['.ts', '.tsx', '.js', '.mjs', '.cjs', '.tpl', '.json', '.yml', '.yaml', '.md'] as const
+
+/** An exact-string edit the token rule cannot express, with its required hit count. */
+interface ExactEdit {
+  readonly id: string
+  readonly file: string
+  readonly find: string
+  readonly replace: string
+  readonly expect: number
+}
+
+/**
+ * A file where an upstream name also appears as a vendor DIRECTORY name or an
+ * upstream runtime identifier: the generic pass is disabled for the listed
+ * names and {@link EXACT_EDITS} renames the real package-name occurrences.
+ */
+interface GenericSkip {
+  readonly file: string
+  readonly upstream: readonly string[]
+}
+
+const GENERIC_SKIPS: readonly GenericSkip[] = [
+  // `vendorPackages` lists vendor/ directory names, joined with 'vendor' below it.
+  { file: 'packages/examples/acp-demo/tests/built-bin.e2e.ts', upstream: ['cordis', 'cosmokit', 'schemastery'] },
+  // `Symbol.for('schemastery')` and the `vendor:` metadata field are upstream identifiers.
+  { file: 'vendor/schemastery/src/index.ts', upstream: ['schemastery'] },
+  // Asserts the vendored-manifest table, which gains an upstream-name column.
+  { file: 'scripts/gen-third-party-notices.spec.ts', upstream: RENAMES.map(rename => rename.upstream) },
+  // `cordis` is also an agent-preset id — the directory name under
+  // apps/cli/config/agent-presets/ — so in these files the bare name is
+  // product data, not a package reference. Renaming it changed which preset
+  // the creator flow stages and which id the roster reports.
+  { file: 'packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx', upstream: ['cordis'] },
+  { file: 'packages/client/ui-agent-preset/src/client/index.ts', upstream: ['cordis'] },
+  { file: 'packages/client/ui-agent-preset/tests/apply.spec.ts', upstream: ['cordis'] },
+  { file: 'packages/client/ui-agent-preset/tests/locales.spec.ts', upstream: ['cordis'] },
+  { file: 'packages/client/ui-agent-preset/tests/section.spec.tsx', upstream: ['cordis'] },
+  { file: 'apps/cli/tests/web-agent-presets.e2e.ts', upstream: ['cordis'] },
+  { file: 'apps/web/tests/agent-preset-authoring.e2e.ts', upstream: ['cordis'] },
+  { file: 'packages/preset/agent-presets/tests/session.spec.ts', upstream: ['cordis'] },
+  // The preset's own composition: its header comment and its system prompt name
+  // the preset a model mounts, so the scoped name would send the model after an
+  // id no roster reports.
+  { file: 'apps/cli/config/agent-presets/cordis/agent.cordis.yml', upstream: ['cordis'] },
+  // GROUP_ORDER holds `packages/<group>/` directory names, not package names.
+  { file: 'scripts/gen-module-graph.ts', upstream: ['cordis'] },
+  { file: 'scripts/gen-doc-graphs.ts', upstream: ['cordis'] },
+]
+
+/** A string that must appear exactly `count` times once the rescope has run. */
+interface PostCondition {
+  readonly file: string
+  readonly text: string
+  readonly count: number
+}
+
+const POSTCONDITIONS: readonly PostCondition[] = [
+  { file: 'vendor/cordis/package.json', text: '"name": "@deepseek-ai/cordis"', count: 1 },
+  { file: 'vendor/hmr/package.json', text: '"name": "@deepseek-ai/cordis-plugin-hmr"', count: 1 },
+  { file: 'scripts/cordis-walk.ts', text: '@deepseek-ai\\/cordis', count: 1 },
+  { file: 'scripts/cordis-walk.ts', text: '!== \'@deepseek-ai/cordis\'', count: 1 },
+  { file: 'scripts/gen-scoped-events.ts', text: '=== \'@deepseek-ai/cordis\'', count: 1 },
+  { file: 'packages/typert/generator/src/analyzer.ts', text: '!== \'@deepseek-ai/cordis\'', count: 2 },
+  { file: 'scripts/check-workspace-constraints.ts', text: '?.[\'@deepseek-ai/cordis\']', count: 2 },
+  { file: 'packages/boot/app-boot/tsdown.config.ts', text: '[\'@deepseek-ai/cordis-plugin-include\']', count: 1 },
+  { file: 'tsconfig.base.json', text: '"@deepseek-ai/cordis-plugin-loader": ["./vendor/loader/src"]', count: 1 },
+  // One insertion, once: a duplicated log entry is what a non-idempotent apply produced.
+  { file: 'vendor/README.md', text: '17. **`@deepseek-ai` rescope**', count: 1 },
+  { file: 'knip.json', text: '@cordisjs', count: 0 },
+  { file: 'pnpm-workspace.yaml', text: '[email protected]', count: 0 },
+  // The preset ids in this table are product data, not package names.
+  { file: 'packages/client/ui-agent-preset/tests/locales.spec.ts', text: '[\'cordis\', \'presetCordisName\'', count: 1 },
+  // The preset id the shipped composition documents to its own model.
+  { file: 'apps/cli/config/agent-presets/cordis/agent.cordis.yml', text: 'The `cordis` agent preset', count: 1 },
+  { file: 'apps/cli/config/agent-presets/cordis/agent.cordis.yml', text: 'corrupting the `cordis` preset', count: 1 },
+  { file: 'packages/examples/acp-demo/tests/built-bin.e2e.ts', text: '\'cordis\', \'loader\', \'include\', \'timer\', \'hmr\', \'logger-console\',', count: 1 },
+]
+
+/**
+ * Every exact edit, in application order. Each `find` is written against the
+ * PRE-rename text because these run before the generic pass, so no `find` may
+ * quote a neighbouring line the generic pass would rewrite.
+ */
+const EXACT_EDITS: readonly ExactEdit[] = [
+  {
+    id: 'cordis-walk-merge-head',
+    file: 'scripts/cordis-walk.ts',
+    find: 'const MERGE_HEAD = /declare module [\'"](?:cordis|\\.\\/context\\.ts)[\'"]/',
+    replace: 'const MERGE_HEAD = /declare module [\'"](?:@deepseek-ai\\/cordis|\\.\\/context\\.ts)[\'"]/',
+    expect: 1,
+  },
+  {
+    id: 'constraints-manifest-lookup',
+    file: 'scripts/check-workspace-constraints.ts',
+    find: `    const peer = manifest.peerDependencies?.cordis
+    const dev = manifest.devDependencies?.cordis
+
+    if (!peer) errors.push(\`\${label}: cordis must be a peerDependency\`)
+    if (!dev) errors.push(\`\${label}: cordis must also be a devDependency\`)
+    if (peer && dev && peer !== dev) {
+      errors.push(\`\${label}: cordis peer (\${peer}) and dev (\${dev}) ranges must match\`)`,
+    replace: `    const peer = manifest.peerDependencies?.['@deepseek-ai/cordis']
+    const dev = manifest.devDependencies?.['@deepseek-ai/cordis']
+
+    if (!peer) errors.push(\`\${label}: @deepseek-ai/cordis must be a peerDependency\`)
+    if (!dev) errors.push(\`\${label}: @deepseek-ai/cordis must also be a devDependency\`)
+    if (peer && dev && peer !== dev) {
+      errors.push(\`\${label}: @deepseek-ai/cordis peer (\${peer}) and dev (\${dev}) ranges must match\`)`,
+    expect: 1,
+  },
+  {
+    // The rescoped name is already covered by the `@deepseek-ai/.+` pattern beside it.
+    id: 'knip-logger-console',
+    file: 'knip.json',
+    find: `      "ignoreDependencies": [
+        "@cordisjs/plugin-logger-console",
+        "@deepseek-ai/.+"
+      ]
+    },
+    "packages/util/home": {`,
+    replace: `      "ignoreDependencies": [
+        "@deepseek-ai/.+"
+      ]
+    },
+    "packages/util/home": {`,
+    expect: 1,
+  },
+  {
+    id: 'knip-bundle-base',
+    file: 'knip.json',
+    find: `    "packages/bundle/base": {
+      "ignoreDependencies": [
+        "@deepseek-ai/.+",
+        "@cordisjs/.+"
+      ]`,
+    replace: `    "packages/bundle/base": {
+      "ignoreDependencies": [
+        "@deepseek-ai/.+"
+      ]`,
+    expect: 1,
+  },
+  {
+    // Rescoped packages are never fetched from a registry, so the exclusion is dead config.
+    id: 'pnpm-release-age',
+    file: 'pnpm-workspace.yaml',
+    find: `minimumReleaseAgeExclude:
+  # Cordis release candidates are source-vendored and pinned in vendor/README.md
+  # during the same-day sync that updates package manifests and the lockfile.
+  - '@cordisjs/[email protected]'
+  - cordis@4.0.0-rc.7
+`,
+    replace: 'minimumReleaseAgeExclude:\n',
+    expect: 1,
+  },
+  {
+    id: 'publication-set-scope-assertion',
+    file: 'scripts/publish-npm-baseline.ts',
+    find: '      if (!isVendored && !name.startsWith(\'@deepseek-ai/\')) {',
+    replace: `      // Vendored packages are rescoped too (vendor/README.md), so publication
+      // never carries an upstream name that would squat it on the registry.
+      if (!name.startsWith('@deepseek-ai/')) {`,
+    expect: 1,
+  },
+  {
+    id: 'vendor-readme-preamble',
+    file: 'vendor/README.md',
+    find: 'All vendored packages keep their **original npm names** and are marked `private: true` — they are never published from this repo. `pnpm-workspace.yaml#linkWorkspacePackages` makes matching upstream semver ranges resolve these pinned workspaces, including imports from built `lib/`; disabling it substitutes npm copies behind the same names.',
+    replace: 'All vendored packages are **renamed into the `@deepseek-ai` scope** (`cordis` → `@deepseek-ai/cordis`, `@cordisjs/plugin-<x>` → `@deepseek-ai/cordis-plugin-<x>`): every harness package declares `cordis` as a peer dependency, so publishing the harness publishes this framework layer too, and a publication under the upstream names would squat them on the registry. Directory names and upstream version numbers are deliberately unchanged, so the manifest below still reads as an upstream snapshot. `pnpm-workspace.yaml#linkWorkspacePackages` makes those preserved semver ranges resolve these pinned workspaces, including imports from built `lib/`.',
+    expect: 1,
+  },
+  {
+    id: 'vendor-readme-schemastery-note',
+    file: 'vendor/README.md',
+    find: 'whose lazy `require(\'cosmokit\')` can race',
+    replace: 'whose lazy `require(\'@deepseek-ai/cosmokit\')` can race',
+    expect: 1,
+  },
+  {
+    id: 'vendor-readme-table-head',
+    file: 'vendor/README.md',
+    find: '| Directory | npm name | Version | Upstream repo | Commit |\n|---|---|---|---|---|',
+    replace: '| Directory | npm name | Upstream name | Version | Upstream repo | Commit |\n|---|---|---|---|---|---|',
+    expect: 1,
+  },
+  {
+    id: 'vendor-readme-local-modification-log',
+    file: 'vendor/README.md',
+    find: '\n16. **`cordis/package.json` publishes `src`**',
+    replace: '\n16. **`cordis/package.json` publishes `src`**: added `src` to the `files` list, joining the other eight vendored packages. Cordis declares `"./src/*": "./src/*"` in its exports, so a tarball without `src` publishes an export map pointing at absent files; the release change judgement also reads `files` to decide whether a diff reaches the payload, and a package whose only published paths are build output has no tracked path to match.\n17. **`@deepseek-ai` rescope**: every vendored manifest `name`, every internal dependency entry among the vendored set, and every module specifier that reaches them use the scoped names in the manifest table\'s `npm name` column. Directory names, version numbers, and dependency ranges are unchanged, and no upstream runtime identifier is renamed — `Symbol.for(\'schemastery\')` and Schemastery\'s `vendor:` metadata field keep their upstream values. Re-apply with `pnpm run rescope-vendor --apply` after a sync; the table\'s two name columns are the mapping, restated for consumers in [docs/rescope.md](../docs/rescope.md).',
+    expect: 1,
+  },
+  {
+    // A plain fence listing the bundle's mounted tree: a bare token, no quotes.
+    id: 'agent-spine-demo-mounted-tree',
+    file: 'packages/examples/agent-spine-demo/README.md',
+    find: '@cordisjs/plugin-timer            timer service',
+    replace: '@deepseek-ai/cordis-plugin-timer  timer service',
+    expect: 1,
+  },
+  {
+    id: 'agent-spine-demo-mounted-tree-zh',
+    file: 'packages/examples/agent-spine-demo/README.zh.md',
+    find: '@cordisjs/plugin-timer            timer service',
+    replace: '@deepseek-ai/cordis-plugin-timer  timer service',
+    expect: 1,
+  },
+  {
+    // The root contract claimed vendored packages keep their upstream names.
+    id: 'root-agents-vendored-name-contract',
+    file: 'AGENTS.md',
+    find: 'vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.',
+    replace: 'vendored packages are rescoped ([mapping](docs/rescope.md)) and `private: true`. `@deepseek-ai/cordis` is a peerDependency (+ dev) of every harness package.',
+    expect: 1,
+  },
+  {
+    // The client purity gate reads `@deepseek-ai/` as "another plugin package".
+    // The rescope moves the vendored framework and its libraries into that
+    // namespace, where the gate would reject the library imports client
+    // bundles have always inlined, so it needs their names.
+    id: 'client-purity-vendored-libraries',
+    file: 'packages/client/tsdown.client.ts',
+    find: '/** Generated descriptor/codec contribution with no shared runtime identity. */',
+    replace: `/**
+ * Vendored framework libraries: rescoped into @deepseek-ai, so the gate below
+ * would read them as plugin packages. They carry no cross-plugin runtime
+ * identity to share — the framework itself is a platform module (external),
+ * while these are ordinary libraries a browser bundle inlines.
+ */
+const VENDORED_LIBRARY = /^@deepseek-ai\\/(cosmokit|schemastery)(\\/|$)/
+
+/** Generated descriptor/codec contribution with no shared runtime identity. */`,
+    expect: 1,
+  },
+  {
+    id: 'client-purity-vendored-libraries-predicate',
+    file: 'packages/client/tsdown.client.ts',
+    find: '        if (INLINE_SAFE.test(source) || GENERATED_REMOTE.test(source)) return null // wire contribution: inline is the point',
+    replace: `        if (VENDORED_LIBRARY.test(source)) return null // vendored library: inline, no shared identity
+        if (INLINE_SAFE.test(source) || GENERATED_REMOTE.test(source)) return null // wire contribution: inline is the point`,
+    expect: 1,
+  },
+  {
+    // The step-1 file tree told the reader to keep the upstream name, one
+    // paragraph above the invariant that says to rescope it.
+    id: 'vendoring-cookbook-tree-comment',
+    file: 'docs/cookbook/adding-a-vendored-package.md',
+    find: '  package.json     # from upstream; set "private": true, keep name/exports/type',
+    replace: '  package.json     # from upstream; set "private": true, rescope the name, keep exports/type',
+    expect: 1,
+  },
+  {
+    id: 'vendoring-cookbook-tree-comment-zh',
+    file: 'docs/cookbook/adding-a-vendored-package.zh.md',
+    find: '  package.json     # from upstream; set "private": true, keep name/exports/type',
+    replace: '  package.json     # from upstream; set "private": true, rescope the name, keep exports/type',
+    expect: 1,
+  },
+  {
+    // The checklist told the next vendoring to keep upstream's name.
+    id: 'vendoring-cookbook-name-invariant',
+    file: 'docs/cookbook/adding-a-vendored-package.md',
+    find: "keep upstream's `name`/`version`/`exports`/`type`",
+    replace: "rescope the `name` ([mapping](../rescope.md)) while keeping upstream's `version`/`exports`/`type`",
+    expect: 1,
+  },
+  {
+    id: 'vendoring-cookbook-name-invariant-zh',
+    file: 'docs/cookbook/adding-a-vendored-package.zh.md',
+    find: '保留上游的 `name`/`version`/`exports`/`type`',
+    replace: '改写 `name` 的 scope（[映射](../rescope.md)），保留上游的 `version`/`exports`/`type`',
+    expect: 1,
+  },
+  {
+    // The real package references in files whose other `cordis` strings are preset ids.
+    id: 'agent-preset-spec-framework-import',
+    file: 'packages/client/ui-agent-preset/tests/apply.spec.ts',
+    find: "import { Context } from 'cordis'",
+    replace: "import { Context } from '@deepseek-ai/cordis'",
+    expect: 1,
+  },
+  {
+    id: 'web-agent-presets-e2e-framework-import',
+    file: 'apps/cli/tests/web-agent-presets.e2e.ts',
+    find: "import { Context } from 'cordis'",
+    replace: "import { Context } from '@deepseek-ai/cordis'",
+    expect: 1,
+  },
+  {
+    id: 'notices-vendored-row-type',
+    file: 'scripts/gen-third-party-notices.ts',
+    find: `export interface VendoredRow {
+  npmName: string
+  upstream: string
+}`,
+    replace: `export interface VendoredRow {
+  npmName: string
+  /** The name this package carries upstream; MIT attribution names the fork's origin, not our scope. */
+  upstreamName: string
+  upstream: string
+}`,
+    expect: 1,
+  },
+  {
+    id: 'notices-vendored-row-parse',
+    file: 'scripts/gen-third-party-notices.ts',
+    find: `    const match = /^\\| \\x60\\S+\\/\\x60 \\| \\x60([^\\x60]+)\\x60 \\| \\S+ \\| (https:\\/\\/\\S+?)(?: \\([^)]*\\))? \\| \\x60[0-9a-f]+\\x60 \\|$/.exec(line)
+    if (match === null) continue
+    const [, npmName, upstream] = match
+    if (npmName === undefined || upstream === undefined) continue
+    rows.push({ npmName, upstream })`,
+    replace: `    const match = new RegExp(String.raw\`^\\| \\x60\\S+\\/\\x60 \\| \\x60([^\\x60]+)\\x60 \\| \\x60([^\\x60]+)\\x60 \\| \\S+ \\| \`
+      + String.raw\`(https:\\/\\/\\S+?)(?: \\([^)]*\\))? \\| \\x60[0-9a-f]+\\x60 \\|$\`).exec(line)
+    if (match === null) continue
+    const [, npmName, upstreamName, upstream] = match
+    if (npmName === undefined || upstreamName === undefined || upstream === undefined) continue
+    rows.push({ npmName, upstreamName, upstream })`,
+    expect: 1,
+  },
+  {
+    id: 'notices-vendored-section',
+    file: 'scripts/gen-third-party-notices.ts',
+    find: 'The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm. All are MIT-licensed',
+    replace: 'The Cordis framework and its foundation libraries are source-vendored into this repository rather than consumed from npm, and republished under the \\`@deepseek-ai\\` scope. All are MIT-licensed',
+    expect: 1,
+  },
+  {
+    id: 'notices-vendored-table',
+    file: 'scripts/gen-third-party-notices.ts',
+    find: `| Package | Upstream | License |
+| --- | --- | --- |
+\${vendored.map(row => \`| \\\`\${row.npmName}\\\` | [\${row.upstream.replace('https://', '')}](\${row.upstream}) | MIT |\`).join('\\n')}`,
+    replace: `| Package | Upstream name | Upstream | License |
+| --- | --- | --- | --- |
+\${vendored.map(row => \`| \\\`\${row.npmName}\\\` | \\\`\${row.upstreamName}\\\` | [\${row.upstream.replace('https://', '')}](\${row.upstream}) | MIT |\`).join('\\n')}`,
+    expect: 1,
+  },
+  {
+    id: 'notices-spec-row-fixture',
+    file: 'scripts/gen-third-party-notices.spec.ts',
+    find: '    expect(rows).toContainEqual({ npmName: \'cordis\', upstream: \'https://github.com/cordiverse/cordis\' })',
+    replace: `    expect(rows).toContainEqual({
+      npmName: '@deepseek-ai/cordis',
+      upstreamName: 'cordis',
+      upstream: 'https://github.com/cordiverse/cordis',
+    })`,
+    expect: 1,
+  },
+  {
+    id: 'notices-spec-shape-fixture',
+    file: 'scripts/gen-third-party-notices.spec.ts',
+    find: 'parseVendoredRows(\'| `cordis/` | cordis | 4.0.0 | https://example.com | `abc123` |\\n\')',
+    replace: 'parseVendoredRows(\'| `cordis/` | `@deepseek-ai/cordis` | cordis | 4.0.0 | https://example.com | `abc123` |\\n\')',
+    expect: 1,
+  },
+  {
+    // The framework peer is no longer a registry name, so the rehearsal must install this
+    // repository's vendored copies; cosmokit comes along as cordis's own dependency.
+    id: 'packed-install-vendored-peer',
+    file: 'packages/sandbox/sandbox-local/tests/packed-install.e2e.ts',
+    find: `  'packages/support/invariants',
+]`,
+    replace: `  'packages/support/invariants',
+  // The framework and the vendored packages the closure declares outright:
+  // rescoped into @deepseek-ai, so the consumer installs this repository's
+  // copies. Schemastery is a hard dependency of three members above, not a
+  // peer, so npm resolves it while installing them.
+  'vendor/cordis',
+  'vendor/cosmokit',
+  'vendor/schemastery',
+]`,
+    expect: 1,
+  },
+  {
+    id: 'packed-install-registry-spec',
+    file: 'packages/sandbox/sandbox-local/tests/packed-install.e2e.ts',
+    find: `    // Peer ranges resolve to the tarballs; Cordis is pinned to their peer range. Do not omit optional
+    // dependencies because the launcher selects its OS/CPU package through one.
+    writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ name: 'dsh-packed-consumer', private: true, type: 'module' }))
+    const install = spawnSync('npm', ['install', '--no-audit', '--no-fund', ...tarballs, '[email protected]'], {`,
+    replace: `    // Peer ranges resolve to the tarballs, the framework peer included. Do not omit optional
+    // dependencies because the launcher selects its OS/CPU package through one.
+    writeFileSync(join(consumerDir, 'package.json'), JSON.stringify({ name: 'dsh-packed-consumer', private: true, type: 'module' }))
+    const install = spawnSync('npm', ['install', '--no-audit', '--no-fund', ...tarballs], {`,
+    expect: 1,
+  },
+  {
+    id: 'packed-install-module-doc',
+    file: 'packages/sandbox/sandbox-local/tests/packed-install.e2e.ts',
+    find: ` * Keyless publish-path rehearsal. It packs the provider, its workspace peers, and the current
+ * repository's Landlock entry/platform packages, then installs those exact tarballs in an external
+ * plain-Node consumer. The host launcher comes from the exact local tarballs, so no registry copy,
+ * tsx, path mapping, or workspace resolution can hide missing files, dependency errors, or lost
+ * executable modes.`,
+    replace: ` * Keyless publish-path rehearsal. It packs the provider, its workspace peers, the vendored framework
+ * peer, and the current repository's Landlock entry/platform packages, then installs those exact
+ * tarballs in an external plain-Node consumer. The host launcher comes from the exact local tarballs,
+ * so no registry copy, tsx, path mapping, or workspace resolution can hide missing files, dependency
+ * errors, or lost executable modes.`,
+    expect: 1,
+  },
+  // The manifest table's name column plus the new upstream-name column, one edit per row.
+  ...RENAMES.map(rename => ({
+    id: `vendor-readme-row-${rename.directory}`,
+    file: 'vendor/README.md',
+    find: `| \`${rename.directory}/\` | \`${rename.upstream}\` | `,
+    replace: `| \`${rename.directory}/\` | \`${rename.scoped}\` | \`${rename.upstream}\` | `,
+    expect: 1,
+  })),
+]
+
+/** Files the rescope must never rewrite. */
+function excluded(file: string): boolean {
+  if (file === 'scripts/rescope-vendor.ts') return true // the mapping itself
+  if (file.startsWith('.agents/notes/')) return true // notes record what was true when written
+  // Recorded model payloads quote documentation verbatim, so they must mirror the
+  // sources on disk — including the notes this rescope leaves alone.
+  if (file.startsWith('scripts/snapshots/')) return true
+  // The mapping documents state both names on purpose.
+  if (file === 'docs/rescope.md' || file === 'docs/rescope.zh.md') return true
+  if (file.endsWith('.i18n.yaml')) return true // blob-hash records, re-recorded by the pairing gate
+  if (file === 'pnpm-lock.yaml') return true // regenerated by pnpm install
+  if (/^vendor\/[^/]+\/(README\.md|LICENSE)$/.test(file)) return true // upstream files kept verbatim
+  return !EXTENSIONS.some(extension => file.endsWith(extension))
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+}
+
+/** One name's rewrite, precompiled for both delimited forms. */
+interface Pattern {
+  readonly upstream: string
+  readonly from: string
+  readonly to: string
+  readonly token: RegExp
+  readonly yamlName: RegExp
+}
+
+function patterns(reverse: boolean): Pattern[] {
+  return RENAMES
+    .map(rename => ({
+      upstream: rename.upstream,
+      from: reverse ? rename.scoped : rename.upstream,
+      to: reverse ? rename.upstream : rename.scoped,
+    }))
+    .sort((left, right) => right.from.length - left.from.length)
+    .map(rename => ({
+      ...rename,
+      token: new RegExp(`(['"\`])${escapeRegExp(rename.from)}((?:/[^'"\`\\s]*)?)\\1`, 'g'),
+      yamlName: new RegExp(`^(\\s*(?:-\\s*)?name:[ \\t]+)${escapeRegExp(rename.from)}([ \\t]*(?:#.*)?)$`, 'gm'),
+    }))
+}
+
+function skipped(file: string, pattern: Pattern): boolean {
+  return GENERIC_SKIPS.some(skip => skip.file === file && skip.upstream.includes(pattern.upstream))
+}
+
+function rewriteLine(line: string, file: string, all: readonly Pattern[]): string {
+  let out = line
+  for (const pattern of all) {
+    if (skipped(file, pattern)) continue
+    out = out.replace(pattern.token, (_match, quote: string, subpath: string) => `${quote}${pattern.to}${subpath}${quote}`)
+    out = out.replace(pattern.yamlName, (_match, prefix: string, suffix: string) => `${prefix}${pattern.to}${suffix}`)
+  }
+  return out
+}
+
+/**
+ * Rewrite a file's eligible lines.
+ *
+ * Markdown splits in two. Every fence is code a reader copies or a
+ * configuration they mount, so every fence follows the rename regardless of its
+ * info string. Prose follows it only under `docs/`, where a sentence quoting
+ * `` `cordis` `` teaches a name this repository no longer resolves; elsewhere
+ * prose is a record of what was true when it was written, and the same spelling
+ * can mean something else entirely — the Python SDK's `cordis` option, or the
+ * unvendored `@cordisjs/plugin-http`.
+ */
+function rewrite(text: string, file: string, all: readonly Pattern[]): { text: string; lines: number } {
+  const markdown = file.endsWith('.md')
+  const prose = markdown && file.startsWith('docs/')
+  let insideFence = false
+  let lines = 0
+  const out = text.split('\n').map((line) => {
+    if (markdown) {
+      if (/^\s*```/.test(line)) {
+        insideFence = !insideFence
+        return line
+      }
+      if (!insideFence && !prose) return line
+    }
+    const next = rewriteLine(line, file, all)
+    if (next !== line) lines += 1
+    return next
+  })
+  return { text: out.join('\n'), lines }
+}
+
+function classify(file: string): string {
+  if (/^vendor\/[^/]+\/package\.json$/.test(file)) return 'vendor manifest name'
+  if (file.endsWith('package.json')) return 'package.json dependencies'
+  if (/\.(ts|tsx|js|mjs|cjs|tpl)$/.test(file)) return 'code specifiers'
+  if (/\.(yml|yaml)$/.test(file)) return 'YAML plugin names'
+  if (file.endsWith('.json')) return 'JSON configuration'
+  return 'Markdown fences and docs prose'
+}
+
+/**
+ * One exact edit's state in the text it targets. `pending` means the source
+ * form is present and the target form absent; `applied` means the reverse;
+ * anything else — a partial application, a moved site, or a DUPLICATED
+ * insertion — is `invalid`, so it fails the run instead of being applied again.
+ */
+export type ExactEditState = 'pending' | 'applied' | 'invalid'
+
+/**
+ * Classify one exact edit against its target text.
+ *
+ * An insertion keeps its anchor (`replace` contains `find`) and a deletion
+ * keeps its remainder (`find` contains `replace`), so neither can be judged by
+ * the source form alone: the surviving side counts the target form instead.
+ * @param text - the complete current text of the edited file.
+ * @param find - the source form, already oriented for the running direction.
+ * @param replace - the target form, already oriented for the running direction.
+ * @param expect - how many occurrences one complete application produces.
+ * @returns Whether the edit is pending, already applied, or invalid.
+ */
+export function exactEditState(text: string, find: string, replace: string, expect: number): ExactEditState {
+  const hits = text.split(find).length - 1
+  const landed = text.split(replace).length - 1
+  if (replace.includes(find)) {
+    if (landed === expect) return 'applied'
+    return landed === 0 && hits === expect ? 'pending' : 'invalid'
+  }
+  if (find.includes(replace)) {
+    if (hits === 0) return landed === expect ? 'applied' : 'invalid'
+    return hits === expect ? 'pending' : 'invalid'
+  }
+  if (hits === 0 && landed === expect) return 'applied'
+  return hits === expect && landed === 0 ? 'pending' : 'invalid'
+}
+
+function main(): void {
+  const args = process.argv.slice(2)
+  const mode = args.includes('--apply') ? 'apply' : args.includes('--check') ? 'check' : 'dry'
+  const reverse = args.includes('--reverse')
+  const all = patterns(reverse)
+  const files = execFileSync('git', ['ls-files', '-z'], { cwd: root, encoding: 'utf8' })
+    .split('\0')
+    .filter(file => file !== '' && !excluded(file))
+
+  const counts = new Map<string, { files: number; lines: number }>()
+  const failures: string[] = []
+  const outstanding: string[] = []
+
+  // Classify every exact edit before writing anything: a single invalid site
+  // means the mapping and the tree disagree, and a half-applied tree is worse
+  // than an untouched one.
+  const planned: { edit: ExactEdit; path: string; find: string; replace: string }[] = []
+  for (const edit of EXACT_EDITS) {
+    const path = resolve(root, edit.file)
+    const before = readFileSync(path, 'utf8')
+    const find = reverse ? edit.replace : edit.find
+    const replace = reverse ? edit.find : edit.replace
+    const state = exactEditState(before, find, replace, edit.expect)
+    if (state === 'invalid') {
+      failures.push(`exact edit ${edit.id}: ${edit.file} is neither pending nor cleanly applied (duplicated, partial, or moved)`)
+      continue
+    }
+    if (mode === 'check') {
+      if (state !== 'applied') failures.push(`exact edit ${edit.id} did not land in ${edit.file}`)
+      continue
+    }
+    if (state === 'pending') planned.push({ edit, path, find, replace })
+  }
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`rescope-vendor: ${failure}`)
+    console.error(`rescope-vendor: ${String(failures.length)} problem(s); nothing was written.`)
+    process.exitCode = 1
+    return
+  }
+  if (mode === 'apply') {
+    // Re-read per edit: two edits can target one file, and a stale snapshot
+    // would let the second write discard the first.
+    for (const { path, find, replace } of planned) {
+      writeFileSync(path, readFileSync(path, 'utf8').split(find).join(replace))
+    }
+  }
+
+  for (const file of files) {
+    const path = resolve(root, file)
+    const before = readFileSync(path, 'utf8')
+    const { text: after, lines } = rewrite(before, file, all)
+    if (after === before) continue
+    outstanding.push(file)
+    const kind = classify(file)
+    const current = counts.get(kind) ?? { files: 0, lines: 0 }
+    counts.set(kind, { files: current.files + 1, lines: current.lines + lines })
+    if (mode === 'apply') writeFileSync(path, after)
+  }
+
+  console.log(`rescope-vendor: ${mode}${reverse ? ' --reverse' : ''} over ${String(files.length)} tracked files`)
+  for (const kind of [...counts.keys()].sort()) {
+    const { files: count, lines } = counts.get(kind) ?? { files: 0, lines: 0 }
+    console.log(`  ${kind.padEnd(24)} ${String(count).padStart(4)} file(s), ${String(lines)} line(s)`)
+  }
+
+  if (mode !== 'dry') {
+    for (const check of POSTCONDITIONS) {
+      if (reverse) break
+      const path = resolve(root, check.file)
+      const hits = existsSync(path) ? readFileSync(path, 'utf8').split(check.text).length - 1 : -1
+      if (hits !== check.count) {
+        failures.push(`postcondition: ${check.file} has ${String(hits)} occurrence(s) of ${JSON.stringify(check.text)}, expected ${String(check.count)}`)
+      }
+    }
+    // The generic pass above already told us which files would still change,
+    // which in check mode is exactly the residue-and-idempotency signal.
+    if (mode === 'check') {
+      for (const file of outstanding) failures.push(`residue: ${file} still carries a pre-rescope name token`)
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) console.error(`rescope-vendor: ${failure}`)
+    console.error(`rescope-vendor: ${String(failures.length)} problem(s); the mapping or an upstream site moved.`)
+    process.exitCode = 1
+  } else if (mode === 'check') {
+    console.log('rescope-vendor: post-state verified — no residue, every exact edit landed, idempotent.')
+  } else if (mode === 'apply') {
+    console.log('rescope-vendor: applied. Run `pnpm install`, `pnpm run gen-third-party-notices`, and re-record the touched bilingual pairs.')
+  }
+}
+
+// Importing this module for its exported classifier must not run the codemod.
+if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  main()
+}

scripts/run-gates.spec.ts

@@ -83,6 +83,15 @@ describe('gate graph validation', () => {
     expect(ids).toContain('public-repository-links')
   })
 
+  it('keeps native Windows coverage blocking while portability inventory remains observational', () => {
+    const gates = withPnpmEntrypoint(() => gatesForMode('ci-windows-complete'))
+    const byId = new Map(gates.map(subject => [subject.id, subject]))
+
+    expect(byId.get('coverage')?.allowFailure).not.toBe(true)
+    expect(byId.get('coverage-exempt-heavy')?.allowFailure).not.toBe(true)
+    expect(byId.get('duplication')?.allowFailure).toBe(true)
+  })
+
   it.each([
     ['empty', [], /gate graph has no gates/],
     ['duplicate ids', [gate('same'), gate('same')], /duplicate gate id "same"/],
@@ -218,7 +227,7 @@ describe('Node 24 lane ownership', () => {
     const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
 
     expect(defaultConcurrency('ci-consumers', subject.length, 4)).toEqual({
-      workers: 11,
+      workers: 10,
       source: 'ci-consumers gate count',
     })
     expect(subject.map(item => item.id)).toEqual([
@@ -232,7 +241,6 @@ describe('Node 24 lane ownership', () => {
       'doc-typecheck',
       'node-next-types',
       'built-bin-smoke',
-      'github-repository-plugin-e2e',
     ])
     expect(subject.find(item => item.id === 'publint')?.needs).toEqual(['build'])
     expect(subject.find(item => item.id === 'built-package-invariants')?.needs).toEqual(['publint'])
@@ -243,7 +251,6 @@ describe('Node 24 lane ownership', () => {
       'doc-typecheck',
       'node-next-types',
       'built-bin-smoke',
-      'github-repository-plugin-e2e',
     ]) {
       expect(subject.find(item => item.id === id)?.needs).toEqual(['built-package-invariants'])
     }
@@ -257,16 +264,6 @@ describe('Node 24 lane ownership', () => {
         'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
       ]),
     )
-    const githubRepositoryPlugin = subject.find(item => item.id === 'github-repository-plugin-e2e')
-    expect(githubRepositoryPlugin).toMatchObject({
-      label: 'GitHub repository Plugin dsh run',
-      env: {
-        DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1',
-      },
-    })
-    expect(githubRepositoryPlugin?.args).toEqual(
-      expect.arrayContaining(['apps/cli/tests/github-repository-plugin.built.e2e.ts']),
-    )
     expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
       displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
       env: { DSH_SNAPSHOT: 'replay' },

scripts/run-gates.ts

@@ -341,7 +341,7 @@ function nodeCompatSmokeGates(options: { cliSmoke?: boolean } = {}): Gate[] {
   return gates
 }
 
-/** Active Node major used to scope version-specific compatibility contracts. */
+/** Active Node major used to select version-specific compatibility checks. */
 function runningNodeMajor(): number {
   const major = Number.parseInt(process.versions.node.split('.')[0] ?? '', 10)
   if (!Number.isSafeInteger(major)) {
@@ -406,7 +406,6 @@ function ciConsumerGates(): Gate[] {
       needs: validatedBuild,
     }),
     builtBinSmokeGate(validatedBuild),
-    githubRepositoryPluginE2eGate(validatedBuild),
   ]
 }
 
@@ -435,6 +434,7 @@ function ciWindowsCompleteGates(): Gate[] {
   return [
     pnpmScript('build', 'build'),
     pnpmScript('windows-site', 'docs:build', { label: 'production site' }),
+    ...coverageGates(),
     ...observational,
   ]
 }
@@ -442,7 +442,7 @@ function ciWindowsCompleteGates(): Gate[] {
 function ciWindowsObservationalGates(): Gate[] {
   return [
     ...ciStaticGates({ ownsBuild: true }),
-    // Linux owns required lint, coverage, and snapshots; Windows omits those duplicates.
+    // Linux owns required lint and snapshots; Windows omits those duplicates.
     pnpmScript('duplication', 'duplication'),
     pnpmScript('publint', 'publint', { needs: ['build'] }),
     pnpmScript('node-next-types', 'verify-node-next-types', {
@@ -472,7 +472,7 @@ function lintGate(options: { needs?: string[] } = {}): Gate {
 // The heavy suites run uninstrumented beside the thresholded gate: their
 // compiler- and subprocess-bound fixtures pay a multiple of their runtime
 // under v8 instrumentation while contributing nothing the thresholds need
-// (membership contract in scripts/coverage-exempt.ts).
+// (membership rules in scripts/coverage-exempt.ts).
 //
 // DSH_COVERAGE_MAX_WORKERS is the lane's worker budget, so the two parallel
 // gates split it instead of each claiming it whole (the failover pool's
@@ -517,7 +517,7 @@ function coverageGates(): Gate[] {
 }
 
 // Example and package snapshots boot their bins in `lib` mode (built artifacts under plain Node,
-// plugins via real exports); repository-script snapshots execute their real source entry path.
+// plugins via real exports); script snapshots execute their real source entry path.
 // Callers wait either on `build` or on a validation gate that transitively owns that build.
 function snapshotGate(needs: string[] = ['build']): Gate {
   return pnpmScript('snapshot', 'test:snapshot', {
@@ -553,6 +553,7 @@ function flagEnabled(envName: string): boolean {
 function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
   const artifactOptions = options.artifactNeeds === undefined ? {} : { needs: options.artifactNeeds }
   return [
+    pnpmScript('rescope-vendor', 'rescope-vendor:check', { label: 'vendor rescope' }),
     pnpmScript('knip', 'knip'),
     pnpmScript('publint', 'publint', artifactOptions),
     pnpmScript('constraints', 'constraints'),
@@ -598,6 +599,7 @@ function docSyncLeafGates(options: {
     pnpmScript('agent-note-format', 'verify-agent-note-format', { label: 'agent note format' }),
     pnpmScript('archived-agent-notes', 'verify-archived-agent-notes', { label: 'archived agent notes' }),
     pnpmScript('type-equivalence', 'verify-type-equiv', { label: 'type equivalence' }),
+    pnpmScript('skill-invocation-metadata', 'verify-skill-invocation-metadata', { label: 'skill invocation metadata' }),
     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' }),
@@ -620,7 +622,7 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
     'apps/cli/tests/built-bin.e2e.ts',
     'packages/examples/acp-demo/tests/built-bin.e2e.ts',
     'packages/host/directory-picker-native/tests/built-worker.e2e.ts',
-    'packages/scaffold/server/tests/built-scope-carrier.e2e.ts',
+    'packages/sdk/server/tests/built-scope-carrier.e2e.ts',
     'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
     'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
     'packages/api/remotes/tests/built-lib.e2e.ts',
@@ -637,20 +639,6 @@ function builtBinSmokeGate(needs: string[] = ['build']): Gate {
   })
 }
 
-function githubRepositoryPluginE2eGate(needs: string[]): Gate {
-  return pnpmExec('github-repository-plugin-e2e', [
-    'vitest',
-    'run',
-    '--config',
-    'vitest.e2e.config.ts',
-    'apps/cli/tests/github-repository-plugin.built.e2e.ts',
-  ], {
-    label: 'GitHub repository Plugin dsh run',
-    needs,
-    env: { DSH_REQUIRE_GITHUB_REPOSITORY_PLUGIN_E2E: '1' },
-  })
-}
-
 /**
  * Reject a gate list whose graph cannot be executed unambiguously.
  * @param gates - complete aggregate to validate.

scripts/smoke-python-runtime.py

@@ -17,7 +17,7 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Callable
 
 if TYPE_CHECKING:
-    from deepseek_harness import TurnResult
+    from deepseek_harness import RunResult
 
 
 EXPECTED_TEXT = "runtime smoke ok"
@@ -25,10 +25,14 @@ CODE_PROMPT = "Use run_code to compute the packaged worker smoke value."
 CODE_WORKER_TEXT = "code worker smoke ok"
 WORKFLOW_PROMPT = "Use workflow to compute the packaged worker smoke value without agents."
 WORKFLOW_WORKER_TEXT = "workflow worker smoke ok"
-PERSISTENT_TOOLS_PROMPT = "Exercise the packaged persistent Bash and string-replacement editor."
-PERSISTENT_TOOLS_TEXT = "persistent tools smoke ok"
-PERSISTENT_EDITOR_PATH_PREFIX = "Editor path: "
-PERSISTENT_BASH_COMMAND = (
+MINIMAL_PROMPT = "Exercise the packaged minimal agent's persistent Bash and string-replacement editor."
+MINIMAL_TEXT = "minimal agent smoke ok"
+MINIMAL_EDITOR_PATH_PREFIX = "Editor path: "
+MINIMAL_SYSTEM_PROMPT = "You are a helpful software engineer assistant."
+MINIMAL_CORDIS = (
+    Path(__file__).resolve().parent.parent / "examples" / "jsonrpc-agent" / "minimal.cordis.yml"
+)
+MINIMAL_BASH_COMMAND = (
     "counter=$(( ${counter:-0} + 1 )); export counter; "
     "printf 'COUNT=%s CWD=%s\\n' \"$counter\" \"$PWD\"; "
     "if [ \"$counter\" -eq 1 ]; then cd /tmp; fi"
@@ -103,51 +107,6 @@ CUSTOM_CORDIS = """\
 - id: cordis-tool
   name: '@deepseek-ai/dsh-tool-cordis'
 """
-PERSISTENT_TOOLS_CORDIS = """\
-- id: jsonrpc
-  name: '@deepseek-ai/dsh-jsonrpc'
-- id: llm
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-- id: sandbox
-  name: '@deepseek-ai/dsh-sandbox-local'
-- id: sandbox-policy
-  name: '@deepseek-ai/dsh-sandbox-policy'
-  config:
-    mode: danger-full-access
-    workspaceRoot: !!js process.env.DSH_CWD
-- id: pty
-  name: '@deepseek-ai/dsh-pty'
-- id: pty-local
-  name: '@deepseek-ai/dsh-pty-local'
-- id: fs
-  name: '@deepseek-ai/dsh-fs-local'
-  config:
-    cwd: !!js process.env.DSH_CWD
-- id: agent-core
-  name: '@deepseek-ai/dsh-agent-spine-demo'
-  config:
-    includeHarnessIdentity: false
-    persona: 'You are a helpful software engineer assistant.'
-    workspaceContext: false
-    skills:
-      enabled: false
-    toolBash: false
-    toolTasks: false
-- id: sessions
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: !!js process.env.DSH_SESSION_ROOT
-    compression: 'none'
-- id: persistent-bash
-  name: '@deepseek-ai/dsh-tool-bash-persistent'
-- id: str-replace-editor
-  name: '@deepseek-ai/dsh-tool-str-replace-editor'
-"""
-
-
 class MockModelHandler(BaseHTTPRequestHandler):
     """Return deterministic text, worker, and orchestration completions."""
 
@@ -182,9 +141,9 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
     if latest.get("role") == "tool":
         call_id, tool_name = latest_tool_call(messages)
         tool_text = message_text(latest.get("content"))
-        persistent = persistent_tool_followup(body, call_id, tool_name, tool_text)
-        if persistent is not None:
-            return persistent
+        minimal = minimal_tool_followup(body, call_id, tool_name, tool_text)
+        if minimal is not None:
+            return minimal
         advanced = advanced_tool_followup(body, call_id, tool_name, tool_text)
         if advanced is not None:
             return advanced
@@ -196,16 +155,35 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
             return text_chunks(WORKFLOW_WORKER_TEXT)
         raise AssertionError(f"unexpected tool follow-up: {tool_name}")
 
-    prompt = message_text(latest.get("content"))
-    if prompt.startswith(f"{PERSISTENT_TOOLS_PROMPT}\n{PERSISTENT_EDITOR_PATH_PREFIX}"):
+    minimal_prompt = next(
+        (
+            message_text(message.get("content"))
+            for message in reversed(messages)
+            if isinstance(message, dict)
+            and message.get("role") == "user"
+            and message_text(message.get("content")).startswith(
+                f"{MINIMAL_PROMPT}\n{MINIMAL_EDITOR_PATH_PREFIX}"
+            )
+        ),
+        None,
+    )
+    if minimal_prompt is not None:
         names = advertised_tool_names(body)
         if names != {"bash", "str_replace_editor"}:
-            raise AssertionError(f"persistent tools smoke advertised unexpected tools: {names}")
+            raise AssertionError(f"minimal agent smoke advertised unexpected tools: {names}")
+        system_prompts = [
+            message_text(message.get("content"))
+            for message in messages
+            if isinstance(message, dict) and message.get("role") == "system"
+        ]
+        if system_prompts != [MINIMAL_SYSTEM_PROMPT]:
+            raise AssertionError(f"minimal agent smoke assembled unexpected system prompts: {system_prompts}")
         return tool_call_chunks(
-            "persistent-bash-1",
+            "minimal-bash-1",
             "bash",
-            {"command": PERSISTENT_BASH_COMMAND},
+            {"command": MINIMAL_BASH_COMMAND},
         )
+    prompt = message_text(latest.get("content"))
     if prompt == SNAPSHOT_DIRECT_CHILD_PROMPT:
         return text_chunks("DIRECT_CHILD_OK")
     if prompt == SNAPSHOT_WORKFLOW_CHILD_PROMPT:
@@ -240,24 +218,24 @@ def completion_chunks(body: dict[str, object]) -> list[dict[str, object]]:
     return text_chunks(EXPECTED_TEXT)
 
 
-def persistent_tool_followup(
+def minimal_tool_followup(
     body: dict[str, object],
     call_id: str,
     tool_name: str,
     tool_text: str,
 ) -> list[dict[str, object]] | None:
-    """Verify packaged PTY persistence, then invoke the packaged editor."""
-    if not call_id.startswith("persistent-"):
+    """Verify the checked-in minimal composition's PTY and editor."""
+    if not call_id.startswith("minimal-"):
         return None
-    if call_id == "persistent-bash-1" and tool_name == "bash":
+    if call_id == "minimal-bash-1" and tool_name == "bash":
         if "COUNT=1" not in tool_text:
             raise AssertionError(f"first persistent bash call lost its output: {tool_text}")
         return tool_call_chunks(
-            "persistent-bash-2",
+            "minimal-bash-2",
             "bash",
-            {"command": PERSISTENT_BASH_COMMAND},
+            {"command": MINIMAL_BASH_COMMAND},
         )
-    if call_id == "persistent-bash-2" and tool_name == "bash":
+    if call_id == "minimal-bash-2" and tool_name == "bash":
         if "COUNT=2 CWD=/tmp" not in tool_text:
             raise AssertionError(f"persistent bash did not retain state: {tool_text}")
         messages = body.get("messages")
@@ -265,18 +243,18 @@ def persistent_tool_followup(
             raise AssertionError("persistent editor smoke request has no messages")
         editor_path = next(
             (
-                text.split(PERSISTENT_EDITOR_PATH_PREFIX, 1)[1].strip()
+                text.split(MINIMAL_EDITOR_PATH_PREFIX, 1)[1].strip()
                 for message in messages
                 if isinstance(message, dict) and message.get("role") == "user"
                 for text in [message_text(message.get("content"))]
-                if PERSISTENT_EDITOR_PATH_PREFIX in text
+                if MINIMAL_EDITOR_PATH_PREFIX in text
             ),
             None,
         )
         if editor_path is None:
             raise AssertionError("persistent editor smoke prompt has no editor path")
         return tool_call_chunks(
-            "persistent-editor",
+            "minimal-editor",
             "str_replace_editor",
             {
                 "command": "create",
@@ -284,11 +262,11 @@ def persistent_tool_followup(
                 "file_text": "created by packaged editor\n",
             },
         )
-    if call_id == "persistent-editor" and tool_name == "str_replace_editor":
+    if call_id == "minimal-editor" and tool_name == "str_replace_editor":
         if "New file created successfully" not in tool_text:
             raise AssertionError(f"packaged editor did not create its file: {tool_text}")
-        return text_chunks(PERSISTENT_TOOLS_TEXT)
-    raise AssertionError(f"unexpected persistent-tools follow-up: {call_id} {tool_name}: {tool_text}")
+        return text_chunks(MINIMAL_TEXT)
+    raise AssertionError(f"unexpected minimal-agent follow-up: {call_id} {tool_name}: {tool_text}")
 
 
 def advanced_tool_followup(
@@ -470,14 +448,14 @@ def main() -> None:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
         "--scenario",
-        choices=("all", "sdk-default", "sdk-custom", "sdk-persistent", "sdk-snapshot", "direct"),
+        choices=("all", "sdk-default", "sdk-custom", "sdk-minimal", "sdk-snapshot", "direct"),
         default="all",
     )
     parser.add_argument("--exe", type=Path)
     parser.add_argument("--update-snapshots", action="store_true")
     args = parser.parse_args()
-    if args.scenario in {"all", "sdk-custom", "sdk-persistent", "sdk-snapshot", "direct"} and args.exe is None:
-        parser.error("--exe is required for custom, persistent, snapshot, and direct scenarios")
+    if args.scenario in {"all", "sdk-custom", "sdk-minimal", "sdk-snapshot", "direct"} and args.exe is None:
+        parser.error("--exe is required for custom, minimal, snapshot, and direct scenarios")
     if args.update_snapshots and args.scenario not in {"all", "sdk-snapshot"}:
         parser.error("--update-snapshots requires --scenario sdk-snapshot or all")
     if args.exe is not None and not args.exe.is_file():
@@ -489,9 +467,9 @@ def main() -> None:
         if args.scenario in {"all", "sdk-custom"}:
             assert args.exe is not None
             smoke_sdk_custom(model.url, args.exe.resolve())
-        if args.scenario in {"all", "sdk-persistent"}:
+        if args.scenario in {"all", "sdk-minimal"}:
             assert args.exe is not None
-            smoke_sdk_persistent_tools(model.url, args.exe.resolve())
+            smoke_sdk_minimal(model.url, args.exe.resolve())
         if args.scenario in {"all", "sdk-snapshot"}:
             assert args.exe is not None
             smoke_sdk_snapshot(model.url, args.exe.resolve(), args.update_snapshots)
@@ -519,7 +497,6 @@ def smoke_sdk_default(base_url: str) -> None:
             request_timeout_seconds=60,
         ) as harness:
             result = harness.run("reply with the smoke text", session_id="default-smoke")
-        assert result.status == "ok", result
         assert result.final_response == EXPECTED_TEXT, result.final_response
         assert_zstd_session_log(sessions)
 
@@ -546,46 +523,40 @@ def smoke_sdk_custom(base_url: str, executable: Path) -> None:
             text_result = harness.run("reply with the smoke text", session_id="custom-smoke")
             code_result = harness.run(CODE_PROMPT, session_id="custom-smoke")
             workflow_result = harness.run(WORKFLOW_PROMPT, session_id="custom-smoke")
-        assert text_result.status == "ok", text_result
         assert text_result.final_response == EXPECTED_TEXT, text_result.final_response
-        assert code_result.status == "ok", code_result
         assert code_result.final_response == CODE_WORKER_TEXT, code_result.final_response
-        assert workflow_result.status == "ok", workflow_result
         assert workflow_result.final_response == WORKFLOW_WORKER_TEXT, workflow_result.final_response
         assert_session_log(sessions, root, EXPECTED_TEXT, CODE_WORKER_TEXT, WORKFLOW_WORKER_TEXT)
 
 
-def smoke_sdk_persistent_tools(base_url: str, executable: Path) -> None:
-    """Exercise native PTY state and the editor through the packaged executable."""
+def smoke_sdk_minimal(base_url: str, executable: Path) -> None:
+    """Exercise the checked-in minimal composition through the packaged executable."""
     from deepseek_harness import DeepSeekHarness
 
-    with tempfile.TemporaryDirectory(prefix="dsh-sdk-persistent-tools-") as temporary:
+    with tempfile.TemporaryDirectory(prefix="dsh-sdk-minimal-") as temporary:
         root = Path(temporary).resolve()
         editor_path = root / "created.txt"
-        prompt = f"{PERSISTENT_TOOLS_PROMPT}\n{PERSISTENT_EDITOR_PATH_PREFIX}{editor_path}"
+        prompt = f"{MINIMAL_PROMPT}\n{MINIMAL_EDITOR_PATH_PREFIX}{editor_path}"
         sessions = root / "sessions"
-        cordis = root / "cordis.yml"
-        cordis.write_text(PERSISTENT_TOOLS_CORDIS)
         with DeepSeekHarness(
-            provider="deepseek",
+            provider="deepseek-official",
             model="smoke-model",
             cwd=str(root),
             session_root=str(sessions),
-            cordis=str(cordis),
+            cordis=str(MINIMAL_CORDIS),
             runtime_bin=str(executable),
             api_key="sk-keyless-smoke",
             base_url=base_url,
             request_timeout_seconds=60,
         ) as harness:
-            result = harness.run(prompt, session_id="persistent-tools-smoke")
+            result = harness.run(prompt, session_id="minimal-agent-smoke")
 
-        assert result.status == "ok", result
         event_text = json.dumps(result.events)
-        if PERSISTENT_TOOLS_TEXT not in event_text:
-            raise AssertionError(f"packaged tools run emitted no final response: {result.events}")
+        if MINIMAL_TEXT not in event_text:
+            raise AssertionError(f"minimal agent run emitted no final response: {result.events}")
         if editor_path.read_text() != "created by packaged editor\n":
             raise AssertionError(f"packaged editor wrote unexpected content: {editor_path.read_text()!r}")
-        assert_session_log(sessions, root, PERSISTENT_TOOLS_TEXT, "COUNT=1", "COUNT=2 CWD=/tmp")
+        assert_session_log(sessions, root, MINIMAL_TEXT, "COUNT=1", "COUNT=2 CWD=/tmp")
 
 
 def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool) -> None:
@@ -610,7 +581,6 @@ def smoke_sdk_snapshot(base_url: str, executable: Path, update_snapshots: bool)
         ) as harness:
             result = harness.run(SNAPSHOT_PROMPT, session_id=SNAPSHOT_SESSION_ID)
 
-        assert result.status == "ok", result
         assert result.final_response == SNAPSHOT_FINAL_TEXT, result.final_response
         methods = [notification.method for notification in result.notifications]
         if methods.count("subagent.started") != 2 or methods.count("subagent.finished") != 2:
@@ -657,8 +627,8 @@ def smoke_direct(base_url: str, executable: Path) -> None:
                 "params": {"sessionId": "direct-smoke", "contentBlocks": [{"type": "text", "text": "reply with the smoke text"}]},
             })
             messages = peer.read_until(lambda message: message.get("id") == "prompt")
-            if not any(message.get("method") == "session.finished" and message.get("params", {}).get("status") == "ok" for message in messages):
-                messages.extend(peer.read_until(lambda message: message.get("method") == "session.finished"))
+            if not any(is_idle_notification(message) for message in messages):
+                messages.extend(peer.read_until(is_idle_notification))
             event_text = json.dumps(messages)
             if EXPECTED_TEXT not in event_text:
                 raise AssertionError(f"direct runtime emitted no final response: {messages}")
@@ -669,6 +639,16 @@ def smoke_direct(base_url: str, executable: Path) -> None:
         assert_session_log(sessions, root, EXPECTED_TEXT)
 
 
+def is_idle_notification(message: dict[str, object]) -> bool:
+    """Return whether a JSON-RPC notification marks a session idle."""
+    params = message.get("params")
+    return (
+        message.get("method") == "session.status"
+        and isinstance(params, dict)
+        and params.get("status") == "idle"
+    )
+
+
 class RuntimePeer:
     def __init__(self, argv: list[str], cwd: Path, environment: dict[str, str]) -> None:
         self.process = subprocess.Popen(
@@ -776,7 +756,7 @@ def read_session_logs(sessions: Path) -> dict[str, list[dict[str, object]]]:
     return logs
 
 
-def snapshot_child_ids(result: "TurnResult") -> list[str]:
+def snapshot_child_ids(result: "RunResult") -> list[str]:
     """Return the two child session ids in their SDK notification order."""
     child_ids: list[str] = []
     for notification in result.notifications:
@@ -794,7 +774,7 @@ def snapshot_child_ids(result: "TurnResult") -> list[str]:
 
 
 def build_snapshot_files(
-    result: "TurnResult",
+    result: "RunResult",
     logs: dict[str, list[dict[str, object]]],
     child_ids: list[str],
     cwd: Path,
@@ -809,7 +789,6 @@ def build_snapshot_files(
 
     result_value = {
         "session_id": result.session_id,
-        "status": result.status,
         "final_response": result.final_response,
         "events": result.events,
         "notifications": [
@@ -834,7 +813,7 @@ def build_snapshot_files(
     return files
 
 
-def snapshot_agent_id(result: "TurnResult", child_id: str) -> str:
+def snapshot_agent_id(result: "RunResult", child_id: str) -> str:
     """Find the successful subagent id paired with one child session."""
     for notification in result.notifications:
         if notification.method != "subagent.finished":

scripts/snapshots/python-sdk-single-exe/advanced/session.1.jsonl

@@ -1,14 +1,18 @@
-{"type":"session","version":0,"id":"{{child-1}}","createdAt":0,"cwd":"{{cwd}}","parentSession":"{{parent}}","delegationDepth":1}
-{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":0,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}}
-{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"smoke-model","reasoningEffort":"high"},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
-{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
-{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}}
-{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
-{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}
-{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"{{child-1}}","createdAt":0,"cwd":"{{cwd}}","parentSession":"{{parent}}","origin":"subagent","delegationDepth":1}
+{"type":"agent/inbox/spliced","seq":0,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
+{"type":"turn/start","seq":1,"time":0,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"subagent/descriptor","seq":3,"time":0,"data":{"version":2,"mode":"one-shot","provider":"spawn","label":"Check direct child"}}
+{"type":"step/start","seq":4,"time":0,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":5,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":0,"data":{"title":"Reply with exactly DIRECT_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":0,"data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":14,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
+{"type":"step/end","seq":15,"time":0,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":16,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}

scripts/snapshots/python-sdk-single-exe/advanced/session.2.jsonl

@@ -1,14 +1,18 @@
-{"type":"session","version":0,"id":"{{child-2}}","createdAt":0,"cwd":"{{cwd}}","parentSession":"{{parent}}","delegationDepth":1}
-{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":0,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[1],"source":{"kind":"fallback"}}}
-{"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"smoke-model","reasoningEffort":"high"},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
-{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
-{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}}
-{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
-{"type":"step/end","seq":11,"time":0,"data":{"turn":1,"step":1}}
-{"type":"turn/end","seq":12,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"session","version":0,"id":"{{child-2}}","createdAt":0,"cwd":"{{cwd}}","parentSession":"{{parent}}","origin":"subagent","delegationDepth":1}
+{"type":"agent/inbox/spliced","seq":0,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
+{"type":"turn/start","seq":1,"time":0,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
+{"type":"subagent/descriptor","seq":3,"time":0,"data":{"version":2,"mode":"one-shot","provider":"spawn"}}
+{"type":"step/start","seq":4,"time":0,"data":{"turn":1,"step":1}}
+{"type":"user/message","seq":5,"time":0,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":6,"time":0,"data":{"title":"Reply with exactly WORKFLOW_CHILD_OK and","messageSeqs":[5],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":7,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
+{"type":"request/context","seq":8,"time":0,"data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":14,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[9,10,11,12,13],"surfaceOp":"append"}
+{"type":"step/end","seq":15,"time":0,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":16,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}

scripts/snapshots/python-sdk-single-exe/advanced/session.jsonl

@@ -1,68 +1,71 @@
 {"type":"session","version":0,"id":"{{parent}}","createdAt":0,"cwd":"{{cwd}}","delegationDepth":0}
-{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
-{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Run the advanced packaged-runtime snapshot scenario."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
-{"type":"session/title","seq":2,"time":0,"data":{"title":"Run the advanced packaged-runtime snapsh","messageSeqs":[1],"source":{"kind":"fallback"}}}
+{"type":"agent/inbox/spliced","seq":0,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Run the advanced packaged-runtime snapshot scenario."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"}]}}
+{"type":"turn/start","seq":1,"time":0,"data":{"turn":1}}
+{"type":"agent/inbox/spliced","seq":2,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":3,"time":0,"data":{"turn":1,"step":1}}
-{"type":"request/header","seq":4,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"smoke-model","reasoningEffort":"high"},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
-{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}}
-{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}}}
-{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":10,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[5,6,7,8,9],"surfaceOp":"append"}
-{"type":"tool/call","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}
-{"type":"tool/result","seq":12,"time":0,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"advanced-mount"},"content":[{"type":"tool-result","toolCallId":"advanced-mount","content":[{"type":"text","text":"Temporary Plugin dyn-1 is running (plugin \"<anonymous>\"; available until unmounted or DSH restarts)."}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[11],"surfaceOp":"append"}
-{"type":"step/end","seq":13,"time":0,"data":{"turn":1,"step":1}}
-{"type":"step/start","seq":14,"time":0,"data":{"turn":1,"step":2}}
-{"type":"request/header","seq":15,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"smoke-model","reasoningEffort":"high"},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"change"}}
-{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}}
-{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}}}
-{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":20,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":21,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[16,17,18,19,20],"surfaceOp":"append"}
-{"type":"tool/call","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}
-{"type":"tool/code-dispatch-start","seq":23,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"snapshot_double","arguments":{"value":21}}}
-{"type":"tool/code-dispatch","seq":24,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"snapshot_double","arguments":{"value":21},"isError":false,"content":[{"type":"text","text":"42"}]}}
-{"type":"tool/result","seq":25,"time":0,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"42"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[22],"surfaceOp":"append"}
-{"type":"step/end","seq":26,"time":0,"data":{"turn":1,"step":2}}
-{"type":"step/start","seq":27,"time":0,"data":{"turn":1,"step":3}}
-{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-direct-child","name":"subagent","argumentsDelta":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}
-{"type":"assistant/chunk","seq":30,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}
-{"type":"assistant/chunk","seq":31,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":32,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":33,"time":0,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[28,29,30,31,32],"surfaceOp":"append"}
-{"type":"tool/call","seq":34,"time":0,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}
-{"type":"tool/result","seq":35,"time":0,"data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"advanced-direct-child"},"content":[{"type":"tool-result","toolCallId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[34],"surfaceOp":"append"}
-{"type":"step/end","seq":36,"time":0,"data":{"turn":1,"step":3}}
-{"type":"step/start","seq":37,"time":0,"data":{"turn":1,"step":4}}
-{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-workflow","name":"workflow","argumentsDelta":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}}
-{"type":"assistant/chunk","seq":40,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}}}
-{"type":"assistant/chunk","seq":41,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":42,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":43,"time":0,"data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[38,39,40,41,42],"surfaceOp":"append"}
-{"type":"tool/call","seq":44,"time":0,"data":{"turn":1,"step":4,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}
-{"type":"tool/result","seq":45,"time":0,"data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"advanced-workflow"},"content":[{"type":"tool-result","toolCallId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-exe-snapshot\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[44],"surfaceOp":"append"}
-{"type":"step/end","seq":46,"time":0,"data":{"turn":1,"step":4}}
-{"type":"step/start","seq":47,"time":0,"data":{"turn":1,"step":5}}
-{"type":"assistant/chunk","seq":48,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
-{"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-unmount","name":"cordis_unmount","argumentsDelta":"{\"id\": \"dyn-1\"}"}}}
-{"type":"assistant/chunk","seq":50,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}}}}
-{"type":"assistant/chunk","seq":51,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":52,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
-{"type":"assistant/message","seq":53,"time":0,"data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[48,49,50,51,52],"surfaceOp":"append"}
-{"type":"tool/call","seq":54,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}}
-{"type":"tool/result","seq":55,"time":0,"data":{"turn":1,"step":5,"message":{"source":{"kind":"tool","callId":"advanced-unmount"},"content":[{"type":"tool-result","toolCallId":"advanced-unmount","content":[{"type":"text","text":"Temporary Plugin dyn-1 was unmounted and removed."}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[54],"surfaceOp":"append"}
-{"type":"step/end","seq":56,"time":0,"data":{"turn":1,"step":5}}
-{"type":"step/start","seq":57,"time":0,"data":{"turn":1,"step":6}}
-{"type":"request/header","seq":58,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"smoke-model","reasoningEffort":"high"},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","subagent","task_kill","task_list","task_output","workflow"]},"reason":"change"}}
-{"type":"assistant/chunk","seq":59,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":60,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_EXECUTABLE_OK"}}}
-{"type":"assistant/chunk","seq":61,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}}}
-{"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
-{"type":"assistant/chunk","seq":63,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
-{"type":"assistant/message","seq":64,"time":0,"data":{"turn":1,"step":6,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[59,60,61,62,63],"surfaceOp":"append"}
-{"type":"step/end","seq":65,"time":0,"data":{"turn":1,"step":6}}
-{"type":"turn/end","seq":66,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}
+{"type":"user/message","seq":4,"time":0,"data":{"content":[{"type":"text","text":"Run the advanced packaged-runtime snapshot scenario."}],"source":{"kind":"user"},"role":"user","id":"{{messageId}}"},"surfaceOp":"append"}
+{"type":"session/title","seq":5,"time":0,"data":{"title":"Run the advanced packaged-runtime snapsh","messageSeqs":[4],"source":{"kind":"fallback"}}}
+{"type":"request/header","seq":6,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","subagent","task_kill","task_list","task_output","workflow"]},"reason":"initial"}}
+{"type":"request/context","seq":7,"time":0,"data":{"provider":"deepseek-official","model":"smoke-model","contextWindow":1000000}}
+{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":9,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}}
+{"type":"assistant/chunk","seq":10,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}}}
+{"type":"assistant/chunk","seq":11,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":12,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":13,"time":0,"data":{"turn":1,"step":1,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[8,9,10,11,12],"surfaceOp":"append"}
+{"type":"tool/call","seq":14,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","name":"cordis_mount","arguments":"{\"code\": \"return (ctx) => {\\n  harness.registerTool(ctx, harness.defineTool({\\n    name: 'snapshot_double',\\n    description: 'Double a number for executable snapshot verification.',\\n    parameters: { value: { type: 'number', required: true } },\\n    output: {\\n      schema: { type: 'number' },\\n      render(_args, value) {\\n        return [{ type: 'text', text: String(value) }]\\n      }\\n    },\\n    async execute(args) {\\n      return args.value * 2\\n    }\\n  }))\\n}\\n\"}"}}
+{"type":"tool/result","seq":15,"time":0,"data":{"turn":1,"step":1,"message":{"source":{"kind":"tool","callId":"advanced-mount"},"content":[{"type":"tool-result","toolCallId":"advanced-mount","content":[{"type":"text","text":"Temporary Plugin dyn-1 is running (plugin \"<anonymous>\"; available until unmounted or DSH restarts)."}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[14],"surfaceOp":"append"}
+{"type":"step/end","seq":16,"time":0,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":17,"time":0,"data":{"turn":1,"step":2}}
+{"type":"request/header","seq":18,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","snapshot_double","subagent","task_kill","task_list","task_output","workflow"]},"reason":"change"}}
+{"type":"assistant/chunk","seq":19,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":20,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}}
+{"type":"assistant/chunk","seq":21,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}}}
+{"type":"assistant/chunk","seq":22,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":23,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":24,"time":0,"data":{"turn":1,"step":2,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[19,20,21,22,23],"surfaceOp":"append"}
+{"type":"tool/call","seq":25,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\": \"return await tools.snapshot_double({ value: 21 })\", \"description\": \"Run the temporary Plugin tool\"}"}}
+{"type":"tool/code-dispatch-start","seq":26,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"snapshot_double","arguments":{"value":21}}}
+{"type":"tool/code-dispatch","seq":27,"time":0,"data":{"rootCallId":"advanced-code","parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"snapshot_double","arguments":{"value":21},"isError":false,"content":[{"type":"text","text":"42"}]}}
+{"type":"tool/result","seq":28,"time":0,"data":{"turn":1,"step":2,"message":{"source":{"kind":"tool","callId":"advanced-code"},"content":[{"type":"tool-result","toolCallId":"advanced-code","content":[{"type":"text","text":"42"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[25],"surfaceOp":"append"}
+{"type":"step/end","seq":29,"time":0,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":30,"time":0,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":31,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":32,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-direct-child","name":"subagent","argumentsDelta":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}
+{"type":"assistant/chunk","seq":33,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}
+{"type":"assistant/chunk","seq":34,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":35,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":36,"time":0,"data":{"turn":1,"step":3,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[31,32,33,34,35],"surfaceOp":"append"}
+{"type":"tool/call","seq":37,"time":0,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\": \"Check direct child\", \"prompt\": \"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}
+{"type":"tool/result","seq":38,"time":0,"data":{"turn":1,"step":3,"message":{"source":{"kind":"tool","callId":"advanced-direct-child"},"content":[{"type":"tool-result","toolCallId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[37],"surfaceOp":"append"}
+{"type":"step/end","seq":39,"time":0,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":40,"time":0,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":41,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":42,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-workflow","name":"workflow","argumentsDelta":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}}
+{"type":"assistant/chunk","seq":43,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}}}
+{"type":"assistant/chunk","seq":44,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":45,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":46,"time":0,"data":{"turn":1,"step":4,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[41,42,43,44,45],"surfaceOp":"append"}
+{"type":"tool/call","seq":47,"time":0,"data":{"turn":1,"step":4,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\": \"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\", \"meta\": {\"name\": \"advanced-exe-snapshot\", \"description\": \"exercise one packaged workflow child\"}}"}}
+{"type":"tool/result","seq":48,"time":0,"data":{"turn":1,"step":4,"message":{"source":{"kind":"tool","callId":"advanced-workflow"},"content":[{"type":"tool-result","toolCallId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-exe-snapshot\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[47],"surfaceOp":"append"}
+{"type":"step/end","seq":49,"time":0,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":50,"time":0,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":51,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":52,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-unmount","name":"cordis_unmount","argumentsDelta":"{\"id\": \"dyn-1\"}"}}}
+{"type":"assistant/chunk","seq":53,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}}}}
+{"type":"assistant/chunk","seq":54,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":55,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":56,"time":0,"data":{"turn":1,"step":5,"message":{"role":"assistant","content":[{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[51,52,53,54,55],"surfaceOp":"append"}
+{"type":"tool/call","seq":57,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\": \"dyn-1\"}"}}
+{"type":"tool/result","seq":58,"time":0,"data":{"turn":1,"step":5,"message":{"source":{"kind":"tool","callId":"advanced-unmount"},"content":[{"type":"tool-result","toolCallId":"advanced-unmount","content":[{"type":"text","text":"Temporary Plugin dyn-1 was unmounted and removed."}],"isError":false}],"role":"user","id":"{{messageId}}"}},"sourceEventSeqs":[57],"surfaceOp":"append"}
+{"type":"step/end","seq":59,"time":0,"data":{"turn":1,"step":5}}
+{"type":"step/start","seq":60,"time":0,"data":{"turn":1,"step":6}}
+{"type":"request/header","seq":61,"time":0,"data":{"header":{"config":{"provider":"deepseek-official","model":"smoke-model","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true,"maxTokens":true},"system":"{{system}}","tools":["cordis_inspect","cordis_mount","cordis_unmount","run_code","subagent","task_kill","task_list","task_output","workflow"]},"reason":"change"}}
+{"type":"assistant/chunk","seq":62,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":63,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_EXECUTABLE_OK"}}}
+{"type":"assistant/chunk","seq":64,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}}}}
+{"type":"assistant/chunk","seq":65,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":66,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":67,"time":0,"data":{"turn":1,"step":6,"message":{"role":"assistant","content":[{"type":"text","text":"ADVANCED_EXECUTABLE_OK"}],"source":{"kind":"model","provider":"deepseek-official","model":"smoke-model"},"id":"{{messageId}}"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[62,63,64,65,66],"surfaceOp":"append"}
+{"type":"step/end","seq":68,"time":0,"data":{"turn":1,"step":6}}
+{"type":"turn/end","seq":69,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}

scripts/snapshots/translation-prompt-v4/request-response.expected.json

@@ -4,47 +4,47 @@
     "messages": [
       {
         "role": "system",
-        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering idiom over literal renderings, and localize metaphors instead of transplanting them.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- Use active voice when it iLine truncated
+        "content": "# Translation Prompt\n\nYou are a senior technical translator specializing in LLM and agent development documentation. Your task is to translate the complete source document from English to Chinese, producing natural, professional technical prose.\n\nRead each complete semantic unit, understand it, and restate it as a native technical author would write it in the target language. Do not mechanically preserve source-language syntax. Then verify the translation against the source clause by clause: preserve every proposition and add none. Fluency never justifies losing or altering meaning, and completeness never justifies unnatural word-for-word prose.\n\n## Priority\n\nApply these authorities in order:\n\n1. Preserve the source meaning and the required document structure, protected content, and formatting.\n2. Follow the injected terminology table exactly.\n3. Use the injected whole-document gold pairs to calibrate target-language voice and phrasing.\n4. Apply the general writing guidance and illustrative examples in this prompt.\n\nA lower-priority rule may refine but never override a higher-priority requirement. Gold pairs calibrate voice; they are not a translation memory. No style preference, gold-pair phrasing, or embedded example may override source meaning, required structure, protected content, or the terminology table.\n\n## Quality Requirements\n\n### Structure and Format Preservation\n- Output a complete translated document that maintains the same document frame as the source: heading hierarchy and order, list kinds and item counts, ordered-list starts, table rows and columns, link targets, and code blocks.\n- Paragraph boundaries may change within the same structural unit when the target language needs different semantic grouping. Do not merge or move content across headings, list items, table cells, or other independent structural units.\n- Keep each prose paragraph on one physical line. Use paragraph breaks, not hard-wrapped lines inside a paragraph.\n- Fenced code blocks must be byte-identical to the source, including info strings, whitespace, and ALL comments inside them. Do NOT translate or reformat any content inside code blocks. This is a hard rule with no exceptions.\n- Inline code spans must be kept verbatim. This includes commands, flags, paths, identifiers, API and event names, config keys, protocol values, version numbers, and other machine-readable tokens. Never translate or reformat them.\n- Every relative link must point to the same target as in the source. Translate link text; do not change link targets.\n- Language switcher line: when an English source contains `English | [中文](source-filename.zh.md)`, write `[English](source-filename.md) | 中文`. When a Chinese source contains `[English](source-filename.md) | 中文`, write `English | [中文](source-filename.zh.md)`. Do NOT copy the source switcher unchanged. If the source has no switcher, do not invent a filename or switcher; the pipeline inserts the canonical target switcher after parsing `<final>`.\n- Preserve emphasis marker types and the semantic spans they cover. Do not add, remove, move, or change bold and italic markers.\n\n### Faithfulness\n- Preserve every proposition in the source and add none. Every sentence, list item, note, FIXME, warning, example, caveat, prerequisite, and guarantee must have an equivalent in the translation. Count list items on both sides.\n- Preserve actors, objects, conditions, exceptions, negation, modality, causal relationships, and distinctions between concepts.\n- Preserve the exact strength and orientation of contracts. Completion and lifecycle conditions, failure behavior, directions and data flow, normal and exceptional result channels, ownership changes, and quantitative bounds must not be weakened, strengthened, reversed, or merged.\n- Translate ideas rather than source-language idioms, but never use fluency as a reason to omit or alter meaning.\n\n### Tone and Style\n- The translation must read as if originally written in the target language by a native technical author. If an expression sounds like a word-for-word rendering from the source language, rephrase it.\n- Write in a professional, formal tone appropriate for developer documentation. Never use colloquial or casual expressions.\n- Name an actor when the target language would otherwise obscure an actor that the source states or unambiguously implies. Never invent responsibility merely to avoid a passive construction.\n- Prefer established target-language engineering terms over literal renderings. Replace metaphors with direct descriptions that preserve the source meaning.\n- Use polite imperative forms where the text instructs the reader to do something. In Chinese, address the reader as `你`, not `您`.\n- Keep the author's register: concise stays concise, detailed stays detailed.\n\n### Sentence Structure\n- Break long sentences where the target language needs a pause. Avoid run-on sentences.\n- UseLine truncated
       },
       {
         "role": "user",
-        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Install\n\nClone the repository, then run the installer:\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\nThe installer requires `git` and Node `^22.19 || >=24`, offers to install `pnpm` when it is missing, prompts for a DeepSeek API key, builds the required repository artifacts, and launches the Web UI.\n\nThe default active checkout is `~/.dsh/source/current`, and the launcher is linked into `~/.local/bin`. Re-run the installer to update. [`scripts/install.sh`](scripts/install.sh) owns alternate locations, update mechanics, and recovery options.\n\n## Use DeepSeek Harness\n\n### Web UI\n\nFor the recommended local interface, choose Web UI when the installer finishes. To start it later, or after updating the active checkout, build the repository and run:\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\nThe path above is the installer's default. If you set `DSH_SOURCE` or `DSH_CURRENT`, or reused an existing checkout, replace `~/.dsh/source/current` with that checkout path; see [`scripts/install.sh`](scripts/install.sh) for details. The Web UI is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\n`dsh` boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nThe [CLI contract](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n"
+        "content": "# DeepSeek Harness\n\nEnglish | [中文](README.zh.md)\n\nDeepSeek Harness (`dsh`) is an open-source coding agent built on the DeepSeek Harness SDK.\n\nIt uses an architecture where **everything is a plugin**.\n\n## Internal testing notice\n\nDeepSeek Harness is under internal testing. Features and interfaces may change.\n\nThe internal build uploads all Session Logs by default to help diagnose reported problems. Set `DSH_TELEMETRY_DISABLED=1` to disable telemetry. Send feedback through the internal WeChat group.\n\n## Run from source\n\nClone this repo, complete the [dependency and API-key setup](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key), then run:\n\n```sh\npnpm dsh web\n```\n\n## Use DeepSeek Harness\n\n### Web UI\n\nStart the recommended local interface from the repository root:\n\n```sh\npnpm dsh web\n```\n\nThe command builds the repository before starting the Web UI, which is served at `http://127.0.0.1:3080` by default.\n\n### Profiles\n\nThe source CLI boots profiles — ordered stacks of plugin-bundle patch layers under your own overrides in `$DSH_HOME/profiles/<name>`:\n\n```sh\npnpm dsh --profile web                       # the browser UI\npnpm dsh plugin --profile tui add <package>  # install a plugin into a custom profile\npnpm dsh --profile tui                       # boot it\n```\n\nThe [CLI reference](apps/cli/README.md#profiles) describes profile layout, layer semantics, and config dump commands.\n\n### Headless\n\nRun one task, print the final answer, and exit:\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### Automation and SDKs\n\nFrom a source checkout with `DEEPSEEK_API_KEY` in the environment or its root `.env`, start the ACP automation server:\n\n```sh\npnpm run demo:acp\n```\n\nThe [Python SDK](python/README.md) drives a bundled JSON-RPC runtime. The [examples](examples/README.md) cover the runnable headless, ACP, JSON-RPC, Code Mode, and self-referential compositions.\n\n## Why DeepSeek Harness\n\nBuilt-in capabilities cover file reading, editing, and search; shell and persistent PTY execution; reusable skills; task tracking, goals, plans, todos, and background tasks; subagents and workflows; sandboxing and approvals; settings and credentials; persistent, resumable, forkable, and queryable sessions; LSP and web access; context compaction; and telemetry. Each composition selects the subset appropriate to its surface. The Web UI includes Plan Mode.\n\n- **Everything is a plugin.** Models, tools, policies, storage, context management, and interfaces are composable [Cordis plugins](docs/user/develop/basic/index.md), so deployments can extend or replace behavior without forking the agent loop. See the [architecture](docs/architecture.md) for the underlying design.\n- **Runs are reconstructable.** Anything visible to the model is logged in the authoritative session stream; persistence, resume/fork/query, replay, telemetry, and UIs derive from the same events. See the [session-log architecture](docs/architecture.md#session-log).\n- **Code Mode (opt-in).** It exposes a `run_code` tool and a generated TypeScript SDK; only program output re-enters model context. See [Code Mode](packages/core/tools/README.md#code-mode).\n- **Self-referential Cordis tools are opt-in.** They let the agent inspect its live runtime and mount or unmount plugins while it runs. See the [Cordis tools](packages/self-modification/tool-cordis/README.md).\n\n## Community\n\nFollow <a href=\"https://x.com/Deepseekharness\">DeepSeek Harness on Twitter</a> for project updates.\n\n## Development\n\nStart with the [development guide](docs/development.md) and read the [architecture](docs/architecture.md) before changing packages.\n\nFor agents, follow [AGENTS.md](AGENTS.md).\n\nDeepSeek Harness is currently in internal testing.\n\n## License\n\n[BSD 3-Clause](LICENSE)\n\nThird-party dependencies and their licenses are disclosed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).\n\n## Contributing\n\nRead [CONTRIBUTING.md](CONTRIBUTING.md) before contributing to this repository.\n"
       },
       {
         "role": "assistant",
-        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 安装\n\n克隆仓库，然后运行安装器：\n\n```sh\ngit clone <repo-url>\ncd deepseek-harness\nscripts/install.sh\n```\n\n安装器要求系统已安装 `git` 和 Node `^22.19 || >=24`，缺少 `pnpm` 时可代为安装，并会提示输入 DeepSeek API 密钥，然后构建所需的仓库产物并启动 Web UI。\n\n默认生效的检出位于 `~/.dsh/source/current`，启动器链接到 `~/.local/bin`。再次运行安装器即可更新。其他位置、更新机制和恢复选项由 [`scripts/install.sh`](scripts/install.sh) 负责。\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n推荐在本地使用 Web UI；安装结束时，选择 Web UI 即可。以后需要启动时，或更新当前生效的检出后，请构建仓库并运行：\n\n```sh\n(cd ~/.dsh/source/current && pnpm run build)\ndsh web\n```\n\n上述路径是安装器的默认位置。如果你设置过 `DSH_SOURCE` 或 `DSH_CURRENT`，或者复用了已有检出，请把 `~/.dsh/source/current` 换成该检出路径；详情见 [`scripts/install.sh`](scripts/install.sh)。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n`dsh` 启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\ndsh --profile web                       # the browser UI (same as: dsh web)\ndsh plugin --profile tui add <package>  # install a plugin into a custom profile\ndsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）约定](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\ndsh run \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n"
+        "content": "# DeepSeek Harness\n\n[English](README.md) | 中文\n\nDeepSeek Harness（`dsh`）是一款基于 DeepSeek Harness SDK 构建的开源 coding agent（智能体）。\n\n它采用了**一切皆插件**的架构。\n\n## 内测声明\n\nDeepSeek Harness 正处于内部测试阶段，功能和接口可能发生变化。\n\n为帮助诊断上报的问题，内测版本默认上传所有会话日志。设置 `DSH_TELEMETRY_DISABLED=1` 可关闭遥测。请通过内部企业微信群反馈问题和建议。\n\n## 从源码运行\n\n克隆本仓库，完成[依赖安装和 API 密钥配置](docs/user/guide/quickstart.md#step-1-install-and-configure-the-api-key)，然后运行：\n\n```sh\npnpm dsh web\n```\n\n## 使用 DeepSeek Harness\n\n### Web UI\n\n请从仓库根目录启动推荐的本地界面：\n\n```sh\npnpm dsh web\n```\n\n该命令会先构建仓库，再启动 Web UI。Web UI 默认通过 `http://127.0.0.1:3080` 提供服务。\n\n### Profile\n\n源码 CLI（命令行界面）会启动 profile：按序叠放的插件组合包 patch 层，之上再叠加你在 `$DSH_HOME/profiles/<name>` 中的自有覆盖层：\n\n```sh\npnpm dsh --profile web                       # the browser UI\npnpm dsh plugin --profile tui add <package>  # install a plugin into a custom profile\npnpm dsh --profile tui                       # boot it\n```\n\nprofile 布局、层语义与配置输出命令详见 [CLI（命令行界面）参考](apps/cli/README.md#profiles)。\n\n### Headless\n\n运行一项任务，打印最终答案后退出：\n\n```sh\npnpm dsh --profile headless \"summarize this workspace\"\n```\n\n### 自动化与 SDK\n\n在源码检出中通过环境变量或根目录 `.env` 设置 `DEEPSEEK_API_KEY`，然后启动 ACP（Agent Client Protocol）自动化服务器：\n\n```sh\npnpm run demo:acp\n```\n\n[Python SDK](python/README.md) 驱动随附的 JSON-RPC 运行时。[示例](examples/README.md)涵盖可运行的 headless、ACP、JSON-RPC、Code Mode 和自指组合。\n\n## 为什么选择 DeepSeek Harness\n\n内置功能涵盖文件读取、编辑与搜索、shell 和持久 PTY 执行、可复用 skill（技能）、任务跟踪、目标、计划、待办事项与后台任务、subagent 与工作流、沙箱与审批、设置与凭据、可持久化、恢复、fork 与查询的会话、LSP 与 Web 访问、上下文压缩（context compaction），以及遥测。每个组合只选用适合其使用方式的能力子集。Web UI 包含 Plan Mode。\n\n- **一切皆插件。** 模型、工具、策略、存储、上下文管理和界面均为可组合的 [Cordis 插件](docs/user/develop/basic/index.md)，部署方无需 fork agent loop（智能体循环）即可扩展或替换行为。底层设计见[架构文档](docs/architecture.md)。\n- **运行可重建。** 凡是模型可见的内容，都会记录在权威会话流中；持久化、恢复／fork／查询、回放、遥测和 UI 均从同一组事件派生。参见[会话日志架构](docs/architecture.md#session-log)。\n- **Code Mode（需显式启用）。** 它会提供 `run_code` 工具和生成的 TypeScript SDK，只有程序输出会重新进入模型上下文。参见 [Code Mode](packages/core/tools/README.md#code-mode)。\n- **自指 Cordis 工具需显式启用。** 这些工具可让 agent 检查自身的实时运行时，并在运行中挂载或卸载插件。参见 [Cordis 工具](packages/self-modification/tool-cordis/README.md)。\n\n## 社区\n\n扫描二维码，或打开 <a href=\"https://wj.qq.com/s2/27234598/03eb/\">DeepSeek Harness 微信社区申请页面</a> 申请加入。\n\n<p>\n  <img src=\"assets/community-wecom-survey.png\" alt=\"DeepSeek Harness 微信社区二维码\" width=\"240\">\n</p>\n\n## 开发\n\n请先阅读[开发指南](docs/development.md)；修改包之前，请阅读[架构文档](docs/architecture.md)。\n\n面向 agent：遵循 [AGENTS.md](AGENTS.md)。\n\nDeepSeek Harness 目前处于内测阶段。\n\n## 许可证\n\n[BSD 3-Clause](LICENSE)\n\n第三方依赖及其许可证在 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 中披露。\n\n## 参与贡献\n\n向本仓库贡献前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。\n"
       },
       {
         "role": "user",
-        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI shape. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler shape (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face: a single-Line truncated
+        "content": "# Development guide\n\nEnglish | [中文](development.zh.md)\n\nThe setup tutorial takes a new contributor from prerequisites to a checked checkout. The contributor reference that follows covers repository layout, daily workflow, and CI organization. Design rationale and implementation details belong to the linked Agent Notes and scripts.\n\n## Setup tutorial\n\n### Prerequisites\n\n- Node.js supports 22.19+ and 24+. CI covers 22.19, 24, and 26; see the [Node engine floor Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md).\n- Corepack-enabled pnpm. The repo pins `pnpm@11.7.0` in `package.json`; run `corepack enable` if `pnpm --version` does not resolve through Corepack.\n- Git 2.26 or newer; hook setup enables Git's worktree-specific configuration extension.\n- Optional: a DeepSeek API key for the Web, headless, and ACP automation demos and real-API e2e tests.\n\n### First-time setup\n\nInstall dependencies from the repo root:\n\n```sh\npnpm install\n```\n\nThe install also configures worktree-local Lefthook hooks and the `dsh-translation-pairing` Git merge driver through `scripts/install-lefthook.mjs`. The [worktree-local hooks Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) owns the hook-path safety contract; the [automatic pairing merges Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the merge driver.\n\nIf either integration is missing because dependencies were restored from cache or `postinstall` was skipped, install them manually:\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\nIf the wrapper rejects existing Git configuration or reports a stale lock, follow its diagnostic and the linked Agent Note rather than editing worktree metadata speculatively. After moving a checkout, rerun the wrapper to regenerate the owned path.\n\nRun typecheck once after a fresh clone:\n\n```sh\npnpm run typecheck\n```\n\nSetup is complete when `pnpm run typecheck` exits successfully.\n\n## Contributor reference\n\n### TypeScript project layout\n\nThe repository uses isolated Host and Client aggregates. An ordinary package is registered in exactly one aggregate: Host packages in `tsconfig.host.json` and Client packages in `tsconfig.client.json`.\n\n| File | Role | Forms a program? |\n|---|---|---|\n| `tsconfig.json` | Solution root: `extends` base, `files: []`, and references to the two aggregates. It is the tsserver discovery entry and the entry for explicitly running the complete Project Reference graph; through the inherited `paths`, it is also the resolution config for tsx running `examples/` and `scripts/`. | No |\n| `tsconfig.host.json` | Host aggregate: Host packages, examples, tests, scripts, website, and the exceptional Host project of `api/remotes`. | Yes |\n| `tsconfig.client.json` | Client aggregate: `packages/client/*` packages and their tests, `apps/web`, and the exceptional Client project of `api/remotes`. | Yes |\n| `tsconfig.base.json` | Shared compilerOptions and the source `paths` map. Also the resolution facade the vitest configs point vite-tsconfig-paths at: it has no `include`, so its `paths` apply to every importer. | No |\n| `tsconfig.base.client.json` | Browser compiler settings (`jsx`, DOM libs, `types: []`) extended by the Client aggregate and every `packages/client/*` package. | No |\n\nHost and Client stay two aggregate programs because both sides declaration-merge the cordis `Context` interface under the same keys with different services; one program seeing both merges reports a collision. The collision exists only inside a `ts.Program` — module resolution never triggers it — which is why the solution may reference both aggregates and one paths facade may span both sides. Three disciplines follow:\n\n- `tsconfig.base.json` never gains `include` or `files`: they would leak into every extending package project and narrow the facade's match-all scope.\n- A script that builds a repo-wide `ts.Program` seeds `tsconfig.host.json` or `tsconfig.client.json` explicitly — never the root solution, because flattening both aggregates into one program collides the `Context` merges.\n- A new package is registered in exactly one aggregate. Having both a Node loader entry and a browser entry is not a reason to split a package; an ordinary Client plugin produces both runtime artifacts during the Client build phase.\n\n`api/remotes` is the repository's only package with split Host and Client tsconfigs. Its Host entry must participate in the Host TypeRT graph, while its Client entry imports `/remote` declarations that Host tsdown must generate first. The package-root `tsconfig.json` is therefore only a solution, and the two aggregates and direct consumers reference `tsconfig.host.json` or `tsconfig.client.json` respectively. The workspace `constraints` gate walks the reachable Project Reference graph and checks each referencing project's own compiler face:Line truncated
       },
       {
         "role": "assistant",
-        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 形态。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译形状（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；完整边界见 [`api-remotes` README](Line truncated
+        "content": "# 开发指南\n\n[English](development.md) | 中文\n\n搭建教程引导新贡献者从准备前置条件开始，直到检出通过检查。后面的贡献者参考介绍仓库布局、日常工作流和 CI 组织方式。设计依据与实现细节属于链接的 Agent Note 和脚本。\n\n## 搭建教程\n\n### 前置条件\n\n- Node.js 支持 22.19+ 与 24+。CI 覆盖 22.19、24 和 26；见 [Node 引擎下限 Agent Note](../.agents/notes/implemented/process/2026-07-06-node-engine-floor.md)。\n- 启用了 Corepack 的 pnpm。仓库在 `package.json` 中固定使用 `pnpm@11.7.0`；如果 `pnpm --version` 无法通过 Corepack 解析，请先运行 `corepack enable`。\n- Git 2.26 或更高版本；钩子设置会启用 Git 的 worktree 专属配置扩展。\n- 可选：一个 DeepSeek API key，用于 Web、headless 和 ACP（Agent Client Protocol）自动化 agent（智能体）演示以及真实 API 的 e2e 测试。\n\n### 首次搭建\n\n在仓库根目录安装依赖：\n\n```sh\npnpm install\n```\n\n安装过程还会通过 `scripts/install-lefthook.mjs` 配置 worktree 本地的 Lefthook 钩子和 `dsh-translation-pairing` Git 合并驱动。[worktree 本地钩子 Agent Note](../.agents/notes/implemented/process/2026-07-27-worktree-local-lefthook.md) 负责钩子路径的安全约定；[自动配对合并 Agent Note](../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责合并驱动。\n\n如果依赖是从缓存恢复或 `postinstall` 被跳过而导致任一集成缺失，请手动安装：\n\n```sh\nnode scripts/install-lefthook.mjs\n```\n\n如果包装脚本拒绝现有 Git 配置或报告陈旧锁，请遵循其诊断和所链接的 Agent Note，不要凭猜测编辑 worktree 元数据。移动检出目录后，请重新运行包装脚本以重新生成自有路径。\n\n新克隆后请先运行一次类型检查：\n\n```sh\npnpm run typecheck\n```\n\n`pnpm run typecheck` 成功退出即表示搭建完成。\n\n## 贡献者参考\n\n### TypeScript 项目布局\n\n仓库使用相互隔离的 Host 与 Client aggregate。普通 package 只登记进其中一个 aggregate；Host 包进入 `tsconfig.host.json`，Client 包进入 `tsconfig.client.json`。\n\n| 文件 | 角色 | 是否构成 program？ |\n|---|---|---|\n| `tsconfig.json` | solution 根：`extends` base、`files: []`、引用两个 aggregate。它是 tsserver 发现入口，也是显式执行整张 Project Reference 图时的入口；经继承的 `paths` 充当 tsx 运行 `examples/` 与 `scripts/` 时的解析配置。 | 否 |\n| `tsconfig.host.json` | Host aggregate：Host package、示例、测试、脚本和 website，以及 `api/remotes` 的 Host 特例 project。 | 是 |\n| `tsconfig.client.json` | Client aggregate：`packages/client/*` package 及其测试、`apps/web`，以及 `api/remotes` 的 Client 特例 project。 | 是 |\n| `tsconfig.base.json` | 共享 compilerOptions 与源码 `paths` 映射。同时是各 vitest 配置让 vite-tsconfig-paths 指向的解析门面：它没有 `include`，因此其 `paths` 适用于任何 importer。 | 否 |\n| `tsconfig.base.client.json` | 浏览器编译设置（`jsx`、DOM lib、`types: []`），由 Client aggregate 和每个 `packages/client/*` package extends。 | 否 |\n\nHost 与 Client 保持两个 aggregate program，是因为两侧在相同键下以不同服务对 cordis `Context` 接口做声明合并；单一 program 同时看到两份合并会报冲突。这种冲突只存在于 `ts.Program` 内部——模块解析永远不会触发它——所以 solution 可以同时引用两个 aggregate，一个 paths 门面也可以横跨两侧。由此推出三条纪律：\n\n- `tsconfig.base.json` 永不添加 `include` 或 `files`：它们会泄漏进每个 extends 它的包项目，并收窄门面的全匹配范围。\n- 构造全仓 `ts.Program` 的脚本显式种子 `tsconfig.host.json` 或 `tsconfig.client.json`——永不种子根 solution，因为把两个 aggregate 展平进一个 program 会撞上 `Context` 合并冲突。\n- 新 package 只登记进一个 aggregate。包同时具有 Node loader 入口和 browser 入口并不构成拆分理由；普通 Client plugin 的两份运行时产物都在 Client 构建阶段生成。\n\n`api/remotes` 是唯一拆分 Host/Client tsconfig 的仓库特例。它的 Host 入口必须进入 Host TypeRT 图，而 Client 入口导入 Host tsdown 才会生成的 `/remote` 声明，因此本包根 `tsconfig.json` 只作为 solution，两个 aggregate 和直接消费方分别引用 `tsconfig.host.json` 或 `tsconfig.client.json`。workspace `constraints` 门禁遍历可达的 Project Reference 图，并按各引用 project 自身的 compiler face 检查：只有单一配置的目标可由任一 face 引用，拆分配置的目标则必须引用匹配的 leaf，不得引用 solution 根或另一侧 leaf。不要把该结构推广到其他包；[`api-remotes` README](../packageLine truncated
       },
       {
         "role": "user",
-        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, enforcement gate, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. The committed agent workflow lives in [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md).\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. `pnpm run gen-translation-brief <pair>` assembles that update's working set mechanically at the narrowest safely aligned granularity — changed Markdown units, then heading sections, then whole document — with the edited side's diff since last confirmation, each changed span's three-way text, the terminology rows the change touches, and the binding update rules; a change confined to the pair's byte-identical code fences is computed outright, and `--apply` splices it into the counterpart after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any uncertain shape remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively)Line truncated
+        "content": "# Bilingual documentation\n\nEnglish | [中文](README.zh.md)\n\nThis repo's documentation is read by people and agents both inside and outside the company, so every document in scope is maintained in English and Simplified Chinese. This page defines the pairing contract, checks, scope, and exclusions; [translation-rules.md](translation-rules.md) defines how to translate; [terminology.md](terminology.md) is the terminology source of truth. Routine agent work follows the lightweight path in [docs/AGENTS.md](../AGENTS.md); the extended [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) workflow is available only through explicit user invocation.\n\n## The pairing contract\n\n- **Both languages carry equal authority.** A document may be authored and reviewed in either language first — a Chinese-first Agent Note is as legitimate as an English-first one — and the counterpart is translated from it. Neither file outranks the other; what binds them is that they must say the same thing.\n- **A pair is three sibling files.** The English `foo.md`, the Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`, all in the same directory. No locale directories, no separate translation repo, no interleaved bilingual files. Pairs merge whole: a PR never lands one language without the other two files.\n- **The consistency record.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last time the two were confirmed to say the same thing:\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  Blob hashes, not commit hashes, so the record is computable for files edited in the same PR (`git hash-object foo.md`) and consistency is a pure content comparison. `--write` stores those snapshots in the local Git object database before recording them, including uncommitted working-tree contents, and pins every distinct stored blob under a content-addressed `refs/dsh/translation-pairing/snapshots/` ref so garbage collection cannot invalidate a recorded recovery pointer. The recorded hashes therefore recover the exact last-confirmed text of either side, so an out-of-sync pair is updated by patching the counterpart minimally against the edited side's diff — never by re-translating whole files. Routine work makes that patch directly; when the user explicitly invokes the extended workflow, `pnpm run gen-translation-brief <pair>` can instead assemble the update at the narrowest safely aligned granularity and `--apply` can splice a code-fence-only change after structural validation ([briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)). After bringing the pair back in line, `pnpm run verify-translation-pairing --write <pair>` re-records both hashes; that yaml diff is the reviewable act of confirming consistency, which is why `--write` requires naming the pairs you confirmed (`--write --all` is the explicit corpus-wide form).\n\n  When two branches contain valid confirmations of the same pair, the installed `dsh-translation-pairing` Git merge driver composes a new record only if Git's default text merge succeeds for both recorded owner-blob triplets and the merged pair retains its required switchers and structural signature. The Chinese file must retain its English backlink; an authored English source must retain its Chinese link, while a listed generated English source is exempt. Any structure the driver cannot verify remains an ordinary conflict; `pnpm run resolve-translation-pairing-conflicts` applies the same fail-closed operation to a merge that has already stopped, stages every safe pairing record, and exits unsuccessfully when other pairing conflicts remain. The [automatic pairing merges Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) owns the mechanism and alternatives.\n- **Language switcher.** The Chinese file always links back immediately after its H1 heading with `[English](foo.md) | 中文`. An authored English file reciprocates there with `English | [中文](foo.zh.md)`; a listed generated English source omits that line so it remains byte-identical to generator output.\n- **Structure mirrors the counterpart.** Heading depths and order, list kinds, ordered-list starts, list item counts, table row and column counts, link targets, and verbatim code blocks match one to one across the pair — see [translation-rules.md](translation-rules.md) for the full preservation rules. Existing Markdown gates apply to `.zh.md` files unchanged (`verify-md-wrap`, `verify-md-links`).\n\n## The gate: verify-translation-pairing\n\n`pnpm run verify-translation-pairing` (part of `doc-sync`, which contributors run locally for documentation changes and CI runs exhaustively) enforces the contract mechanically:\n\n1. Every document in scope has a complete pair. README discovery iLine truncated
       },
       {
         "role": "assistant",
-        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、强制门禁、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。仓库内置的 agent 工作流见 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。`pnpm run gen-translation-brief <pair>` 会以能安全对齐的最窄粒度——先是有改动的 Markdown 单元，再是标题小节，最后是整篇文档——机械地汇集这次更新的工作集：被改一侧自上次确认以来的 diff、每个改动块的三方文本、改动触及的术语表行，以及有约束力的更新规则；仅落在配对中逐字节一致的围栏代码块内的改动可以直接算出，`--apply` 则经结构签名校验后把它拼接进对侧文件（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何无法确定的情形都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都Line truncated
+        "content": "# 双语文档\n\n[English](README.md) | 中文\n\n本仓库的文档会被公司内外的人和 agent（智能体）阅读，因此范围内的每篇文档都以英文和简体中文维护。本页定义配对约定、检查、范围与排除规则；[translation-rules.md](translation-rules.md) 定义如何翻译；[terminology.md](terminology.md) 是术语真源。agent 的日常工作遵循 [docs/AGENTS.md](../AGENTS.md) 中的轻量路径；扩展版 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 工作流仅在用户显式调用时可用。\n\n## 配对约定\n\n- **两种语言同权。** 一篇文档可以先用任一语言撰写和评审（先写中文的 Agent Note 与先写英文的一样正当），另一侧由它翻译而来。两个文件谁也不高于谁；约束它们的是二者必须说同样的话。\n- **一对文档是三个同目录文件。** 英文 `foo.md`、中文 `foo.zh.md`，加一份一致性记录 `foo.i18n.yaml`，都在同一目录。不用语言目录，不用独立翻译仓库，不用中英混排的单文件。配对必须整体合并：PR（Pull Request）永远不会只带一种语言而缺其余两个文件。\n- **一致性记录。**`foo.i18n.yaml` 保存两侧文件在上一次被确认「说同样的话」时各自的完整 git blob hash：\n\n  ```yaml\n  foo.md: 3f786850e387550fdab836ed7e6dc881de23001b\n  foo.zh.md: 89e6c98d92887913cadf06b2adb97f26cde4849b\n  ```\n\n  用 blob hash 而不是 commit hash，这样同一个 PR 里改动的文件也能算出记录（`git hash-object foo.md`），一致性是纯内容比较。`--write` 会先把这些快照存入本地 Git 对象库再写下记录，未提交的工作树内容也不例外；它还会在内容寻址的 `refs/dsh/translation-pairing/snapshots/` ref 下固定每个不同的已存 blob，使垃圾回收无法让已记录的恢复指针失效。因此记录的 hash 能还原任一侧上次确认时的确切文本，所以失去同步的配对是「按被改一侧的 diff 最小化地修补另一侧」，从不整篇重译。日常工作会直接完成这份修补；用户显式调用扩展工作流时，可改由 `pnpm run gen-translation-brief <pair>` 以能安全对齐的最窄粒度汇集这次更新，并由 `--apply` 在结构校验后拼接仅涉及围栏代码块的改动（[briefed-updates Agent Note](../../.agents/notes/implemented/process/2026-07-26-briefed-minimal-translation-updates.md)）。两侧对齐后，`pnpm run verify-translation-pairing --write <pair>` 重新记录两个 hash；那份 yaml diff 就是「确认一致」这个动作本身，可以被评审，也正因如此，`--write` 要求点名你确认过的配对（`--write --all` 是显式的全语料形式）。\n\n  当两个分支都包含同一配对的有效确认时，已安装的 `dsh-translation-pairing` Git 合并驱动只会在 Git 默认文本合并能分别干净合并记录所指向的英文三方 blob 与中文三方 blob，且合并后的配对仍保留必需的语言切换行和结构签名时，组合出一份新记录。中文文件必须保留指向英文的反向链接；普通撰写的英文源必须保留指向中文的链接，而清单内的生成英文源不作此要求。任何合并驱动无法验证的结构都保留为普通冲突；`pnpm run resolve-translation-pairing-conflicts` 会对已经停止的合并执行同一套遇错即保留冲突的操作，暂存每份可安全生成的配对记录，并在还有其他配对冲突时以非零状态退出。[自动配对合并 Agent Note](../../.agents/notes/implemented/process/2026-08-08-automatic-translation-pairing-merges.md) 负责记录该机制与备选方案。\n- **语言切换行。** 中文文件一律在 H1 标题后立即以 `[English](foo.md) | 中文` 链回英文。普通撰写的英文文件在同一位置以 `English | [中文](foo.zh.md)` 互链；清单内的生成英文源省略此行，以便与生成器输出逐字节一致。\n- **结构与另一侧一一对应。** 标题深度与顺序、列表类型、有序列表起始编号、列表项数量、表格行列数、链接目标与逐字节一致的代码块在配对两侧一一对应；完整保持规则见 [translation-rules.md](translation-rules.md)。既有 Markdown 门禁对 `.zh.md` 文件原样生效（`verify-md-wrap`、`verify-md-links`）。\n\n## 门禁：verify-translation-pairing\n\n`pnpm run verify-translation-pairing`（`doc-sync`（文档同步门禁）的一环，贡献者会针对文档变更在本地运行，CI 则会完整运行）机械地强制执行这份约定：\n\n1. 范围内的每篇文档都有完整配对。发现 README 时，basename 不区分大小写，因此 `missions/readme.md` 与其他文档根一样属于范围。\n2. 任何已存在的配对产物都完整且一致：三个文件齐全、每一侧的当前 blob hash 等于记录值（改了任一侧而没重新确认配对就变红）Line truncated
       },
       {
         "role": "user",
-        "content": "# Translation rules\n\nEnglish | [中文](translation-rules.zh.md)\n\nHow to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority ([README.md](README.md)): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally; the committed agent workflow that applies them is [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md). Rule levels follow RFC 2119 usage: **MUST** / **MUST NOT** are gate- or review-blocking; **SHOULD** needs a stated reason to deviate; **MAY** is discretionary.\n\n## Faithfulness\n\n- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.\n- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.\n- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.\n\n## Voice\n\n- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.\n- Write as a native technical author restating the content, not as a translator transposing sentences. Then verify against the source clause by clause: nothing added, nothing dropped — fluency never justifies losing a clause.\n- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).\n- Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.\n- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.\n- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.\n\n## Structure preservation\n\nThe pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:\n\n- heading hierarchy (same levels, same order — heading TEXT is translated),\n- list shape and numbering,\n- tables (same columns, same row order; header cells translated per terminology),\n- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,\n- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,\n- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.\n\nThe repo's Markdown conventions apply to `.zh.md` files unchanged: one physical line per paragraph (`verify-md-wrap`), resolving relative links (`verify-md-links`), exactly one trailing newline.\n\n## Terminology\n\n- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its \"不要译作\" prohibitions. A Chinese target uses the \"中文\" column and its \"首次出现\" annotation; an English target uses the \"English\" column without adding a Chinese gloss.\n- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST stay in English and be listed under 「待定术语」(pending terms) with a suggested rendering.\nLine truncated
+        "content": "# Translation rules\n\nEnglish | [中文](translation-rules.zh.md)\n\nHow to translate between the two sides of a documentation pair in this repo. Both languages carry equal authority ([README.md](README.md)): a change is authored in either language, and that side is the source for that update — these rules govern producing or updating the counterpart. They bind humans and agents equally. Routine agent work translates the changed content directly in one terminology-guided pass; the extended [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) workflow runs only when the user explicitly invokes it. Rule levels follow RFC 2119 usage: **MUST** / **MUST NOT** are gate- or review-blocking; **SHOULD** needs a stated reason to deviate; **MAY** is discretionary.\n\n## Faithfulness\n\n- The counterpart *MUST* say what the authored side says — no added behavior, prerequisites, warnings, version claims, or examples, and no dropped ones. If the pair disagrees on substance, neither language wins by default: fix the side that is wrong, then bring the other along in the same change.\n- The counterpart *SHOULD* read as natural technical writing in its own language, not word-by-word gloss. Translate meaning, restructure sentences where the target grammar wants it, and keep the author's register — terse stays terse.\n- Do not translate the untranslatable: if a sentence resists natural rendering because it leans on an idiom of the source language, translate the idea, not the idiom.\n\n## Voice\n\n- The register is calibrated by [style-samples.md](style-samples.md) — human-approved gold pairs, one per document genre. The counterpart MUST match the target-language side of the nearest sample; where its voice and a prose voice rule disagree, the sample wins. Chinese targets use institutional technical Chinese; English targets use concise professional developer prose.\n- Write as a native technical author restating the content, not as a translator transposing sentences, while preserving every source clause: nothing added, nothing dropped — fluency never justifies losing a clause.\n- Give sentences an explicit actor when the target language would otherwise obscure it; for Chinese, replace vague passives or abstract subjects with the actual actor (系统、门禁、评审人).\n- Prefer established target-language engineering idiom over calques (误报／漏检 for false positive/negative, 执行红线 for enforcement frontier); localize metaphors instead of transplanting them, and unpack noun chains where the target language requires it.\n- Split long paragraphs by semantic unit — one idea per paragraph. Paragraph boundaries MAY differ from the source; the structural signature does not count paragraphs.\n- When translating into Chinese, category nouns use Chinese with a first-mention English annotation (实操手册（cookbook）); when translating into English, use the conventional English category name. Literal directory or file references stay code-formatted English.\n\n## Structure preservation\n\nThe pairing gate checks heading depths, fenced code blocks, table row and column counts, list kinds, ordered-list starts, list item counts, and link targets. Preserve the rest of the frame manually; the paired files MUST match one to one in:\n\n- heading hierarchy (same levels, same order — heading TEXT is translated),\n- list shape and numbering,\n- tables (same columns, same row order; header cells translated per terminology),\n- fenced code blocks — **byte-identical, including comments**; the pairing signature compares their info strings and contents, and ` ```ts ` blocks compile under `doc-typecheck`,\n- inline code spans (commands, flags, config keys, file paths, event names, API names, version numbers) — verbatim, never translated or reformatted,\n- links and anchors: every relative link MUST point at the same target in both files — by convention the `.md` path, not the `.zh.md` sibling — so links never dangle when one pair lands before its neighbors. The ONLY zh-specific link is the language switcher. Link TEXT is translated; the target is not.\n\nThe repo's Markdown conventions apply to `.zh.md` files unchanged: one physical line per paragraph (`verify-md-wrap`), resolving relative links (`verify-md-links`), exactly one trailing newline.\n\n## Terminology\n\n- [terminology.md](terminology.md) is the source of truth in both directions. Before translating, load it; every listed term MUST follow its row and its \"不要译作\" prohibitions. A Chinese target uses the \"中文\" column and its \"首次出现\" annotation; an English target uses the \"English\" column without adding a Chinese gloss.\n- For a Chinese target, an unlisted technical term MAY use an established rendering from a major Chinese-language OSS or vendor source (K8s/Vue/MDN Chinese docs, 微软简中风格指南, big-tech project docs), cited in the PR. Without such precedent it MUST sLine truncated
       },
       {
         "role": "assistant",
-        "content": "# 翻译规则\n\n[English](translation-rules.md) | 中文\n\n本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 [README.md](README.md)）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效；应用这些规则的仓库内置 agent 工作流是 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md)。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ／ **禁止（MUST NOT）** 会卡门禁或评审；**应当（SHOULD）** 偏离时要说明理由；**可以（MAY）** 自行裁量。\n\n## 忠实性\n\n- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。\n- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。\n- 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。\n\n## 行文\n\n- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。\n- 以母语技术作者的身份重述内容，而不是逐句转写的译者。写完后逐句对照原文核验：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。\n- 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。\n- 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。\n- 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。\n- 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。\n\n## 结构保持\n\n配对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起���编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：\n\n- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；\n- 列表形态与编号；\n- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；\n- 围栏代码块：**逐字节一致，包括注释**。配对签名比对信息字符串与内容，` ```ts ` 块还要通过 `doc-typecheck` 编译；\n- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；\n- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。\n\n本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。\n\n## 术语\n\n- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。\n- 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。\n- 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简短说明，并列入「待定术语」。两个方向都不得自行创造译法；确定后的术语Line truncated
+        "content": "# 翻译规则\n\n[English](translation-rules.md) | 中文\n\n本文规定：如何在本仓库文档配对的中英文两种语言之间进行翻译。两种语言同权（见 [README.md](README.md)）：每次变更可以用任一语言撰写，被编辑的一侧即为本次更新的源；本文的规则约束如何产出或更新对侧文件。这些规则对人类和 agent（智能体）同等生效。日常工作中，agent 会在术语指导下直接一次完成有改动内容的翻译；扩展版 [.agents/skills/dsh-translate-docs](../../.agents/skills/dsh-translate-docs/SKILL.md) 工作流仅在用户显式调用时运行。规则级别沿用 RFC 2119 的用法：**必须（MUST）** ／ **禁止（MUST NOT）** 会卡门禁或评审；**应当（SHOULD）** 偏离时要说明理由；**可以（MAY）** 自行裁量。\n\n## 忠实性\n\n- 对侧文件*必须*传达与撰写侧相同的内容：不添加行为、前置条件、警告、版本声明或示例，也不漏掉任何一项。如果两侧在实质内容上不一致，没有哪种语言默认获胜；请修正错误的一侧，并在同一个变更里同步更新另一侧。\n- 对侧文件读起来*应当*是其语言自然的技术文字，而非逐词对照的译文。请根据语义翻译，在目标语言语法需要时重组句子，并保持原作者的语域（比如：简练的保持简练）。\n- 不要翻译不可译的内容：如果一句话依赖源语言的习语、无法自然转换，请翻译它的意思，而非习语本身。\n\n## 行文\n\n- 语体以 [style-samples.md](style-samples.md) 为校准锚点。人工定稿的金标样例按文体各一组，译文必须参照文体最接近的样例，采用其中目标语言一侧的语体；如果样例与本文的行文规则冲突，以样例为准。译成中文时，采用规范的技术制度文；译成英文时，采用简洁、专业的开发者文档语体。\n- 以母语技术作者的身份重述内容，而不是以译者身份逐句转写，同时保留原文的每个语义成分：不添加、不遗漏——流畅永远不是丢掉语义成分的理由。\n- 如果直译会让执行主体含糊，请明确写出实际执行者；译成中文时，应由「系统、门禁、评审人」等实际执行者作主语，避免含糊的被动句或抽象主语。\n- 优先采用目标语言中通行的工程表达，避免生硬直译（false positive/negative→误报／漏检、enforcement frontier→执行红线）；隐喻应自然改写，名词链则按目标语言的习惯拆开。\n- 长段按语义单元拆分，一段一件事。段落边界可以与原文不同；结构签名不比对段落数。\n- 翻译为中文时，类别名词使用中文并在首现括注英文（实操手册（cookbook））；翻译为英文时，使用通行的英文类别名。指目录或文件本身时保留代码体英文。\n\n## 结构保持\n\n���对门禁会检查标题深度、围栏代码块、表格行列数、列表类型、有序列表起始编号、列表项数量与链接目标；门禁未覆盖的结构仍需人工核对。两个配对文件必须在以下方面一一对应：\n\n- 标题层级（相同级别、相同顺序；标题的**文字**要翻译）；\n- 列表形态与编号；\n- 表格（相同的列、相同的行序；表头单元格按术语表翻译）；\n- 围栏代码块：**逐字节一致，包括注释**。配对签名比对信息字符串与内容，` ```ts ` 块还要通过 `doc-typecheck` 编译；\n- 行内代码（命令、flag、配置键、文件路径、事件名、API 名、版本号）：原样保留，从不翻译或重排；\n- 链接与锚点：每个相对链接在两个文件中必须指向相同的目标（按约定是 `.md` 路径而非 `.zh.md` 兄弟文件），这样即使某对文档先于相邻文件落地，链接也不会悬空。唯一的 zh 特有链接是语言切换行。链接**文字**翻译；链接目标不翻。\n\n本仓库的 Markdown 约定对 `.zh.md` 文件原样生效：一个段落一个物理行（`verify-md-wrap`）、相对链接必须可解析（`verify-md-links`）、文件末尾恰好一个换行。\n\n## 术语\n\n- [terminology.md](terminology.md) 是双向的术语真源。翻译前请先加载它；表内术语必须遵守对应行与「不要译作」禁项。译成中文时，采用「中文」列，并按「首次出现」列括注；译成英文时，采用「English」列，不加中文括注。\n- 译成中文时，术语表未收录的技术术语只有在主流中文 OSS 文档或厂商资料中已有通行译法时才可以翻译（K8s／Vue／MDN 中文文档、微软简中风格指南、大厂项目文档），并须在 PR 中注明出处；否则必须保留英文，并在 PR 描述的「待定术语」中给出建议译法。\n- 译成英文时，采用通行的英文技术术语。如果源术语没有明确的通行对应词，则保留原词、附上简Line truncated
       },
       {
         "role": "user",
-        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** The committed workflow is [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md), following the same pattern as [dsh-code-review](../../../skills/dsh-code-review/SKILL.md): the skill carries the workflow and defers to the docs as sources of truth. The skill directs the orchestrating agent to delegate translation writing to a subagent.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-prompt runnable snapshot](../../../../sLine truncated
+        "content": "# Agent Note: Bilingual documentation via paired sibling files and a pairing gate\n\nStatus: implemented\n\nEnglish | [中文](2026-07-02-bilingual-docs-and-pairing-gate.zh.md)\n\n## Problem\n\nThis repo's documentation corpus is read by people and agents inside and outside the company, in both English and Chinese. Maintaining a second language by hand, with no mechanism, is how translations rot: one side moves on, the other silently lies, and no gate notices. The repo's standing answer to invariants of this kind is to encode them as a mechanical check (see [quality gates](2026-06-11-quality-gates.md) and [doc-sync enforcement](../../archived/process/2026-06-11-doc-sync-enforcement.md)), so the bilingual policy ships with one.\n\n## Decision\n\n- **Paired sibling files with equal authority.** A documentation pair is three sibling files: English `foo.md`, Chinese `foo.zh.md`, and a consistency record `foo.i18n.yaml`. Neither language is canonical — a document may be authored and reviewed Chinese-first and translated to English afterwards, or the reverse; what binds the pair is that both sides must say the same thing, and pairs merge whole (both languages plus the record, never one alone). Policy: [docs/i18n/README.md](../../../../docs/i18n/README.md); translation rules: [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md); terminology source of truth: [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md).\n- **A sidecar record of both blob hashes makes consistency checkable.** `foo.i18n.yaml` holds the full git blob hash of each side as of the last confirmed-consistent state. An edit to either side without re-confirming the pair is then mechanically detectable as a pure content comparison — no history lookup — and the hashes are computable for files edited in the same PR, which a commit-hash record is not. Re-recording (`verify-translation-pairing --write <pair>`, which requires naming the confirmed pairs — bulk re-record is an explicit `--write --all`) produces a reviewable yaml diff: confirming consistency is an explicit, visible act in the PR.\n- **`verify-translation-pairing` joins `doc-sync`.** The gate ([scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)) enforces: every discovered, non-excluded source has a complete pair; every existing pair is complete (all three files) and consistent (both hashes match, the Chinese side and every authored English source carry their switchers while listed generated English sources are exempt, structural signatures identical); and excluded generated, instruction, or bilingual-by-construction files stay unpaired. [scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) contains only explicit exclusions, so no requirement can bypass discovery and receive a weaker check. Source-oriented code gates consume a `.zh.md` fence sequence as a derivative only when its unsuffixed sibling has the same tracked fences in the same order with byte-identical bodies; an incomplete, reordered, reclassified, or changed sequence stays independent, so the owning code gate or pairing gate reports the mismatch.\n- **One corpus-wide requirement.** Every document in scope requires a complete pair from creation; the policy has no per-file rollout state, date cutoff, or README-specific class. README discovery covers every case-insensitive README basename outside vendored, dependency, and ignored build-output trees, including future top-level directories. A site-published pair uses `pairedPages()` so the root locale projects `.zh.md` and `/en/` projects `.md`; creating a counterpart alone does not publish it.\n- **Pairing records are metadata, not Cordis Loader configuration.** Cordis configuration discovery accepts actual `.cordis.yml` and `.cordis.yaml` files while excluding `*.i18n.yaml`, even when the document name contains `cordis`. This preserves validation of executable Loader entries without parsing translation hashes as configuration.\n- **Translation is agent work with human review.** Routine changes use the direct one-pass path owned by the [lightweight-translation decision](2026-08-08-lightweight-routine-documentation-translation.md). The [extended translation skill](../../../skills/dsh-translate-docs/SKILL.md) retains delegated translation and the other heavier mechanisms for explicit user invocation; both paths defer to the documentation contracts as their sources of truth.\n\n## Verification\n\nThe verification contract covers each boundary independently. `verify-translation-pairing` pins pair completeness, hashes, switchers, and structure; [`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) pins locale-specific source selection for published pairs; [`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) pins discovery of Loader YAML and exclusion of translation records; and the [translation-pLine truncated
       },
       {
         "role": "assistant",
-        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 仓库内置的工作流是 [.agents/skills/dsh-translate-docs](../../../skills/dsh-translate-docs/SKILL.md)，与 [dsh-code-review](../../../skills/dsh-code-review/SKILL.md) 模式相同：skill（技能）承载工作流，并将文档作为真源。该 skill 要求编排 agent 把翻译写作委派给 subagent。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分Line truncated
+        "content": "# Agent Note: 通过配对兄弟文件与配对门禁实现双语文档\n\nStatus: implemented\n\n[English](2026-07-02-bilingual-docs-and-pairing-gate.md) | 中文\n\n## 问题\n\n本仓库的文档语料会被公司内外的人和 agent（智能体）以中英两种语言阅读。在没有机制的情况下纯靠手工维护第二语言，正是译文腐烂的根源：一侧持续演进，另一侧默默失实，而没有门禁会注意到。对于这类不变式，本仓库一贯的做法是将其编码为机械检查（见[质量门禁](2026-06-11-quality-gates.md)与 [doc-sync 强制](../../archived/process/2026-06-11-doc-sync-enforcement.md)），因此双语政策随附一道门禁一起交付。\n\n## 决策\n\n- **配对兄弟文件，两种语言同权。** 一对文档由三个兄弟文件组成：英文 `foo.md`、中文 `foo.zh.md`，以及一份一致性记录 `foo.i18n.yaml`。没有哪种语言是正典：一篇文档可以先用中文撰写和评审、之后再译成英文，反之亦可；约束配对的是：两侧必须表达相同的内容，且配对整体合并（两种语言加记录，绝不单独落一侧）。政策见 [docs/i18n/README.md](../../../../docs/i18n/README.md)；翻译规则见 [docs/i18n/translation-rules.md](../../../../docs/i18n/translation-rules.md)；术语真源见 [docs/i18n/terminology.md](../../../../docs/i18n/terminology.md)。\n- **伴随记录保存两侧 blob hash，使一致性可检查。** `foo.i18n.yaml` 保存两侧文件在上一次确认一致时各自的完整 git blob hash。此后修改了任一侧而未重新确认配对，都能被机械检测出来（纯内容比较，无需查询历史），而且同一个 PR（Pull Request）内改动的文件也能计算出 hash，commit hash 式的记录做不到这一点。重新记录（`verify-translation-pairing --write <pair>`，要求点名所确认的配对；批量重新记录是显式的 `--write --all`）会产生一份可评审的 yaml diff：确认一致在 PR 中是一个显式、可见的动作。\n- **`verify-translation-pairing` 加入 `doc-sync`。** 门禁（[scripts/verify-translation-pairing.ts](../../../../scripts/verify-translation-pairing.ts)）强制执行以下规则：每个已发现且未排除的源文档都有完整配对；每个现有配对都完整（三个文件齐全）且一致（两个 hash 匹配、中文侧和所有普通撰写的英文源都带切换行而清单内的生成英文源除外、结构签名一致）；被排除的生成文档、指令文档或本身即双语的文档不得配对。[scripts/translation-pairing.manifest.json](../../../../scripts/translation-pairing.manifest.json) 只包含显式排除项，因此任何要求都无法绕过发现流程而接受较弱的检查。只有当 `.zh.md` 围栏序列与其无后缀兄弟文件拥有顺序相同、正文按字节一致的同一组受跟踪围栏时，面向源码的代码门禁才会将其作为派生内容消费；不完整、顺序变更、重分类或已改动的序列仍会独立受检，因此由其所属的代码门禁或配对门禁报告不匹配。\n- **全语料统一要求。** 范围内的每篇文档从创建起就必须有完整配对；政策没有逐文件推进状态、日期分界或 README 专用类别。README 发现会覆盖 vendor 源码、依赖目录与被忽略的构建产物目录之外所有文件名不区分大小写匹配 README 的文件，包括今后新增的顶层目录。发布到文档站的配对使用 `pairedPages()`，由根 locale 投影 `.zh.md`，由 `/en/` 投影 `.md`；仅创建对侧文件并不会发布它。\n- **配对记录是元数据，而不是 Cordis Loader 配置。** Cordis 配置发现会接受实际的 `.cordis.yml` 和 `.cordis.yaml` 文件，同时排除 `*.i18n.yaml`，即使文档名中包含 `cordis` 也不例外。这样既能继续校验可执行的 Loader 配置项，又不会把翻译 hash 当作配置来解析。\n- **翻译是 agent 的工作，由人评审。** 常规改动采用由[轻量翻译决策](2026-08-08-lightweight-routine-documentation-translation.md)确立的直接单遍路径。[扩展翻译 skill（技能）](../../../skills/dsh-translate-docs/SKILL.md)保留委派翻译和其他较重机制，供用户显式调用；两条路径均以文档契约为真源。\n\n## 验证\n\n验证约定分别覆盖每个边界。`verify-translation-pairing` 固定配对完整性、hash、切换行和结构；[`project-doc-site.spec.ts`](../../../../scripts/project-doc-site.spec.ts) 固定已发布配对按 locale 选择对应源文件；[`cordis-config-files.spec.ts`](../../../../scripts/cordis-config-files.spec.ts) 固定 Loader YAML 的发现以及翻译记录的排除；[翻译提示词可运行快照](../../../../scripts/translation-prompt.snapshot.ts)则固定渲染后的系统消息、五对经评审的示例、源请求和响应消费结果。这些检查共同使配对漂移、发布漂移、配置误分Line truncated
       },
       {
         "role": "user",

scripts/test-invariants.spec.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, vi } from 'vitest'
-import { Context, FiberState, Service, ValidationError } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import z from 'schemastery'
+import { Context, FiberState, Service, ValidationError } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import z from '@deepseek-ai/schemastery'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
 import { packageInvariantOwners } from './package-invariants.ts'
@@ -13,7 +13,7 @@ import {
   usesManualInvariantTree,
 } from './test-invariants.ts'
 
-declare module 'cordis' {
+declare module '@deepseek-ai/cordis' {
   interface Context {
     testInvariantProbe: TestInvariantProbe
   }
@@ -39,18 +39,6 @@ function requiredConfig() {
   })
 }
 
-function queuedReadinessConfig(
-  ctx: Context,
-  onPublished: (dispose: () => void) => void,
-) {
-  return z.transform(z.any(), () => {
-    queueMicrotask(() => {
-      onPublished(ctx.provide(TEST_INVARIANT_READY_SERVICE, true))
-    })
-    return {}
-  }, true)
-}
-
 function invalidConfigApply(): never {
   throw new Error('invalid plugin apply executed')
 }
@@ -137,7 +125,7 @@ describe('global test invariant host', () => {
       .toEqual(Object.keys(testInvariantCompanions).sort())
   })
 
-  it('loads and executes every source companion through the real Loader shape', async () => {
+  it('loads and executes every source companion through the real Loader setup', async () => {
     const owners = new Map(packageInvariantOwners(process.cwd()).map(owner => [owner.sourcePath, owner.packageName]))
     const registrations = new Map<string, string>()
     const loader = Object.create(Loader.prototype) as Loader
@@ -189,84 +177,55 @@ describe('global test invariant host', () => {
     expect(apply).not.toHaveBeenCalled()
   })
 
-  it('disposes invalid config when readiness refresh wins the rejection-handler race', async () => {
+  it('disposes invalid config after delayed invariant readiness', async () => {
     await withDelayedFirstCompanion(
       async ({ started, release }) => {
         const ctx = new Context()
         const apply = vi.fn(invalidConfigApply)
-        let disposeQueuedReadiness: (() => void) | undefined
         const plugin = {
           apply,
-          Config: z.intersect([
-            queuedReadinessConfig(ctx, (dispose) => {
-              disposeQueuedReadiness = dispose
-            }),
-            requiredConfig(),
-          ]),
+          Config: requiredConfig(),
         }
 
         const fiber = ctx.plugin(plugin, {})
-        const firstError = await rejectionOf(fiber)
-        expectRequiredConfigValidation(firstError)
-        expect(fiber.state).toBe(FiberState.DISPOSED)
+        const returnedError = rejectionOf(fiber)
+        await started
+        expect(fiber.state).toBe(FiberState.PENDING)
         expect(apply).not.toHaveBeenCalled()
 
-        await started
-        if (disposeQueuedReadiness === undefined) throw new Error('queued readiness was not published')
-        disposeQueuedReadiness()
         release()
-        await ctx.plugin(TestInvariantProbe)
-
-        const secondError = await rejectionOf(fiber)
-        expect(secondError).toBe(firstError)
+        expectRequiredConfigValidation(await returnedError)
         expect(fiber.state).toBe(FiberState.DISPOSED)
         expect(apply).not.toHaveBeenCalled()
       },
     )
   })
 
-  it('retains a valid plugin failure when readiness wins the initial-probe race', async () => {
+  it('retains a valid plugin failure after delayed invariant readiness', async () => {
     await withDelayedFirstCompanion(
       async ({ started, release }) => {
         const ctx = new Context()
         const failure = new Error('valid plugin apply failed')
-        const applied = deferred()
         const apply = vi.fn(function validConfigApply() {
-          applied.resolve()
           throw failure
         })
-        let disposeQueuedReadiness: (() => void) | undefined
         const plugin = {
           apply,
-          Config: queuedReadinessConfig(ctx, (dispose) => {
-            disposeQueuedReadiness = dispose
-          }),
+          Config: z.object({}),
         }
 
         const fiber = ctx.plugin(plugin, {})
         const returnedError = rejectionOf(fiber)
-        try {
-          await Promise.all([started, applied.promise])
-          expect(fiber.state).toBe(FiberState.FAILED)
-          expect(apply).toHaveBeenCalledOnce()
-          expect(ctx.registry.has(plugin)).toBe(true)
-          expect(ctx.registry.get(plugin)?.fibers).toHaveLength(1)
+        await started
+        expect(fiber.state).toBe(FiberState.PENDING)
+        expect(apply).not.toHaveBeenCalled()
 
-          if (disposeQueuedReadiness === undefined) throw new Error('queued readiness was not published')
-          Reflect.deleteProperty(fiber.inject, TEST_INVARIANT_READY_SERVICE)
-          disposeQueuedReadiness()
-          release()
-
-          expect(await returnedError).toBe(failure)
-          expect(fiber.state).toBe(FiberState.FAILED)
-          expect(apply).toHaveBeenCalledOnce()
-          expect(ctx.registry.has(plugin)).toBe(true)
-          expect(ctx.registry.get(plugin)?.fibers).toHaveLength(1)
-        } finally {
-          Reflect.deleteProperty(fiber.inject, TEST_INVARIANT_READY_SERVICE)
-          disposeQueuedReadiness?.()
-          release()
-        }
+        release()
+        expect(await returnedError).toBe(failure)
+        expect(fiber.state).toBe(FiberState.FAILED)
+        expect(apply).toHaveBeenCalledOnce()
+        expect(ctx.registry.has(plugin)).toBe(true)
+        expect(ctx.registry.get(plugin)?.fibers).toHaveLength(1)
       },
     )
   })

scripts/test-invariants.ts

@@ -6,8 +6,15 @@
  */
 
 import { expect } from 'vitest'
-import { FiberState, Inject, RegistryService } from 'cordis'
-import type { Context, Plugin } from 'cordis'
+import { FiberState, Inject, RegistryService, ValidationError } from '@deepseek-ai/cordis'
+import type { Context, Plugin } from '@deepseek-ai/cordis'
+import { AttachmentStore } from '@deepseek-ai/dsh-attachment'
+import type {
+  ImageAttachmentLimits,
+  ImageAttachmentRef,
+  SaveImageAttachment,
+  StoredImageAttachment,
+} from '@deepseek-ai/dsh-attachment'
 import InvariantService from '@deepseek-ai/dsh-invariants'
 
 declare global {
@@ -17,7 +24,7 @@ declare global {
   }
 }
 
-/** Loader-safe shape shared by every package invariant companion. */
+/** Loader-safe exports shared by every package invariant companion. */
 export interface TestInvariantCompanion {
   readonly name: string
   readonly inject: readonly string[]
@@ -102,6 +109,29 @@ export function usesManualInvariantTree(testPath: string): boolean {
 }
 
 const ALL_COMPANION_TESTS = ['/scripts/test-invariants.spec.ts'] as const
+const ATTACHMENT_COMPANION = '../packages/attachment/attachment-local/src/invariant.ts'
+
+class TestAttachmentStore extends AttachmentStore {
+  readonly imageLimits: ImageAttachmentLimits = {
+    maxImageBytes: 1,
+    maxImagesPerMessage: 1,
+    maxMessageImageBytes: 1,
+    maxImagePixels: 1,
+    mediaTypes: ['image/png'],
+  }
+
+  validateImage(_input: SaveImageAttachment): Promise<void> {
+    return Promise.reject(new Error('test invariant attachment store does not validate images'))
+  }
+
+  saveImage(_input: SaveImageAttachment): Promise<ImageAttachmentRef> {
+    return Promise.reject(new Error('test invariant attachment store does not save images'))
+  }
+
+  readImage(_ref: ImageAttachmentRef): Promise<StoredImageAttachment> {
+    return Promise.reject(new Error('test invariant attachment store does not read images'))
+  }
+}
 
 /**
  * Select the package companions that an ordinary test root must register.
@@ -148,6 +178,9 @@ function startInvariantHost(root: Context): InvariantHost {
   const testPath = expect.getState().testPath ?? ''
   const companionPaths = testInvariantCompanionPaths(testPath)
   const ready = requireActive(serviceFiber, 'invariant service').then(async () => {
+    const attachmentFiber = companionPaths.includes(ATTACHMENT_COMPANION)
+      ? mount(TestAttachmentStore)
+      : undefined
     const companions = await Promise.all(companionPaths.map(async (path) => {
       const load = testInvariantCompanions[path]
       if (load === undefined) {
@@ -163,7 +196,12 @@ function startInvariantHost(root: Context): InvariantHost {
       fiber: mount(companion),
       path,
     }))
-    await Promise.all(companionFibers.map(({ fiber, path }) => requireActive(fiber, path)))
+    await Promise.all([
+      ...(attachmentFiber === undefined
+        ? []
+        : [requireActive(attachmentFiber, 'test attachment store')]),
+      ...companionFibers.map(({ fiber, path }) => requireActive(fiber, path)),
+    ])
     root.provide(TEST_INVARIANT_READY_SERVICE, true)
   })
   const host = { byCallback, barrierOwners, ready }
@@ -210,22 +248,25 @@ function withInvariantReadiness(plugin: Plugin, callback: PluginCallback): Plugi
 function joinInvariantStartup(
   fiber: PluginFiber,
   invariantReady: Promise<void>,
-  disposeInitialFailure = false,
+  disposePendingValidationFailure = false,
 ): PluginFiber {
   // RegistryService returns a thenable wrapper whose context still points to
   // the raw Fiber. Calling inherited await() on the wrapper would return and
   // assimilate that thenable, accidentally following later plugin startup.
   const rawFiber = fiber.ctx.fiber
-  const initialized = disposeInitialFailure
-    ? rawFiber.await().catch(async (error: unknown) => {
-      // Config validation is the only failure recorded while a gated fiber
-      // is initially PENDING. Dispose it even if queued readiness publication
-      // changes its state before this rejection handler runs.
-      await rawFiber.dispose()
+  const readiness = invariantReady.then(async () => {
+    try {
+      return await rawFiber.await()
+    } catch (error) {
+      // Config resolves only after the readiness injection activates. Dispose
+      // validation failures owned by an initially pending target; ordinary
+      // callback failures remain inspectable.
+      if (disposePendingValidationFailure && error instanceof ValidationError) {
+        await rawFiber.dispose()
+      }
       throw error
-    })
-    : Promise.resolve()
-  const readiness = initialized.then(() => invariantReady).then(() => rawFiber.await())
+    }
+  })
   const joined = Object.create(fiber) as PluginFiber
   joined.then = readiness.then.bind(readiness)
   return joined

scripts/translation-pairing-git.ts

@@ -54,7 +54,7 @@ export interface GitIndexBlob {
  * @param root - Repository root.
  * @param path - Repository-relative path.
  * @returns The stage-zero blob, or `undefined` when the path is absent.
- * @throws Error when the path is unmerged or has an invalid index shape.
+ * @throws Error when the path is unmerged or its index entries are not a valid merge state.
  */
 export function readGitIndexBlob(root: string, path: string): GitIndexBlob | undefined {
   const output = runGit(

scripts/translation-pairing-merge.spec.ts

@@ -19,7 +19,7 @@ import {
 const driver = fileURLToPath(new URL('./merge-translation-pairing.ts', import.meta.url))
 const driverLauncher = fileURLToPath(new URL('./merge-translation-pairing-driver.sh', import.meta.url))
 const workspaceRoot = fileURLToPath(new URL('../', import.meta.url))
-const tsxLoader = fileURLToPath(import.meta.resolve('tsx/esm'))
+const tsxLoader = import.meta.resolve('tsx/esm')
 const fixtures: string[] = []
 
 interface Fixture {
@@ -231,7 +231,7 @@ function expectMergedPair(fixture: Fixture): void {
   )
 }
 
-describe('translation pairing merge composition', () => {
+describe('translation pairing merge composition', { timeout: 15_000 }, () => {
   it('rejects a pairing-record path outside the repository', () => {
     const fixture = createFixture(false)
 

scripts/translation-pairing.spec.ts

@@ -182,6 +182,9 @@ describe('translation pairing records', () => {
 describe('translation scope discovery', () => {
   it.each([
     'README.md',
+    'CONTRIBUTING.md',
+    'CONTRIBUTING.zh.md',
+    'CONTRIBUTING.i18n.yaml',
     'apps/cli/README.md',
     'future/subtree/readme.md',
     'packages/example/README.zh.md',
@@ -195,6 +198,7 @@ describe('translation scope discovery', () => {
 
   it.each([
     'packages/example/guide.md',
+    'packages/example/CONTRIBUTING.md',
     'examples/tutorial.md',
     'website/reference.md',
     'packages/example/README.txt',

scripts/translation-pairing.ts

@@ -80,7 +80,7 @@ const PAIR_META_LINE = /^([^:#]+\.md): ([0-9a-f]{40})$/
 /**
  * Parse a `foo.i18n.yaml` consistency record into basename → recorded blob
  * hash, or undefined when any non-comment line deviates from the exact
- * `<basename>.md: <40-hex>` shape or repeats a key. Consumers must
+ * `<basename>.md: <40-hex>` format or repeats a key. Consumers must
  * additionally require exactly the two expected basenames — a renamed key is
  * a malformed record, never a silently-missing entry.
  * @param content - Sidecar file text.
@@ -118,13 +118,14 @@ export function renderPairMeta(source: string, sourceHash: string, zh: string, z
   ].join('\n')
 }
 
-/** Validated shape of `scripts/translation-pairing.manifest.json`. */
+/** Validated fields of `scripts/translation-pairing.manifest.json`. */
 export interface TranslationPairingManifest {
   /** Source documents exempt from pairing because they are generated, instructional, or bilingual by construction. */
   excluded: string[]
 }
 
 const README_ARTIFACT = /(?:^|\/)readme(?:\.md|\.zh\.md|\.i18n\.yaml)$/i
+const ROOT_CONTRIBUTING_ARTIFACT = /^contributing(?:\.md|\.zh\.md|\.i18n\.yaml)$/i
 const NON_SOURCE_DIRECTORIES = new Set([
   'node_modules',
   'lib',
@@ -179,6 +180,7 @@ function isTranslationSourceExcluded(file: string): boolean {
 export function isTranslationScopeFile(file: string): boolean {
   return !file.startsWith('.agents/notes/archived/')
     && !isTranslationSourceExcluded(file) && (README_ARTIFACT.test(file)
+    || ROOT_CONTRIBUTING_ARTIFACT.test(file)
     || file.startsWith('.agents/notes/')
     || file.startsWith('docs/')
     || file.startsWith('python/'))
@@ -281,7 +283,7 @@ export function parseTranslationPairingCliArgs(argv: string[]): TranslationPairi
   }
 }
 
-/** The structural surface compared between the two sides of a pair. */
+/** The structural signature compared between the two sides of a pair. */
 export interface TranslationStructureSignature {
   /** Heading depths in document order (h2 -> 2). */
   headings: number[]

scripts/translation-prompt.spec.ts

@@ -21,7 +21,7 @@ const retainedExamples = [
   ['### Stiff passive voice → Active and natural', 'a green gate means the pair was confirmed consistent at these exact contents, not that the confirmation was sound.', '门禁通过意味着这组文档在当前内容上的一致性得到了确认，不代表确认本身正确可靠。'],
   ['### Invented word → Natural expression', 'A sidecar record of both blob hashes makes consistency checkable', '伴随记录保存两侧 blob hash，使一致性可检查'],
   ['### Em-dash → Colon/period', 'FIXME — an issue that should block a new release.', 'FIXME：应当阻塞新版本发布的问题。'],
-  ['### Overly literal → Meaningful rendering', 'awkward phrasing is easier to hear without the source anchoring you', '不对照原文时，更容易察觉别扭的表达'],
+  ['### Overly literal → Meaningful rendering', 'awkward phrasing is easier to notice when you read the translation without comparing it with the source', '不对照原文阅读译文时，更容易察觉别扭的表达'],
   ['### Terminology — do not translate what should be kept in English', 'typed service seams, and explicit extension points', '类型化的服务 seam 与显式扩展点'],
   ['### Slang/jargon → Professional phrasing', 'The committed agent workflow lives in .agents/skills/dsh-translate-docs', '仓库内置的 agent 工作流见 .agents/skills/dsh-translate-docs'],
   ['### "For humans" — translate the intent, not the word', 'For humans, start with the development guide', '面向开发者：请先阅读开发指南'],
@@ -44,7 +44,7 @@ describe('translation prompt rendering', () => {
     expect(zh).toContain('from Chinese to English')
   })
 
-  it('retains every v4 embedded example', () => {
+  it('contains every embedded example', () => {
     for (const example of retainedExamples) {
       for (const fragment of example) expect(document).toContain(fragment)
     }

scripts/translation-prompt.ts

@@ -169,7 +169,7 @@ function unescapeResponseBody(value: string): string {
   }).join('\n')
 }
 
-/** Serialize a response in the exact escaped three-section shape the prompt requests. */
+/** Serialize a response in the exact escaped three-section format the prompt requests. */
 export function renderTranslationResponse(response: TranslationResponse): string {
   return RESPONSE_SECTIONS.map(section => `<${section}>\n${escapeResponseBody(response[section])}\n</${section}>`).join('\n\n')
 }
@@ -178,7 +178,7 @@ export function renderTranslationResponse(response: TranslationResponse): string
  * Parse the three-section response. Sections must each appear exactly once
  * and in order; escaped delimiter lines in Markdown bodies are restored.
  * A fenced ```xml wrapper around the whole response is tolerated, matching
- * the shape some models echo back from the prompt's own example.
+ * the wrapper some models copy from the prompt's own example.
  */
 export function parseTranslationResponse(text: string): TranslationResponse {
   let body = text.trim()

scripts/type-equiv.manifest.json

@@ -520,6 +520,11 @@
       "symbol": "SessionLocation",
       "source": "packages/session/session-persistence/src/index.ts"
     },
+    {
+      "doc": "docs/subsystems/persistence.md",
+      "symbol": "SessionRawArtifact",
+      "source": "packages/session/session-persistence/src/index.ts"
+    },
     {
       "doc": "docs/subsystems/session-query.md",
       "symbol": "SessionEventSurface",
@@ -860,6 +865,31 @@
       "symbol": "ApprovalRequest",
       "source": "packages/interaction/user-approval/src/index.ts"
     },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageMediaType",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageAttachmentRef",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "ImageAttachmentLimits",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "SaveImageAttachment",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/attachment.md",
+      "symbol": "StoredImageAttachment",
+      "source": "packages/attachment/attachment/src/types.ts"
+    },
     {
       "doc": "docs/subsystems/bash.md",
       "symbol": "BashExecRequest",
@@ -1140,6 +1170,11 @@
       "symbol": "SkillLookupOptions",
       "source": "packages/skill/skill/src/index.ts"
     },
+    {
+      "doc": "docs/subsystems/skills.md",
+      "symbol": "SkillViewOptions",
+      "source": "packages/skill/skill/src/index.ts"
+    },
     {
       "doc": "docs/subsystems/skills.md",
       "symbol": "SkillProviderObservation",
@@ -1215,6 +1250,11 @@
       "symbol": "SubagentReportDelivery",
       "source": "packages/subagent/subagent/src/continuation.ts"
     },
+    {
+      "doc": "docs/subsystems/subagent.md",
+      "symbol": "SubagentSettledMessageSource",
+      "source": "packages/subagent/subagent/src/continuation.ts"
+    },
     {
       "doc": "docs/subsystems/subagent.md",
       "symbol": "SubagentReportOptions",
@@ -1328,7 +1368,7 @@
     {
       "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowStartRequest",
-      "source": "packages/workflow/workflow/src/types.ts"
+      "source": "packages/workflow/workflow/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/workflow.md",
@@ -1343,7 +1383,7 @@
     {
       "doc": "docs/subsystems/workflow.md",
       "symbol": "WorkflowRun",
-      "source": "packages/workflow/workflow/src/types.ts"
+      "source": "packages/workflow/workflow/src/runtime-types.ts"
     },
     {
       "doc": "docs/subsystems/lsp.md",
@@ -1670,6 +1710,11 @@
       "symbol": "WebBootGraph",
       "source": "packages/client/modules/src/client/manifest.ts"
     },
+    {
+      "doc": "docs/subsystems/telemetry.md",
+      "symbol": "TelemetrySharingStatus",
+      "source": "packages/session/session-telemetry/src/index.ts"
+    },
     {
       "doc": "docs/subsystems/telemetry.md",
       "symbol": "TelemetrySeverity",
@@ -1784,6 +1829,101 @@
       "doc": "docs/subsystems/core.md",
       "symbol": "AgentOptions",
       "source": "packages/core/agent/src/runtime-types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackVersion",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackRating",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackItem",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackListRequest",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackListValue",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackPutRequest",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackDeleteRequest",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackDeleteValue",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackSessionNotFound",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackTargetNotFound",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackVersionConflict",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackNoteBlank",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackNoteTooLarge",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackFailure",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackSuccess",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackRejected",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackListResult",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackPutResult",
+      "source": "packages/feedback/message-feedback/src/types.ts"
+    },
+    {
+      "doc": "docs/subsystems/feedback.md",
+      "symbol": "MessageFeedbackDeleteResult",
+      "source": "packages/feedback/message-feedback/src/types.ts"
     }
   ]
 }

scripts/verify-agent-note-classification.ts

@@ -1,6 +1,6 @@
 /**
  * Enforce Agent Note lifecycle/class paths and dated filenames. Structural rules
- * are shared with `agent-note-tree.ts`; the closed classification contract lives
+ * are shared with `agent-note-tree.ts`; the closed classification rules live
  * in `.agents/notes/README.md`.
  */
 

scripts/verify-agent-note-format.ts

@@ -9,7 +9,7 @@ import { readFileSync } from 'node:fs'
 import { resolve } from 'node:path'
 import { agentNoteRoot, walkAgentNoteTree } from './agent-note-tree.ts'
 
-/** The date the format contract landed; the grandfather comment is valid only before it. */
+/** The date these format rules took effect; the grandfather comment is valid only before it. */
 const FORMAT_ADOPTED = '2026-07-05'
 
 /** The exact comment a pre-format Agent Note carries in place of `## Alternatives considered`. */

scripts/verify-archived-agent-notes.ts

@@ -99,7 +99,7 @@ if (!writeMode) {
 }
 
 if (errors.length > 0) {
-  console.error('verify-archived-agent-notes: archive contract violated:')
+  console.error('verify-archived-agent-notes: archive rules violated:')
   for (const error of errors) console.error(`  ${error}`)
   process.exit(1)
 }

scripts/verify-client-domain-graph.ts

@@ -6,7 +6,7 @@
  * across domains.
  *
  * Layer model (lower may not import higher):
- *   0  contract/            shared contract surface (types + slot declarations)
+ *   0  contract/            shared contract API (types + slot declarations)
  *   1  <domain>/ + service  domain implementations (skeleton/, chat/, ...)
  *   2  apply.ts, index.ts   assembly point and re-export shell
  *
@@ -71,7 +71,7 @@ function checkPackage(pkgName: string, clientDir: string): Violation[] {
         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/)`,
+          : `domain "${fromDomain}" imports sibling domain "${toDomain}" (route shared API through contract/)`,
       })
     }
   }

scripts/verify-config-source-ownership.ts

@@ -19,7 +19,7 @@ const SHIPPED_CONFIG_GLOBS = [
   'python/*/src/**/cordis.yml',
 ]
 
-/** Ordinary single-line forms this narrow source-shape check rejects; not full YAML analysis. */
+/** Ordinary single-line configuration forms this source check rejects; not full YAML analysis. */
 const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
 
 /** Return every forbidden inline environment form in shipped configuration. */

scripts/verify-cordis-config.ts

@@ -79,6 +79,7 @@ for (const file of files) {
 errors.push(...validateExampleResolution())
 errors.push(...validateAppResolution())
 errors.push(...validateSourcePlaneResolution())
+errors.push(...validatePresetPlaneSeparation())
 
 if (errors.length > 0) {
   console.error('verify-cordis-config: invalid Loader metadata or plugin package resolution:')
@@ -88,6 +89,76 @@ if (errors.length > 0) {
   console.log(`verify-cordis-config: ${files.length} config files passed.`)
 }
 
+/**
+ * No shipped agent preset may repeat a row the host composition still runs.
+ *
+ * A preset contributes what ONE session adds to the host's registries. A row
+ * active on both planes is therefore mounted twice — once per process and once
+ * per session — and what that costs depends on what the row does: a provider
+ * behind an `isolate` realm shadows the host's for its own consumers, so a host
+ * contributor to that service reaches nobody; a row that registers into a host
+ * singleton registers once per live session, so the second one collides.
+ *
+ * Both have happened. `bash-env` in a preset realm left `DSH_WEB_URL` reaching
+ * no shell, and `tool-subagent-report` handed every child `report` once per live
+ * session until the second registration threw. Neither changes a tool catalog,
+ * so no catalog assertion can see them — and the shipped presets are near-copies
+ * of each other, so a fix applied to three of four is the normal failure.
+ * @returns one diagnostic per preset row that is also active on the host plane.
+ */
+function validatePresetPlaneSeparation(): string[] {
+  const problems: string[] = []
+  // The shipped Web surface is two bundle patch layers over an empty root.
+  const hostFile = 'packages/bundle/base/cordis.patch.yml'
+  const overlayFile = 'packages/bundle/web-app/cordis.patch.yml'
+  const hostRows = rowIds(hostFile)
+  const overlay = loadEntries(overlayFile)
+  const disabled = new Set<string>()
+  for (const entry of overlay) {
+    if (!isRecord(entry)) continue
+    if (entry.disabled === true && typeof entry.id === 'string') disabled.add(entry.id)
+  }
+  // The overlay's own inserts are host-plane too; its disables take them back out.
+  const active = new Set([...hostRows, ...rowIds(overlayFile)].filter(id => !disabled.has(id)))
+  for (const file of globSync('apps/cli/config/agent-presets/*/agent.cordis.yml', { cwd: root })) {
+    for (const id of rowIds(file)) {
+      if (!active.has(id)) continue
+      problems.push(
+        `${file}: row "${id}" is also active in the host composition; `
+        + 'a row belongs to exactly one plane',
+      )
+    }
+  }
+  return problems
+}
+
+/** Every entry of one config file, or an empty list when it is not an entry array. */
+function loadEntries(file: string): unknown[] {
+  const document: unknown = yaml.load(readFileSync(resolve(root, file), 'utf8'), { schema })
+  return isUnknownArray(document) ? document : []
+}
+
+/**
+ * Row ids declared anywhere in one config file, including inside group `config`
+ * lists — a preset nests most of its rows in `isolate` groups.
+ * @param file - repository-relative config path.
+ * @returns the declared ids.
+ */
+function rowIds(file: string): Set<string> {
+  const ids = new Set<string>()
+  const walk = (value: unknown): void => {
+    if (isUnknownArray(value)) {
+      for (const item of value) walk(item)
+      return
+    }
+    if (!isRecord(value)) return
+    if (typeof value.id === 'string' && typeof value.name === 'string') ids.add(value.id)
+    for (const child of Object.values(value)) walk(child)
+  }
+  walk(loadEntries(file))
+  return ids
+}
+
 function validateEntry(value: unknown, file: string, path: string): void {
   if (!isRecord(value)) {
     errors.push(`${file}${path}: entry must be an object`)
@@ -95,7 +166,7 @@ function validateEntry(value: unknown, file: string, path: string): void {
   }
   recordPlugin(value, file)
   validateMetadata(value, file, path)
-  if ((value.group === true || value.name === '@cordisjs/plugin-group') && isUnknownArray(value.config)) {
+  if ((value.group === true || value.name === '@deepseek-ai/cordis-plugin-group') && isUnknownArray(value.config)) {
     for (let index = 0; index < value.config.length; index++) {
       validateEntry(value.config[index], file, `${path}.config[${index}]`)
     }
@@ -105,7 +176,7 @@ function validateEntry(value: unknown, file: string, path: string): void {
       validateEntry(value.insert[index], file, `${path}.insert[${index}]`)
     }
   }
-  if (value.name !== '@cordisjs/plugin-include') return
+  if (value.name !== '@deepseek-ai/cordis-plugin-include') return
   const config = value.config
   if (!isRecord(config) || !isUnknownArray(config.patches)) return
   for (let index = 0; index < config.patches.length; index++) {

scripts/verify-export-jsdoc.ts

@@ -58,7 +58,7 @@ function thisReceiver(p: ts.ParameterDeclaration): boolean {
 }
 
 /**
- * Peel wrapper expressions that carry no surface of their own — parentheses,
+ * Peel wrapper expressions that define no API of their own — parentheses,
  * `as` / `satisfies` / angle-bracket casts, non-null assertions — so a
  * wrapped function expression is still classified as function-like.
  * @param e - the expression to unwrap.
@@ -75,9 +75,9 @@ function unwrapExpression(e: ts.Expression): ts.Expression {
 
 /**
  * Classify inline callable annotations. Mixed callable literals fail closed;
- * other annotations are ordinary value shapes.
+ * other annotations are ordinary value types.
  * @param type - the declarator's type annotation.
- * @returns the signature to check, 'refuse' for an unclassifiable callable literal, or null for a non-callable shape.
+ * @returns the signature to check, 'refuse' for an unclassifiable callable literal, or null for a non-callable type.
  */
 function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'refuse' | null {
   if (ts.isFunctionTypeNode(type)) return type
@@ -91,7 +91,7 @@ function callableAnnotation(type: ts.TypeNode): ts.SignatureDeclarationBase | 'r
 }
 
 /**
- * Find inherited documentation for a class member without exempting newly public surface.
+ * Find inherited documentation for a class member without exempting a newly public API.
  * @param cls - the class whose heritage to search.
  * @param name - the member name to look up.
  * @param staticSide - whether to search the constructor side instead of the instance side.
@@ -112,7 +112,7 @@ function heritageExemption(
       const prop = type.getProperty(name)
       if (prop === undefined) continue
       const decls = prop.declarations ?? []
-      if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new surface
+      if (decls.length > 0 && decls.every(isProtected)) continue // public override of a protected base: new API
       let baseParams: Set<string> | null = null
       let baseVoidReturn: boolean | null = null
       for (const d of decls) {
@@ -192,7 +192,7 @@ function checkFunctionLike(
   if (!raw) { w.violations.push(`${where} has no JSDoc.`); return }
   if (!parseJsDoc(raw).doc) w.violations.push(`${where} has no description prose above its block tags.`)
   const { params, returns } = parseTags(raw)
-  checkParams(where, 'export', parameters, params, w.sf, thisReceiver, w.violations)
+  checkParams(where, 'exported', parameters, params, w.sf, thisReceiver, w.violations)
   if (!returnsWaived) checkReturns(where, returnType, returns, w.sf, w.violations)
 }
 
@@ -205,7 +205,7 @@ function checkFunctionLike(
  * statics are exempt; constructors are not checked (framework-constructed
  * plugins, and the class doc owns the story).
  * @param cls - the exported class declaration.
- * @param name - the class's surface name (namespace-qualified).
+ * @param name - the class's exported name (namespace-qualified).
  * @param w - the walk state violations append to.
  */
 function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
@@ -230,12 +230,12 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
         const raw = rawJsDoc(w.text, m)
         // The heritage declaration owns the prose; parameters the base never
         // names — including binding patterns, which no base declaration can
-        // name — are new surface and keep their @param duty.
+        // name — are new API and keep their @param duty.
         const base = exemption.baseParams
         const inBase = (p: ts.ParameterDeclaration): boolean =>
           base !== null && ts.isIdentifier(p.name) && base.has(p.name.text.replace(/^_+/, ''))
         if (base !== null && m.parameters.some(p => !thisReceiver(p) && !inBase(p))) {
-          checkParams(where, 'export', m.parameters, parseTags(raw).params, w.sf,
+          checkParams(where, 'exported', m.parameters, parseTags(raw).params, w.sf,
             p => thisReceiver(p) || inBase(p), w.violations)
         }
         // A void base return carried no @returns duty, so an override growing a concrete result
@@ -258,7 +258,7 @@ function checkClass(cls: ts.ClassDeclaration, name: string, w: Walk): void {
     } else if (ts.isSetAccessorDeclaration(m) && !documentedGetters.has(mname)) {
       checkDescribed(`exported class accessor '${name}.${mname}' (${pointer(w.rel, w.sf, m)})`, rawJsDoc(w.text, m), w)
     }
-    // index signatures / static blocks: not named surface
+    // index signatures / static blocks: no named API
   }
 }
 
@@ -310,7 +310,7 @@ function checkDecl(
     const raw = rawJsDoc(w.text, stmt) // JSDoc sits on the statement, not the declarator
     for (const d of stmt.declarationList.declarations) {
       const name = ts.isIdentifier(d.name) ? d.name.text : d.name.getText(w.sf)
-      if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not surface
+      if (only !== null && !only.has(name)) continue // sibling declarator the export list never named: not exported API
       if (prefix === '' && PROTOCOL_EXPORTS.has(name)) continue // cordis plugin-protocol slot
       const where = `exported const '${prefix}${name}'${at(d)}`
       const annotation = d.type !== undefined ? callableAnnotation(d.type) : null
@@ -321,7 +321,7 @@ function checkDecl(
         // tags against — fail closed rather than silently narrow the check.
         w.violations.push(`${where}: its callable type literal is not gate-classifiable; extract a named type and document it there.`)
       } else if (annotation !== null) {
-        // An INLINE callable annotation is the surface signature itself: its
+        // An INLINE callable annotation is the exported signature itself: its
         // parameters and result need docs right here. (A NAMED reference
         // type carries its docs at the type's own declaration instead.)
         checkFunctionLike(where, raw, annotation.parameters, annotation.type, false, w)
@@ -350,7 +350,7 @@ function checkDecl(
     }
     // In an ambient (`declare`) namespace body, members are implicitly
     // exported — no `export` modifier required — so the recursion must treat
-    // every statement as surface.
+    // every statement as exported API.
     const declared = ambient
       || ((ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined)?.some(m => m.kind === ts.SyntaxKind.DeclareKeyword) ?? false)
     if (body !== undefined && ts.isModuleBlock(body)) checkScope(body.statements, nsPrefix, w, declared)
@@ -376,7 +376,7 @@ function checkDecl(
   }
   // Fail CLOSED: an exported statement kind this dispatch does not recognize
   // must never pass silently — the gate's whole promise is that unchecked
-  // surface cannot exist. New TypeScript export forms extend the gate here.
+  // unchecked API cannot exist. New TypeScript export forms extend the gate here.
   w.violations.push(`exported statement${at(stmt)} uses an export form verify-export-jsdoc does not handle; extend the gate.`)
 }
 
@@ -385,7 +385,7 @@ function checkDecl(
  * exported declaration, resolving `export { … }` lists (no module specifier)
  * to their local declarations.
  * @param statements - the scope's statements.
- * @param prefix - the namespace qualification for surface names ('' at top level).
+ * @param prefix - the namespace qualification for exported names ('' at top level).
  * @param w - the walk state violations append to.
  * @param ambient - whether this scope is ambient (`declare` namespace or a declaration file), where members export implicitly.
  */
@@ -445,8 +445,8 @@ function checkScope(
     }
     if (ts.isExportAssignment(stmt)) {
       if (stmt.isExportEquals) {
-        // `export =` has no ESM consumer surface in this repo and the walk
-        // cannot classify its operand's shape; refuse rather than fail open.
+        // `export =` has no ESM consumer API in this repo and the walk
+        // cannot classify its operand's type; refuse rather than fail open.
         w.violations.push(`export-equals assignment (${pointer(w.rel, w.sf, stmt)}) is not a gate-supported export form; use ESM named exports.`)
         continue
       }
@@ -599,11 +599,11 @@ export function collectExportJsdocViolations(scanRoot: string = root): string[]
   return violations
 }
 
-/** CLI entry: list every violation and exit 1, or confirm a clean surface. */
+/** CLI entry: list every violation and exit 1, or confirm a documented API. */
 function main(): void {
   const violations = collectExportJsdocViolations()
   if (violations.length === 0) {
-    console.log('verify-export-jsdoc: every exported name on the package surface is documented.')
+    console.log('verify-export-jsdoc: every exported name in each package API is documented.')
     return
   }
   console.error(`verify-export-jsdoc: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):`)

scripts/verify-md-links.ts

@@ -27,7 +27,6 @@ const PATTERNS = [
   'AGENTS.md',
   'packages/AGENTS.md',
   '.agents/skills/**/*.md',
-  'skills/**/*.md',
 ]
 
 /** A broken relative link: a missing target path or a missing anchor on it. */

scripts/verify-mermaid.ts

@@ -26,7 +26,6 @@ const PATTERNS = [
   'AGENTS.md',
   'packages/AGENTS.md',
   '.agents/skills/**/*.md',
-  'skills/**/*.md',
 ]
 
 interface Block {

scripts/verify-node-next-types.ts

@@ -151,7 +151,7 @@ try {
     cwd: root,
     stdio: 'pipe',
   })
-  console.log(`verify-node-next-types: ${packages.length} workspace package declaration surface(s) compile under NodeNext.`)
+  console.log(`verify-node-next-types: ${packages.length} workspace package declaration API(s) compile under NodeNext.`)
 } catch (error: unknown) {
   failed = true
   const output = error as { stdout?: Buffer; stderr?: Buffer }

scripts/verify-package-invariants.ts

@@ -1,4 +1,4 @@
-/** Verify package-owned invariant source and publication contracts. */
+/** Verify package-owned invariant source and publication rules. */
 
 import { resolve } from 'node:path'
 import {

scripts/verify-package-paths.ts

@@ -68,7 +68,7 @@ function isDriftedPackageReference(ref: string): boolean {
   // A missing reference is drift only when a path segment names a live package.
   // A leading segment that is itself an existing group directory is explained by
   // the group, not by a relocated leaf sharing its name (`client` is both the
-  // client-modules group and the scaffold leaf), so only later segments count.
+  // client-modules group and the sdk leaf), so only later segments count.
   const segments = ref.split('/').slice(1)
   const [group] = segments
   const scanned = group !== undefined && segments.length > 1 && existsSync(resolve(root, 'packages', group))

scripts/verify-package-readme-model-experience.ts

@@ -38,63 +38,70 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
 
 /**
  * Packages whose Model Experience is simple enough for one gated sentence plus
- * a KV-cache field. Every other package must carry canonical context-surface
+ * a KV-cache field. Every other package must carry canonical model-context
  * blocks. A package moves on or off this list with its context behavior.
  */
 const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
+  'packages/attachment/attachment': { kind: 'indirect', reason: 'The storage seam delegates model request rendering to provider adapters.' },
+  'packages/attachment/attachment-local': { kind: 'indirect', reason: 'The local backend delegates model request rendering to provider adapters.' },
   'packages/bash/bash': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
-  'packages/bash/bash-env': { kind: 'indirect', reason: 'The env service surfaces managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' },
+  'packages/bash/bash-env': { kind: 'indirect', reason: 'The env service exposes managed DSH_* facts through the shell tools (dsh-tool-bash/dsh-tool-pwsh); it registers no prompt or schema of its own.' },
   'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
   'packages/bash/pwsh-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-pwsh.' },
   'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/core/agent-tool-mode': { kind: 'indirect', reason: 'The row only selects between the two projections dsh-tools owns; it registers no prompt, schema, or result of its own.' },
   'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/client/ui-agent-preset': { kind: 'indirect', reason: 'Browser-side settings row; the preset it selects owns every model-facing effect.' },
   'packages/core/agent-default-model': { kind: 'indirect', reason: 'The service supplies a ModelSelection; request assembly and adapters own the model-visible request.' },
+  'packages/preset/agent-presets': { kind: 'indirect', reason: 'The mount installs a preset\'s own plugins, which own every model-facing registration it makes visible.' },
   'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
   'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
   'packages/e2b/e2b': { kind: 'none', reason: 'The shared remote-runtime owner registers no model context; provider adapters and consumers own rendered effects.' },
-  'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers no model surface.' },
-  'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers no model surface.' },
-  '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/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers no model surface.' },
-  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers nothing model-facing.' },
+  'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers nothing model-facing.' },
+  'packages/client/ui-slots': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-primitives': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/web-react': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/schema-form': { kind: 'none', reason: 'Browser-side form-rendering library; registers nothing model-facing.' },
+  'packages/client/connection': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/api/remotes': { kind: 'none', reason: 'The Remote BFF selects business methods and identity policy; selected services own any model-visible effect.' },
-  '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/runtime': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-layout': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-sidebar': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-conversation': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-tool': { kind: 'none', reason: 'Browser-side Tool presentation layer; renders logged calls without changing model context.' },
-  'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
+  'packages/client/ui-deliverables': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-task': { kind: 'none', reason: 'Browser-side read-only projection of ctx.tasks records; dsh-tool-tasks owns the model-facing behavior.' },
+  'packages/client/ui-workflow-run': { kind: 'none', reason: 'Browser-side UI plugin layer; renders durable workflow records without changing model context.' },
+  'packages/client/ui-slash': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
   'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the Host snapshots the selection at the next prompt-assembly boundary and owns the model-visible effect.' },
   'packages/client/ui-goal': { kind: 'indirect', reason: 'The strip verbs route goal.* mutations; the host GoalService owns the model-visible goal/change context message.' },
   'packages/client/ui-permission': { kind: 'indirect', reason: 'The picker submits the host /permission command; the knob events it appends own the model-visible effect through the sandbox/approval consumers.' },
   'packages/client/ui-plan': { kind: 'indirect', reason: 'The chip dispatches /plan off; dsh-plan-mode owns the model-visible policy, exit tool, and logged state.' },
   'packages/client/ui-question': { kind: 'indirect', reason: 'The package mounts dsh-tool-ask-user; that tool owns the model-visible schema and answer rendering.' },
-  'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-workspace': { 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/ui-settings': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-settings-general': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/ui-models': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
-  'packages/client/locale': { 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/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-workspace': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-theme': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-settings': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-settings-general': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/ui-models': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/locale': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
+  'packages/client/web': { kind: 'none', reason: 'Browser-side UI plugin layer; registers nothing model-facing.' },
   '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/e2b/fs-e2b': { kind: 'indirect', reason: 'The provider backend 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/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/directory-picker': { kind: 'none', reason: 'The GUI-host picking seam registers no model surface.' },
-  'packages/host/directory-picker-auto': { kind: 'none', reason: 'The GUI-host picking chooser only mounts a backend row; registers no model surface.' },
-  'packages/host/directory-picker-browse': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' },
-  'packages/host/directory-picker-native': { kind: 'none', reason: 'The GUI-host picking backend registers no model surface.' },
-  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers no model surface.' },
-  'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers no model surface.' },
-  'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model surface.' },
+  'packages/host/apiproxy': { kind: 'none', reason: 'The wire contract and fetch carriers move already-composed messages and register nothing model-facing.' },
+  'packages/host/directory-picker': { kind: 'none', reason: 'The GUI-host picking seam registers nothing model-facing.' },
+  'packages/host/directory-picker-auto': { kind: 'none', reason: 'The GUI-host picking chooser only mounts a backend row; it registers nothing model-facing.' },
+  'packages/host/directory-picker-browse': { kind: 'none', reason: 'The GUI-host picking backend registers nothing model-facing.' },
+  'packages/host/directory-picker-native': { kind: 'none', reason: 'The GUI-host picking backend registers nothing model-facing.' },
+  'packages/host/webserver': { kind: 'none', reason: 'The HTTP carrier bridges browser and API handler and registers nothing model-facing.' },
+  'packages/host/frontend-static': { kind: 'none', reason: 'The SPA dist server answers browser asset requests and registers nothing model-facing.' },
+  'packages/bundle/base': { kind: 'indirect', reason: 'The bundle is a patch-list carrier; each inserted row\'s package owns its model-facing behavior.' },
   'packages/bundle/headless': { kind: 'none', reason: 'The one-shot runner submits the task as an ordinary user message; prompts and tools belong to the composed base and headless bundles.' },
   '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.' },
@@ -104,29 +111,26 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/e2b/subprocess-e2b': { kind: 'indirect', reason: 'The remote spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/subprocess/subprocess-local': { kind: 'indirect', reason: 'The spawn backend delegates model rendering to consumer seams such as the bash executor family.' },
   'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
-  'packages/scaffold/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },
-  'packages/scaffold/helper': { kind: 'none', reason: 'The project domain edits files and registers no live agent or model surface.' },
-  'packages/scaffold/scripts': { kind: 'indirect', reason: 'The launcher delegates model context to the loaded project plugin tree.' },
-  'packages/scaffold/client': { kind: 'none', reason: 'Client-process library; the model surface lives in the spawned runtime\'s composed plugins.' },
-  'packages/scaffold/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own the model surface.' },
-  'packages/scaffold/telemetry': { kind: 'none', reason: 'The launcher-side reporter sends developer-cycle telemetry and registers no live agent or model surface.' },
-  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers no model surface.' },
-  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers no model surface.' },
-  'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers no model surface.' },
-  'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers no model surface.' },
-  'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model surface a value feeds.' },
-  'packages/settings/settings-local': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model surface.' },
-  'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model surface a value authorizes.' },
-  'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model surface.' },
-  'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers no model surface.' },
-  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers no model surface.' },
-  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers no model surface.' },
+  'packages/sandbox/sandbox-windows-acl': { kind: 'indirect', reason: 'The provider backend delegates model rendering to the bash/pwsh sandbox executors and their tools.' },
+  'packages/sdk/client': { kind: 'none', reason: 'Client-process library; model-facing behavior lives in the spawned runtime\'s composed plugins.' },
+  'packages/sdk/protocol': { kind: 'none', reason: 'Client-facing wire library; the runtime plugins behind the serving entry own model-facing behavior.' },
+  'packages/session/session-projection': { kind: 'none', reason: 'The projection registry serves client-facing read models of already-logged session state and registers nothing model-facing.' },
+  'packages/session/session-projection-cache': { kind: 'none', reason: 'The persisted cache accelerates host-side cold reads of projection state and registers nothing model-facing.' },
+  'packages/session-query/session-query': { kind: 'none', reason: 'The trusted query service exposes cloned records only to callers and registers nothing model-facing.' },
+  'packages/session-query/session-query-sqlite': { kind: 'none', reason: 'The search backend returns hits only to callers and registers nothing model-facing.' },
+  'packages/settings/settings': { kind: 'indirect', reason: 'The seam stores and resolves user settings; consumer plugins own any model-facing content fed by a value.' },
+  'packages/settings/settings-local': { kind: 'indirect', reason: 'The file provider stores and publishes namespace sections; consumers of ctx.settings own any model-facing behavior.' },
+  'packages/credentials/credentials': { kind: 'indirect', reason: 'The seam resolves credential references; the consuming adapter owns every model-facing use a value authorizes.' },
+  'packages/credentials/credentials-local': { kind: 'indirect', reason: 'The file/environment provider stores credential values; consumers of ctx.credentials own any model-facing behavior.' },
+  'packages/util/atomic-write': { kind: 'none', reason: 'Pure filesystem write primitive; registers nothing model-facing.' },
+  'packages/session/session-telemetry': { kind: 'none', reason: 'The seam observes the session stream and hands redacted copies outward; it registers nothing model-facing.' },
+  'packages/session/session-telemetry-otel': { kind: 'none', reason: 'The backend forwards seam records into the OTel SDK pipeline and registers nothing model-facing.' },
+  'packages/session/user-id': { kind: 'none', reason: 'The shared identifier appears only in telemetry metadata and a direct human command response; it registers nothing model-facing.' },
   'packages/skill/skill': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-badge': { kind: 'indirect', reason: 'The bundled provider delegates model rendering to dsh-tool-skill.' },
   'packages/skill/skill-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-skill.' },
   'packages/spill/spill': { kind: 'indirect', reason: 'The storage seam delegates model rendering to spill consumers.' },
   'packages/spill/spill-local': { kind: 'indirect', reason: 'The storage backend delegates model rendering to spill consumers.' },
-  'packages/subagent/subagent': { kind: 'indirect', reason: 'The provider registry delegates parent-model rendering to dsh-tool-subagent.' },
   'packages/support/acp-snapshot': { kind: 'none', reason: 'The test harness observes and normalizes transcripts without changing live requests.' },
   'packages/support/agent-loop-testkit': { kind: 'none', reason: 'The test helper mounts services but neither drives nor modifies model requests.' },
   'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
@@ -134,18 +138,19 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
   'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
   'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
   'packages/api/gateway': { kind: 'none', reason: 'Remote dispatch infrastructure; invoked business methods own any model-visible effect.' },
-  'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers no model surface.' },
+  'packages/typert/type-meta': { kind: 'none', reason: 'Compiler-independent Remote protocol declarations; registers nothing model-facing.' },
   'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
-  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
+  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and controller plugins own all model rendering over the task registry.' },
   'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
   'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
   'packages/boot/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
+  'packages/boot/cmdline': { kind: 'none', reason: 'Resolves the process command line before any session exists; configured rows own every model-visible consequence.' },
   'packages/examples/jsonrpc-demo': { kind: 'indirect', reason: 'Only the externally configured plugin tree contributes model context.' },
   'packages/interaction/permission': { kind: 'indirect', reason: 'The service writes mechanism events rendered by dsh-user-approval and dsh-tool-bash.' },
   'packages/interaction/user-interaction': { kind: 'indirect', reason: 'Model-facing consumers render provider answers and seam errors.' },
   'packages/util/timeout': { kind: 'indirect', reason: 'Only timeout consumers render timeout outcomes.' },
   'packages/util/retention': { kind: 'indirect', reason: 'Only retention consumers render retained content and omission metadata.' },
-  'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers no model surface.' },
+  'packages/util/native-command': { kind: 'none', reason: 'The host-side subprocess runner registers nothing model-facing.' },
   'packages/web/web': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-web.' },
   'packages/web/web-fetch-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
   'packages/web/web-search-exa': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-web.' },
@@ -159,7 +164,7 @@ interface Failure {
 
 type Line = MarkdownProseLine
 
-interface ContextSurface {
+interface ModelExperienceEntry {
   heading: Line
   modelView: Line
   tokenEffect: Line
@@ -191,7 +196,7 @@ function validateNestedVerbatim(raw: readonly string[], fragments: Set<string>):
     const fragment = headingFragment(title)
     if (fragment.length === 0) return { blocks, error: 'verbatim H5 title must be non-empty' }
     if (fragments.has(fragment)) {
-      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its context surface` }
+      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its model-context entry` }
     }
     fragments.add(fragment)
     cursor += 1
@@ -210,13 +215,13 @@ function validateNestedVerbatim(raw: readonly string[], fragments: Set<string>):
   return { blocks }
 }
 
-/** GitHub-style fragment for the simple ASCII nested titles allowed by this contract. */
+/** GitHub-style fragment for the simple ASCII nested titles allowed by these rules. */
 function headingFragment(title: string): string {
   return title.toLowerCase().replaceAll('`', '').replaceAll(/[^a-z0-9 _-]/g, '').trim().replaceAll(/\s+/g, '-')
 }
 
-/** A direct stable system-prompt contribution, as named by the README contract. */
-function isDirectSystemPromptSurface(title: string): boolean {
+/** A direct stable system-prompt contribution, as named by the README rules. */
+function isDirectSystemPromptEntry(title: string): boolean {
   return /\bsystem prompt\b/i.test(title)
 }
 
@@ -236,13 +241,13 @@ const failures: Failure[] = []
 const packageJsons = globSync('packages/*/*/package.json', { cwd: root }).map(path => path.split(sep).join('/')).sort()
 const scannedPackages = new Set(packageJsons.map(path => path.slice(0, -'/package.json'.length)))
 let structuredCount = 0
-let contextSurfaceCount = 0
+let modelContextEntryCount = 0
 let omittedSectionCount = 0
 let explainedNoneCount = 0
 let indirectCount = 0
 let verbatimBlockCount = 0
-let systemPromptSurfaceCount = 0
-let toolSchemaSurfaceCount = 0
+let systemPromptEntryCount = 0
+let toolSchemaEntryCount = 0
 let kvCacheEffectCount = 0
 
 for (const [pkg, reason] of Object.entries(NO_MODEL_EXPERIENCE_SECTION)) {
@@ -262,7 +267,7 @@ for (const [pkg, contract] of Object.entries(SENTENCE_MODEL_EXPERIENCE)) {
     failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry does not name a scanned package' })
   }
   if (contract.reason.trim().length === 0) {
-    failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry must justify why structured context surfaces are unnecessary' })
+    failures.push({ path: `${pkg}/README.md`, message: 'sentence allowlist entry must justify why structured model-context entries are unnecessary' })
   }
 }
 
@@ -371,47 +376,47 @@ for (const packageJson of packageJsons) {
     continue
   }
 
-  const surfaceStarts = content
+  const entryStarts = content
     .map((line, index) => ({ line, index }))
     .filter(entry => /^### \S/.test(entry.line.raw))
-  if (surfaceStarts.length === 0 || surfaceStarts[0]?.index !== 0) {
-    failures.push({ path: readme, message: 'must contain one or more complete context-surface blocks' })
+  if (entryStarts.length === 0 || entryStarts[0]?.index !== 0) {
+    failures.push({ path: readme, message: 'must contain one or more complete model-context entries' })
     continue
   }
 
-  const surfaces: ContextSurface[] = []
-  const surfaceFragments = new Set<string>()
-  let surfaceError = false
-  for (let surfaceIndex = 0; surfaceIndex < surfaceStarts.length; surfaceIndex += 1) {
-    const start = surfaceStarts[surfaceIndex] as { line: Line; index: number }
-    const end = surfaceStarts[surfaceIndex + 1]?.index ?? content.length
+  const modelContextEntries: ModelExperienceEntry[] = []
+  const entryFragments = new Set<string>()
+  let entryError = false
+  for (let entryIndex = 0; entryIndex < entryStarts.length; entryIndex += 1) {
+    const start = entryStarts[entryIndex] as { line: Line; index: number }
+    const end = entryStarts[entryIndex + 1]?.index ?? content.length
     const entries = content.slice(start.index, end)
     const heading = entries[0] as Line
     const title = heading.raw.slice('### '.length)
     const fragment = headingFragment(title)
     if (fragment.length === 0) {
-      failures.push({ path: readme, message: `line ${heading.index}: each context surface requires a non-empty H3 heading` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: each model-context entry requires a non-empty H3 heading` })
+      entryError = true
       break
     }
-    if (surfaceFragments.has(fragment)) {
-      failures.push({ path: readme, message: `line ${heading.index}: duplicate context-surface link fragment ${JSON.stringify(fragment)}` })
-      surfaceError = true
+    if (entryFragments.has(fragment)) {
+      failures.push({ path: readme, message: `line ${heading.index}: duplicate model-context entry link fragment ${JSON.stringify(fragment)}` })
+      entryError = true
       break
     }
     const fieldStarts = entries
       .map((line, index) => ({ line, index }))
       .filter(entry => /^#### \S/.test(entry.line.raw))
     if (fieldStarts.length !== FIELD_HEADINGS.length || fieldStarts[0]?.index !== 1) {
-      failures.push({ path: readme, message: `line ${heading.index}: context surface requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: model-context entry requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
+      entryError = true
       break
     }
-    if ((surfaceIndex === 0 && heading.index !== modelHeading.index + 2)
+    if ((entryIndex === 0 && heading.index !== modelHeading.index + 2)
       || rawLines[heading.index - 2]?.trim().length !== 0
       || fieldStarts[0].line.index !== heading.index + 2) {
-      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and first field require one blank line between them` })
-      surfaceError = true
+      failures.push({ path: readme, message: `line ${heading.index}: model-context entry heading and first field require one blank line between them` })
+      entryError = true
       break
     }
     const parsedFields: ParsedField[] = []
@@ -421,7 +426,7 @@ for (const packageJson of packageJsons) {
       const expectedHeading = FIELD_HEADINGS[fieldIndex] as string
       if (fieldStart.line.raw !== expectedHeading) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: expected exact field heading ${JSON.stringify(expectedHeading)}, found ${JSON.stringify(fieldStart.line.raw)}` })
-        surfaceError = true
+        entryError = true
         break
       }
       const fieldEnd = fieldStarts[fieldIndex + 1]?.index ?? entries.length
@@ -429,42 +434,42 @@ for (const packageJson of packageJsons) {
       const value = fieldEntries[1]
       if (value === undefined || /^#{1,6} /.test(value.raw) || value.raw.trim().length === 0) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} requires one non-empty paragraph` })
-        surfaceError = true
+        entryError = true
         break
       }
       if (value.index !== fieldStart.line.index + 2) {
         failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} and its paragraph require one blank line between them` })
-        surfaceError = true
+        entryError = true
         break
       }
       const unexpected = fieldEntries.slice(2).find(line => !/^##### \S/.test(line.raw))
       if (unexpected !== undefined) {
         failures.push({ path: readme, message: `line ${unexpected.index}: content after ${expectedHeading} paragraph must be a titled H5 plus \`markdown\` fence owned by that field` })
-        surfaceError = true
+        entryError = true
         break
       }
       const nextHeadingLine = fieldStarts[fieldIndex + 1]?.line.index
-        ?? surfaceStarts[surfaceIndex + 1]?.line.index
+        ?? entryStarts[entryIndex + 1]?.line.index
         ?? nextH2Line
       if (rawLines[nextHeadingLine - 2]?.trim().length !== 0) {
         failures.push({ path: readme, message: `line ${nextHeadingLine}: Model Experience headings require a preceding blank line` })
-        surfaceError = true
+        entryError = true
         break
       }
       const verbatim = validateNestedVerbatim(rawLines.slice(value.index, nextHeadingLine - 1), verbatimFragments)
       if (verbatim.error !== undefined) {
         failures.push({ path: readme, message: `line ${value.index}: ${verbatim.error}` })
-        surfaceError = true
+        entryError = true
         break
       }
       if (fieldEntries.length - 2 !== verbatim.blocks) {
         failures.push({ path: readme, message: `line ${value.index}: every nested H5 must own exactly one \`markdown\` fence` })
-        surfaceError = true
+        entryError = true
         break
       }
       parsedFields.push({ value, verbatimBlocks: verbatim.blocks })
     }
-    if (surfaceError) break
+    if (entryError) break
     const modelViewField = parsedFields[0] as ParsedField
     const tokenEffectField = parsedFields[1] as ParsedField
     const kvCacheEffectField = parsedFields[2] as ParsedField
@@ -473,11 +478,11 @@ for (const packageJson of packageJsons) {
     const kvCacheEffect = kvCacheEffectField.value
     if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw) || /\]\(#[^)]+\)/.test(kvCacheEffect.raw)) {
       failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H5 in its owning H4 field` })
-      surfaceError = true
+      entryError = true
       break
     }
-    surfaceFragments.add(fragment)
-    surfaces.push({
+    entryFragments.add(fragment)
+    modelContextEntries.push({
       heading,
       modelView,
       tokenEffect,
@@ -487,49 +492,49 @@ for (const packageJson of packageJsons) {
       verbatimBlocks: parsedFields.reduce((total, field) => total + field.verbatimBlocks, 0),
     })
   }
-  if (surfaceError) continue
+  if (entryError) continue
 
-  const promptWithoutVerbatim = surfaces.find(surface => isDirectSystemPromptSurface(surface.title)
-    && surface.modelViewVerbatimBlocks === 0)
+  const promptWithoutVerbatim = modelContextEntries.find(entry => isDirectSystemPromptEntry(entry.title)
+    && entry.modelViewVerbatimBlocks === 0)
   if (promptWithoutVerbatim !== undefined) {
-    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
+    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt entry must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
     continue
   }
-  const hasConcreteLiteral = surfaces.some(surface => surface.verbatimBlocks > 0
-    || surface.modelView.raw.includes('`')
-    || surface.tokenEffect.raw.includes('`')
-    || toolCatalogLinkFragments(surface.modelView.raw).length > 0)
+  const hasConcreteLiteral = modelContextEntries.some(entry => entry.verbatimBlocks > 0
+    || entry.modelView.raw.includes('`')
+    || entry.tokenEffect.raw.includes('`')
+    || toolCatalogLinkFragments(entry.modelView.raw).length > 0)
   if (!hasConcreteLiteral) {
-    failures.push({ path: readme, message: 'structured Model Experience must ground at least one surface with inline code, a nested `markdown` block, or an anchored tool-catalog link' })
+    failures.push({ path: readme, message: 'structured Model Experience must ground at least one entry with inline code, a nested `markdown` block, or an anchored tool-catalog link' })
     continue
   }
   let catalogError = false
-  for (const surface of surfaces) {
-    if (!/\bschemas?\b/i.test(surface.title)) continue
-    const fragments = toolCatalogLinkFragments(surface.modelView.raw)
+  for (const entry of modelContextEntries) {
+    if (!/\bschemas?\b/i.test(entry.title)) continue
+    const fragments = toolCatalogLinkFragments(entry.modelView.raw)
     if (fragments.length === 0) {
-      failures.push({ path: readme, message: `line ${surface.heading.index}: tool-schema surface must link an anchored section of ../../../docs/tool-catalog.md` })
+      failures.push({ path: readme, message: `line ${entry.heading.index}: tool-schema entry must link an anchored section of ../../../docs/tool-catalog.md` })
       catalogError = true
       break
     }
     const invalid = fragments.find(fragment => !toolCatalogFragments.has(fragment))
     if (invalid !== undefined) {
-      failures.push({ path: readme, message: `line ${surface.modelView.index}: tool-catalog link fragment ${JSON.stringify(invalid)} does not name an H2 section` })
+      failures.push({ path: readme, message: `line ${entry.modelView.index}: tool-catalog link fragment ${JSON.stringify(invalid)} does not name an H2 section` })
       catalogError = true
       break
     }
   }
   if (catalogError) continue
-  verbatimBlockCount += surfaces.reduce((total, surface) => total + surface.verbatimBlocks, 0)
-  contextSurfaceCount += surfaces.length
-  systemPromptSurfaceCount += surfaces.filter(surface => isDirectSystemPromptSurface(surface.title)).length
-  toolSchemaSurfaceCount += surfaces.filter(surface => /\bschemas?\b/i.test(surface.title)).length
-  kvCacheEffectCount += surfaces.length
+  verbatimBlockCount += modelContextEntries.reduce((total, entry) => total + entry.verbatimBlocks, 0)
+  modelContextEntryCount += modelContextEntries.length
+  systemPromptEntryCount += modelContextEntries.filter(entry => isDirectSystemPromptEntry(entry.title)).length
+  toolSchemaEntryCount += modelContextEntries.filter(entry => /\bschemas?\b/i.test(entry.title)).length
+  kvCacheEffectCount += modelContextEntries.length
   structuredCount += 1
 }
 
 if (failures.length === 0) {
-  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${kvCacheEffectCount} KV-cache fields, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
+  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${modelContextEntryCount} model-context entries, ${kvCacheEffectCount} KV-cache fields, ${systemPromptEntryCount} fenced system-prompt entries, ${toolSchemaEntryCount} catalog-linked tool-schema entries, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
   process.exit(0)
 }
 

scripts/verify-public-repository-links.spec.ts

@@ -1,60 +1,45 @@
 import { describe, expect, it } from 'vitest'
-import { findInternalRepositoryReferences } from './verify-public-repository-links.ts'
+import { findUnavailableRepositoryReferences } from './verify-public-repository-links.ts'
 
-describe('public repository link policy', () => {
-  it('rejects encoded and case-varied internal identities without blocking public repositories', () => {
-    const internalOwner = ['deepseek', 'harness'].join('-')
-    const internalRepository = [internalOwner, internalOwner].join('/')
-    const encodedRepository = internalRepository.replaceAll('-', '%2D').replace('/', '%2F')
-    const htmlEncodedRepository = internalRepository.replace('/', '/')
-    const jsonEscapedRepository = internalRepository.replace('/', '\\/')
-    const unicodeEscapedRepository = internalRepository.replace('/', String.raw`\u002f`)
+describe('repository link policy', () => {
+  it('rejects encoded and case-varied references to the unavailable repository', () => {
+    const unavailableOwner = ['deepseek', 'ai'].join('-')
+    const unavailableName = ['deepseek', 'harness', 'sdk'].join('-')
+    const unavailableRepository = `${unavailableOwner}/${unavailableName}`
+    const encodedRepository = unavailableRepository.replaceAll('-', '%2D').replace('/', '%2F')
+    const htmlEncodedRepository = unavailableRepository.replace('/', '/')
+    const jsonEscapedRepository = unavailableRepository.replace('/', '\\/')
+    const unicodeEscapedRepository = unavailableRepository.replace('/', String.raw`\u002f`)
     const source = [
-      'https://github.com/deepseek-ai/deepseek-harness-sdk',
-      `https://github.com/${internalOwner}/cordis`,
-      `https://github.com/${internalRepository.toUpperCase()}/issues/1`,
+      'https://github.com/deepseek-ai/deepseek-harness',
+      `https://github.com/${unavailableRepository.toUpperCase()}/issues/1`,
       `https://github.com/${encodedRepository}/issues/2`,
       `https://github.com/${htmlEncodedRepository}/issues/3`,
       `"https:\\/\\/github.com\\/${jsonEscapedRepository}\\/issues\\/4"`,
       `"https:\\/\\/github.com\\/${unicodeEscapedRepository}\\/issues\\/5"`,
-      `${internalOwner.toUpperCase()}#6`,
+      `https://github.com/${unavailableOwner}/cordis`,
+      `https://github.com/example/${unavailableName}`,
     ].join('\n')
 
-    expect(findInternalRepositoryReferences('subject.md', source)).toEqual([
+    expect(findUnavailableRepositoryReferences('subject.md', source)).toEqual([
+      { file: 'subject.md', line: 2 },
       { file: 'subject.md', line: 3 },
       { file: 'subject.md', line: 4 },
       { file: 'subject.md', line: 5 },
       { file: 'subject.md', line: 6 },
-      { file: 'subject.md', line: 7 },
-      { file: 'subject.md', line: 8 },
     ])
   })
 
-  it('allows only the exact audited trusted-publishing repository declarations', () => {
-    const internalOwner = ['deepseek', 'harness'].join('-')
-    const internalRepository = [internalOwner, internalOwner].join('/')
-    const repositoryUrl = `git+https://github.com/${internalRepository}.git`
-    const manifestLine = `  "url": "${repositoryUrl}",`
-    const constraintLine = `const repositoryUrl = '${repositoryUrl}'`
-    const allowedDeclarations = [
-      ['native/landlock-run/packages/entry/package.json', manifestLine],
-      ['native/landlock-run/packages/linux-arm64/package.json', manifestLine],
-      ['native/landlock-run/packages/linux-x64/package.json', manifestLine],
-      ['scripts/check-workspace-constraints.ts', constraintLine],
-    ] as const
+  it('preserves frozen archived Agent Notes', () => {
+    const unavailableRepository = ['deepseek-ai', 'deepseek-harness-sdk'].join('/')
 
-    for (const [file, source] of allowedDeclarations) {
-      expect(findInternalRepositoryReferences(file, source)).toEqual([])
-    }
-
-    const wrongFile = 'native/landlock-run/package.json'
-    expect(findInternalRepositoryReferences(wrongFile, manifestLine)).toEqual([{ file: wrongFile, line: 1 }])
-
-    const manifestFile = 'native/landlock-run/packages/entry/package.json'
-    const wrongField = `  "homepage": "${repositoryUrl}",`
-    expect(findInternalRepositoryReferences(manifestFile, wrongField)).toEqual([{ file: manifestFile, line: 1 }])
-
-    const encodedLine = manifestLine.replace('github.com/', 'github.com\\/')
-    expect(findInternalRepositoryReferences(manifestFile, encodedLine)).toEqual([{ file: manifestFile, line: 1 }])
+    expect(findUnavailableRepositoryReferences(
+      '.agents/notes/archived/process/historical-record.md',
+      `https://github.com/${unavailableRepository}`,
+    )).toEqual([])
+    expect(findUnavailableRepositoryReferences(
+      '.agents/notes/implemented/process/active-record.md',
+      `https://github.com/${unavailableRepository}`,
+    )).toEqual([{ file: '.agents/notes/implemented/process/active-record.md', line: 1 }])
   })
 })

scripts/verify-public-repository-links.ts

@@ -1,4 +1,4 @@
-/** Reject tracked files that expose the internal repository identity outside audited publishing declarations. */
+/** Reject tracked files that reference an unavailable legacy repository. */
 
 import { execFileSync } from 'node:child_process'
 import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs'
@@ -6,22 +6,13 @@ import { resolve } from 'node:path'
 import { pathToFileURL } from 'node:url'
 
 const root = resolve(import.meta.dirname, '..')
-const internalOwner = ['deepseek', 'harness'].join('-')
-const internalRepository = [internalOwner, internalOwner].join('/')
-const internalIssueShorthand = `${internalOwner}#`
-const trustedPublishingRepositoryUrl = `git+https://github.com/${internalRepository}.git`
-
-/** Exact declarations that intentionally expose the source repository for trusted publishing. */
-const allowedInternalRepositoryLineByFile: Readonly<Record<string, string>> = {
-  'native/landlock-run/packages/entry/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
-  'native/landlock-run/packages/linux-arm64/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
-  'native/landlock-run/packages/linux-x64/package.json': `"url": "${trustedPublishingRepositoryUrl}",`,
-  'scripts/check-workspace-constraints.ts': `const repositoryUrl = '${trustedPublishingRepositoryUrl}'`,
-}
+const unavailableOwner = ['deepseek', 'ai'].join('-')
+const unavailableRepositoryName = ['deepseek', 'harness', 'sdk'].join('-')
+const unavailableRepository = `${unavailableOwner}/${unavailableRepositoryName}`
+const archivedAgentNotePrefix = '.agents/notes/archived/'
 
 const namedReferenceCharacters: Readonly<Record<string, string>> = {
   hyphen: '-',
-  num: '#',
   sol: '/',
 }
 
@@ -40,8 +31,8 @@ function canonicalReferenceText(source: string): string {
     .toLowerCase()
 }
 
-/** One tracked reference to the internal repository. */
-export interface InternalRepositoryReference {
+/** One tracked reference to the unavailable repository. */
+export interface UnavailableRepositoryReference {
   /** Repository-relative file path. */
   file: string
   /** One-based source line. */
@@ -49,20 +40,18 @@ export interface InternalRepositoryReference {
 }
 
 /**
- * Locate unaudited internal-repository references in one text file.
+ * Locate unavailable-repository references in one active text file.
  * @param file - Repository-relative path used in diagnostics.
  * @param source - Text to inspect.
- * @returns every matching source line.
+ * @returns every matching source line, excluding frozen archived Agent Notes.
  */
-export function findInternalRepositoryReferences(file: string, source: string): InternalRepositoryReference[] {
-  const references: InternalRepositoryReference[] = []
+export function findUnavailableRepositoryReferences(file: string, source: string): UnavailableRepositoryReference[] {
+  if (file.startsWith(archivedAgentNotePrefix)) return []
+
+  const references: UnavailableRepositoryReference[] = []
   for (const [index, line] of source.split('\n').entries()) {
     const canonicalLine = canonicalReferenceText(line)
-    const isAllowedPublishingDeclaration = line.trim() === allowedInternalRepositoryLineByFile[file]
-    if (!isAllowedPublishingDeclaration
-      && (canonicalLine.includes(internalRepository) || canonicalLine.includes(internalIssueShorthand))) {
-      references.push({ file, line: index + 1 })
-    }
+    if (canonicalLine.includes(unavailableRepository)) references.push({ file, line: index + 1 })
   }
   return references
 }
@@ -73,8 +62,8 @@ function trackedFiles(repoRoot: string): string[] {
     .filter(file => file !== '')
 }
 
-function scanRepository(repoRoot: string): InternalRepositoryReference[] {
-  const references: InternalRepositoryReference[] = []
+function scanRepository(repoRoot: string): UnavailableRepositoryReference[] {
+  const references: UnavailableRepositoryReference[] = []
   for (const file of trackedFiles(repoRoot)) {
     const path = resolve(repoRoot, file)
     if (!existsSync(path)) continue
@@ -82,7 +71,7 @@ function scanRepository(repoRoot: string): InternalRepositoryReference[] {
     if (!stat.isFile() && !stat.isSymbolicLink()) continue
     const source = stat.isSymbolicLink() ? readlinkSync(path) : readFileSync(path, 'utf8')
     if (source.includes('\0')) continue
-    references.push(...findInternalRepositoryReferences(file, source))
+    references.push(...findUnavailableRepositoryReferences(file, source))
   }
   return references
 }
@@ -92,9 +81,9 @@ const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(re
 if (isMain) {
   const references = scanRepository(root)
   if (references.length === 0) {
-    console.log('verify-public-repository-links: tracked files expose no unexpected internal repository identity.')
+    console.log('verify-public-repository-links: tracked files reference no unavailable repository.')
   } else {
-    console.error('verify-public-repository-links: unexpected internal repository references found:')
+    console.error('verify-public-repository-links: unavailable repository references found:')
     for (const reference of references) console.error(`  ${reference.file}:${String(reference.line)}`)
     process.exitCode = 1
   }

scripts/verify-skill-invocation-metadata.spec.ts

@@ -0,0 +1,53 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectSkillInvocationMetadataViolations } from './verify-skill-invocation-metadata.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function fixtureRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-skill-invocation-metadata-'))
+  roots.push(root)
+  return root
+}
+
+function writeSkill(root: string, name: string, frontmatter: string, policy = ''): void {
+  const directory = join(root, '.agents/skills', name)
+  mkdirSync(join(directory, 'agents'), { recursive: true })
+  writeFileSync(join(directory, 'SKILL.md'), `---\nname: ${name}\ndescription: Test skill\n${frontmatter}---\n\nTest.\n`)
+  writeFileSync(
+    join(directory, 'agents/openai.yaml'),
+    `interface:\n  display_name: "Test"\n${policy}`,
+  )
+}
+
+describe('cross-product skill invocation metadata gate', () => {
+  it('accepts aligned default and manual-only policies', () => {
+    const root = fixtureRoot()
+    writeSkill(root, 'default-skill', '')
+    writeSkill(
+      root,
+      'manual-skill',
+      'disable-model-invocation: true\nuser-invocable: true\n',
+      'policy:\n  allow_implicit_invocation: false\n',
+    )
+
+    expect(collectSkillInvocationMetadataViolations(root)).toEqual([])
+  })
+
+  it('rejects either direction of a manual-only policy mismatch', () => {
+    const root = fixtureRoot()
+    writeSkill(root, 'claude-only', 'disable-model-invocation: true\n')
+    writeSkill(root, 'codex-only', '', 'policy:\n  allow_implicit_invocation: false\n')
+
+    expect(collectSkillInvocationMetadataViolations(root)).toEqual([
+      '.agents/skills/claude-only: Claude Code manual-only=true but Codex manual-only=false',
+      '.agents/skills/codex-only: Claude Code manual-only=false but Codex manual-only=true',
+    ])
+  })
+})

scripts/verify-skill-invocation-metadata.ts

@@ -0,0 +1,122 @@
+/**
+ * Keep Claude Code and Codex invocation metadata aligned for repository skills.
+ * @module scripts/verify-skill-invocation-metadata
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { load } from 'js-yaml'
+
+const ROOT = resolve(import.meta.dirname, '..')
+
+/** Return an object-shaped YAML value, or undefined for every other shape. */
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : undefined
+}
+
+/** Parse a skill's YAML frontmatter as an object. */
+function parseSkillFrontmatter(source: string): Record<string, unknown> {
+  const lines = source.split('\n')
+  if (lines[0] !== '---') throw new Error('SKILL.md must start with YAML frontmatter')
+  const end = lines.indexOf('---', 1)
+  if (end < 0) throw new Error('SKILL.md frontmatter is not closed')
+  const metadata = asRecord(load(lines.slice(1, end).join('\n')))
+  if (metadata === undefined) throw new Error('SKILL.md frontmatter must be a YAML object')
+  return metadata
+}
+
+/** Find repository skill directories that carry Codex product metadata. */
+function skillDirectories(root: string): string[] {
+  const skillsRoot = resolve(root, '.agents/skills')
+  if (!existsSync(skillsRoot)) return []
+  return readdirSync(skillsRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && existsSync(resolve(skillsRoot, entry.name, 'agents/openai.yaml')))
+    .map(entry => entry.name)
+    .sort()
+}
+
+/**
+ * Report cross-product invocation-policy mismatches for repository skills.
+ * @param root - Repository root containing `.agents/skills`.
+ * @returns diagnostics for malformed metadata or policies that expose a skill differently.
+ */
+export function collectSkillInvocationMetadataViolations(root: string): string[] {
+  const violations: string[] = []
+
+  for (const skill of skillDirectories(root)) {
+    const relativeRoot = `.agents/skills/${skill}`
+    const skillFile = resolve(root, relativeRoot, 'SKILL.md')
+    const openaiFile = resolve(root, relativeRoot, 'agents/openai.yaml')
+    if (!existsSync(skillFile)) {
+      violations.push(`${relativeRoot}: agents/openai.yaml has no sibling SKILL.md`)
+      continue
+    }
+
+    let frontmatter: Record<string, unknown>
+    let openai: Record<string, unknown>
+    try {
+      frontmatter = parseSkillFrontmatter(readFileSync(skillFile, 'utf8'))
+    }
+    catch (error) {
+      violations.push(`${relativeRoot}/SKILL.md: ${error instanceof Error ? error.message : String(error)}`)
+      continue
+    }
+    try {
+      const parsed = asRecord(load(readFileSync(openaiFile, 'utf8')))
+      if (parsed === undefined) throw new Error('agents/openai.yaml must be a YAML object')
+      openai = parsed
+    }
+    catch (error) {
+      violations.push(`${relativeRoot}/agents/openai.yaml: ${error instanceof Error ? error.message : String(error)}`)
+      continue
+    }
+
+    const disableModelInvocation = frontmatter['disable-model-invocation']
+    if (disableModelInvocation !== undefined && typeof disableModelInvocation !== 'boolean') {
+      violations.push(`${relativeRoot}/SKILL.md: disable-model-invocation must be a boolean`)
+      continue
+    }
+    const userInvocable = frontmatter['user-invocable']
+    if (userInvocable !== undefined && typeof userInvocable !== 'boolean') {
+      violations.push(`${relativeRoot}/SKILL.md: user-invocable must be a boolean`)
+      continue
+    }
+
+    const policy = asRecord(openai.policy)
+    const allowImplicitInvocation = policy?.allow_implicit_invocation
+    if (allowImplicitInvocation !== undefined && typeof allowImplicitInvocation !== 'boolean') {
+      violations.push(`${relativeRoot}/agents/openai.yaml: policy.allow_implicit_invocation must be a boolean`)
+      continue
+    }
+
+    const claudeManualOnly = disableModelInvocation === true
+    const codexManualOnly = allowImplicitInvocation === false
+    if (claudeManualOnly !== codexManualOnly) {
+      violations.push(
+        `${relativeRoot}: Claude Code manual-only=${String(claudeManualOnly)}`
+        + ` but Codex manual-only=${String(codexManualOnly)}`,
+      )
+    }
+    if (claudeManualOnly && userInvocable === false) {
+      violations.push(`${relativeRoot}/SKILL.md: a manual-only skill must remain user-invocable`)
+    }
+  }
+
+  return violations
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  const skills = skillDirectories(ROOT)
+  const violations = collectSkillInvocationMetadataViolations(ROOT)
+  if (violations.length > 0) {
+    process.stderr.write('verify-skill-invocation-metadata: violations found:\n')
+    for (const violation of violations) process.stderr.write(`  ${violation}\n`)
+    process.exit(1)
+  }
+
+  process.stdout.write(
+    `verify-skill-invocation-metadata: ${String(skills.length)} cross-product skill policy pair(s) aligned.\n`,
+  )
+}

scripts/verify-translation-pairing.ts

@@ -291,6 +291,6 @@ if (errors.length === 0) {
   process.exit(0)
 }
 
-console.error('verify-translation-pairing: bilingual pairing contract violated (see docs/i18n/README.md):')
+console.error('verify-translation-pairing: bilingual pairing rules violated (see docs/i18n/README.md):')
 for (const message of errors) console.error(`  ${message}`)
 process.exit(1)