Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-06-21-bounded-llm-request-recovery.i18n.yaml # .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.i18n.yaml # .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.md # .agents/notes/implemented/feature/2026-06-18-compaction-capability-seam.zh.md # .agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-06-sandbox.md # .agents/notes/implemented/feature/2026-07-06-sandbox.zh.md # .agents/notes/implemented/feature/2026-07-27-tmux-location-context.i18n.yaml # .agents/notes/implemented/simplification/2026-06-20-public-agent-stop-surface.i18n.yaml # .agents/notes/implemented/simplification/2026-07-28-remove-synthetic-log-only-turns.i18n.yaml # .agents/notes/implemented/simplification/2026-07-30-private-agent-send.i18n.yaml # docs/architecture.i18n.yaml # docs/architecture.md # docs/architecture.zh.md # docs/config-catalog.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/compaction.i18n.yaml # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/core.md # docs/core-data-structures/core.zh.md # docs/core-data-structures/llm-streaming.i18n.yaml # docs/core-data-structures/llm-streaming.md # docs/core-data-structures/llm-streaming.zh.md # docs/core-data-structures/session.i18n.yaml # docs/event-producer-consumer.md # docs/module-graph.md # docs/persistence-catalog.md # examples/acp-agent/tests/goal-snapshots/goal-session/session.expected.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/acp-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/acp-agent/tests/snapshots/bash-spill/session.jsonl # examples/acp-agent/tests/snapshots/bash-tool-turn/session.jsonl # examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl # examples/acp-agent/tests/snapshots/cancel-tool-calls/session.jsonl # examples/acp-agent/tests/snapshots/cancel/session.jsonl # examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl # examples/acp-agent/tests/snapshots/code-mode-workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl # examples/acp-agent/tests/snapshots/empty-response-retry/session.jsonl # examples/acp-agent/tests/snapshots/error-finish/session.jsonl # examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/acp-agent/tests/snapshots/fs-edit/session.jsonl # examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/fs-glob-sampling/session.jsonl # examples/acp-agent/tests/snapshots/fs-policy-reject/session.jsonl # examples/acp-agent/tests/snapshots/fs-read-window/session.jsonl # examples/acp-agent/tests/snapshots/fs-read/session.jsonl # examples/acp-agent/tests/snapshots/fs-write-overwrite/session.jsonl # examples/acp-agent/tests/snapshots/fs-write/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-invalid-matcher/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-posttool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-posttool-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-deny/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-stop-continue/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-invalid-matcher/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-posttool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-posttool-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-pretool-block/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-promptsubmit-context/session.jsonl # examples/acp-agent/tests/snapshots/hook-codex-stop-continue/session.jsonl # examples/acp-agent/tests/snapshots/lsp-definition/session.jsonl # examples/acp-agent/tests/snapshots/multi-turn/session.jsonl # examples/acp-agent/tests/snapshots/packed-chunks/session.jsonl # examples/acp-agent/tests/snapshots/parallel-tool-calls/session.jsonl # examples/acp-agent/tests/snapshots/pty-tools/session.jsonl # examples/acp-agent/tests/snapshots/repeat-tool-guard/session.jsonl # examples/acp-agent/tests/snapshots/session-query-spill/session.jsonl # examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl # examples/acp-agent/tests/snapshots/session-title-after-turn/session.jsonl # examples/acp-agent/tests/snapshots/skill-load/session.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-depth-two-rejection/session.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-fork/session.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-mixed/session.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.2.jsonl # examples/acp-agent/tests/snapshots/subagent-multi/session.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/acp-agent/tests/snapshots/subagent-spawn/session.jsonl # examples/acp-agent/tests/snapshots/text-turn/session.jsonl # examples/acp-agent/tests/snapshots/todo-write/session.jsonl # examples/acp-agent/tests/snapshots/tool-call-turn/session.jsonl # examples/acp-agent/tests/snapshots/web-fetch/session.jsonl # examples/acp-agent/tests/snapshots/workflow-run/session.1.jsonl # examples/acp-agent/tests/snapshots/workflow-run/session.jsonl # examples/acp-agent/tests/snapshots/workspace-context/session.jsonl # examples/acp-agent/tests/snapshots/workspace-edit/session.jsonl # examples/headless-agent/tests/semantic-checkpoint-snapshots/tool-outcome-unknown/session.expected.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl # examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.expected.jsonl # examples/headless-agent/tests/snapshots/goal-tools/stream-json.expected.jsonl # examples/headless-agent/tests/snapshots/missing-credential/stream-json.expected.jsonl # examples/headless-agent/tests/snapshots/provider-retry/stream-json.expected.jsonl # examples/headless-agent/tests/snapshots/pty-tools/session.jsonl # examples/headless-agent/tests/snapshots/pty-tools/stream-json.expected.jsonl # examples/headless-agent/tests/snapshots/ralph-loop/stream-json.expected.jsonl # examples/headless-agent/tests/subagent-inheritance-snapshots/parent-override/child.expected.jsonl # examples/headless-agent/tests/subagent-inheritance-snapshots/parent-override/parent.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/bash-tool/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/bash-tool/session.jsonl # examples/jsonrpc-agent/tests/snapshots/persistent-tools/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/persistent-tools/session.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/session.1.jsonl # examples/jsonrpc-agent/tests/snapshots/subagent-spawn/session.jsonl # examples/jsonrpc-agent/tests/snapshots/text-turn/notifications.expected.jsonl # examples/jsonrpc-agent/tests/snapshots/text-turn/session.jsonl # packages/client/runtime/README.i18n.yaml # packages/client/runtime/src/client/sessions/request-inspection.ts # packages/compact/compact-basic/README.i18n.yaml # packages/compact/compact-basic/README.md # packages/compact/compact-basic/README.zh.md # packages/compact/compact-basic/src/index.ts # packages/context/time-context/tests/time-context.spec.ts # packages/context/tmux-context/README.i18n.yaml # packages/context/tmux-context/tests/tmux-context.spec.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.md # packages/core/agent-loop/README.zh.md # packages/core/agent-loop/src/agent.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/core/agent/src/types.ts # packages/core/session/README.i18n.yaml # packages/core/session/README.md # packages/core/session/README.zh.md # packages/fs/tool-str-replace-editor/tests/tools.spec.ts # packages/goal/command-goal/tests/command-goal.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/host/apiproxy/README.i18n.yaml # packages/host/apiproxy/README.md # packages/host/apiproxy/README.zh.md # packages/host/apiproxy/src/api/index.ts # packages/host/apiproxy/tests/api-proxy-workspace.spec.ts # packages/llm/llm/README.i18n.yaml # packages/llm/llm/README.md # packages/llm/llm/README.zh.md # packages/llm/llm/src/index.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/pty/tests/service.spec.ts # packages/pty/tool-bash-persistent/tests/loader-composition.spec.ts # packages/pty/tool-bash-persistent/tests/tools.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/session-persistence/session-checkpoint-policy/tests/crash-recovery.e2e.ts # packages/skill/tool-skill/tests/tool-skill.spec.ts # packages/tasks/tasks-local/tests/tasks.spec.ts # packages/ui/tui/README.i18n.yaml # packages/ui/tui/tests/tui.spec.ts # packages/ui/user-approval/src/index.ts # packages/ui/user-approval/tests/approval.spec.ts
2026-07-31 22:16:40 +08:00
parent afedf18ccf 9a3bdd599c
commit e0988abc74
1010 changed files with 105572 additions and 5504 deletions
--- a/apps/cli/src/app-cli-entry.ts
+++ b/apps/cli/src/app-cli-entry.ts
@@ -3,7 +3,7 @@
 * 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
+ * flags + the resolved frontend dist), and the fail-loud activation audit 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.
@@ -246,7 +246,7 @@ export class AppCLIEntry {
    if (telemetryPatch !== undefined) this.patches.push(telemetryPatch)
  }

-  /** Shared Loader boot; the dev HMR row mounts before await so the fail-loud sweep covers it. */
+  /** Shared Loader boot; the dev HMR row mounts before await so the activation audit covers it. */
  private async bootTree(): Promise<void> {
    // One include of the shared base with every overlay as a sibling patch
    // list: patches never cross an include boundary, so nesting them would
--- a/apps/cli/src/args.ts
+++ b/apps/cli/src/args.ts
@@ -2,8 +2,9 @@
 * 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; `meta` and
- * `web` are real subcommands. Commander owns `--help`/`--version` and parse
+ * subcommand) is the TUI/headless surface with option-only flags;
+ * `experimental-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
@@ -23,6 +24,22 @@ interface TuiInvocation {
  resume?: string
 }

+/**
+ * Print the composed config tree and exit, without booting: `--dump-config`
+ * composes the shipped base, the surface overlay, and the `--config` or
+ * personal overlay — exactly the layers that surface would boot;
+ * `--dump-default-config` stops at the surface overlay (the shipped tree, no
+ * user layer).
+ */
+interface DumpConfigInvocation {
+  mode: 'dump-config'
+  surface: 'tui' | 'web'
+  /** Omit the `--config`/personal layer and print only the shipped composition. */
+  defaultOnly: boolean
+  /** The `--config` overlay to compose instead of the personal one. */
+  config?: string
+}
+
 /** Headless one-shot: `dsh -p "task"`. */
 interface HeadlessInvocation {
  mode: 'headless'
@@ -35,8 +52,8 @@ interface MetaInvocation {
 }

 /**
- * Guided fresh-session entry: `dsh upgrade` seeds the first turn with the
- * `dsh-upgrade` skill. It always mints a
+ * Guided fresh-session entry: `dsh experimental-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.
 */
@@ -69,6 +86,7 @@ interface WebInvocation {
 /** The resolved `dsh` invocation: exactly one mode. `--help`/`--version`/errors exit inside {@link parseDshArgs}. */
 export type DshInvocation =
  | TuiInvocation
+  | DumpConfigInvocation
  | HeadlessInvocation
  | MetaInvocation
  | SkillSessionInvocation
@@ -82,6 +100,34 @@ interface WebOptions {
  dev?: boolean
  workspaceRoot?: string
  trustedHost?: string[]
+  dumpConfig?: boolean
+  dumpDefaultConfig?: boolean
+}
+
+/**
+ * Resolve the two dump flags for one surface, or return `undefined` when
+ * neither was passed. Both flags together are contradictory (one includes the
+ * user layer, the other excludes it) and fail loud through `error`.
+ */
+function resolveDump(
+  surface: 'tui' | 'web',
+  options: { config?: string; dumpConfig?: boolean; dumpDefaultConfig?: boolean },
+  error: (message: string) => never,
+): DumpConfigInvocation | undefined {
+  if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) return undefined
+  if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
+    error('error: --dump-config and --dump-default-config are mutually exclusive')
+  }
+  const defaultOnly = options.dumpDefaultConfig === true
+  if (defaultOnly && options.config !== undefined) {
+    error('error: --dump-default-config prints the shipped tree and takes no --config')
+  }
+  return {
+    mode: 'dump-config',
+    surface,
+    defaultOnly,
+    ...options.config !== undefined && { config: options.config },
+  }
 }

 /**
@@ -135,7 +181,26 @@ Examples:
    .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 }) => {
+    .option('--dump-config', 'print the composed config tree (base + surface + --config/personal overlay) and exit')
+    .option('--dump-default-config', 'print the shipped config tree (base + surface overlay, no user layer) and exit')
+    .action((options: {
+      config?: string
+      configReplace?: string
+      prompt?: string
+      resume?: string
+      dumpConfig?: boolean
+      dumpDefaultConfig?: boolean
+    }) => {
+      const dump = resolveDump('tui', options, message => program.error(message))
+      if (dump !== undefined) {
+        // The dump prints composition; a boot-only flag alongside it would be
+        // silently ignored, so reject the mix loud.
+        if (options.prompt !== undefined || options.resume !== undefined || options.configReplace !== undefined) {
+          program.error('error: --dump-config/--dump-default-config take none of -p/--prompt, --resume, or --config-replace')
+        }
+        resolved = dump
+        return
+      }
      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
@@ -168,22 +233,31 @@ Examples:
  // 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 }>()
+    const parent = program.opts<{
+      config?: string
+      configReplace?: string
+      prompt?: string
+      resume?: string
+      dumpConfig?: boolean
+      dumpDefaultConfig?: boolean
+    }>()
    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`)
+      || parent.prompt !== undefined || parent.resume !== undefined
+      || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
+      program.error(`error: ${command} takes none of --config, --config-replace, -p/--prompt, --resume, --dump-config, or --dump-default-config`)
    }
  }

  // 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.
+  // and the harness-development surfaces (`web --dev`, `experimental-meta`)
+  // come last. `experimental-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')
+    .command('experimental-upgrade')
    .description('update this dsh installation to the latest version')
    .action(() => {
-      rejectParentOptions('upgrade')
+      rejectParentOptions('experimental-upgrade')
      resolved = { mode: 'upgrade' }
    })

@@ -198,16 +272,23 @@ Examples:
    .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)')
+    .option('--dump-config', 'print the composed config tree (base + web + --config/personal overlay) and exit')
+    .option('--dump-default-config', 'print the shipped config tree (base + web overlay, no user layer) and exit')
    .action((options: WebOptions) => {
      rejectParentOptions('web')
+      const dump = resolveDump('web', options, message => program.error(message))
+      if (dump !== undefined) {
+        resolved = dump
+        return
+      }
      resolved = resolveWeb(options)
    })

  program
-    .command('meta')
+    .command('experimental-meta')
    .description('work on the dsh source that runs this command, from any directory')
    .action(() => {
-      rejectParentOptions('meta')
+      rejectParentOptions('experimental-meta')
      resolved = { mode: 'meta' }
    })

--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -43,14 +43,19 @@ switch (invocation.mode) {
    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
    break
  }
+  case 'dump-config': {
+    const { runDumpConfig } = await import('./dump-config.ts')
+    runDumpConfig(invocation.surface, invocation.defaultOnly, invocation.config)
+    break
+  }
  case 'meta': {
-    const { runMeta } = await import('./tui.ts')
-    await runMeta()
+    const { runTui, SOURCE_ROOT } = await import('./tui.ts')
+    await runTui(undefined, undefined, SOURCE_ROOT)
    break
  }
  case 'upgrade': {
-    const { runSkillSession } = await import('./tui.ts')
-    await runSkillSession(`dsh-${invocation.mode}`)
+    const { runTui } = await import('./tui.ts')
+    await runTui(undefined, undefined, undefined, `dsh-${invocation.mode}`)
    break
  }
  default:
--- a/apps/cli/src/dump-config.ts
+++ b/apps/cli/src/dump-config.ts
@@ -0,0 +1,61 @@
+/**
+ * `dsh --dump-config` / `dsh web --dump-config` — print the composed config
+ * tree without booting: the shipped base, the surface overlay, and (unless
+ * `--dump-default-config`) the `--config` or personal overlay, composed
+ * through the include's own patch algorithm so the printed tree is exactly
+ * what that surface would mount. `!!js` expressions print verbatim,
+ * unevaluated — the dump shows composition, not one process's environment.
+ * Launcher-provided boot-context values (session identity, CLI-flag patches)
+ * are per-invocation facts outside the config tree and do not appear.
+ * @module @deepseek-ai/dsh/dump-config
+ */
+
+import { basename, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  loadOverlayPatches,
+  loadPersonalPatches,
+  PERSONAL_CONFIG_FILENAME,
+  renderConfigDump,
+  type ConfigDumpLayer,
+} from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+
+const NAME = 'dsh'
+
+const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
+const SURFACE_OVERLAYS = {
+  tui: fileURLToPath(new URL('../config/tui.cordis.yml', import.meta.url)),
+  web: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
+} as const
+
+/* v8 ignore start -- composition over the unit-tested renderConfigDump; the
+   built-bin e2e drives this path end to end */
+/**
+ * Print one surface's composed config tree to stdout, with a comment
+ * separator naming the file each section of rows comes from (and the layers
+ * that patched it).
+ * @param surface - which surface overlay to compose over the shared base.
+ * @param defaultOnly - stop at the surface overlay (no `--config`/personal layer).
+ * @param config - the `--config` overlay path composed instead of the personal
+ * one, or `undefined` to use `$DSH_HOME/config.yaml`.
+ */
+export function runDumpConfig(surface: 'tui' | 'web', defaultOnly: boolean, config?: string): void {
+  const overlay = SURFACE_OVERLAYS[surface]
+  const layers: ConfigDumpLayer[] = [
+    { label: basename(overlay), patches: loadOverlayPatches(NAME, overlay) },
+  ]
+  if (!defaultOnly) {
+    if (config === undefined) {
+      const personal = loadPersonalPatches(NAME)
+      // The personal file may be absent; the shipped layers still print.
+      if (personal !== undefined) {
+        layers.push({ label: join(resolveDshHome(), PERSONAL_CONFIG_FILENAME), patches: personal })
+      }
+    } else {
+      layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
+    }
+  }
+  process.stdout.write(renderConfigDump(NAME, BASE_CONFIG, layers))
+}
+/* v8 ignore stop */
--- a/apps/cli/src/tui-onboarding/tui-first-run-welcome-art.ts
+++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome-art.ts
@@ -0,0 +1,111 @@
+/**
+ * Static terminal rasters derived from the official 24x24 DeepSeek icon.
+ *
+ * Source: `../../assets/deepseek-color.svg`, whose path data is copied exactly
+ * from the supplied official icon (viewBox `0 0 24 24`, fill `#4D6BFE`). Each
+ * tier rasterizes that path into a square binary
+ * mask without redrawing its contour. The Unicode form packs two source rows
+ * into `▀`/`▄`/`█`; the ASCII fallback packs the same two bits into
+ * `'`/`_`/`#`. Assets contain no ANSI and are never generated at runtime.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-art
+ */
+
+/** Responsive official-icon raster tier. */
+export type TuiFirstRunWelcomeArtTier = 'full' | 'compact' | 'minimal'
+
+/** One raster with a block-cell primary and bit-equivalent ASCII fallback. */
+export interface TuiFirstRunWelcomeArt {
+  /** Two vertical source pixels per terminal cell. */
+  readonly unicode: readonly string[]
+  /** Same two-bit cells encoded as top `'`, bottom `_`, and both `#`. */
+  readonly ascii: readonly string[]
+}
+
+const fullUnicode = Object.freeze([
+  '                           ▄',
+  '       ▄▄▄▄▄▄▄▄▄▄███▀      ██▄',
+  '    ▄███████████████▄      ████▄  ▄▄▄▄██',
+  '  ▄███████████████████▄    ████████████▀',
+  ' ▄██████████████████████▄   ▀█████████▀',
+  '▄███▀█████████████████████▄   ████▀▀',
+  '███       ▀▀█████████▀▀▀█████████▀',
+  '███          ▀███████▀█  ▀███████',
+  '███▄           ▀███████▄  ▀█████▀',
+  '▀███             ▀██████████████',
+  ' ▀███▄            ▀███████████▀',
+  '  ▀███▄      ▄▄▄    ▀████████▀',
+  '    █████▄    ███▄▄   ▀█████▄▄',
+  '      ▀█████████████▄▄▄▄█▀█████▀',
+  '        ▀▀███████████▀▀',
+])
+
+const fullAscii = Object.freeze([
+  '                           _',
+  "       __________###'      ##_",
+  '    _###############_      ####_  ____##',
+  "  _###################_    ############'",
+  " _######################_   '#########'",
+  "_###'#####################_   ####''",
+  "###       ''#########'''#########'",
+  "###          '#######'#  '#######",
+  "###_           '#######_  '#####'",
+  "'###             '##############",
+  " '###_            '###########'",
+  "  '###_      ___    '########'",
+  "    #####_    ###__   '#####__",
+  "      '#############____#'#####'",
+  "        ''###########''",
+])
+
+const compactUnicode = Object.freeze([
+  '     ▄▄▄▄▄▄▄██▀    █▄      ▄',
+  '  ▄███████████▄▄   ███▄▄████',
+  ' ████████████████▄ ▀██████▀',
+  '██▀▀▀▀▀████████████▄▄██▀',
+  '██       ▀█████▄ ▀█████',
+  '██▄        ▀████▄ ▄████',
+  ' ██▄         ████████▀',
+  '  ██▄    ▄▄   ▀█████▀',
+  '   ▀███▄▄▄███▄  ████▄▄',
+  '     ▀▀▀███████▀▀',
+])
+
+const compactAscii = Object.freeze([
+  "     _______##'    #_      _",
+  '  _###########__   ###__####',
+  " ################_ '######'",
+  "##'''''############__##'",
+  "##       '#####_ '#####",
+  "##_        '####_ _####",
+  " ##_         ########'",
+  "  ##_    __   '#####'",
+  "   '###___###_  ####__",
+  "     '''#######''",
+])
+
+const minimalUnicode = Object.freeze([
+  '   ▄▄▄▄▄▄   ▄▄',
+  ' ▄████████▄ ▀████▀',
+  '█▀▀▀▀███████▄██▀',
+  '█▄    ▀███ ▀███',
+  '▀█▄     ▀█████',
+  ' ▀█▄▄ █▄▄▀███▄',
+  '    ▀▀▀▀▀▀',
+])
+
+const minimalAscii = Object.freeze([
+  '   ______   __',
+  " _########_ '####'",
+  "#''''#######_##'",
+  "#_    '### '###",
+  "'#_     '#####",
+  " '#__ #__'###_",
+  "    ''''''",
+])
+
+/** Exact-path terminal rasters by responsive tier. */
+export const TUI_FIRST_RUN_WELCOME_WHALE = Object.freeze({
+  full: Object.freeze({ unicode: fullUnicode, ascii: fullAscii }),
+  compact: Object.freeze({ unicode: compactUnicode, ascii: compactAscii }),
+  minimal: Object.freeze({ unicode: minimalUnicode, ascii: minimalAscii }),
+}) satisfies Readonly<Record<TuiFirstRunWelcomeArtTier, TuiFirstRunWelcomeArt>>
--- a/apps/cli/src/tui-onboarding/tui-first-run-welcome-copy.ts
+++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome-copy.ts
@@ -0,0 +1,49 @@
+/**
+ * Centrally owned version and all-locale Chinese copy for the shipped TUI first-run notice.
+ *
+ * A material wording change increments {@link TUI_FIRST_RUN_WELCOME_NOTICE_VERSION}
+ * so every Harness home presents the revised notice once.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome-copy
+ */
+
+/** Copy version persisted after the user explicitly continues. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_VERSION = 4
+
+/** Locale-shaped text rendered by the first-run welcome overlay. */
+export interface TuiFirstRunWelcomeNoticeCopy {
+  /** Overlay heading. */
+  readonly title: string
+  /** Ordered prose paragraphs. */
+  readonly paragraphs: readonly string[]
+  /** Enter action label. */
+  readonly continueLabel: string
+  /** Hint shown when the prose is scrollable. */
+  readonly scrollHint: string
+  /** Status shown while the acknowledgement reaches disk. */
+  readonly saving: string
+  /** Retry message shown when the acknowledgement cannot be persisted. */
+  readonly saveError: string
+}
+
+/** Complete Chinese notice used for every locale. */
+const TUI_FIRST_RUN_WELCOME_CHINESE_COPY = Object.freeze<TuiFirstRunWelcomeNoticeCopy>({
+  title: 'DeepSeek Harness',
+  paragraphs: Object.freeze([
+    '感谢您愿意拨冗试用 DeepSeek Harness。当前版本仍处于内部测试阶段，功能仍待完善，体验难免有些粗糙。',
+    '“如切如磋，如琢如磨。” 产品的成长，离不开一次次真实的碰撞与坦诚的反馈。您在真实使用中发现的问题，也可能促使我们重新审视，甚至推翻已有的设计。',
+    '为了帮助我们更准确地还原您真实使用中的问题，内测版本默认会上传所有 Session Log；如需关闭，请设置环境变量 DSH_TELEMETRY_DISABLED=1。另外，如果您有任何反馈与建议，请在企业微信群中留言告诉我们。每一条反馈，都会帮助我们把它打磨得更好。',
+  ]),
+  continueLabel: '继续',
+  scrollHint: '↑/↓ 滚动',
+  saving: '正在保存确认…',
+  saveError: '无法保存确认，请按 Enter 重试。',
+})
+
+/** Locale map whose entries deliberately share the single Chinese owner copy. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_COPY = Object.freeze({
+  'zh-CN': TUI_FIRST_RUN_WELCOME_CHINESE_COPY,
+  en: TUI_FIRST_RUN_WELCOME_CHINESE_COPY,
+})
+
+/** Locale presented by the shipped first-run notice. */
+export const TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE = 'zh-CN' as const
--- a/apps/cli/src/tui-onboarding/tui-first-run-welcome.ts
+++ b/apps/cli/src/tui-onboarding/tui-first-run-welcome.ts
@@ -0,0 +1,385 @@
+/**
+ * Effect-owned first-run overlay for the shipped `dsh` TUI.
+ *
+ * The launcher owns the per-DSH_HOME acknowledgement boundary; the component
+ * reaches the terminal only through the mounted `ctx.tui` overlay service and
+ * never touches the session or model context.
+ * @module @deepseek-ai/dsh/tui-onboarding/tui-first-run-welcome
+ */
+
+import { randomUUID } from 'node:crypto'
+import { lstat, mkdir, open, rename, rm } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
+import type { Context } from 'cordis'
+import {
+  Key,
+  matchesKey,
+  truncateToWidth,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from '@earendil-works/pi-tui'
+import {
+  disposeRootAndExit,
+  type TuiComponent,
+  type TuiFocusable,
+  type TuiOverlayHost,
+} from '@deepseek-ai/dsh-tui'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_COPY,
+  TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE,
+  TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+  type TuiFirstRunWelcomeNoticeCopy,
+} from './tui-first-run-welcome-copy.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_WHALE,
+  type TuiFirstRunWelcomeArtTier,
+} from './tui-first-run-welcome-art.ts'
+
+// TODO: Move acknowledgement persistence behind @deepseek-ai/dsh-storage once
+// its backend contract supports concurrent host processes. This same-value
+// marker must not inherit JSON lost updates or SQLite busy failures.
+const ACKNOWLEDGEMENT_DIRECTORY = 'notices'
+const ACKNOWLEDGEMENT_BASENAME = 'tui-first-run-welcome'
+
+/** Cordis plugin name. */
+export const name = 'tui-first-run-welcome'
+/** The notice can open only after the terminal-local overlay service mounts. */
+export const inject = ['tui']
+
+/** Launcher-resolved configuration for the terminal-local notice. */
+interface Config {
+  /** Absolute DeepSeek Harness home owning this acknowledgement. */
+  readonly dshHome: string
+  /** Render the bit-equivalent printable ASCII icon fallback. */
+  readonly asciiArt?: boolean
+}
+
+/**
+ * Detect an explicitly non-Unicode terminal locale for the static ASCII art fallback.
+ * @param env - Process environment carrying locale and terminal declarations.
+ * @returns `true` only when the environment explicitly declares an ASCII-only locale or dumb terminal.
+ */
+export function needsTuiFirstRunWelcomeAsciiArt(
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): boolean {
+  const locale = env.LC_ALL ?? env.LC_CTYPE ?? env.LANG
+  return env.TERM === 'dumb' || locale === 'C' || locale === 'POSIX'
+}
+
+/**
+ * Resolve the immutable marker for one notice version.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version whose acknowledgement is queried.
+ * @returns Absolute marker path beneath the Harness home.
+ */
+export function tuiFirstRunWelcomeAcknowledgementPath(dshHome: string, version: number): string {
+  return join(
+    dshHome,
+    ACKNOWLEDGEMENT_DIRECTORY,
+    `${ACKNOWLEDGEMENT_BASENAME}-v${String(version)}.ack`,
+  )
+}
+
+/**
+ * Test whether one notice version has been acknowledged.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version to inspect.
+ * @returns `true` only for a regular marker file; a malformed marker fails loud.
+ */
+export async function hasTuiFirstRunWelcomeAcknowledgement(
+  dshHome: string,
+  version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+): Promise<boolean> {
+  const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version)
+  try {
+    const info = await lstat(path)
+    if (!info.isFile()) throw new Error(`TUI welcome acknowledgement is not a file: ${path}`)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/**
+ * Persist one version acknowledgement by syncing a random same-directory file
+ * before atomically replacing the immutable marker. Concurrent launches publish
+ * the same fact, so same-value last-writer-wins replacement loses no state.
+ * @param dshHome - Resolved Harness home.
+ * @param version - Copy version being acknowledged.
+ */
+export async function acknowledgeTuiFirstRunWelcome(
+  dshHome: string,
+  version: number = TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+): Promise<void> {
+  const path = tuiFirstRunWelcomeAcknowledgementPath(dshHome, version)
+  const directory = dirname(path)
+  const temp = join(directory, `.${basename(path)}.${randomUUID()}.tmp`)
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  await syncDirectory(dirname(directory))
+  let handle: Awaited<ReturnType<typeof open>> | undefined
+  try {
+    handle = await open(temp, 'wx', 0o600)
+    await handle.sync()
+    const created = handle
+    handle = undefined
+    await created.close()
+    await rename(temp, path)
+  } catch (error) {
+    /* v8 ignore start -- fault-injected UI coverage proves failed acknowledgements stay uncommitted and retryable */
+    try {
+      await handle?.close()
+    } finally {
+      await rm(temp, { force: true })
+    }
+    throw error
+    /* v8 ignore stop */
+  }
+  try {
+    await syncDirectory(directory)
+  /* v8 ignore next -- rename is the commit point; directory-fsync fault injection is platform-specific */
+  } catch {
+    // Swallow post-rename directory fsync failure: the marker is already committed,
+    // and crash loss can only make the notice reappear on the safe side.
+  }
+}
+
+/** Sync one POSIX directory after publishing a child entry. */
+/* v8 ignore start -- Windows rejects directory opens; POSIX unit coverage owns this path. */
+async function syncDirectory(path: string): Promise<void> {
+  if (process.platform === 'win32') return
+  const handle = await open(path, 'r')
+  try {
+    await handle.sync()
+  } finally {
+    await handle.close()
+  }
+}
+/* v8 ignore stop */
+
+/** Render one visible-width-padded line inside the notice frame. */
+function framed(content: string, innerWidth: number, host: TuiOverlayHost): string {
+  const clipped = truncateToWidth(content, innerWidth, '')
+  return `${host.theme.dim('│')} ${clipped}${' '.repeat(Math.max(0, innerWidth - visibleWidth(clipped)))} ${host.theme.dim('│')}`
+}
+
+/** Center one line by terminal column width. */
+function centered(content: string, width: number): string {
+  const clipped = truncateToWidth(content, width, '')
+  const remaining = Math.max(0, width - visibleWidth(clipped))
+  return `${' '.repeat(Math.floor(remaining / 2))}${clipped}`
+}
+
+/**
+ * Select the art tier for the actual overlay width and viewport height.
+ * @param innerWidth - Columns inside the frame.
+ * @param viewportRows - Current terminal rows.
+ * @returns full, compact, minimal, or no art when prose must take priority.
+ */
+export function tuiFirstRunWelcomeArtTier(
+  innerWidth: number,
+  viewportRows: number,
+): TuiFirstRunWelcomeArtTier | undefined {
+  const compositionCapacity = Math.max(1, Math.max(7, Math.floor(viewportRows * 0.9)) - 5)
+  if (innerWidth >= 96 && TUI_FIRST_RUN_WELCOME_WHALE.full.unicode.length <= compositionCapacity) return 'full'
+  if (innerWidth >= 80 && TUI_FIRST_RUN_WELCOME_WHALE.compact.unicode.length + 4 <= compositionCapacity) return 'compact'
+  if (innerWidth >= 64 && TUI_FIRST_RUN_WELCOME_WHALE.minimal.unicode.length + 4 <= compositionCapacity) return 'minimal'
+  return undefined
+}
+
+/** Wrap the centrally owned prose while promoting its opening quotation. */
+function proseLines(
+  copy: TuiFirstRunWelcomeNoticeCopy,
+  width: number,
+  host: TuiOverlayHost,
+): string[] {
+  const lines: string[] = []
+  for (const [index, paragraph] of copy.paragraphs.entries()) {
+    if (index > 0) lines.push('')
+    const quoteEnd = paragraph.startsWith('“') ? paragraph.indexOf('”') : -1
+    if (quoteEnd > 0) {
+      const quote = paragraph.slice(0, quoteEnd + 1)
+      const remainder = paragraph.slice(quoteEnd + 1).trimStart()
+      lines.push(...wrapTextWithAnsi(host.theme.bold(host.theme.text(host.display(quote))), width))
+      lines.push('')
+      if (remainder !== '') lines.push(...wrapTextWithAnsi(host.theme.text(host.display(remainder)), width))
+    } else {
+      lines.push(...wrapTextWithAnsi(host.theme.text(host.display(paragraph)), width))
+    }
+  }
+  return lines
+}
+
+/** Render centered static brand art without putting ANSI into its owner file. */
+function artLines(
+  tier: TuiFirstRunWelcomeArtTier,
+  width: number,
+  host: TuiOverlayHost,
+  asciiArt: boolean,
+): string[] {
+  const art = TUI_FIRST_RUN_WELCOME_WHALE[tier][asciiArt ? 'ascii' : 'unicode']
+  return art.map(line => centered(host.theme.brand(line), width))
+}
+
+/** Responsive, scrollable notice whose only completion input is Enter. */
+export class TuiFirstRunWelcomeComponent implements TuiComponent, TuiFocusable {
+  focused = false
+  private scrollOffset = 0
+  private bodyCapacity = 1
+  private maxScrollOffset = 0
+  private saving = false
+  private saveFailed = false
+
+  constructor(
+    private readonly host: TuiOverlayHost,
+    private readonly copy: TuiFirstRunWelcomeNoticeCopy,
+    private readonly acknowledge: () => Promise<void>,
+    private readonly exit: () => void,
+    private readonly asciiArt = false,
+  ) {}
+
+  invalidate(): void {}
+
+  render(width: number): string[] {
+    const frameWidth = Math.max(6, width)
+    const innerWidth = Math.max(1, frameWidth - 4)
+    const viewportRows = this.host.viewport.rows
+    const tier = tuiFirstRunWelcomeArtTier(innerWidth, viewportRows)
+    const availableRows = Math.max(7, Math.floor(viewportRows * 0.9))
+    const title = this.host.theme.bold(this.host.theme.brand(this.copy.title))
+    let fixedHeader: string[] = []
+    let fullContentHeader: string[] = []
+    let body: string[]
+    let fullArt: string[] | undefined
+    const fullArtWidth = 44
+
+    if (tier === 'full') {
+      fullArt = artLines(tier, fullArtWidth, this.host, this.asciiArt)
+      const contentWidth = Math.max(1, innerWidth - fullArtWidth - 3)
+      fullContentHeader = [centered(title, contentWidth), '']
+      body = proseLines(this.copy, contentWidth, this.host)
+    } else {
+      const art = tier === undefined ? [] : artLines(tier, innerWidth, this.host, this.asciiArt)
+      fixedHeader = [...art, ...art.length === 0 ? [] : [''], centered(title, innerWidth), '']
+      body = proseLines(this.copy, innerWidth, this.host)
+    }
+
+    const compositionCapacity = Math.max(1, availableRows - 5)
+    const bodyLimit = Math.max(1, compositionCapacity - fixedHeader.length - fullContentHeader.length)
+    this.bodyCapacity = Math.min(body.length, bodyLimit)
+    const maxOffset = Math.max(0, body.length - this.bodyCapacity)
+    this.maxScrollOffset = maxOffset
+    this.scrollOffset = Math.min(this.scrollOffset, maxOffset)
+    const visibleBody = body.slice(this.scrollOffset, this.scrollOffset + this.bodyCapacity)
+
+    const top = this.host.theme.dim(`╭${'─'.repeat(Math.max(0, frameWidth - 2))}╮`)
+    const separator = this.host.theme.dim(`├${'─'.repeat(Math.max(0, frameWidth - 2))}┤`)
+    const bottom = this.host.theme.dim(`╰${'─'.repeat(Math.max(0, frameWidth - 2))}╯`)
+    const action = this.host.theme.bold(this.host.theme.accent(`Enter  ${this.copy.continueLabel}`))
+    const hasAbove = this.scrollOffset > 0
+    const hasBelow = this.scrollOffset < maxOffset
+    const scroll = hasAbove || hasBelow
+      ? `${hasAbove ? '↑' : ' '} ${this.copy.scrollHint} ${hasBelow ? '↓' : ' '}`
+      : ''
+    const status = this.saveFailed
+      ? this.host.theme.error(this.copy.saveError)
+      : this.saving
+        ? this.host.theme.dim(this.copy.saving)
+        : this.host.theme.dim(scroll)
+
+    const fullContent = [...fullContentHeader, ...visibleBody]
+    const composition = fullArt === undefined
+      ? [...fixedHeader, ...visibleBody]
+      : Array.from({ length: Math.max(fullArt.length, fullContent.length) }, (_, index) => {
+        const art = fullArt[index] ?? ''
+        const line = fullContent[index] ?? ''
+        const left = `${art}${' '.repeat(Math.max(0, fullArtWidth - visibleWidth(art)))}`
+        return `${left}   ${line}`
+      })
+
+    return [
+      top,
+      ...composition.map(line => framed(line, innerWidth, this.host)),
+      separator,
+      framed(centered(action, innerWidth), innerWidth, this.host),
+      framed(centered(status, innerWidth), innerWidth, this.host),
+      bottom,
+    ]
+  }
+
+  handleInput(data: string): void {
+    if (matchesKey(data, Key.ctrl('c')) || matchesKey(data, Key.ctrl('d'))) {
+      this.exit()
+      return
+    }
+    if (matchesKey(data, Key.enter)) {
+      if (!this.saving) void this.commit()
+      return
+    }
+    if (this.saving || matchesKey(data, Key.escape)) return
+    if (matchesKey(data, Key.up)) this.scrollBy(-1)
+    else if (matchesKey(data, Key.down)) this.scrollBy(1)
+    else if (matchesKey(data, Key.pageUp)) this.scrollBy(-this.bodyCapacity)
+    else if (matchesKey(data, Key.pageDown)) this.scrollBy(this.bodyCapacity)
+    else if (matchesKey(data, Key.home)) this.scrollTo(0)
+    else if (matchesKey(data, Key.end)) this.scrollTo(this.maxScrollOffset)
+  }
+
+  private scrollBy(delta: number): void {
+    this.scrollTo(this.scrollOffset + delta)
+  }
+
+  private scrollTo(offset: number): void {
+    this.scrollOffset = Math.min(this.maxScrollOffset, Math.max(0, offset))
+    this.host.invalidate()
+  }
+
+  private async commit(): Promise<void> {
+    this.saving = true
+    this.saveFailed = false
+    this.host.invalidate()
+    try {
+      await this.acknowledge()
+      this.host.close()
+    } catch {
+      this.saving = false
+      this.saveFailed = true
+      this.host.invalidate()
+    }
+  }
+}
+
+/**
+ * Open the first-run notice through the mounted TUI's FIFO overlay owner.
+ * @param ctx - Plugin context carrying the terminal-local TUI service.
+ * @param config - Launcher-resolved Harness home.
+ */
+export function apply(ctx: Context, config: Config): void {
+  const copy = TUI_FIRST_RUN_WELCOME_NOTICE_COPY[TUI_FIRST_RUN_WELCOME_NOTICE_LOCALE]
+  const pending = new Set<Promise<void>>()
+  const acknowledge = (): Promise<void> => {
+    const task = acknowledgeTuiFirstRunWelcome(config.dshHome)
+    pending.add(task)
+    const settled = (): void => { pending.delete(task) }
+    void task.then(settled, settled)
+    return task
+  }
+  ctx.effect(() => async () => {
+    await Promise.allSettled(pending)
+  }, 'tui first-run welcome acknowledgement')
+  ctx.tui.openOverlay({
+    create: host => new TuiFirstRunWelcomeComponent(
+      host,
+      copy,
+      acknowledge,
+      () => { disposeRootAndExit(ctx, 0) },
+      config.asciiArt ?? false,
+    ),
+    options: {
+      width: '100%',
+      maxHeight: '90%',
+      anchor: 'center',
+      margin: 0,
+    },
+  })
+}
--- a/apps/cli/src/tui.ts
+++ b/apps/cli/src/tui.ts
@@ -8,12 +8,11 @@
 * 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.
+ * `dsh experimental-meta` is the one exception — it makes this harness
+ * checkout the workspace. `dsh experimental-upgrade` 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
 */

@@ -30,6 +29,7 @@ import {
  loadPersonalPatches,
  resolveConfigPath,
 } from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import { configHasTelemetryRow, resolveTelemetryPatch } from './app-cli-entry.ts'
 import { SESSION_QUERY_SQLITE_PATH_KEY } from '@deepseek-ai/dsh-session-query-sqlite'
@@ -42,6 +42,16 @@ import {
  type MainSessionIdentity,
  type TuiResumeHost,
 } from '@deepseek-ai/dsh-tui'
+import {
+  apply as applyTuiFirstRunWelcome,
+  hasTuiFirstRunWelcomeAcknowledgement,
+  inject as tuiFirstRunWelcomeInject,
+  name as tuiFirstRunWelcomeName,
+  needsTuiFirstRunWelcomeAsciiArt,
+} from './tui-onboarding/tui-first-run-welcome.ts'
+import {
+  TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+} from './tui-onboarding/tui-first-run-welcome-copy.ts'

 const NAME = 'dsh'

@@ -61,30 +71,11 @@ const SESSION_QUERY_DB = `session-query-${String(process.pid)}-${randomUUID()}.d
 // 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
 // symlink, an arbitrary cwd). The agent is told where its own source lives.
-const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+/** The harness checkout used as the `dsh experimental-meta` workspace and source prompt path. */
+export const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))

 /* v8 ignore start -- composition over the unit-tested dsh-app-boot helpers;
   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 - an overlay patch list applied over the shared base and the
@@ -97,10 +88,10 @@ export async function runSkillSession(skill: string): Promise<void> {
 * {@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.
+ * one, or `undefined` to keep the cwd. Only `dsh experimental-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
+ * first turn, or `undefined`. Set only by `dsh experimental-upgrade` 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`
@@ -133,6 +124,11 @@ export async function runTui(
  // 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)
+  const dshHome = resolveDshHome()
+  const showFirstRunWelcome = !await hasTuiFirstRunWelcomeAcknowledgement(
+    dshHome,
+    TUI_FIRST_RUN_WELCOME_NOTICE_VERSION,
+  )
  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
@@ -144,8 +140,9 @@ export async function runTui(
  const entry = process.argv[1]
  const execve = process.execve?.bind(process)
  const app: { current?: Context } = {}
-  // Resume always enters the default surface because meta rejects parent
-  // options, including `--resume`. The resumed session already persists its cwd.
+  // Resume always enters the default surface because experimental-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
@@ -251,5 +248,15 @@ export async function runTui(
  )
  app.current = ctx
  addHarnessSourceSection(ctx, SOURCE_ROOT)
+  if (showFirstRunWelcome) {
+    await ctx.plugin({
+      name: tuiFirstRunWelcomeName,
+      inject: tuiFirstRunWelcomeInject,
+      apply: applyTuiFirstRunWelcome,
+    }, {
+      dshHome,
+      asciiArt: needsTuiFirstRunWelcomeAsciiArt(),
+    })
+  }
 }
 /* v8 ignore stop */
--- a/apps/cli/src/web.ts
+++ b/apps/cli/src/web.ts
@@ -57,12 +57,14 @@ export async function runWeb(
    void Promise.resolve(ctx.fiber.dispose()).finally(() => { process.exit(code) })
  }

+  // Install shutdown handling before publishing readiness: supervisors may
+  // send a signal as soon as they observe the URL line.
+  process.on('SIGTERM', () => { shutdown(0) })
+  process.on('SIGINT', () => { shutdown(130) })
+
  // The entry's boot-time snapshot, not a fresh sample: the printed LAN URL
  // must name an address the /api trust fence was configured with.
  const lanCandidate = entry.lanAddresses[0]
  const localUrl = `http://${LOOPBACK_HOST}:${boundPort}`
  console.log(`dsh web: ${localUrl}${lanCandidate === undefined ? '' : ` (LAN: http://${lanCandidate}:${boundPort})`}`)
-
-  process.on('SIGTERM', () => { shutdown(0) })
-  process.on('SIGINT', () => { shutdown(130) })
 }