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.

apps/cli/config/base.cordis.yml

@@ -360,7 +360,6 @@
   name: '@deepseek-ai/dsh-web-search-deepseek'
   config:
     apiKeyEnv: DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_SEARCH_BASE_URL
 
 - id: tool-web
   name: '@deepseek-ai/dsh-tool-web'

apps/cli/config/tui.cordis.yml

@@ -40,8 +40,6 @@
 # resolution materializes request defaults before the request header is logged.
 - id: llm-deepseek
   config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
     thinking: enabled
     reasoningEffort: max
 

apps/cli/config/web.cordis.yml

@@ -36,11 +36,6 @@
     # once the web UI owns the choice per session.
     mode: !!js process.env.DSH_TOOLS_MODE
 
-- id: llm-deepseek
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
-    baseURL: !!js process.env.DEEPSEEK_BASE_URL
-
 # ── web-only host rows, the transport layer, and the browser roster ─────────
 
 # `dshClient` rows are the browser roster the modules node half scans into

apps/cli/package.json

@@ -54,6 +54,7 @@
     "@deepseek-ai/dsh-compact-basic": "workspace:^",
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
     "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-frontend": "workspace:^",
     "@deepseek-ai/dsh-fs-local": "workspace:^",
     "@deepseek-ai/dsh-fs-policy": "workspace:^",
@@ -74,9 +75,9 @@
     "@deepseek-ai/dsh-paths": "workspace:^",
     "@deepseek-ai/dsh-permission": "workspace:^",
     "@deepseek-ai/dsh-plan-mode": "workspace:^",
-    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
     "@deepseek-ai/dsh-pty": "workspace:^",
     "@deepseek-ai/dsh-pty-local": "workspace:^",
+    "@deepseek-ai/dsh-repeat-tool-guard": "workspace:^",
     "@deepseek-ai/dsh-repository-plugin": "workspace:^",
     "@deepseek-ai/dsh-sandbox-local": "workspace:^",
     "@deepseek-ai/dsh-sandbox-policy": "workspace:^",

apps/cli/src/app-cli-entry.ts

@@ -14,6 +14,7 @@ import { createRequire } from 'node:module'
 import { networkInterfaces } from 'node:os'
 import { resolve } from 'node:path'
 import { Context } from 'cordis'
+import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
 import { boot, installFailLoud, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
@@ -102,6 +103,8 @@ const includeYamlSchema = yaml.JSON_SCHEMA.extend(jsExprType)
 
 /** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
 export interface AppCLIEntryOptions {
+  /** This run's frozen environment, provided to the tree before any config entry mounts. */
+  environment: EnvironmentSnapshot
   /** Absolute path of the shared base config the Loader includes. */
   configPath: string
   /**
@@ -255,6 +258,9 @@ export class AppCLIEntry {
         ...this.patches,
       ]
     this.ctx = await boot('dsh', resolve(this.bootConfigPath()), patches, async (ctx) => {
+      // Before any config-tree entry mounts, so a plugin that resolves a
+      // user-facing value at construction already sees this run's layers.
+      ctx.provide(DSH_ENVIRONMENT_KEY, this.options.environment)
       await this.options.prepare?.(ctx)
       if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
     })

apps/cli/src/bin.ts

@@ -24,24 +24,27 @@ function readVersion(): string {
   return typeof manifest.version === 'string' ? manifest.version : '0.0.0'
 }
 
-loadLayeredEnv('dsh')
+const environment = loadLayeredEnv('dsh')
 // The env opt-in is read at the process boundary; `1` is the documented value.
 const invocation = parseDshArgs(process.argv.slice(2), readVersion(), process.env.DSH_EXPERIMENTAL === '1')
 
 switch (invocation.mode) {
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
+    await runWeb(
+      environment, invocation.host, invocation.port, invocation.dev,
+      invocation.workspaceRoot, invocation.trustedHosts, invocation.config,
+    )
     break
   }
   case 'headless': {
     const { runHeadless } = await import('./headless.ts')
-    await runHeadless(invocation.prompt, invocation.config, invocation.configReplace)
+    await runHeadless(environment, invocation.prompt, invocation.config, invocation.configReplace)
     break
   }
   case 'tui': {
     const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
+    await runTui(environment, invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
     break
   }
   case 'dump-config': {
@@ -51,12 +54,12 @@ switch (invocation.mode) {
   }
   case 'meta': {
     const { runTui, SOURCE_ROOT } = await import('./tui.ts')
-    await runTui(invocation.config, undefined, SOURCE_ROOT, undefined, invocation.configReplace)
+    await runTui(environment, invocation.config, undefined, SOURCE_ROOT, undefined, invocation.configReplace)
     break
   }
   case 'upgrade': {
     const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, undefined, undefined, `dsh-${invocation.mode}`, invocation.configReplace)
+    await runTui(environment, invocation.config, undefined, undefined, `dsh-${invocation.mode}`, invocation.configReplace)
     break
   }
   default:

apps/cli/src/headless.ts

@@ -10,6 +10,7 @@
 
 import { fileURLToPath } from 'node:url'
 import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import type { EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
 import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
 import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
@@ -71,15 +72,19 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
  * Run one headless turn for `task` and exit (completed → 0, else 1). The task
  * is the non-empty prompt the argument adapter parsed from `-p`/`--prompt`
  * (the adapter rejects an empty task, so no guard is needed here).
+ * @param environment - this run's frozen environment snapshot.
  * @param task - the prompt text for the single turn.
  * @param config - a `--config` overlay applied over the shipped composition, or `undefined`.
  * @param configReplace - a `--config-replace` tree booted instead of the
  * shipped composition, or `undefined`. It must mount a webserver row: this
  * surface reaches its own agent over the same HTTP gateway the browser uses.
  */
-export async function runHeadless(task: string, config?: string, configReplace?: string): Promise<void> {
+export async function runHeadless(
+  environment: EnvironmentSnapshot, task: string, config?: string, configReplace?: string,
+): Promise<void> {
   // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
   const entry = new AppCLIEntry({
+    environment,
     configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
     overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },

apps/cli/src/tui.ts

@@ -29,6 +29,7 @@ import {
   resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import type { PatchOptions } from '@cordisjs/plugin-include'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
@@ -78,6 +79,8 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
    the CLI PTY smoke drives this path end to end, --config overlay included */
 /**
  * Run the interactive TUI from the invoking directory.
+ * @param environment - this run's frozen environment snapshot, provided to the
+ * tree before any config entry mounts.
  * @param config - an overlay patch list applied over the shared base and the
  * TUI overlay, or `undefined` for the shipped composition alone; already
  * parsed from `--config`.
@@ -97,6 +100,7 @@ export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
  * already parsed from `--config-replace`.
  */
 export async function runTui(
+  environment: EnvironmentSnapshot,
   config: string | undefined,
   resumeSessionId: string | undefined,
   workspace?: string,
@@ -225,6 +229,7 @@ export async function runTui(
       // Runs after the Loader installs and before any config-tree entry mounts,
       // so the fail-loud release hook can reach the tree for the whole window in
       // which an entry may reject.
+      hostCtx.provide(DSH_ENVIRONMENT_KEY, environment)
       app.current = hostCtx
       // The launcher owns session identity and the exit line: a config-mounted
       // app bundle reads both from these slots, so no cordis.yml key can drop

apps/cli/src/web.ts

@@ -12,6 +12,7 @@ import { addHarnessSourceSection, resolveConfigPath } from '@deepseek-ai/dsh-app
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tool-bash'
+import type { EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
 import { AppCLIEntry } from './app-cli-entry.ts'
 
 // The shared core every `dsh` surface mounts, plus this surface's overlay over it.
@@ -85,6 +86,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
 /**
  * Serve the browser UI from the shipped config tree. `host`/`port` are passed
  * through only when the flag was given; absent, the shipped Web overlay value stands.
+ * @param environment - this run's frozen environment snapshot.
  * @param host - the bind host, or `undefined` to keep the config default.
  * @param port - the listen port (`0` requests an OS-assigned port), or `undefined` to keep the config default.
  * @param dev - mount the client HMR receiver; `pnpm run dev:web` separately rebuilds watched plugin bundles.
@@ -95,6 +97,7 @@ export function prepareWebRuntimeContext(ctx: Context, sourceRoot: string, mode:
  * personal overlay; already parsed from `--config`.
  */
 export async function runWeb(
+  environment: EnvironmentSnapshot,
   host: string | undefined,
   port: number | undefined,
   dev: boolean,
@@ -104,6 +107,7 @@ export async function runWeb(
 ): Promise<void> {
   const mode: WebMode = dev ? 'development' : 'production'
   const entry = new AppCLIEntry({
+    environment,
     configPath: BASE_CONFIG,
     overlayPath: WEB_OVERLAY,
     ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },

apps/cli/tests/tui-keyless-smoke.e2e.ts

@@ -672,9 +672,9 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
     // layering underneath it. The named file patches the `tui` row — a row the
     // SURFACE OVERLAY inserted, not one the base declares — proving a later
     // patch list reaches a row an earlier one inserted. The `!!js` expression
-    // renders both halves of the layering in one line: `DSH_LAYER_WELCOME` is
+    // renders both halves of the layering in one line: `OVERLAY_LAYER_WELCOME` is
     // set by BOTH .env files and must render the project value, while
-    // `DSH_USER_ONLY` exists only in the harness home's .env and must still
+    // `OVERLAY_USER_ONLY` exists only in the harness home's .env and must still
     // arrive. Credentials are not part of this: they live in
     // `.credentials.yaml`, which is never hoisted into `process.env`.
     const output = await smoke({
@@ -683,17 +683,17 @@ describe('dsh CLI keyless smoke (apps/cli through the same PTY)', () => {
       binScript: dshBinScript,
       configArgs: ['--config', '.dsh/config.yaml'],
       prepare: seedWorkspace({
-        workspace: { '.env': 'DSH_LAYER_WELCOME=PROJECT WINS.\n' },
+        workspace: { '.env': 'OVERLAY_LAYER_WELCOME=PROJECT WINS.\n' },
         harnessHome: {
-          '.env': 'DSH_LAYER_WELCOME=USER LAYER LOST.\nDSH_USER_ONLY=USER LAYER LOADED.\n',
+          '.env': 'OVERLAY_LAYER_WELCOME=USER LAYER LOST.\nOVERLAY_USER_ONLY=USER LAYER LOADED.\n',
           'config.yaml': [
             '- id: workspace-context',
             '  disabled: true',
             '- id: tui',
             '  config:',
             "    sessionId: !!js configuredAgentIdentities?.main?.id ?? 'main'",
-            '    welcome: !!js "(process.env.DSH_LAYER_WELCOME ?? \'PROJECT LAYER MISSING.\')'
-            + ' + \' \' + (process.env.DSH_USER_ONLY ?? \'USER LAYER MISSING.\')"',
+            '    welcome: !!js "(process.env.OVERLAY_LAYER_WELCOME ?? \'PROJECT LAYER MISSING.\')'
+            + ' + \' \' + (process.env.OVERLAY_USER_ONLY ?? \'USER LAYER MISSING.\')"',
             '',
           ].join('\n'),
         },

apps/cli/tsconfig.json

@@ -29,6 +29,9 @@
     {
       "path": "../../packages/ui/tui"
     },
+    {
+      "path": "../../packages/util/environment"
+    },
     {
       "path": "../../packages/util/paths"
     },