Merge remote-tracking branch 'origin/master' into codex/cli-one-shot-demo

# Conflicts:
#	AGENTS.md
#	docs/architecture.md
#	docs/capability-seams.md
#	docs/cookbook/extension-cookbook.i18n.yaml
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	knip.json
#	packages/README.md
#	packages/support/loader-smoke/README.md
#	packages/support/loader-smoke/src/index.ts
#	vitest.snapshot.config.ts

vitest.snapshot.config.ts

@@ -1,9 +1,28 @@
+import { availableParallelism } from 'node:os'
 import tsconfigPaths from 'vite-tsconfig-paths'
 import { defineConfig } from 'vitest/config'
 
+const DEFAULT_SNAPSHOT_MAX_CONCURRENCY = 5
+
+function positiveIntFromEnv(name: string, fallback: number): number {
+  const raw = process.env[name]
+  if (raw === undefined || raw === '') return fallback
+
+  const value = Number(raw)
+  if (!Number.isInteger(value) || value < 1) {
+    throw new Error(`${name} must be a positive integer, got ${JSON.stringify(raw)}`)
+  }
+  return value
+}
+
+const snapshotMaxConcurrency = positiveIntFromEnv(
+  'DSH_SNAPSHOT_MAX_CONCURRENCY',
+  Math.min(DEFAULT_SNAPSHOT_MAX_CONCURRENCY, availableParallelism()),
+)
+
 // Replay is the keyless default: boot real example subprocesses from recorded model scripts and diff
-// normalized protocol/event output plus persisted-log goldens. ACP `record` calls the real API and
-// updates fixtures and goldens; `refresh` replays committed scripts and updates current goldens.
+// normalized protocol or transcript output plus persisted-log goldens. `record` calls the real API
+// and updates fixtures and goldens; `refresh` replays committed scripts and updates current goldens.
 // Replay/refresh never load `.env`; only record reads a key from the environment or root `.env`.
 if (process.env.DSH_SNAPSHOT === 'record') {
   try {
@@ -21,10 +40,12 @@ export default defineConfig({
   plugins: [tsconfigPaths({ projects: ['./tsconfig.json'] })],
   test: {
     include: ['examples/*/tests/**/*.snapshot.ts', 'packages/sdk/*/tests/**/*.snapshot.ts'],
-    // Each test boots a subprocess; give it room, and run files one at a time
-    // (a record run hits the live API, and replay subprocess boot is heavy).
+    // Each test boots a subprocess; give it room and keep the worker file singular. Replay tests
+    // opt into bounded in-file concurrency, while record/refresh stay serial because they write
+    // fixtures. The environment knob restores serial replay with value 1 on constrained machines.
     testTimeout: 120_000,
     hookTimeout: 30_000,
     fileParallelism: false,
+    maxConcurrency: snapshotMaxConcurrency,
   },
 })