feat(config)!: one ordering for configuration sources, and a bootstrap deny rule

$DSH_HOME/.env had just become an ordinary environment layer, which left the
harness resolving user-facing values from a flattened process.env that could
no longer say where a value came from. A key stored through the web page
stayed shadowed by an older key in the user's own .env. An endpoint could be
redirected by the project: the invoking directory's .env is materialized like
every other layer, and a base URL decides where a resolved API key is sent, so
a DEEPSEEK_BASE_URL written into a model-editable workspace would send the
user's credential — and the prompts carrying their code — to whatever host
that file named.

Give every user-facing value one ordering, with four kinds of source:

  explicit for this run     per-operation override, CLI argument
  > authored by deployment  --config / --config-replace
  > this launch's shell     inherited process environment
  > product-managed store   settings.yaml, .credentials.yaml
  > discovered file         $DSH_HOME/.env
  > defaults                schema default, shipped base, public default

The domains differ only in which tiers exist. The earlier split — credentials
ranking the environment over the managed file while settings ranked over the
environment — was inconsistent: the distinguishing fact is who authored the
source, not the domain.

packages/util/environment owns an immutable snapshot with per-layer
provenance. getFrom(name, sources) searches only the layers a caller names,
and omitting one is a refusal rather than a demotion: the adapters ask for
['process', 'user-env'], so no reordering can let a project file back into a
decision it was excluded from.

isBootstrapOnly rejects, before anything is materialized, any .env setting a
variable that governs how a process launches (PATH, SHELL, NODE_OPTIONS,
LD_PRELOAD), where code or model-visible instructions load from (the whole
DSH_* namespace, HOME, XDG_*), or how the network is reached (proxy and CA
variables). The namespace is denied wholesale so a switch added later cannot
become settable by being forgotten, and there is no opt-out.

verify-config-source-ownership keeps both rules: no unregistered process.env
read under packages/*/*/src (26 allowlisted with reasons), and no apiKey,
baseURL, or headers inlined from the environment in shipped Cordis config —
removing those inlines is what makes the deployment tier meaningful.

scripts/run-gates.ts

@@ -569,6 +569,7 @@ function docSyncLeafGates(options: {
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
     pnpmScript('package-paths', 'verify-package-paths', { label: 'package paths' }),
+    pnpmScript('config-source-ownership', 'verify-config-source-ownership', { label: 'config source ownership' }),
     pnpmScript('package-readme-model-experience', 'verify-package-readme-model-experience', { label: 'package README model experience' }),
     pnpmScript('mermaid', 'verify-mermaid'),
     pnpmScript('agent-note-classification', 'verify-agent-note-classification', { label: 'agent note classification' }),

scripts/verify-config-source-ownership.ts

@@ -0,0 +1,117 @@
+/**
+ * Gate: every user-facing value has one owner, and no shipped file smuggles a
+ * second one in.
+ *
+ * Two rules, both about the same failure — a value reaching the harness
+ * through a path nobody ranked:
+ *
+ * 1. Production package source does not read `process.env` directly. A
+ *    credential belongs to `ctx.credentials`, a user-configurable value to the
+ *    environment snapshot plus its owner's resolve step, and a real
+ *    process-launch fact to the app bootstrap. Each remaining read is listed
+ *    below with the reason it is one of those.
+ * 2. Shipped Cordis configuration does not inline a credential or an endpoint
+ *    from the environment. Doing so re-creates the layer the snapshot exists
+ *    to rank: `apiKey: !!js process.env.X` and `baseURL: !!js process.env.X`
+ *    bypass both the credential seam and the endpoint ladder, and a project
+ *    file could then decide where a key is sent.
+ * @module scripts/verify-config-source-ownership
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
+const ROOT = resolve(import.meta.dirname, '..')
+
+/**
+ * Production package sources allowed to read `process.env`, each with the
+ * reason it is a process fact rather than a user-configurable value. Adding a
+ * row is a deliberate act: state which of the three owners it belongs to and
+ * why it cannot go there.
+ */
+const ENV_READ_ALLOWLIST: Readonly<Record<string, string>> = {
+  // The environment plane itself.
+  'packages/util/environment/src/index.ts': 'defines the snapshot; the inherited environment is its input',
+  'packages/ui/app-boot/src/index.ts': 'the app bootstrap that builds the snapshot and reads $DSH_SNAPSHOT',
+  'packages/util/paths/src/index.ts': 'resolves $DSH_HOME before any snapshot exists',
+
+  // Process-launch facts owned by the boundary that spawns or is spawned.
+  'packages/subprocess/subprocess/src/index.ts': 'scrubs the parent environment for children',
+  'packages/workflow/workflow-workerthread/src/host.ts': 'passes the parent environment to a worker thread',
+  'packages/ui/tui/src/index.ts': 'reads $COLORTERM, a terminal capability of this process',
+  'packages/lsp/lsp-local/src/index.ts': 'passes the parent environment to a language server it spawns',
+  'packages/cordis/repository-plugin/src/index.ts': 'resolves an MCP manifest against the spawning environment',
+
+  // Bootstrap-only DSH_* switches, which no discovered file may set.
+  'packages/skill/skill-local/src/index.ts': 'reads $DSH_AGENTS_HOME and $DSH_BUNDLED_SKILL_DIR, both bootstrap-only',
+  'packages/web/web/src/index.ts': 'reads $DSH_WEB_SEARCH_PROVIDER and $DSH_WEB_FETCH_PROVIDER, both bootstrap-only',
+  'packages/host/directory-picker-auto/src/index.ts': 'reads launch facts (display, SSH) of this process',
+  'packages/host/directory-picker-auto/src/resolve.ts': 'reads launch facts (display, SSH) of this process',
+
+  // Telemetry identity and consent, resolved once per process at bootstrap.
+  'packages/telemetry/session-telemetry-otel/src/user-id.ts': 'derives a machine identity from process facts',
+  'packages/sdk/telemetry/src/consent-resolver.ts': 'reads the SDK bootstrap consent switch',
+  'packages/sdk/telemetry/src/anonymous-id.ts': 'derives a machine identity from process facts',
+
+  // SDK and example bins: their own app bootstrap, outside the product CLI.
+  'packages/sdk/sdk-client/src/client.ts': 'SDK host bootstrap',
+  'packages/sdk/helper/src/features/builtin/provider.ts': 'SDK scaffolding reads the developer environment',
+  'packages/sdk/helper/src/features/builtin/app.ts': 'SDK scaffolding reads the developer environment',
+  'packages/sdk/helper/src/package-managers/package-manager.ts': 'detects the invoking package manager',
+  'packages/sdk/create-sdk/src/create-wizard.ts': 'SDK scaffolding reads the developer environment',
+  'packages/examples/jsonrpc-demo/src/bin.ts': 'demo bin bootstrap',
+  'packages/examples/acp-demo/src/bin.ts': 'demo bin bootstrap',
+
+  // Test and replay infrastructure.
+  'packages/support/loader-smoke/src/index.ts': 'test launcher composing a child environment',
+  'packages/support/llm-replay/src/index.ts': 'replay fixture switch',
+  'packages/support/acp-snapshot/src/launcher.ts': 'snapshot launcher composing a child environment',
+
+  // Browser bundle: `process.env` is replaced at build time, never read at runtime.
+  'packages/client/runtime/src/client/contract/store.ts': 'build-time constant folded by the bundler',
+}
+
+/** Shipped Cordis configuration these rules apply to. */
+const SHIPPED_CONFIG_GLOBS = ['apps/*/config/*.yml', 'examples/*/*.cordis.yml', 'examples/*/cordis.yml']
+
+/** Config keys that must never be inlined from the environment. */
+const INLINE_DENY = /^\s*(apiKey|baseURL|apiKeyEnv|authToken|headers)\s*:\s*!!js\b/
+
+const failures: string[] = []
+
+for (const file of globSync('packages/*/*/src/**/*.ts', { cwd: ROOT })) {
+  const rel = file.split(sep).join('/')
+  if (!readFileSync(resolve(ROOT, rel), 'utf8').includes('process.env')) continue
+  if (rel in ENV_READ_ALLOWLIST) continue
+  failures.push(
+    `${rel}: reads process.env directly. A credential belongs to ctx.credentials, a user-configurable`
+    + ' value to environmentOf(ctx) plus its owner\'s resolve step, and a process-launch fact to the app'
+    + ' bootstrap. If it is genuinely one of those, add it to ENV_READ_ALLOWLIST with the reason.',
+  )
+}
+
+for (const glob of SHIPPED_CONFIG_GLOBS) {
+  for (const file of globSync(glob, { cwd: ROOT })) {
+    const rel = file.split(sep).join('/')
+    readFileSync(resolve(ROOT, rel), 'utf8').split('\n').forEach((line, index) => {
+      if (!INLINE_DENY.test(line)) return
+      failures.push(
+        `${rel}:${String(index + 1)}: inlines a credential or endpoint from the environment.`
+        + ' The adapter resolves apiKeyEnv through ctx.credentials and the endpoint through the'
+        + ' environment snapshot; inlining here bypasses both ladders.',
+      )
+    })
+  }
+}
+
+if (failures.length > 0) {
+  process.stderr.write('verify-config-source-ownership: configuration source ownership violated:\n')
+  for (const failure of failures) process.stderr.write(`  ${failure}\n`)
+  process.exit(1)
+}
+
+const allowed = Object.keys(ENV_READ_ALLOWLIST).length
+process.stdout.write(
+  `verify-config-source-ownership: no unregistered process.env reads (${String(allowed)} allowlisted)`
+  + ' and no credential or endpoint inlined in shipped configuration.\n',
+)

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

@@ -33,6 +33,7 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
   'packages/core/scope': 'The package is a model-agnostic registration and lifecycle primitive; model-facing consumers own any context selection.',
   'packages/util/brand': 'The package is a type-only primitive erased at compile time.',
   'packages/util/paths': 'The package only resolves harness-owned host paths; model-facing consumers own any rendered use.',
+  'packages/util/environment': 'The package only resolves host environment values; model-facing consumers own any rendered use.',
 }
 
 /**