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