Merge remote-tracking branch 'origin/master' into mergebot/pr711

# Conflicts:
#	apps/cli/README.i18n.yaml
#	apps/cli/README.md
#	apps/cli/README.zh.md
#	apps/cli/cordis.yml
#	apps/cli/package.json
#	docs/config-catalog.md
#	packages/client/runtime/README.i18n.yaml
#	packages/client/runtime/src/client/contract/sessions.ts
#	packages/client/test-runtime/src/sessions.ts
#	packages/client/ui-workspace/README.i18n.yaml
#	packages/client/ui-workspace/README.md
#	packages/client/ui-workspace/README.zh.md
#	packages/client/ui-workspace/src/client/WorkspaceBrowser.tsx
#	packages/client/ui-workspace/src/client/tree.ts
#	packages/client/ui-workspace/tests/apply.spec.ts
#	packages/client/ui-workspace/tests/tree.spec.ts
#	packages/host/apiproxy/README.i18n.yaml
#	packages/host/apiproxy/src/api-proxy.ts
#	packages/host/apiproxy/src/api/index.ts
#	packages/host/apiproxy/tests/client-handler.spec.ts
#	packages/host/apiproxy/tests/rpc-schemas.spec.ts
#	pnpm-lock.yaml

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

@@ -1,24 +1,22 @@
 /**
  * AppCLIEntry — the pre-cordis boot glue the config-tree dsh surfaces share
- * (`dsh web` and `dsh -p` boot the one composition; TUI migrates later).
- * Everything here is what must exist before the Loader runs: layered env,
- * the patch composition over the shipped cordis.yml (profile json + CLI
- * flags + the resolved frontend dist), and the fail-loud triple after the
- * tree settles.
+ * for the Web/headless surface.
+ * Everything here is what must exist before the Loader runs: the patch
+ * composition over the shipped base and surface overlay (profile json + CLI
+ * flags + the resolved frontend dist), and the fail-loud triple after the tree
+ * settles. The environment is what the bin already loaded (ambient plus the
+ * invoking directory's `.env`); `$DSH_HOME/.env` belongs to the credential
+ * provider and is never hoisted here.
  */
 
 import { readFileSync } from 'node:fs'
 import { createRequire } from 'node:module'
 import { networkInterfaces } from 'node:os'
 import { join, resolve } from 'node:path'
-import { pathToFileURL } from 'node:url'
 import { Context } from 'cordis'
-import type { FiberState } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import Include, { type PatchOptions } from '@cordisjs/plugin-include'
+import type { PatchOptions } from '@cordisjs/plugin-include'
 import yaml from 'js-yaml'
-import { assertEntriesLoaded, installFailLoud, loadEnv } from '@deepseek-ai/dsh-app-boot'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { boot, installFailLoud, loadOverlayPatches, loadPersonalPatches } from '@deepseek-ai/dsh-app-boot'
 // Empty type import carries the httpServer Context merge for the port read below.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 
@@ -90,18 +88,23 @@ const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
 })
 const includeYamlSchema = yaml.JSON_SCHEMA.extend(jsExprType)
 
-/**
- * Value mirror of cordis's `FiberState` const enum members the sweep needs
- * (a const enum has no runtime object to import; same rationale as the
- * client-side mirror in dsh-client-web).
- */
-const FIBER_ACTIVE = 2 as FiberState.ACTIVE
-const FIBER_PENDING = 0 as FiberState.PENDING
-
 /** Constructor facts for one dsh invocation over the shared composition (argv already parsed by the surface bin). */
 export interface AppCLIEntryOptions {
-  /** Absolute path of the shipped cordis.yml. */
+  /** Absolute path of the shared base config the Loader includes. */
   configPath: string
+  /**
+   * Absolute path of this surface's overlay: a patch list applied over
+   * {@link configPath} before this entry's own profile/flag patches. Its rows
+   * are also merge inputs, so a flag override preserves the overlay's other
+   * fields on the same row.
+   */
+  overlayPath: string
+  /**
+   * Optional explicit overlay applied after {@link overlayPath} and before
+   * this entry's own profile/flag patches. When absent, the personal
+   * `$DSH_HOME/config.yaml` overlay is applied instead.
+   */
+  extraOverlayPath?: string
   /** Whether to append the HMR row (the whole prod/dev difference; web surface only). */
   dev: boolean
   /** --host when explicitly passed; undefined keeps the yml engineering default. */
@@ -142,12 +145,11 @@ export class AppCLIEntry {
   constructor(private readonly options: AppCLIEntryOptions) {}
 
   /**
-   * Run the boot chain: layered env → patch composition → Loader include
-   * boot (dev row before await) → fail-loud triple.
+   * Run the boot chain: patch composition → Loader include boot (dev row
+   * before await) → fail-loud triple.
    * @returns the settled root context and the listening port.
    */
   async run(): Promise<{ ctx: Context; port: number }> {
-    this.loadEnvLayers()
     this.composePatches()
     await this.bootTree()
     this.assertBoot()
@@ -157,16 +159,9 @@ export class AppCLIEntry {
     return { ctx: this.ctx, port }
   }
 
-  /** Layered .env: ambient > cwd (bin already loaded) > $DSH_HOME (loadEnvFile never overrides). */
-  private loadEnvLayers(): void {
-    loadEnv('dsh', resolveDshHome())
-  }
-
   /**
-   * Compose the patch set from the non-yml config sources: computed
-   * engineering defaults (the global session root), profile json (user
-   * config, overriding those defaults), CLI flags, and the resolved frontend
-   * dist. Patches replace a row's config wholesale, so each patched row's yml
+   * Compose the patch set from profile json, CLI flags, and the resolved
+   * frontend dist. Patches replace a row's config wholesale, so each patched row's yml
    * static values are re-read here (bypass parse) and merged under the overrides.
    */
   private composePatches(): void {
@@ -178,12 +173,6 @@ export class AppCLIEntry {
       overrides.set(entryId, bag)
     }
 
-    // Source 0: computed engineering defaults. The session store defaults to
-    // a global dir under the Harness home ($DSH_HOME, else ~/.dsh) so history
-    // is shared across every cwd, not a project-local ./.sessions. The profile
-    // (Source 1) overwrites this same field via last-write-wins in put().
-    put('session-persistence-jsonl', 'root', join(resolveDshHome(), 'sessions'))
-
     // Source 1: profile json (missing file = empty; unmapped key = loud).
     for (const [key, value] of Object.entries(this.readProfile())) {
       const mapping = PROFILE_MAPPINGS.find(m => m.jsonPath === key)
@@ -216,60 +205,60 @@ export class AppCLIEntry {
     })
   }
 
-  /** Loader include boot; the dev HMR row mounts before await so the fail-loud triple covers it. */
+  /** Shared Loader boot; the dev HMR row mounts before await so the fail-loud sweep covers it. */
   private async bootTree(): Promise<void> {
-    const ctx = new Context()
-    ctx.baseUrl = pathToFileURL(join(resolve(this.options.configPath), '..')).href + '/'
-    await ctx.plugin(Loader)
-    ctx.loader.builtins.include = Include
-    await ctx.loader.create({
-      name: 'cordis:include',
-      config: {
-        path: pathToFileURL(resolve(this.options.configPath)).href,
-        ...this.patches.length > 0 ? { patches: this.patches } : {},
-      },
+    // One include of the shared base with every overlay as a sibling patch
+    // list: patches never cross an include boundary, so nesting them would
+    // silently stop reaching base rows. The surface overlay applies first, then
+    // this entry's profile-json and CLI-flag patches, which therefore win.
+    const patches = [
+      ...loadOverlayPatches('dsh', this.options.overlayPath),
+      ...this.options.extraOverlayPath === undefined
+        ? loadPersonalPatches('dsh') ?? []
+        : loadOverlayPatches('dsh', this.options.extraOverlayPath),
+      ...this.patches,
+    ]
+    this.ctx = await boot('dsh', resolve(this.options.configPath), patches, async (ctx) => {
+      if (this.options.dev) await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
     })
-    if (this.options.dev) {
-      await ctx.loader.create({ name: '@deepseek-ai/dsh-client-hmr' })
-    }
-    this.ctx = ctx
-    await ctx.loader.await()
+  }
+
+  /** Install the diagnostic for plugin rejections that happen after settled boot. */
+  private assertBoot(): void {
+    installFailLoud('dsh')
   }
 
   /**
-   * Fail-loud triple: assertEntriesLoaded catches import failures,
-   * installFailLoud catches late apply rejections, and the all-ACTIVE sweep
-   * below catches PENDING fibers (cordis inject waiting has no timeout).
+   * Bypass parse of the base and this surface's overlay (id → row) for
+   * patch-merge inputs; the Loader still reads both files itself. The overlay
+   * wins per row, matching the order its patches are applied in, and its
+   * `insert` rows are indexed too because a flag may target one of them.
    */
-  private assertBoot(): void {
-    installFailLoud('dsh')
-    assertEntriesLoaded(this.ctx, 'dsh')
-    const failures: string[] = []
-    for (const entry of this.ctx.loader.entries()) {
-      if (entry.fiber === undefined || entry.disabled) continue
-      const state = entry.fiber.state
-      if (state === FIBER_ACTIVE) continue
-      if (state === FIBER_PENDING) {
-        const missing = Object.keys(entry.fiber.inject).filter(service => this.ctx.get(service) === undefined)
-        failures.push(`${entry.options.name}: pending (waiting for service${missing.length === 1 ? '' : 's'}: ${missing.join(', ') || 'unknown'})`)
-      } else {
-        failures.push(`${entry.options.name}: fiber state ${String(state)}`)
+  private parseYmlRows(): Map<string, { config?: unknown }> {
+    const rows = new Map<string, { config?: unknown }>()
+    const files = [this.options.configPath, this.options.overlayPath]
+    if (this.options.extraOverlayPath !== undefined) files.push(this.options.extraOverlayPath)
+    for (const file of files) {
+      for (const row of this.parseRowList(file)) {
+        if (typeof row.id === 'string') rows.set(row.id, row)
+        for (const inserted of row.insert ?? []) {
+          if (typeof inserted.id === 'string') rows.set(inserted.id, inserted)
+        }
       }
     }
-    if (failures.length > 0) {
-      throw new Error(`dsh: ${String(failures.length)} entr${failures.length === 1 ? 'y' : 'ies'} did not activate\n${failures.join('\n')}`)
-    }
+    return rows
   }
 
-  /** Bypass parse of the shipped yml (id → row) for patch-merge inputs; Loader still reads the file itself. */
-  private parseYmlRows(): Map<string, { config?: unknown }> {
-    const doc = yaml.load(readFileSync(this.options.configPath, 'utf8'), { schema: includeYamlSchema })
-    if (!Array.isArray(doc)) throw new Error(`dsh: ${this.options.configPath} is not a top-level entry list`)
-    const rows = new Map<string, { config?: unknown }>()
-    for (const row of doc as { id?: string; config?: unknown }[]) {
-      if (typeof row.id === 'string') rows.set(row.id, row)
-    }
-    return rows
+  /**
+   * Parse one entry or patch list, rejecting anything that is not a top-level
+   * array so a malformed file fails here rather than at row lookup.
+   * @param file - absolute path of the config or overlay file.
+   * @returns the parsed top-level entries.
+   */
+  private parseRowList(file: string): { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[] {
+    const doc = yaml.load(readFileSync(file, 'utf8'), { schema: includeYamlSchema })
+    if (!Array.isArray(doc)) throw new Error(`dsh: ${file} is not a top-level entry list`)
+    return doc as { id?: string; config?: unknown; insert?: { id?: string; config?: unknown }[] }[]
   }
 
   /** Profile json under cwd; read-only — never created here, absent = no user config. */

apps/cli/src/args.ts

@@ -2,19 +2,24 @@
  * Commander adapter for the `dsh` command-line entry: the one place argv is
  * parsed and routed to a mode. `bin.ts` switches on the returned discriminant
  * and dynamic-imports that mode's module. One program: the default (no
- * subcommand) is the TUI/headless surface with option-only flags; `web` is a
- * real subcommand. Commander owns `--help`/`--version` and parse errors — it
- * prints and exits at the point of failure (a domain failure routes through
+ * subcommand) is the TUI/headless surface with option-only flags; `meta` and
+ * `web` are real subcommands. Commander owns `--help`/`--version` and parse
+ * errors — it prints and exits at the point of failure (a domain failure routes through
  * `command.error`), so this returns only a resolved mode.
  * @module @deepseek-ai/dsh/args
  */
 
 import { Command, CommanderError } from 'commander'
 
-/** Interactive TUI: the default mode. `--config` swaps the tree; `--resume <id>` rehydrates a session. */
+/**
+ * Interactive TUI: the default mode. `--config` applies an overlay over the
+ * shipped composition in place of the personal one, `--config-replace` boots a
+ * file as the whole tree instead, and `--resume <id>` rehydrates a session.
+ */
 interface TuiInvocation {
   mode: 'tui'
   config?: string
+  configReplace?: string
   resume?: string
 }
 
@@ -24,18 +29,35 @@ interface HeadlessInvocation {
   prompt: string
 }
 
+/** Interactive fresh TUI over this harness checkout; accepts no default-surface options. */
+interface MetaInvocation {
+  mode: 'meta'
+}
+
+/**
+ * Guided fresh-session entry: `dsh upgrade` seeds the first turn with the
+ * `dsh-upgrade` skill. It always mints a
+ * fresh session in the invoking directory and takes no options — `--resume`,
+ * `--config`, and `-p` are rejected as mistyped, so there is nothing to carry.
+ */
+interface SkillSessionInvocation {
+  mode: 'upgrade'
+}
+
 /**
  * Browser UI: `dsh web`. `host`/`port` are present only when the flag was
  * passed — pass-through overrides with no CLI default and no CLI validation:
  * the `dsh-host-webserver` schema (`host` a loopback/all-interfaces literal,
  * `port` a natural ≤ 65535) is the single source of both the default (the
- * shipped `cordis.yml` value stands when a flag is absent) and validity (a bad
+ * shipped Web overlay value stands when a flag is absent) and validity (a bad
  * value fails loud at boot). `port` is `Number`-coerced only because the schema
  * wants a number, not a string. `dev` mounts the client HMR driver;
  * `workspaceRoot` is the parent directory for name-created workspaces.
  */
 interface WebInvocation {
   mode: 'web'
+  /** Overlay of loader patches applied over the shipped web composition. */
+  config?: string
   host?: string
   port?: number
   dev: boolean
@@ -45,10 +67,16 @@ interface WebInvocation {
 }
 
 /** The resolved `dsh` invocation: exactly one mode. `--help`/`--version`/errors exit inside {@link parseDshArgs}. */
-export type DshInvocation = TuiInvocation | HeadlessInvocation | WebInvocation
+export type DshInvocation =
+  | TuiInvocation
+  | HeadlessInvocation
+  | MetaInvocation
+  | SkillSessionInvocation
+  | WebInvocation
 
 /** Raw web-subcommand options straight from Commander. */
 interface WebOptions {
+  config?: string
   host?: string
   port?: string
   dev?: boolean
@@ -65,6 +93,7 @@ interface WebOptions {
 function resolveWeb(options: WebOptions): WebInvocation {
   return {
     mode: 'web',
+    ...options.config !== undefined && { config: options.config },
     ...options.host !== undefined && { host: options.host },
     ...options.port !== undefined && { port: Number(options.port) },
     dev: options.dev === true,
@@ -86,21 +115,34 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
   const program = new Command()
     .name('dsh')
     .version(version, '-V, --version', 'output the version number')
-    .description('dsh: interactive TUI (default), headless task, and browser UI')
+    .description('dsh: DeepSeek Harness — an interactive coding agent for your terminal.\nRun `dsh` with no arguments to start a session in the current directory.')
+    // The default surface takes no positional task, so `dsh "task"` fails
+    // commander's arity check with no hint; these examples are where a first
+    // reader learns the entry points and that a one-shot task rides `-p`.
+    .addHelpText('after', `
+Examples:
+  dsh                     start an interactive session in this directory
+  dsh -p "run the tests"  answer one task, print the result, and exit
+  dsh --resume <id>       continue a past session
+`)
     .exitOverride()
+    // Stop parent options at a subcommand boundary so `web --config` belongs to
+    // Web while `--config ... web` remains a leaked default-surface option.
+    .enablePositionalOptions()
     // Default surface: option-only (no positional), so `web` can be a real
     // subcommand without a positional collision.
-    .option('--config <path>', 'boot an alternate cordis.yml instead of the shipped tree (TUI mode)')
-    .option('-p, --prompt <task>', 'run one headless turn for this task, print the result, and exit')
-    .option('--resume <id>', 'resume the persisted session with this id (TUI mode)')
-    .action((options: { config?: string; prompt?: string; resume?: string }) => {
+    .option('-p, --prompt <task>', 'answer this task without the interactive UI, then exit')
+    .option('--resume <id>', 'continue a past session by id')
+    .option('--config <path>', 'apply this overlay of loader patches instead of the personal one')
+    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped and personal configuration')
+    .action((options: { config?: string; configReplace?: string; prompt?: string; resume?: string }) => {
       if (options.prompt !== undefined) {
         // A headless prompt owns the invocation; an empty task has nothing to
         // run, and --config/--resume are TUI inputs that must not silently
         // vanish from a headless run.
         if (options.prompt === '') program.error('error: --prompt needs a task')
-        if (options.config !== undefined || options.resume !== undefined) {
-          program.error('error: --prompt takes no --config or --resume')
+        if (options.config !== undefined || options.configReplace !== undefined || options.resume !== undefined) {
+          program.error('error: --prompt takes no --config, --config-replace, or --resume')
         }
         resolved = { mode: 'headless', prompt: options.prompt }
         return
@@ -108,32 +150,67 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
       // An empty --resume= id would silently start a fresh session downstream
       // (agent-loop treats '' as no-resume), so a mistyped resume must fail loud.
       if (options.resume === '') program.error('error: --resume needs a session id')
+      // The two config flags are mutually exclusive: one layers over the shipped
+      // tree, the other discards it, so accepting both would silently drop one.
+      if (options.config !== undefined && options.configReplace !== undefined) {
+        program.error('error: --config and --config-replace are mutually exclusive')
+      }
       resolved = {
         mode: 'tui',
         ...options.config !== undefined && { config: options.config },
+        ...options.configReplace !== undefined && { configReplace: options.configReplace },
         ...options.resume !== undefined && { resume: options.resume },
       }
     })
 
-  const web = program.command('web').description('serve the browser UI (host/port default to the shipped config)')
+  // Commander parses the parent (default-surface) options on either side of a
+  // subcommand into `program.opts()`. For a subcommand that shares none of them,
+  // a leaked config/prompt/resume option is a mistyped invocation that must fail
+  // loud rather than silently run and drop the input.
+  const rejectParentOptions = (command: string): void => {
+    const parent = program.opts<{ config?: string; configReplace?: string; prompt?: string; resume?: string }>()
+    if (parent.config !== undefined || parent.configReplace !== undefined
+      || parent.prompt !== undefined || parent.resume !== undefined) {
+      program.error(`error: ${command} takes none of --config, --config-replace, -p/--prompt, or --resume`)
+    }
+  }
+
+  // Registration order is the rendered help order, so daily use comes first
+  // and the harness-development surfaces (`web --dev`, `meta`) come last.
+  // `upgrade` is a guided fresh-session entry: it takes no options and always
+  // mints a fresh session, so nothing is left to carry.
+  program
+    .command('upgrade')
+    .description('update this dsh installation to the latest version')
+    .action(() => {
+      rejectParentOptions('upgrade')
+      resolved = { mode: 'upgrade' }
+    })
+
+  // Host and port name no default: the CLI passes neither through when the flag
+  // is absent, so the shipped Web overlay value stands and restating it here
+  // would duplicate a fact this file does not own.
+  const web = program.command('web').description('serve the browser UI on the configured host and port')
   web
-    .option('--host <host>', 'override the config bind host (127.0.0.1 or 0.0.0.0)')
-    .option('--port <port>', 'override the config listen port (0 requests an OS-assigned port)')
-    .option('--dev', 'mount the client HMR driver and watch plugin bundles for rebuilds')
-    .option('--workspace-root <path>', 'parent directory for name-created workspaces')
+    .option('--config <path>', 'apply this overlay of loader patches over the shipped configuration')
+    .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
+    .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
+    .option('--dev', 'developer mode: hot-reload the browser client')
+    .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
     .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
     .action((options: WebOptions) => {
-      // Commander parses the parent (default-surface) options on either side of
-      // the subcommand into `program.opts()`. `web` shares none of them, so a
-      // leaked `--config`/`-p`/`--resume` is a mistyped invocation that must
-      // fail loud rather than silently start the web server and drop it.
-      const parent = program.opts<{ config?: string; prompt?: string; resume?: string }>()
-      if (parent.config !== undefined || parent.prompt !== undefined || parent.resume !== undefined) {
-        program.error('error: web takes none of --config, -p/--prompt, or --resume')
-      }
+      rejectParentOptions('web')
       resolved = resolveWeb(options)
     })
 
+  program
+    .command('meta')
+    .description('work on the dsh source that runs this command, from any directory')
+    .action(() => {
+      rejectParentOptions('meta')
+      resolved = { mode: 'meta' }
+    })
+
   try {
     program.parse(argv, { from: 'user' })
   } catch (error) {

apps/cli/src/bin.ts

@@ -30,7 +30,7 @@ const invocation = parseDshArgs(process.argv.slice(2), readVersion())
 switch (invocation.mode) {
   case 'web': {
     const { runWeb } = await import('./web.ts')
-    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts)
+    await runWeb(invocation.host, invocation.port, invocation.dev, invocation.workspaceRoot, invocation.trustedHosts, invocation.config)
     break
   }
   case 'headless': {
@@ -40,7 +40,17 @@ switch (invocation.mode) {
   }
   case 'tui': {
     const { runTui } = await import('./tui.ts')
-    await runTui(invocation.config, invocation.resume)
+    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
+    break
+  }
+  case 'meta': {
+    const { runMeta } = await import('./tui.ts')
+    await runMeta()
+    break
+  }
+  case 'upgrade': {
+    const { runSkillSession } = await import('./tui.ts')
+    await runSkillSession(`dsh-${invocation.mode}`)
     break
   }
   default:

apps/cli/src/headless.ts

@@ -1,6 +1,6 @@
 /**
  * `dsh -p "task"` — headless over the one shared composition: AppCLIEntry
- * boots the same cordis.yml as `dsh web` (port 0, so parallel runs never
+ * boots the same base plus Web overlay as `dsh web` (port 0, so parallel runs never
  * collide), then in-process isomorphic injection (InProcessApiClient over
  * toFetchHandler(ctx.apiProxy), so the full carrier chain — wire
  * serialization, zod, SSE framing — really runs). The printed URL opens the
@@ -75,7 +75,8 @@ async function consumeUntilTurnEnd(frames: AsyncIterable<RpcRequest<MuxFrame>>,
 export async function runHeadless(task: string): Promise<void> {
   // A missing DEEPSEEK_API_KEY throws here (plugin load is fail-loud, uncaught by design).
   const entry = new AppCLIEntry({
-    configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
+    configPath: fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url)),
+    overlayPath: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
     dev: false,
     port: 0,
   })

apps/cli/src/tui.ts

@@ -1,40 +1,61 @@
 /**
  * `dsh` default surface — the interactive TUI coding agent. Boots the shipped
- * tui-agent config (or the `--config` override) with the personal overlay
+ * shared base and TUI overlay, followed by either `--config` or the personal overlay
  * from the Harness home (`~/.dsh`): its `.env` fills environment gaps (precedence:
  * ambient environment, then the invoking directory's `.env`, then the personal one)
  * and its `config.yaml` patches the booted tree. The workspace is the invoking
- * directory: sessions, relative paths, and workspace instructions resolve from
- * the cwd, so `dsh` acts on whatever project it is launched in. After boot, the
- * agent's system prompt is told the path to this harness checkout so it can find
- * its own source.
+ * directory: the session cwd, relative paths, and workspace instructions resolve
+ * from it, so `dsh` acts on whatever project it is launched in. Session storage
+ * is the exception — it lives under the Harness home so `/resume` reaches every
+ * workspace, and an in-place resume enters the selected session's own directory.
+ * `dsh meta`
+ * ({@link runMeta}) is the one exception — it makes this harness checkout the
+ * workspace. `dsh upgrade` ({@link runSkillSession}) is a fresh
+ * session whose first turn auto-invokes a bundled skill. After boot, the
+ * agent's system prompt is told the path to this harness checkout so it can
+ * find its own source.
  * @module @deepseek-ai/dsh/tui
  */
 
-import { join } from 'node:path'
+import { randomUUID } from 'node:crypto'
+import { rm } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
+import { tmpdir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import {
   addHarnessSourceSection,
   boot,
   installFailLoud,
-  loadEnv,
+  loadOverlayPatches,
   loadPersonalPatches,
-  RESUME_SESSION_ID_KEY,
   resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite'
+import { CONFIGURED_AGENT_IDENTITIES_KEY } from '@deepseek-ai/dsh-agent-loop'
 import type { Context } from 'cordis'
 import {
+  INITIAL_SKILL_KEY,
+  MAIN_SESSION_ID_KEY,
   TUI_GOODBYE_MESSAGE_KEY,
+  type MainSessionIdentity,
   type TuiResumeHost,
 } from '@deepseek-ai/dsh-tui'
 
 const NAME = 'dsh'
 
-// Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
-// one directory under apps/cli, so the shipped default config resolves with
-// the same relative hop from either artifact.
-const DEFAULT_CONFIG = fileURLToPath(new URL('../../../examples/tui-agent/cordis.yml', import.meta.url))
+// The shared core every `dsh` surface mounts, and the TUI's own overlay over
+// it. Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib)
+// sit one directory under apps/cli, so each resolves with the same hop.
+const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
+const TUI_OVERLAY = fileURLToPath(new URL('../config/tui.cordis.yml', import.meta.url))
+
+// The `agents` entry in tui.cordis.yml the TUI drives; the launcher binds its
+// session identity by this config id.
+const MAIN_AGENT_ID = 'main'
+
+/** Per-process filename of the disposable `/resume` index. */
+const SESSION_QUERY_DB = `session-query-${String(process.pid)}-${randomUUID()}.db`
 
 // The harness checkout root: three hops up from apps/cli/{src,lib}, resolved
 // from this bin's location so it holds however `dsh` is launched (a PATH
@@ -42,17 +63,55 @@ const DEFAULT_CONFIG = fileURLToPath(new URL('../../../examples/tui-agent/cordis
 const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
 
 /* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers;
-   the tui-agent PTY smoke drives this path end to end, personal overlay included */
+   the CLI PTY smoke drives this path end to end, personal overlay included */
+/**
+ * Run the interactive TUI with this harness checkout as the workspace
+ * (`dsh meta`), whatever directory it was launched from.
+ */
+export async function runMeta(): Promise<void> {
+  return runTui(undefined, undefined, SOURCE_ROOT)
+}
+
+/**
+ * Run the interactive TUI as a guided fresh session whose first turn invokes a
+ * bundled skill (`dsh upgrade` → `dsh-upgrade`).
+ * Always mints a fresh session in the invoking directory; the skill is seeded
+ * only on this first launch, so a later `--resume` of the session is an ordinary
+ * TUI session with no re-injection.
+ * @param skill - the bundled skill name to auto-invoke as the first turn.
+ */
+export async function runSkillSession(skill: string): Promise<void> {
+  return runTui(undefined, undefined, undefined, skill)
+}
+
 /**
  * Run the interactive TUI from the invoking directory.
- * @param config - a config path to boot instead of the shipped default, or
- * `undefined` for the default; already parsed from `--config`.
- * @param resumeSessionId - a persisted session id to resume, or `undefined`;
- * already parsed and non-empty-validated from `--resume`. It is provided on the
- * boot context under {@link RESUME_SESSION_ID_KEY}, which the shipped config
- * reads through `!!js` to rehydrate that session.
+ * @param config - an overlay patch list applied over the shared base and the
+ * TUI overlay, REPLACING the personal `~/.dsh/config.yaml` so a named tree never
+ * inherits the user's route, or `undefined` to use the personal overlay;
+ * already parsed from `--config`.
+ * @param resumeSessionId - a persisted session id to resume, or `undefined` to
+ * mint a fresh one; already parsed and non-empty-validated from `--resume`.
+ * Either way the resulting identity reaches the booted app through
+ * {@link CONFIGURED_AGENT_IDENTITIES_KEY}, so no config key selects the session
+ * and an overlay replacing the agent row cannot drop it.
+ * @param workspace - a directory to make the workspace instead of the invoking
+ * one, or `undefined` to keep the cwd. Only `dsh meta` passes it.
+ * @param initialSkill - a bundled skill to auto-invoke as a fresh session's
+ * first turn, or `undefined`. Set only by {@link runSkillSession} and ignored
+ * on a resume, so it never re-fires; reaches the app through
+ * {@link INITIAL_SKILL_KEY}.
+ * @param configReplace - a config path to boot as the ENTIRE tree, bypassing the
+ * shared base, the TUI overlay, and the personal overlay alike, or `undefined`
+ * to compose them; already parsed from `--config-replace`.
  */
-export async function runTui(config: string | undefined, resumeSessionId: string | undefined): Promise<void> {
+export async function runTui(
+  config: string | undefined,
+  resumeSessionId: string | undefined,
+  workspace?: string,
+  initialSkill?: string,
+  configReplace?: string,
+): Promise<void> {
   // Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree
   // is logged per-entry rather than rethrown, so a piped launch would
   // otherwise settle into an idle UI-less process instead of exiting nonzero.
@@ -63,31 +122,56 @@ export async function runTui(config: string | undefined, resumeSessionId: string
     process.exit(1)
   }
   installFailLoud(NAME)
-  // The bin already loaded the invoking directory's .env; the personal .env
-  // only fills what is still unset (process.loadEnvFile never overrides).
-  loadEnv(NAME, resolveDshHome())
+  // The bin already loaded the invoking directory's .env, and that is the
+  // whole environment: $DSH_HOME/.env is credentials-local's writable store,
+  // and hoisting it would make every stored key read as a read-only ambient
+  // override on the next run — unrotatable from the TUI or the web page.
+  // The environment is settled, so switching the workspace here cannot alter
+  // its precedence. The cwd IS the workspace seam: the shipped config
+  // resolves the session cwd and the HMR watch root from it, so one chdir moves
+  // both together. Sessions themselves live under the Harness home so `/resume`
+  // spans every workspace, and are unaffected by this chdir.
+  if (workspace !== undefined) process.chdir(workspace)
   process.env.DSH_BUNDLED_SKILL_DIR = join(SOURCE_ROOT, 'skills')
   // The in-place `/resume` handoff re-execs `dsh` with a normalized `--resume`
-  // flag, so the resumed process rehydrates through this same intake. The host
-  // is offered only when Node exposes `process.execve` and knows its own entry.
+  // flag, so the resumed process rehydrates through this same intake. The
+  // selected session may belong to another workspace, so the handoff also enters
+  // that directory. The host is offered only when Node exposes `process.execve`
+  // and knows its own entry.
+  const resolvedConfig = config === undefined ? undefined : resolve(config)
+  const resolvedConfigReplace = configReplace === undefined ? undefined : resolve(configReplace)
   const entry = process.argv[1]
   const execve = process.execve?.bind(process)
   const app: { current?: Context } = {}
-  const resumeCommand = (sessionId: string): string =>
-    `${NAME} --resume=${sessionId}${config === undefined ? '' : ` --config ${config}`}`
+  // Resume always enters the default surface because meta rejects parent
+  // options, including `--resume`. The resumed session already persists its cwd.
+  const resumeArgs = (sessionId: string): string[] => [
+    `--resume=${sessionId}`,
+    // Both config flags must survive the handoff: resuming into a different
+    // tree than the session was created in would silently change the agent.
+    ...resolvedConfig !== undefined ? ['--config', resolvedConfig] : [],
+    ...resolvedConfigReplace !== undefined ? ['--config-replace', resolvedConfigReplace] : [],
+  ]
+  // Mint the fresh id here rather than in the app bundle: the exit line names
+  // the session to resume, so the launcher must know it before the tree boots.
+  const identity: MainSessionIdentity = resumeSessionId === undefined
+    ? { id: SessionId(`main-session-${randomUUID()}`), resume: false }
+    : { id: SessionId(resumeSessionId), resume: true }
+  const goodbye = `To resume this session: ${NAME} ${resumeArgs(identity.id).join(' ')}`
   const resumeHost: TuiResumeHost | undefined = entry === undefined || execve === undefined ? undefined : {
     async handoff(sessionId, cwd): Promise<never> {
       const current = app.current
       if (current === undefined) throw new Error(`${NAME}: app boot has not completed`)
-      // Rebuild argv from the parsed config plus the selected id: TUI mode's
-      // only arguments are `--config <path>` and `--resume <id>`.
       const nextArgv = [
         process.execPath,
         ...process.execArgv,
         entry,
-        `--resume=${sessionId}`,
-        ...config !== undefined ? ['--config', config] : [],
+        ...resumeArgs(sessionId),
       ]
+      // `execve` inherits the cwd, and the target session may belong to another
+      // workspace. Enter it BEFORE teardown commits: an unreachable directory
+      // (deleted, unreadable) must reject while the caller can still restore the
+      // terminal, and a chdir after disposal would have no owner to report to.
       try {
         process.chdir(cwd)
       } catch (error) {
@@ -103,18 +187,55 @@ export async function runTui(config: string | undefined, resumeSessionId: string
       }
     },
   }
+  // One include of the shared base, with every overlay applied as a sibling
+  // patch list: patches never cross an include boundary, so stacking these as
+  // nested includes would silently stop reaching base rows. Later lists win.
+  //
+  // `--config` REPLACES the personal overlay rather than layering under it: an
+  // explicitly named tree must not inherit `~/.dsh/config.yaml`'s route, or a
+  // demo or test config would silently run on the user's provider and model.
+  // `--config-replace` additionally discards the base and the surface overlay.
+  const replaceTree = configReplace !== undefined
+  const patches = replaceTree ? [] : [
+    ...loadOverlayPatches(NAME, TUI_OVERLAY),
+    ...resolvedConfig === undefined
+      ? loadPersonalPatches(NAME) ?? []
+      : loadOverlayPatches(NAME, resolveConfigPath(resolvedConfig, undefined)),
+  ]
+  const queryIndexPath = join(tmpdir(), SESSION_QUERY_DB)
   const ctx = await boot(
     NAME,
-    resolveConfigPath(config ?? DEFAULT_CONFIG, undefined),
-    loadPersonalPatches(NAME),
+    resolvedConfigReplace === undefined ? BASE_CONFIG : resolveConfigPath(resolvedConfigReplace, undefined),
+    patches,
     (hostCtx) => {
-      // Inject the resume id (or undefined) so the shipped config's `!!js`
-      // reads it as a bare identifier; then offer the in-place handoff host.
-      hostCtx.provide(RESUME_SESSION_ID_KEY, resumeSessionId)
-      if (resumeSessionId !== undefined) {
-        hostCtx.provide(TUI_GOODBYE_MESSAGE_KEY, `To resume this session: ${resumeCommand(resumeSessionId)}`)
-      }
+      // 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
+      // resume.
+      hostCtx.provide(MAIN_SESSION_ID_KEY, identity)
+      hostCtx.provide(TUI_GOODBYE_MESSAGE_KEY, goodbye)
+      // Shared-store policy is the launcher's: sessions live in one root under
+      // the Harness home across every cwd, so /resume sees every workspace.
+      // The bundle treats the slot as opaque.
+      // The agent-loop row reads this to bind `main`, and the tui row reads the
+      // same id, so a personal overlay repointing the model route cannot drop
+      // the session identity or desynchronise the two.
+      hostCtx.provide(CONFIGURED_AGENT_IDENTITIES_KEY, { [MAIN_AGENT_ID]: identity })
+      // The query database is a disposable derived index with single-process
+      // ownership. Keep it process-local while it indexes the shared logs.
+      hostCtx.provide(SESSION_QUERY_SQLITE_PATH_KEY, queryIndexPath)
+      hostCtx.effect(() => async () => {
+        await Promise.all([
+          rm(queryIndexPath, { force: true }),
+          rm(`${queryIndexPath}-wal`, { force: true }),
+          rm(`${queryIndexPath}-shm`, { force: true }),
+        ])
+      }, `${SESSION_QUERY_SQLITE_PATH_KEY}.cleanup`)
       if (resumeHost !== undefined) hostCtx.provide('tuiResumeHost', resumeHost)
+      // Seed the first turn only for a fresh session, so resuming never
+      // re-invokes the skill.
+      if (initialSkill !== undefined && resumeSessionId === undefined) {
+        hostCtx.provide(INITIAL_SKILL_KEY, initialSkill)
+      }
     },
   )
   app.current = ctx

apps/cli/src/web.ts

@@ -1,15 +1,18 @@
 /**
  * `dsh web` — thin bin over the config-tree boot: run AppCLIEntry with the
  * already-parsed host/port/dev, print the URL line, wire signals. All
- * composition lives in cordis.yml; all boot glue lives in AppCLIEntry. Host and
+ * composition lives in the shared base plus Web overlay; all boot glue lives in AppCLIEntry. Host and
  * port are unvalidated pass-through overrides — the `dsh-host-webserver` schema
  * gates them at boot.
  */
 
 import { fileURLToPath } from 'node:url'
+import { resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 import { AppCLIEntry } from './app-cli-entry.ts'
 
-const CONFIG_PATH = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+// The shared core every `dsh` surface mounts, plus this surface's overlay over it.
+const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
+const WEB_OVERLAY = fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url))
 
 // Display-only mirror of the webserver schema's loopback host: the address the
 // local URL always prints. Not a source of truth — the schema is.
@@ -17,12 +20,15 @@ const LOOPBACK_HOST = '127.0.0.1'
 
 /**
  * Serve the browser UI from the shipped config tree. `host`/`port` are passed
- * through only when the flag was given; absent, the `cordis.yml` value stands.
+ * through only when the flag was given; absent, the shipped Web overlay value stands.
  * @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 driver and watch plugin bundles for rebuilds.
  * @param workspaceRoot - parent directory for name-created workspaces, or `undefined` for the gateway's cwd fallback.
  * @param trustedHosts - extra authorities for the /api browser-trust fence, or `undefined` for the derived LAN literals alone.
+ * @param config - an overlay of loader patches applied over the shipped web
+ * composition instead of `$DSH_HOME/config.yaml`, or `undefined` to use the
+ * personal overlay; already parsed from `--config`.
  */
 export async function runWeb(
   host: string | undefined,
@@ -30,9 +36,12 @@ export async function runWeb(
   dev: boolean,
   workspaceRoot: string | undefined,
   trustedHosts: string[] | undefined,
+  config?: string,
 ): Promise<void> {
   const entry = new AppCLIEntry({
-    configPath: CONFIG_PATH,
+    configPath: BASE_CONFIG,
+    overlayPath: WEB_OVERLAY,
+    ...config !== undefined && { extraOverlayPath: resolveConfigPath(config, undefined) },
     dev,
     ...host !== undefined && { host },
     ...port !== undefined && { port },