@crazyhappyone/dsh-tui 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhangyangrui
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,5 @@
+# Bilingual-pair consistency record: both languages carry equal authority.
+# This source-only mirror has no DSH pairing runner. Recompute with:
+#   git hash-object README.md README.zh.md
+README.md: 87fc088f1ef0e8f09d582ca4075d7be650ed5312
+README.zh.md: 0f23e7e5d1f1a5f9b2fdf41f8bf4e593114b1111

package/README.md

@@ -0,0 +1,169 @@
+---
+description: "Installable source-runtime launcher and private source mirror for the DeepSeek Harness terminal interface."
+kind: "package-group"
+---
+
+# dsh-tui — DeepSeek Harness terminal interface
+
+English | [中文](README.zh.md)
+
+## Summary
+
+`@crazyhappyone/dsh-tui` provides the `dsh-tui` command for running and safely updating the DeepSeek Harness terminal interface. The launcher manages a dedicated DSH source checkout, so it never pulls, resets, stashes, or cleans a contributor's development checkout. This repository also mirrors the `packages/tui/` bundle and renderer sources for review. DSH continues to own agents, sessions, tools, persistence, providers, permissions, and profile assembly.
+
+## Table of Contents
+
+- [Install the launcher](#install-the-launcher)
+- [Run and update](#run-and-update)
+- [Configure the source runtime](#configure-the-source-runtime)
+- [Relationship to DSH](#relationship-to-dsh)
+- [Packages](#packages)
+- [Development workflow](#development-workflow)
+- [Publish the npm package](#publish-the-npm-package)
+- [Known limitations](#known-limitations)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="install-the-launcher"></a>
+## Install the launcher
+
+The unscoped `dsh-tui` package belongs to another maintainer. This project publishes only under the authenticated `crazyhappyone` npm scope.
+
+After a prerelease is published:
+
+```text
+npm install --global @crazyhappyone/dsh-tui@next
+dsh-tui version
+```
+
+Installation creates only the launcher. It does not clone DSH, run `pnpm install`, prompt for Git credentials, or execute a postinstall script. Run `dsh-tui update` explicitly to create the source runtime.
+
+-----
+
+<a id="run-and-update"></a>
+## Run and update
+
+Initialize the dedicated runtime, then start the TUI:
+
+```text
+dsh-tui update
+dsh-tui
+```
+
+Ordinary arguments pass to the `deepseek-tui` profile unchanged:
+
+```text
+dsh-tui "review this repository"
+dsh-tui --resume <session-id>
+dsh-tui --cwd <directory>
+```
+
+`dsh-tui update` clones the configured source when the runtime is absent. For an existing runtime it requires a clean worktree, fetches the configured ref, proves the current HEAD is its ancestor, applies only `git merge --ff-only`, and runs `pnpm install --frozen-lockfile`. Dirty or divergent history stops before HEAD changes.
+
+`dsh-tui version` reports the launcher version, runtime directory, runtime Git SHA, and DSH version without network access. The exact words `update` and `version` are launcher commands; use `dsh-tui -- update` or `dsh-tui -- version` to send either word as a TUI task.
+
+Updating the launcher and updating the runtime are separate operations:
+
+```text
+npm install --global @crazyhappyone/dsh-tui@next
+dsh-tui update
+```
+
+-----
+
+<a id="configure-the-source-runtime"></a>
+## Configure the source runtime
+
+The defaults track the owner's private `feat/deepseek-tui` branch. Git authorization for that repository is required. Other users can select a compatible accessible repository and ref.
+
+| Environment variable | Default | Purpose |
+|---|---|---|
+| `DSH_TUI_RUNTIME_DIR` | `~/.local/share/dsh-tui/runtime` | Dedicated clone used only by the launcher |
+| `DSH_TUI_SOURCE_URL` | `https://github.com/zhangyang-crazy-one/deepseek-harness.git` | Git remote cloned and fetched by `update` |
+| `DSH_TUI_SOURCE_REF` | `feat/deepseek-tui` | Branch or ref fetched by `update` |
+| `DSH_TUI_PNPM` | `pnpm` | pnpm executable used for install and launch |
+
+Values must be non-empty, and the runtime directory must be absolute. The launcher refuses a symbolic-link runtime path and an existing directory that is not a Git checkout. Child commands receive argument arrays without shell interpolation.
+
+If dependency refresh fails after a fast-forward, the runtime stays at the reported new SHA but is not ready. Run the exact recovery command printed by the launcher. For dirty or divergent state, inspect only the dedicated runtime directory or select a new empty `DSH_TUI_RUNTIME_DIR`; the launcher never discards it automatically.
+
+-----
+
+<a id="relationship-to-dsh"></a>
+## Relationship to DSH
+
+The TUI is a DSH profile layer, not a separate agent runtime:
+
+```text
+@deepseek-ai/dsh-base
+  └─ @deepseek-ai/dsh-tui          profile patch, terminal lifecycle, controller
+       └─ @deepseek-ai/dsh-tui-render   Ink projection and terminal I/O
+```
+
+The integration source lives on the private [`feat/deepseek-tui` DSH branch](https://github.com/zhangyang-crazy-one/deepseek-harness/tree/feat/deepseek-tui/packages/tui). Changes that affect DSH services, profile composition, assembled CLI snapshots, or Agent Notes belong in that monorepo and follow its architecture, testing, and documentation rules.
+
+-----
+
+<a id="packages"></a>
+## Packages
+
+| Package | DSH shape | Responsibility |
+|---|---|---|
+| [`tui/`](tui/README.md) | Profile bundle plus runtime plugin | Composes the terminal layer over `dsh-base`, owns the live terminal session, and maps user actions to DSH services |
+| [`tui-render/`](tui-render/README.md) | Library | Projects controller state through Ink without owning agents, persistence, or model requests |
+
+-----
+
+<a id="development-workflow"></a>
+## Development workflow
+
+Implement TUI behavior in the complete DSH checkout, run the checks selected by the changed behavior, and export the confirmed `packages/tui/` tree here. Develop the launcher in this repository with `npm test`; test installation through a packed tarball rather than a workspace link.
+
+The launcher runtime must remain separate from the development checkout. To test against another source safely, point `DSH_TUI_RUNTIME_DIR` at a temporary absolute directory and configure `DSH_TUI_SOURCE_URL` and `DSH_TUI_SOURCE_REF`.
+
+-----
+
+<a id="publish-the-npm-package"></a>
+## Publish the npm package
+
+The operator authenticates through npm's browser flow and verifies the selected account:
+
+```text
+npm config delete //registry.npmjs.org/:_authToken
+npm config set registry https://registry.npmjs.org/
+npm login --registry=https://registry.npmjs.org/ --auth-type=web
+npm whoami
+```
+
+`npm whoami` must print `crazyhappyone`. Never place the password, OTP, or npm token in this repository, an issue, command output captured for review, or an AI conversation.
+
+After tests and packed-install verification pass, publish a prerelease only with explicit operator approval:
+
+```text
+npm publish --access public --tag next
+```
+
+When npm requires two-factor authentication, the operator supplies the current code locally:
+
+```text
+npm publish --access public --tag next --otp=<six-digit-code>
+```
+
+Promotion to `latest` is a separate release decision. Local implementation and verification never create or change a registry package automatically.
+
+-----
+
+<a id="known-limitations"></a>
+## Known limitations
+
+- **Private default source** — npm installation is public, but the default DSH runtime remote requires repository authorization; anonymous users must configure an accessible compatible source.
+- **Source toolchain required** — runtime initialization requires Git, pnpm, and a DSH-supported Node version.
+- **No automatic conflict resolution** — dirty or non-fast-forward runtime history requires explicit human action or a new runtime directory.
+- **Runtime update is not launcher update** — `dsh-tui update` refreshes DSH source and dependencies; npm updates the launcher package.
+- **Integration owns release readiness** — launcher success does not replace the DSH branch's behavior, snapshot, build, or hygiene checks.
+
+<a id="dev-note"></a>
+## Dev Note
+
+None.

package/README.zh.md

@@ -0,0 +1,169 @@
+---
+description: "DeepSeek Harness 终端界面的可安装源码运行时 launcher 与 private 源码镜像。"
+kind: "package-group"
+---
+
+# dsh-tui — DeepSeek Harness 终端界面
+
+[English](README.md) | 中文
+
+## 概述
+
+`@crazyhappyone/dsh-tui` 提供 `dsh-tui` 命令，用于运行和安全更新 DeepSeek Harness 终端界面。Launcher 管理专用 DSH 源码 checkout，因此不会 pull、reset、stash 或 clean 贡献者的开发 checkout。本仓库还镜像 `packages/tui/` bundle 与 renderer 源码以供审查。Agent、会话、工具、持久化、provider、权限与 profile 组装仍由 DSH 拥有。
+
+## 目录
+
+- [安装 launcher](#install-the-launcher)
+- [运行与更新](#run-and-update)
+- [配置源码运行时](#configure-the-source-runtime)
+- [与 DSH 的关系](#relationship-to-dsh)
+- [包](#packages)
+- [开发工作流](#development-workflow)
+- [发布 npm 包](#publish-the-npm-package)
+- [已知限制](#known-limitations)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="install-the-launcher"></a>
+## 安装 launcher
+
+无 scope 的 `dsh-tui` 包属于另一位 maintainer。本项目只在已认证的 `crazyhappyone` npm scope 下发布。
+
+发布 prerelease 后运行：
+
+```text
+npm install --global @crazyhappyone/dsh-tui@next
+dsh-tui version
+```
+
+安装只创建 launcher。它不会 clone DSH、运行 `pnpm install`、请求 Git 凭据或执行 postinstall script。请显式运行 `dsh-tui update` 创建源码运行时。
+
+-----
+
+<a id="run-and-update"></a>
+## 运行与更新
+
+初始化专用运行时，然后启动 TUI：
+
+```text
+dsh-tui update
+dsh-tui
+```
+
+普通参数会原样传递给 `deepseek-tui` profile：
+
+```text
+dsh-tui "review this repository"
+dsh-tui --resume <session-id>
+dsh-tui --cwd <directory>
+```
+
+运行时不存在时，`dsh-tui update` 会 clone 配置的源码。对于现有运行时，它要求工作树干净、fetch 配置的 ref、证明当前 HEAD 是该 ref 的祖先、只应用 `git merge --ff-only`，再运行 `pnpm install --frozen-lockfile`。Dirty 或 divergent history 会在 HEAD 改变前停止。
+
+`dsh-tui version` 会报告 launcher 版本、运行时目录、运行时 Git SHA 与 DSH 版本，并且不访问网络。精确单词 `update` 与 `version` 是 launcher 命令；使用 `dsh-tui -- update` 或 `dsh-tui -- version` 将其作为 TUI task 发送。
+
+更新 launcher 与更新运行时是不同操作：
+
+```text
+npm install --global @crazyhappyone/dsh-tui@next
+dsh-tui update
+```
+
+-----
+
+<a id="configure-the-source-runtime"></a>
+## 配置源码运行时
+
+默认值跟踪所有者的 private `feat/deepseek-tui` 分支。该仓库需要 Git authorization。其他用户可以选择一个兼容且可访问的仓库与 ref。
+
+| 环境变量 | 默认值 | 用途 |
+|---|---|---|
+| `DSH_TUI_RUNTIME_DIR` | `~/.local/share/dsh-tui/runtime` | 仅供 launcher 使用的专用 clone |
+| `DSH_TUI_SOURCE_URL` | `https://github.com/zhangyang-crazy-one/deepseek-harness.git` | `update` clone 和 fetch 的 Git remote |
+| `DSH_TUI_SOURCE_REF` | `feat/deepseek-tui` | `update` fetch 的 branch 或 ref |
+| `DSH_TUI_PNPM` | `pnpm` | 安装和启动所用的 pnpm executable |
+
+所有值都不得为空，运行时目录必须是绝对路径。Launcher 会拒绝 symbolic-link runtime path，也会拒绝不是 Git checkout 的现有目录。Child command 接收参数数组，不使用 shell interpolation。
+
+如果 fast-forward 后的依赖刷新失败，运行时会停留在报告的新 SHA，但不会被声明为 ready。请运行 launcher 打印的精确恢复命令。对于 dirty 或 divergent 状态，只检查专用运行时目录，或选择新的空 `DSH_TUI_RUNTIME_DIR`；launcher 不会自动丢弃它。
+
+-----
+
+<a id="relationship-to-dsh"></a>
+## 与 DSH 的关系
+
+TUI 是 DSH profile 层，而不是独立的 agent 运行时：
+
+```text
+@deepseek-ai/dsh-base
+  └─ @deepseek-ai/dsh-tui          profile patch, terminal lifecycle, controller
+       └─ @deepseek-ai/dsh-tui-render   Ink projection and terminal I/O
+```
+
+集成源码位于 private [`feat/deepseek-tui` DSH 分支](https://github.com/zhangyang-crazy-one/deepseek-harness/tree/feat/deepseek-tui/packages/tui)。影响 DSH 服务、profile 组合、组装后 CLI snapshot 或 Agent Note 的变更归该 monorepo 所有，并遵循其中的架构、测试与文档规则。
+
+-----
+
+<a id="packages"></a>
+## 包
+
+| 包 | DSH 形态 | 职责 |
+|---|---|---|
+| [`tui/`](tui/README.zh.md) | Profile bundle 与运行时插件 | 在 `dsh-base` 上组合终端层、拥有 live 终端会话，并将用户动作映射到 DSH 服务 |
+| [`tui-render/`](tui-render/README.zh.md) | Library | 通过 Ink 投影控制器状态，但不拥有 agent、持久化或模型请求 |
+
+-----
+
+<a id="development-workflow"></a>
+## 开发工作流
+
+在完整 DSH checkout 中实现 TUI 行为，运行受变更行为影响的检查，并将确认后的 `packages/tui/` tree 导出到这里。在本仓库中使用 `npm test` 开发 launcher；通过 packed tarball 测试安装，不使用 workspace link。
+
+Launcher runtime 必须与开发 checkout 分离。要安全测试其他源码，请将 `DSH_TUI_RUNTIME_DIR` 指向临时绝对目录，并配置 `DSH_TUI_SOURCE_URL` 与 `DSH_TUI_SOURCE_REF`。
+
+-----
+
+<a id="publish-the-npm-package"></a>
+## 发布 npm 包
+
+Operator 通过 npm browser flow 认证，并验证所选账号：
+
+```text
+npm config delete //registry.npmjs.org/:_authToken
+npm config set registry https://registry.npmjs.org/
+npm login --registry=https://registry.npmjs.org/ --auth-type=web
+npm whoami
+```
+
+`npm whoami` 必须打印 `crazyhappyone`。绝不要把密码、OTP 或 npm token 放入本仓库、issue、供审查捕获的命令输出或 AI conversation。
+
+测试与 packed-install 验证通过后，仅在 operator 显式批准时发布 prerelease：
+
+```text
+npm publish --access public --tag next
+```
+
+npm 要求双因素认证时，operator 在本地提供当前验证码：
+
+```text
+npm publish --access public --tag next --otp=<six-digit-code>
+```
+
+提升到 `latest` 是单独的 release 决策。本地实现与验证绝不会自动创建或更改 registry package。
+
+-----
+
+<a id="known-limitations"></a>
+## 已知限制
+
+- **Private 默认源码** — npm 安装是 public，但默认 DSH runtime remote 需要仓库授权；匿名用户必须配置一个可访问的兼容源码。
+- **需要源码工具链** — 初始化运行时需要 Git、pnpm 与 DSH 支持的 Node 版本。
+- **不自动解决冲突** — dirty 或 non-fast-forward runtime history 需要显式人工操作或新的运行时目录。
+- **运行时更新不是 launcher 更新** — `dsh-tui update` 刷新 DSH 源码与依赖；npm 更新 launcher package。
+- **集成分支拥有发布就绪状态** — launcher 成功不能替代 DSH 分支的行为、snapshot、build 或 hygiene 检查。
+
+<a id="dev-note"></a>
+## 开发备注
+
+无。

package/bin/dsh-tui.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/** Command-line entry for the dsh-tui source-runtime launcher. */
+
+import { lstatSync, mkdirSync, readFileSync } from 'node:fs'
+import { constants, homedir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { spawnSync } from 'node:child_process'
+import { parseLauncherInvocation, resolveLauncherSettings, runLauncher } from '../src/launcher.js'
+
+function inspectPath(path) {
+  try {
+    const stat = lstatSync(path)
+    if (stat.isSymbolicLink()) return 'symlink'
+    if (stat.isDirectory()) return 'directory'
+    if (stat.isFile()) return 'file'
+    return 'other'
+  } catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return 'missing'
+    throw error
+  }
+}
+
+function run(command, args, options = {}) {
+  const capture = options.capture === true
+  const result = spawnSync(command, args, {
+    cwd: options.cwd,
+    encoding: capture ? 'utf8' : undefined,
+    env: process.env,
+    maxBuffer: capture ? 16 * 1024 * 1024 : undefined,
+    shell: false,
+    stdio: options.stdio === 'inherit' ? 'inherit' : capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+  })
+  if (result.error !== undefined) {
+    return { status: 1, stdout: '', stderr: result.error.message }
+  }
+  const status = result.status ?? signalOutcome(result.signal)
+  return {
+    status,
+    stdout: typeof result.stdout === 'string' ? result.stdout : '',
+    stderr: typeof result.stderr === 'string' ? result.stderr : '',
+    ...(result.signal === null ? {} : { signal: result.signal }),
+  }
+}
+
+function signalOutcome(signal) {
+  if (signal === null) return 1
+  const number = constants.signals[signal]
+  return number === undefined ? 1 : 128 + number
+}
+
+const manifest = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'))
+
+try {
+  const invocation = parseLauncherInvocation(process.argv.slice(2))
+  const settings = resolveLauncherSettings({ env: process.env, homeDirectory: homedir() })
+  process.exitCode = runLauncher({
+    invocation,
+    settings,
+    packageVersion: manifest.version,
+    adapters: {
+      inspectPath,
+      makeDirectory: path => mkdirSync(path, { recursive: true, mode: 0o700 }),
+      readText: path => readFileSync(path, 'utf8'),
+      run,
+      writeOut: text => process.stdout.write(text),
+      writeError: text => process.stderr.write(text),
+    },
+  })
+} catch (error) {
+  process.stderr.write(`dsh-tui: ${error instanceof Error ? error.message : String(error)}\n`)
+  process.exitCode = 1
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crazyhappyone/dsh-tui",
+  "version": "0.1.0-alpha.1",
+  "description": "Source-runtime launcher for the DeepSeek Harness terminal interface",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "dsh-tui": "bin/dsh-tui.js"
+  },
+  "files": [
+    "bin/dsh-tui.js",
+    "src/**/*.js",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run --json"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zhangyang-crazy-one/dsh-tui.git"
+  },
+  "keywords": [
+    "deepseek",
+    "dsh",
+    "tui",
+    "terminal"
+  ]
+}

package/src/launcher.js

@@ -0,0 +1,253 @@
+/**
+ * Source-runtime launcher for the DeepSeek Harness TUI.
+ * @module @crazyhappyone/dsh-tui/launcher
+ */
+
+import { dirname, isAbsolute, join } from 'node:path'
+
+const DEFAULT_SOURCE_URL = 'https://github.com/zhangyang-crazy-one/deepseek-harness.git'
+const DEFAULT_SOURCE_REF = 'feat/deepseek-tui'
+
+/** @typedef {'missing' | 'directory' | 'file' | 'symlink' | 'other'} PathKind */
+
+/**
+ * @typedef {object} LauncherSettings
+ * @property {string} runtimeDirectory
+ * @property {string} sourceUrl
+ * @property {string} sourceRef
+ * @property {string} packageManager
+ */
+
+/**
+ * @typedef {object} CommandResult
+ * @property {number} status
+ * @property {string} stdout
+ * @property {string} stderr
+ * @property {string | undefined} [signal]
+ */
+
+/**
+ * @typedef {object} LauncherAdapters
+ * @property {(path: string) => PathKind} inspectPath
+ * @property {(path: string) => void} makeDirectory
+ * @property {(path: string) => string} readText
+ * @property {(command: string, args: string[], options?: {cwd?: string, stdio?: 'inherit', capture?: boolean}) => CommandResult} run
+ * @property {(text: string) => void} writeOut
+ * @property {(text: string) => void} writeError
+ */
+
+/**
+ * Parse the launcher's reserved management commands.
+ * @param {readonly string[]} argv - arguments after the executable.
+ * @returns {{kind: 'version'} | {kind: 'update'} | {kind: 'launch', args: string[]}}
+ */
+export function parseLauncherInvocation(argv) {
+  if (argv[0] === '--') return { kind: 'launch', args: [...argv.slice(1)] }
+  if (argv[0] === 'version') {
+    if (argv.length !== 1) throw new Error('version takes no arguments; use `dsh-tui -- version ...` to send it as a task')
+    return { kind: 'version' }
+  }
+  if (argv[0] === 'update') {
+    if (argv.length !== 1) throw new Error('update takes no arguments; use `dsh-tui -- update ...` to send it as a task')
+    return { kind: 'update' }
+  }
+  return { kind: 'launch', args: [...argv] }
+}
+
+/**
+ * Resolve deployment settings without touching the filesystem.
+ * @param {{env: Readonly<Record<string, string | undefined>>, homeDirectory: string}} input
+ * @returns {LauncherSettings}
+ */
+export function resolveLauncherSettings({ env, homeDirectory }) {
+  const runtimeDirectory = environmentValue(
+    env,
+    'DSH_TUI_RUNTIME_DIR',
+    join(homeDirectory, '.local', 'share', 'dsh-tui', 'runtime'),
+  )
+  if (!isAbsolute(runtimeDirectory)) throw new Error('DSH_TUI_RUNTIME_DIR must be an absolute path')
+  return {
+    runtimeDirectory,
+    sourceUrl: environmentValue(env, 'DSH_TUI_SOURCE_URL', DEFAULT_SOURCE_URL),
+    sourceRef: environmentValue(env, 'DSH_TUI_SOURCE_REF', DEFAULT_SOURCE_REF),
+    packageManager: environmentValue(env, 'DSH_TUI_PNPM', 'pnpm'),
+  }
+}
+
+/**
+ * Run one parsed launcher invocation.
+ * @param {{invocation: ReturnType<typeof parseLauncherInvocation>, settings: LauncherSettings, packageVersion: string, adapters: LauncherAdapters}} input
+ * @returns {number} process exit status.
+ */
+export function runLauncher({ invocation, settings, packageVersion, adapters }) {
+  switch (invocation.kind) {
+    case 'version':
+      return showVersion({ settings, packageVersion, adapters })
+    case 'update':
+      return updateRuntime({ settings, adapters })
+    case 'launch':
+      return launchTui({ args: invocation.args, settings, adapters })
+    default:
+      return assertNever(invocation)
+  }
+}
+
+function environmentValue(env, name, fallback) {
+  const value = env[name]
+  if (value === undefined) return fallback
+  if (value.trim() === '') throw new Error(`${name} must not be empty`)
+  return value
+}
+
+function runtimeState(settings, adapters) {
+  const kind = adapters.inspectPath(settings.runtimeDirectory)
+  if (kind === 'symlink') return { ok: false, message: `runtime path is a symbolic link: ${settings.runtimeDirectory}` }
+  if (kind === 'missing') return { ok: true, initialized: false }
+  if (kind !== 'directory') return { ok: false, message: `runtime path is not a directory: ${settings.runtimeDirectory}` }
+  const gitKind = adapters.inspectPath(join(settings.runtimeDirectory, '.git'))
+  if (gitKind !== 'directory' && gitKind !== 'file') {
+    return { ok: false, message: `runtime directory is not a Git checkout: ${settings.runtimeDirectory}` }
+  }
+  return { ok: true, initialized: true }
+}
+
+function launchTui({ args, settings, adapters }) {
+  const state = runtimeState(settings, adapters)
+  if (!state.ok) return reportError(adapters, state.message)
+  if (!state.initialized) {
+    return reportError(adapters, `runtime is not initialized at ${settings.runtimeDirectory}; run \`dsh-tui update\` first`)
+  }
+  const result = adapters.run(
+    settings.packageManager,
+    ['dsh', '--profile', 'deepseek-tui', ...args],
+    { cwd: settings.runtimeDirectory, stdio: 'inherit' },
+  )
+  return result.status
+}
+
+function showVersion({ settings, packageVersion, adapters }) {
+  adapters.writeOut(`dsh-tui ${packageVersion}\n`)
+  adapters.writeOut(`runtime directory: ${settings.runtimeDirectory}\n`)
+  const state = runtimeState(settings, adapters)
+  if (!state.ok) return reportError(adapters, state.message)
+  if (!state.initialized) {
+    adapters.writeOut('runtime: uninitialized\n')
+    return 0
+  }
+  const revision = captureGit(adapters, settings.runtimeDirectory, ['rev-parse', 'HEAD'], 'read runtime HEAD')
+  if (!revision.ok) return revision.status
+  adapters.writeOut(`runtime SHA: ${revision.stdout}\n`)
+  adapters.writeOut(`DSH version: ${readDshVersion(settings.runtimeDirectory, adapters)}\n`)
+  return 0
+}
+
+function readDshVersion(runtimeDirectory, adapters) {
+  try {
+    const manifest = JSON.parse(adapters.readText(join(runtimeDirectory, 'package.json')))
+    return typeof manifest.version === 'string' && manifest.version !== '' ? manifest.version : 'unknown'
+  } catch (error) {
+    return `unreadable (${errorMessage(error)})`
+  }
+}
+
+function updateRuntime({ settings, adapters }) {
+  const state = runtimeState(settings, adapters)
+  if (!state.ok) return reportError(adapters, state.message)
+  if (!state.initialized) return cloneRuntime({ settings, adapters })
+
+  const clean = captureGit(adapters, settings.runtimeDirectory, ['status', '--porcelain'], 'inspect runtime worktree')
+  if (!clean.ok) return clean.status
+  if (clean.stdout !== '') {
+    return reportError(adapters, `runtime worktree is not clean: ${settings.runtimeDirectory}`)
+  }
+
+  const before = captureGit(adapters, settings.runtimeDirectory, ['rev-parse', 'HEAD'], 'read current runtime HEAD')
+  if (!before.ok) return before.status
+  const fetched = adapters.run(
+    'git',
+    ['fetch', '--no-tags', '--', settings.sourceUrl, settings.sourceRef],
+    { cwd: settings.runtimeDirectory, capture: true },
+  )
+  if (fetched.status !== 0) {
+    return reportCommandFailure(adapters, 'fetch configured runtime source', fetched, [settings.sourceUrl])
+  }
+  const after = captureGit(adapters, settings.runtimeDirectory, ['rev-parse', 'FETCH_HEAD'], 'read fetched runtime HEAD')
+  if (!after.ok) return after.status
+
+  const ancestry = adapters.run(
+    'git',
+    ['merge-base', '--is-ancestor', before.stdout, after.stdout],
+    { cwd: settings.runtimeDirectory, capture: true },
+  )
+  if (ancestry.status === 1) {
+    return reportError(
+      adapters,
+      `runtime update is not a fast-forward (${before.stdout} -> ${after.stdout}); replace the dedicated runtime only after reviewing its history`,
+    )
+  }
+  if (ancestry.status !== 0) return reportCommandFailure(adapters, 'verify runtime ancestry', ancestry)
+
+  const merge = adapters.run('git', ['merge', '--ff-only', after.stdout], {
+    cwd: settings.runtimeDirectory,
+    capture: true,
+  })
+  if (merge.status !== 0) return reportCommandFailure(adapters, 'fast-forward runtime', merge)
+  const installStatus = installDependencies({ settings, adapters, currentSha: after.stdout })
+  if (installStatus !== 0) return installStatus
+  adapters.writeOut(`runtime updated: ${before.stdout} -> ${after.stdout}\n`)
+  return 0
+}
+
+function cloneRuntime({ settings, adapters }) {
+  adapters.makeDirectory(dirname(settings.runtimeDirectory))
+  const clone = adapters.run(
+    'git',
+    ['clone', '--branch', settings.sourceRef, '--single-branch', '--', settings.sourceUrl, settings.runtimeDirectory],
+    { capture: true },
+  )
+  if (clone.status !== 0) return reportCommandFailure(adapters, 'clone configured runtime source', clone, [settings.sourceUrl])
+  const installStatus = installDependencies({ settings, adapters, currentSha: 'new checkout' })
+  if (installStatus !== 0) return installStatus
+  const revision = captureGit(adapters, settings.runtimeDirectory, ['rev-parse', 'HEAD'], 'read cloned runtime HEAD')
+  if (!revision.ok) return revision.status
+  adapters.writeOut(`runtime initialized: ${revision.stdout}\n`)
+  return 0
+}
+
+function installDependencies({ settings, adapters, currentSha }) {
+  const install = adapters.run(settings.packageManager, ['install', '--frozen-lockfile'], {
+    cwd: settings.runtimeDirectory,
+    stdio: 'inherit',
+  })
+  if (install.status === 0) return 0
+  adapters.writeError(`dsh-tui: dependency refresh failed at ${currentSha}; runtime is not ready\n`)
+  adapters.writeError(`dsh-tui: recover with: cd ${settings.runtimeDirectory} && ${settings.packageManager} install --frozen-lockfile\n`)
+  return install.status
+}
+
+function captureGit(adapters, cwd, args, label) {
+  const result = adapters.run('git', args, { cwd, capture: true })
+  if (result.status !== 0) return { ok: false, status: reportCommandFailure(adapters, label, result) }
+  return { ok: true, stdout: result.stdout.trim() }
+}
+
+function reportCommandFailure(adapters, label, result, redactions = []) {
+  let detail = result.stderr.trim()
+  for (const value of redactions) detail = detail.replaceAll(value, '<source>')
+  detail = detail.replaceAll(/https?:\/\/[^/@\s]+@/g, 'https://<credentials>@')
+  adapters.writeError(`dsh-tui: ${label} failed${detail === '' ? '' : `: ${detail}`}\n`)
+  return result.status === 0 ? 1 : result.status
+}
+
+function reportError(adapters, message) {
+  adapters.writeError(`dsh-tui: ${message}\n`)
+  return 1
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error)
+}
+
+function assertNever(value) {
+  throw new Error(`unhandled launcher invocation: ${JSON.stringify(value)}`)
+}